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@finalout 9 10@c @ovar(ARG) 11@c ---------- 12@c The ARG is an optional argument. To be used for macro arguments in 13@c their documentation (@defmac). 14@macro ovar{varname} 15@r{[}@var{\varname\}@r{]} 16@end macro 17 18@c @dvar(ARG, DEFAULT) 19@c ------------------- 20@c The ARG is an optional argument, defaulting to DEFAULT. To be used 21@c for macro arguments in their documentation (@defmac). 22@macro dvar{varname, default} 23@r{[}@var{\varname\} = @samp{\default\}@r{]} 24@end macro 25 26@c Handling the indexes with Texinfo yields several different problems. 27@c 28@c Because we want to drop out the AC_ part of the macro names in the 29@c printed manual, but not in the other outputs, we need a layer above 30@c the usual @acindex{} etc. That's why we first define indexes such as 31@c acx meant to become the macro @acindex. First of all, using ``ac_'' 32@c does not work with makeinfo, and using ``ac1'' doesn't work with TeX. 33@c So use something more regular ``acx''. Then you finish with a printed 34@c index saying ``index is not existent''. Of course: you ought to use 35@c two letters :( So you use capitals. 36@c 37@c Second, when defining a macro in the TeX world, following spaces are 38@c eaten. But then, since we embed @acxindex commands that use the end 39@c of line as an end marker, the whole things wrecks itself. So make 40@c sure you do *force* an additional end of line, add a ``@c''. 41@c 42@c Finally, you might want to get rid of TeX expansion, using --expand 43@c with texi2dvi. But then you wake up an old problem: we use macros 44@c in @defmac etc. where TeX does perform the expansion, but not makeinfo. 45 46@c Define an environment variable index, for variables users may set 47@c in their environment or on the configure command line. 48@defcodeindex ev 49@c Define an output variable index, for commonly AC_SUBST'ed variables. 50@defcodeindex ov 51@c Define a cache variable index, for variables matching *_cv_*. 52@defcodeindex CA 53@c Other shell variables not fitting the above categories should be 54@c listed in the predefined vrindex, which we merge in the concept index. 55@syncodeindex vr cp 56@c Define a CPP preprocessor macro index, for #define'd strings. 57@defcodeindex cv 58@c Define an Autoconf macro index that @defmac doesn't write to. 59@defcodeindex AC 60@c Define an Autotest macro index that @defmac doesn't write to. 61@defcodeindex AT 62@c Define an M4sugar macro index that @defmac doesn't write to. 63@defcodeindex MS 64@c Define an index for *foreign* programs: `mv' etc. Used for the 65@c portability sections and so on. 66@defindex pr 67 68@c shortindexflag 69@c -------------- 70@c Shall we factor AC_ out of the Autoconf macro index etc.? 71@iftex 72@set shortindexflag 73@end iftex 74 75@c @acindex{MACRO} 76@c --------------- 77@c Registering an AC_\MACRO\. 78@ifset shortindexflag 79@macro acindex{macro} 80@ACindex \macro\ 81@c 82@end macro 83@end ifset 84@ifclear shortindexflag 85@macro acindex{macro} 86@ACindex AC_\macro\ 87@end macro 88@end ifclear 89 90@c @ahindex{MACRO} 91@c --------------- 92@c Registering an AH_\MACRO\. 93@macro ahindex{macro} 94@ACindex AH_\macro\ 95@c 96@end macro 97 98@c @asindex{MACRO} 99@c --------------- 100@c Registering an AS_\MACRO\. 101@ifset shortindexflag 102@macro asindex{macro} 103@MSindex \macro\ 104@c 105@end macro 106@end ifset 107@ifclear shortindexflag 108@macro asindex{macro} 109@MSindex AS_\macro\ 110@end macro 111@end ifclear 112 113@c @atindex{MACRO} 114@c --------------- 115@c Registering an AT_\MACRO\. 116@ifset shortindexflag 117@macro atindex{macro} 118@ATindex \macro\ 119@c 120@end macro 121@end ifset 122@ifclear shortindexflag 123@macro atindex{macro} 124@ATindex AT_\macro\ 125@end macro 126@end ifclear 127 128@c @auindex{MACRO} 129@c --------------- 130@c Registering an AU_\MACRO\. 131@macro auindex{macro} 132@ACindex AU_\macro\ 133@c 134@end macro 135 136@c @hdrindex{MACRO} 137@c ---------------- 138@c Indexing a header. 139@macro hdrindex{macro} 140@prindex @file{\macro\} 141@c 142@end macro 143 144@c @msindex{MACRO} 145@c --------------- 146@c Registering an m4_\MACRO\. 147@ifset shortindexflag 148@macro msindex{macro} 149@MSindex \macro\ 150@c 151@end macro 152@end ifset 153@ifclear shortindexflag 154@macro msindex{macro} 155@MSindex m4_\macro\ 156@end macro 157@end ifclear 158 159 160@c @caindex{VARIABLE} 161@c ------------------ 162@c Registering an ac_cv_\VARIABLE\ cache variable. 163@ifset shortindexflag 164@macro caindex{macro} 165@CAindex \macro\ 166@end macro 167@end ifset 168@ifclear shortindexflag 169@macro caindex{macro} 170@CAindex ac_cv_\macro\ 171@end macro 172@end ifclear 173 174@c Define an index for functions: `alloca' etc. Used for the 175@c portability sections and so on. We can't use `fn' (aka `fnindex), 176@c since `@defmac' goes into it => we'd get all the macros too. 177 178@c FIXME: Aaarg! It seems there are too many indices for TeX :( 179@c 180@c ! No room for a new @write . 181@c l.112 @defcodeindex fu 182@c 183@c so don't define yet another one :( Just put some tags before each 184@c @prindex which is actually a @funindex. 185@c 186@c @defcodeindex fu 187@c 188@c 189@c @c Put the programs and functions into their own index. 190@c @syncodeindex fu pr 191 192@comment %**end of header 193@comment ======================================================== 194 195@copying 196 197This manual (@value{UPDATED}) is for GNU Autoconf 198(version @value{VERSION}), 199a package for creating scripts to configure source code packages using 200templates and an M4 macro package. 201 202Copyright @copyright{} 1992-1996, 1998-2012 Free Software Foundation, 203Inc. 204 205@quotation 206Permission is granted to copy, distribute and/or modify this document 207under the terms of the GNU Free Documentation License, 208Version 1.3 or any later version published by the Free Software 209Foundation; with no Invariant Sections, no Front-Cover texts, and 210no Back-Cover Texts. A copy of the license is included in the section 211entitled ``GNU Free Documentation License.'' 212@end quotation 213@end copying 214 215 216 217@dircategory Programming & development tools 218@direntry 219* Autoconf: (autoconf). Create source code configuration scripts. 220@end direntry 221 222@titlepage 223@title Autoconf 224@subtitle Creating Automatic Configuration Scripts 225@subtitle for version @value{VERSION}, @value{UPDATED} 226@author David MacKenzie 227@author Ben Elliston 228@author Akim Demaille 229@page 230@vskip 0pt plus 1filll 231@insertcopying 232@end titlepage 233 234@contents 235 236 237@ifnottex 238@node Top 239@top Autoconf 240@insertcopying 241@end ifnottex 242 243@c The master menu, created with texinfo-master-menu, goes here. 244 245@menu 246* Introduction:: Autoconf's purpose, strengths, and weaknesses 247* The GNU Build System:: A set of tools for portable software packages 248* Making configure Scripts:: How to organize and produce Autoconf scripts 249* Setup:: Initialization and output 250* Existing Tests:: Macros that check for particular features 251* Writing Tests:: How to write new feature checks 252* Results:: What to do with results from feature checks 253* Programming in M4:: Layers on top of which Autoconf is written 254* Programming in M4sh:: Shell portability layer 255* Writing Autoconf Macros:: Adding new macros to Autoconf 256* Portable Shell:: Shell script portability pitfalls 257* Portable Make:: Makefile portability pitfalls 258* Portable C and C++:: C and C++ portability pitfalls 259* Manual Configuration:: Selecting features that can't be guessed 260* Site Configuration:: Local defaults for @command{configure} 261* Running configure Scripts:: How to use the Autoconf output 262* config.status Invocation:: Recreating a configuration 263* Obsolete Constructs:: Kept for backward compatibility 264* Using Autotest:: Creating portable test suites 265* FAQ:: Frequent Autoconf Questions, with answers 266* History:: History of Autoconf 267* GNU Free Documentation License:: License for copying this manual 268* Indices:: Indices of symbols, concepts, etc. 269 270@detailmenu 271 --- The Detailed Node Listing --- 272 273The GNU Build System 274 275* Automake:: Escaping makefile hell 276* Gnulib:: The GNU portability library 277* Libtool:: Building libraries portably 278* Pointers:: More info on the GNU build system 279 280Making @command{configure} Scripts 281 282* Writing Autoconf Input:: What to put in an Autoconf input file 283* autoscan Invocation:: Semi-automatic @file{configure.ac} writing 284* ifnames Invocation:: Listing the conditionals in source code 285* autoconf Invocation:: How to create configuration scripts 286* autoreconf Invocation:: Remaking multiple @command{configure} scripts 287 288Writing @file{configure.ac} 289 290* Shell Script Compiler:: Autoconf as solution of a problem 291* Autoconf Language:: Programming in Autoconf 292* Autoconf Input Layout:: Standard organization of @file{configure.ac} 293 294Initialization and Output Files 295 296* Initializing configure:: Option processing etc. 297* Versioning:: Dealing with Autoconf versions 298* Notices:: Copyright, version numbers in @command{configure} 299* Input:: Where Autoconf should find files 300* Output:: Outputting results from the configuration 301* Configuration Actions:: Preparing the output based on results 302* Configuration Files:: Creating output files 303* Makefile Substitutions:: Using output variables in makefiles 304* Configuration Headers:: Creating a configuration header file 305* Configuration Commands:: Running arbitrary instantiation commands 306* Configuration Links:: Links depending on the configuration 307* Subdirectories:: Configuring independent packages together 308* Default Prefix:: Changing the default installation prefix 309 310Substitutions in Makefiles 311 312* Preset Output Variables:: Output variables that are always set 313* Installation Directory Variables:: Other preset output variables 314* Changed Directory Variables:: Warnings about @file{datarootdir} 315* Build Directories:: Supporting multiple concurrent compiles 316* Automatic Remaking:: Makefile rules for configuring 317 318Configuration Header Files 319 320* Header Templates:: Input for the configuration headers 321* autoheader Invocation:: How to create configuration templates 322* Autoheader Macros:: How to specify CPP templates 323 324Existing Tests 325 326* Common Behavior:: Macros' standard schemes 327* Alternative Programs:: Selecting between alternative programs 328* Files:: Checking for the existence of files 329* Libraries:: Library archives that might be missing 330* Library Functions:: C library functions that might be missing 331* Header Files:: Header files that might be missing 332* Declarations:: Declarations that may be missing 333* Structures:: Structures or members that might be missing 334* Types:: Types that might be missing 335* Compilers and Preprocessors:: Checking for compiling programs 336* System Services:: Operating system services 337* Posix Variants:: Special kludges for specific Posix variants 338* Erlang Libraries:: Checking for the existence of Erlang libraries 339 340Common Behavior 341 342* Standard Symbols:: Symbols defined by the macros 343* Default Includes:: Includes used by the generic macros 344 345Alternative Programs 346 347* Particular Programs:: Special handling to find certain programs 348* Generic Programs:: How to find other programs 349 350Library Functions 351 352* Function Portability:: Pitfalls with usual functions 353* Particular Functions:: Special handling to find certain functions 354* Generic Functions:: How to find other functions 355 356Header Files 357 358* Header Portability:: Collected knowledge on common headers 359* Particular Headers:: Special handling to find certain headers 360* Generic Headers:: How to find other headers 361 362Declarations 363 364* Particular Declarations:: Macros to check for certain declarations 365* Generic Declarations:: How to find other declarations 366 367Structures 368 369* Particular Structures:: Macros to check for certain structure members 370* Generic Structures:: How to find other structure members 371 372Types 373 374* Particular Types:: Special handling to find certain types 375* Generic Types:: How to find other types 376 377Compilers and Preprocessors 378 379* Specific Compiler Characteristics:: Some portability issues 380* Generic Compiler Characteristics:: Language independent tests and features 381* C Compiler:: Checking its characteristics 382* C++ Compiler:: Likewise 383* Objective C Compiler:: Likewise 384* Objective C++ Compiler:: Likewise 385* Erlang Compiler and Interpreter:: Likewise 386* Fortran Compiler:: Likewise 387* Go Compiler:: Likewise 388 389Writing Tests 390 391* Language Choice:: Selecting which language to use for testing 392* Writing Test Programs:: Forging source files for compilers 393* Running the Preprocessor:: Detecting preprocessor symbols 394* Running the Compiler:: Detecting language or header features 395* Running the Linker:: Detecting library features 396* Runtime:: Testing for runtime features 397* Systemology:: A zoology of operating systems 398* Multiple Cases:: Tests for several possible values 399 400Writing Test Programs 401 402* Guidelines:: General rules for writing test programs 403* Test Functions:: Avoiding pitfalls in test programs 404* Generating Sources:: Source program boilerplate 405 406Results of Tests 407 408* Defining Symbols:: Defining C preprocessor symbols 409* Setting Output Variables:: Replacing variables in output files 410* Special Chars in Variables:: Characters to beware of in variables 411* Caching Results:: Speeding up subsequent @command{configure} runs 412* Printing Messages:: Notifying @command{configure} users 413 414Caching Results 415 416* Cache Variable Names:: Shell variables used in caches 417* Cache Files:: Files @command{configure} uses for caching 418* Cache Checkpointing:: Loading and saving the cache file 419 420Programming in M4 421 422* M4 Quotation:: Protecting macros from unwanted expansion 423* Using autom4te:: The Autoconf executables backbone 424* Programming in M4sugar:: Convenient pure M4 macros 425* Debugging via autom4te:: Figuring out what M4 was doing 426 427M4 Quotation 428 429* Active Characters:: Characters that change the behavior of M4 430* One Macro Call:: Quotation and one macro call 431* Quoting and Parameters:: M4 vs. shell parameters 432* Quotation and Nested Macros:: Macros calling macros 433* Changequote is Evil:: Worse than INTERCAL: M4 + changequote 434* Quadrigraphs:: Another way to escape special characters 435* Balancing Parentheses:: Dealing with unbalanced parentheses 436* Quotation Rule Of Thumb:: One parenthesis, one quote 437 438Using @command{autom4te} 439 440* autom4te Invocation:: A GNU M4 wrapper 441* Customizing autom4te:: Customizing the Autoconf package 442 443Programming in M4sugar 444 445* Redefined M4 Macros:: M4 builtins changed in M4sugar 446* Diagnostic Macros:: Diagnostic messages from M4sugar 447* Diversion support:: Diversions in M4sugar 448* Conditional constructs:: Conditions in M4 449* Looping constructs:: Iteration in M4 450* Evaluation Macros:: More quotation and evaluation control 451* Text processing Macros:: String manipulation in M4 452* Number processing Macros:: Arithmetic computation in M4 453* Set manipulation Macros:: Set manipulation in M4 454* Forbidden Patterns:: Catching unexpanded macros 455 456Programming in M4sh 457 458* Common Shell Constructs:: Portability layer for common shell constructs 459* Polymorphic Variables:: Support for indirect variable names 460* Initialization Macros:: Macros to establish a sane shell environment 461* File Descriptor Macros:: File descriptor macros for input and output 462 463Writing Autoconf Macros 464 465* Macro Definitions:: Basic format of an Autoconf macro 466* Macro Names:: What to call your new macros 467* Reporting Messages:: Notifying @command{autoconf} users 468* Dependencies Between Macros:: What to do when macros depend on other macros 469* Obsoleting Macros:: Warning about old ways of doing things 470* Coding Style:: Writing Autoconf macros @`a la Autoconf 471 472Dependencies Between Macros 473 474* Prerequisite Macros:: Ensuring required information 475* Suggested Ordering:: Warning about possible ordering problems 476* One-Shot Macros:: Ensuring a macro is called only once 477 478Portable Shell Programming 479 480* Shellology:: A zoology of shells 481* Invoking the Shell:: Invoking the shell as a command 482* Here-Documents:: Quirks and tricks 483* File Descriptors:: FDs and redirections 484* Signal Handling:: Shells, signals, and headaches 485* File System Conventions:: File names 486* Shell Pattern Matching:: Pattern matching 487* Shell Substitutions:: Variable and command expansions 488* Assignments:: Varying side effects of assignments 489* Parentheses:: Parentheses in shell scripts 490* Slashes:: Slashes in shell scripts 491* Special Shell Variables:: Variables you should not change 492* Shell Functions:: What to look out for if you use them 493* Limitations of Builtins:: Portable use of not so portable /bin/sh 494* Limitations of Usual Tools:: Portable use of portable tools 495 496Portable Make Programming 497 498* $< in Ordinary Make Rules:: $< in ordinary rules 499* Failure in Make Rules:: Failing portably in rules 500* Special Chars in Names:: Special Characters in Macro Names 501* Backslash-Newline-Empty:: Empty lines after backslash-newline 502* Backslash-Newline Comments:: Spanning comments across line boundaries 503* Long Lines in Makefiles:: Line length limitations 504* Macros and Submakes:: @code{make macro=value} and submakes 505* The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues 506* The Make Macro SHELL:: @code{$(SHELL)} portability issues 507* Parallel Make:: Parallel @command{make} quirks 508* Comments in Make Rules:: Other problems with Make comments 509* Newlines in Make Rules:: Using literal newlines in rules 510* Comments in Make Macros:: Other problems with Make comments in macros 511* Trailing whitespace in Make Macros:: Macro substitution problems 512* Command-line Macros and whitespace:: Whitespace trimming of values 513* obj/ and Make:: Don't name a subdirectory @file{obj} 514* make -k Status:: Exit status of @samp{make -k} 515* VPATH and Make:: @code{VPATH} woes 516* Single Suffix Rules:: Single suffix rules and separated dependencies 517* Timestamps and Make:: Subsecond timestamp resolution 518 519@code{VPATH} and Make 520 521* Variables listed in VPATH:: @code{VPATH} must be literal on ancient hosts 522* VPATH and Double-colon:: Problems with @samp{::} on ancient hosts 523* $< in Explicit Rules:: @code{$<} does not work in ordinary rules 524* Automatic Rule Rewriting:: @code{VPATH} goes wild on Solaris 525* Tru64 Directory Magic:: @command{mkdir} goes wild on Tru64 526* Make Target Lookup:: More details about @code{VPATH} lookup 527 528Portable C and C++ Programming 529 530* Varieties of Unportability:: How to make your programs unportable 531* Integer Overflow:: When integers get too large 532* Preprocessor Arithmetic:: @code{#if} expression problems 533* Null Pointers:: Properties of null pointers 534* Buffer Overruns:: Subscript errors and the like 535* Volatile Objects:: @code{volatile} and signals 536* Floating Point Portability:: Portable floating-point arithmetic 537* Exiting Portably:: Exiting and the exit status 538 539Integer Overflow 540 541* Integer Overflow Basics:: Why integer overflow is a problem 542* Signed Overflow Examples:: Examples of code assuming wraparound 543* Optimization and Wraparound:: Optimizations that break uses of wraparound 544* Signed Overflow Advice:: Practical advice for signed overflow issues 545* Signed Integer Division:: @code{INT_MIN / -1} and @code{INT_MIN % -1} 546 547Manual Configuration 548 549* Specifying Target Triplets:: Specifying target triplets 550* Canonicalizing:: Getting the canonical system type 551* Using System Type:: What to do with the system type 552 553Site Configuration 554 555* Help Formatting:: Customizing @samp{configure --help} 556* External Software:: Working with other optional software 557* Package Options:: Selecting optional features 558* Pretty Help Strings:: Formatting help string 559* Option Checking:: Controlling checking of @command{configure} options 560* Site Details:: Configuring site details 561* Transforming Names:: Changing program names when installing 562* Site Defaults:: Giving @command{configure} local defaults 563 564Transforming Program Names When Installing 565 566* Transformation Options:: @command{configure} options to transform names 567* Transformation Examples:: Sample uses of transforming names 568* Transformation Rules:: Makefile uses of transforming names 569 570Running @command{configure} Scripts 571 572* Basic Installation:: Instructions for typical cases 573* Compilers and Options:: Selecting compilers and optimization 574* Multiple Architectures:: Compiling for multiple architectures at once 575* Installation Names:: Installing in different directories 576* Optional Features:: Selecting optional features 577* Particular Systems:: Particular systems 578* System Type:: Specifying the system type 579* Sharing Defaults:: Setting site-wide defaults for @command{configure} 580* Defining Variables:: Specifying the compiler etc. 581* configure Invocation:: Changing how @command{configure} runs 582 583Obsolete Constructs 584 585* Obsolete config.status Use:: Obsolete convention for @command{config.status} 586* acconfig Header:: Additional entries in @file{config.h.in} 587* autoupdate Invocation:: Automatic update of @file{configure.ac} 588* Obsolete Macros:: Backward compatibility macros 589* Autoconf 1:: Tips for upgrading your files 590* Autoconf 2.13:: Some fresher tips 591 592Upgrading From Version 1 593 594* Changed File Names:: Files you might rename 595* Changed Makefiles:: New things to put in @file{Makefile.in} 596* Changed Macros:: Macro calls you might replace 597* Changed Results:: Changes in how to check test results 598* Changed Macro Writing:: Better ways to write your own macros 599 600Upgrading From Version 2.13 601 602* Changed Quotation:: Broken code which used to work 603* New Macros:: Interaction with foreign macros 604* Hosts and Cross-Compilation:: Bugward compatibility kludges 605* AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token 606* AC_ACT_IFELSE vs AC_TRY_ACT:: A more generic scheme for testing sources 607 608Generating Test Suites with Autotest 609 610* Using an Autotest Test Suite:: Autotest and the user 611* Writing Testsuites:: Autotest macros 612* testsuite Invocation:: Running @command{testsuite} scripts 613* Making testsuite Scripts:: Using autom4te to create @command{testsuite} 614 615Using an Autotest Test Suite 616 617* testsuite Scripts:: The concepts of Autotest 618* Autotest Logs:: Their contents 619 620Frequent Autoconf Questions, with answers 621 622* Distributing:: Distributing @command{configure} scripts 623* Why GNU M4:: Why not use the standard M4? 624* Bootstrapping:: Autoconf and GNU M4 require each other? 625* Why Not Imake:: Why GNU uses @command{configure} instead of Imake 626* Defining Directories:: Passing @code{datadir} to program 627* Autom4te Cache:: What is it? Can I remove it? 628* Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree 629* Expanded Before Required:: Expanded Before Required 630* Debugging:: Debugging @command{configure} scripts 631 632History of Autoconf 633 634* Genesis:: Prehistory and naming of @command{configure} 635* Exodus:: The plagues of M4 and Perl 636* Leviticus:: The priestly code of portability arrives 637* Numbers:: Growth and contributors 638* Deuteronomy:: Approaching the promises of easy configuration 639 640Indices 641 642* Environment Variable Index:: Index of environment variables used 643* Output Variable Index:: Index of variables set in output files 644* Preprocessor Symbol Index:: Index of C preprocessor symbols defined 645* Cache Variable Index:: Index of documented cache variables 646* Autoconf Macro Index:: Index of Autoconf macros 647* M4 Macro Index:: Index of M4, M4sugar, and M4sh macros 648* Autotest Macro Index:: Index of Autotest macros 649* Program & Function Index:: Index of those with portability problems 650* Concept Index:: General index 651 652@end detailmenu 653@end menu 654 655@c ============================================================= Introduction. 656 657@node Introduction 658@chapter Introduction 659@cindex Introduction 660 661@flushright 662A physicist, an engineer, and a computer scientist were discussing the 663nature of God. ``Surely a Physicist,'' said the physicist, ``because 664early in the Creation, God made Light; and you know, Maxwell's 665equations, the dual nature of electromagnetic waves, the relativistic 666consequences@enddots{}'' ``An Engineer!,'' said the engineer, ``because 667before making Light, God split the Chaos into Land and Water; it takes a 668hell of an engineer to handle that big amount of mud, and orderly 669separation of solids from liquids@enddots{}'' The computer scientist 670shouted: ``And the Chaos, where do you think it was coming from, hmm?'' 671 672---Anonymous 673@end flushright 674@c (via Franc,ois Pinard) 675 676Autoconf is a tool for producing shell scripts that automatically 677configure software source code packages to adapt to many kinds of 678Posix-like systems. The configuration scripts produced by Autoconf 679are independent of Autoconf when they are run, so their users do not 680need to have Autoconf. 681 682The configuration scripts produced by Autoconf require no manual user 683intervention when run; they do not normally even need an argument 684specifying the system type. Instead, they individually test for the 685presence of each feature that the software package they are for might need. 686(Before each check, they print a one-line message stating what they are 687checking for, so the user doesn't get too bored while waiting for the 688script to finish.) As a result, they deal well with systems that are 689hybrids or customized from the more common Posix variants. There is 690no need to maintain files that list the features supported by each 691release of each variant of Posix. 692 693For each software package that Autoconf is used with, it creates a 694configuration script from a template file that lists the system features 695that the package needs or can use. After the shell code to recognize 696and respond to a system feature has been written, Autoconf allows it to 697be shared by many software packages that can use (or need) that feature. 698If it later turns out that the shell code needs adjustment for some 699reason, it needs to be changed in only one place; all of the 700configuration scripts can be regenerated automatically to take advantage 701of the updated code. 702 703@c "Those who do not understand Unix are condemned to reinvent it, poorly." 704@c --Henry Spencer, 1987 (see http://en.wikipedia.org/wiki/Unix_philosophy) 705Those who do not understand Autoconf are condemned to reinvent it, poorly. 706The primary goal of Autoconf is making the @emph{user's} life easier; 707making the @emph{maintainer's} life easier is only a secondary goal. 708Put another way, the primary goal is not to make the generation of 709@file{configure} automatic for package maintainers (although patches 710along that front are welcome, since package maintainers form the user 711base of Autoconf); rather, the goal is to make @file{configure} 712painless, portable, and predictable for the end user of each 713@dfn{autoconfiscated} package. And to this degree, Autoconf is highly 714successful at its goal --- most complaints to the Autoconf list are 715about difficulties in writing Autoconf input, and not in the behavior of 716the resulting @file{configure}. Even packages that don't use Autoconf 717will generally provide a @file{configure} script, and the most common 718complaint about these alternative home-grown scripts is that they fail 719to meet one or more of the GNU Coding Standards (@pxref{Configuration, , , 720standards, The GNU Coding Standards}) that users 721have come to expect from Autoconf-generated @file{configure} scripts. 722 723The Metaconfig package is similar in purpose to Autoconf, but the 724scripts it produces require manual user intervention, which is quite 725inconvenient when configuring large source trees. Unlike Metaconfig 726scripts, Autoconf scripts can support cross-compiling, if some care is 727taken in writing them. 728 729Autoconf does not solve all problems related to making portable 730software packages---for a more complete solution, it should be used in 731concert with other GNU build tools like Automake and 732Libtool. These other tools take on jobs like the creation of a 733portable, recursive makefile with all of the standard targets, 734linking of shared libraries, and so on. @xref{The GNU Build System}, 735for more information. 736 737Autoconf imposes some restrictions on the names of macros used with 738@code{#if} in C programs (@pxref{Preprocessor Symbol Index}). 739 740Autoconf requires GNU M4 version 1.4.6 or later in order to 741generate the scripts. It uses features that some versions of M4, 742including GNU M4 1.3, do not have. Autoconf works better 743with GNU M4 version 1.4.14 or later, though this is not 744required. 745 746@xref{Autoconf 1}, for information about upgrading from version 1. 747@xref{History}, for the story of Autoconf's development. @xref{FAQ}, 748for answers to some common questions about Autoconf. 749 750See the @uref{http://@/www.gnu.org/@/software/@/autoconf/, 751Autoconf web page} for up-to-date information, details on the mailing 752lists, pointers to a list of known bugs, etc. 753 754Mail suggestions to @email{autoconf@@gnu.org, the Autoconf mailing 755list}. Past suggestions are 756@uref{http://@/lists.gnu.org/@/archive/@/html/@/autoconf/, archived}. 757 758Mail bug reports to @email{bug-autoconf@@gnu.org, the 759Autoconf Bugs mailing list}. Past bug reports are 760@uref{http://@/lists.gnu.org/@/archive/@/html/@/bug-autoconf/, archived}. 761 762If possible, first check that your bug is 763not already solved in current development versions, and that it has not 764been reported yet. Be sure to include all the needed information and a 765short @file{configure.ac} that demonstrates the problem. 766 767Autoconf's development tree is accessible via @command{git}; see the 768@uref{http://@/savannah.gnu.org/@/projects/@/autoconf/, Autoconf 769Summary} for details, or view 770@uref{http://@/git.sv.gnu.org/@/gitweb/@/?p=autoconf.git, the actual 771repository}. Anonymous CVS access is also available, see 772@file{README} for more details. Patches relative to the 773current @command{git} version can be sent for review to the 774@email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}, with 775discussion on prior patches 776@uref{http://@/lists.gnu.org/@/archive/@/html/@/autoconf-@/patches/, 777archived}; and all commits are posted in the read-only 778@email{autoconf-commit@@gnu.org, Autoconf Commit mailing list}, which is 779also @uref{http://@/lists.gnu.org/@/archive/@/html/@/autoconf-commit/, 780archived}. 781 782Because of its mission, the Autoconf package itself 783includes only a set of often-used 784macros that have already demonstrated their usefulness. Nevertheless, 785if you wish to share your macros, or find existing ones, see the 786@uref{http://@/www.gnu.org/@/software/@/autoconf-archive/, Autoconf Macro 787Archive}, which is kindly run by @email{simons@@cryp.to, 788Peter Simons}. 789 790 791@c ================================================= The GNU Build System 792 793@node The GNU Build System 794@chapter The GNU Build System 795@cindex GNU build system 796 797Autoconf solves an important problem---reliable discovery of 798system-specific build and runtime information---but this is only one 799piece of the puzzle for the development of portable software. To this 800end, the GNU project has developed a suite of integrated 801utilities to finish the job Autoconf started: the GNU build 802system, whose most important components are Autoconf, Automake, and 803Libtool. In this chapter, we introduce you to those tools, point you 804to sources of more information, and try to convince you to use the 805entire GNU build system for your software. 806 807@menu 808* Automake:: Escaping makefile hell 809* Gnulib:: The GNU portability library 810* Libtool:: Building libraries portably 811* Pointers:: More info on the GNU build system 812@end menu 813 814@node Automake 815@section Automake 816 817The ubiquity of @command{make} means that a makefile is almost the 818only viable way to distribute automatic build rules for software, but 819one quickly runs into its numerous limitations. Its lack of 820support for automatic dependency tracking, recursive builds in 821subdirectories, reliable timestamps (e.g., for network file systems), and 822so on, mean that developers must painfully (and often incorrectly) 823reinvent the wheel for each project. Portability is non-trivial, thanks 824to the quirks of @command{make} on many systems. On top of all this is the 825manual labor required to implement the many standard targets that users 826have come to expect (@code{make install}, @code{make distclean}, 827@code{make uninstall}, etc.). Since you are, of course, using Autoconf, 828you also have to insert repetitive code in your @file{Makefile.in} to 829recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions 830provided by @command{configure}. Into this mess steps @dfn{Automake}. 831@cindex Automake 832 833Automake allows you to specify your build needs in a @file{Makefile.am} 834file with a vastly simpler and more powerful syntax than that of a plain 835makefile, and then generates a portable @file{Makefile.in} for 836use with Autoconf. For example, the @file{Makefile.am} to build and 837install a simple ``Hello world'' program might look like: 838 839@example 840bin_PROGRAMS = hello 841hello_SOURCES = hello.c 842@end example 843 844@noindent 845The resulting @file{Makefile.in} (~400 lines) automatically supports all 846the standard targets, the substitutions provided by Autoconf, automatic 847dependency tracking, @code{VPATH} building, and so on. @command{make} 848builds the @code{hello} program, and @code{make install} installs it 849in @file{/usr/local/bin} (or whatever prefix was given to 850@command{configure}, if not @file{/usr/local}). 851 852The benefits of Automake increase for larger packages (especially ones 853with subdirectories), but even for small programs the added convenience 854and portability can be substantial. And that's not all@enddots{} 855 856@node Gnulib 857@section Gnulib 858 859GNU software has a well-deserved reputation for running on 860many different types of systems. While our primary goal is to write 861software for the GNU system, many users and developers have 862been introduced to us through the systems that they were already using. 863 864@cindex Gnulib 865Gnulib is a central location for common GNU code, intended to 866be shared among free software packages. Its components are typically 867shared at the source level, rather than being a library that gets built, 868installed, and linked against. The idea is to copy files from Gnulib 869into your own source tree. There is no distribution tarball; developers 870should just grab source modules from the repository. The source files 871are available online, under various licenses, mostly GNU 872GPL or GNU LGPL. 873 874Gnulib modules typically contain C source code along with Autoconf 875macros used to configure the source code. For example, the Gnulib 876@code{stdbool} module implements a @file{stdbool.h} header that nearly 877conforms to C99, even on old-fashioned hosts that lack @file{stdbool.h}. 878This module contains a source file for the replacement header, along 879with an Autoconf macro that arranges to use the replacement header on 880old-fashioned systems. 881 882@node Libtool 883@section Libtool 884 885Often, one wants to build not only programs, but libraries, so that 886other programs can benefit from the fruits of your labor. Ideally, one 887would like to produce @emph{shared} (dynamically linked) libraries, 888which can be used by multiple programs without duplication on disk or in 889memory and can be updated independently of the linked programs. 890Producing shared libraries portably, however, is the stuff of 891nightmares---each system has its own incompatible tools, compiler flags, 892and magic incantations. Fortunately, GNU provides a solution: 893@dfn{Libtool}. 894@cindex Libtool 895 896Libtool handles all the requirements of building shared libraries for 897you, and at this time seems to be the @emph{only} way to do so with any 898portability. It also handles many other headaches, such as: the 899interaction of Make rules with the variable suffixes of 900shared libraries, linking reliably with shared libraries before they are 901installed by the superuser, and supplying a consistent versioning system 902(so that different versions of a library can be installed or upgraded 903without breaking binary compatibility). Although Libtool, like 904Autoconf, can be used without Automake, it is most simply utilized in 905conjunction with Automake---there, Libtool is used automatically 906whenever shared libraries are needed, and you need not know its syntax. 907 908@node Pointers 909@section Pointers 910 911Developers who are used to the simplicity of @command{make} for small 912projects on a single system might be daunted at the prospect of 913learning to use Automake and Autoconf. As your software is 914distributed to more and more users, however, you otherwise 915quickly find yourself putting lots of effort into reinventing the 916services that the GNU build tools provide, and making the 917same mistakes that they once made and overcame. (Besides, since 918you're already learning Autoconf, Automake is a piece of cake.) 919 920There are a number of places that you can go to for more information on 921the GNU build tools. 922 923@itemize @minus 924 925@item Web 926 927The project home pages for 928@uref{http://@/www@/.gnu@/.org/@/software/@/autoconf/, Autoconf}, 929@uref{http://@/www@/.gnu@/.org/@/software/@/automake/, Automake}, 930@uref{http://@/www@/.gnu@/.org/@/software/@/gnulib/, Gnulib}, and 931@uref{http://@/www@/.gnu@/.org/@/software/@/libtool/, Libtool}. 932 933@item Automake Manual 934 935@xref{Top, , Automake, automake, GNU Automake}, for more 936information on Automake. 937 938@item Books 939 940The book @cite{GNU Autoconf, Automake and 941Libtool}@footnote{@cite{GNU Autoconf, Automake and Libtool}, 942by G. V. Vaughan, B. Elliston, T. Tromey, and I. L. Taylor. SAMS (originally 943New Riders), 2000, ISBN 1578701902.} describes the complete GNU 944build environment. You can also find 945@uref{http://@/sources.redhat.com/@/autobook/, the entire book on-line}. 946 947@end itemize 948 949@c ================================================= Making configure Scripts. 950 951@node Making configure Scripts 952@chapter Making @command{configure} Scripts 953@cindex @file{aclocal.m4} 954@cindex @command{configure} 955 956The configuration scripts that Autoconf produces are by convention 957called @command{configure}. When run, @command{configure} creates several 958files, replacing configuration parameters in them with appropriate 959values. The files that @command{configure} creates are: 960 961@itemize @minus 962@item 963one or more @file{Makefile} files, usually one in each subdirectory of the 964package (@pxref{Makefile Substitutions}); 965 966@item 967optionally, a C header file, the name of which is configurable, 968containing @code{#define} directives (@pxref{Configuration Headers}); 969 970@item 971a shell script called @file{config.status} that, when run, recreates 972the files listed above (@pxref{config.status Invocation}); 973 974@item 975an optional shell script normally called @file{config.cache} 976(created when using @samp{configure --config-cache}) that 977saves the results of running many of the tests (@pxref{Cache Files}); 978 979@item 980a file called @file{config.log} containing any messages produced by 981compilers, to help debugging if @command{configure} makes a mistake. 982@end itemize 983 984@cindex @file{configure.in} 985@cindex @file{configure.ac} 986To create a @command{configure} script with Autoconf, you need to write an 987Autoconf input file @file{configure.ac} (or @file{configure.in}) and run 988@command{autoconf} on it. If you write your own feature tests to 989supplement those that come with Autoconf, you might also write files 990called @file{aclocal.m4} and @file{acsite.m4}. If you use a C header 991file to contain @code{#define} directives, you might also run 992@command{autoheader}, and you can distribute the generated file 993@file{config.h.in} with the package. 994 995Here is a diagram showing how the files that can be used in 996configuration are produced. Programs that are executed are suffixed by 997@samp{*}. Optional files are enclosed in square brackets (@samp{[]}). 998@command{autoconf} and @command{autoheader} also read the installed Autoconf 999macro files (by reading @file{autoconf.m4}). 1000 1001@noindent 1002Files used in preparing a software package for distribution, when using 1003just Autoconf: 1004@example 1005your source files --> [autoscan*] --> [configure.scan] --> configure.ac 1006 1007@group 1008configure.ac --. 1009 | .------> autoconf* -----> configure 1010[aclocal.m4] --+---+ 1011 | `-----> [autoheader*] --> [config.h.in] 1012[acsite.m4] ---' 1013@end group 1014 1015Makefile.in 1016@end example 1017 1018@noindent 1019Additionally, if you use Automake, the following additional productions 1020come into play: 1021 1022@example 1023@group 1024[acinclude.m4] --. 1025 | 1026[local macros] --+--> aclocal* --> aclocal.m4 1027 | 1028configure.ac ----' 1029@end group 1030 1031@group 1032configure.ac --. 1033 +--> automake* --> Makefile.in 1034Makefile.am ---' 1035@end group 1036@end example 1037 1038@noindent 1039Files used in configuring a software package: 1040@example 1041@group 1042 .-------------> [config.cache] 1043configure* ------------+-------------> config.log 1044 | 1045[config.h.in] -. v .-> [config.h] -. 1046 +--> config.status* -+ +--> make* 1047Makefile.in ---' `-> Makefile ---' 1048@end group 1049@end example 1050 1051@menu 1052* Writing Autoconf Input:: What to put in an Autoconf input file 1053* autoscan Invocation:: Semi-automatic @file{configure.ac} writing 1054* ifnames Invocation:: Listing the conditionals in source code 1055* autoconf Invocation:: How to create configuration scripts 1056* autoreconf Invocation:: Remaking multiple @command{configure} scripts 1057@end menu 1058 1059@node Writing Autoconf Input 1060@section Writing @file{configure.ac} 1061 1062To produce a @command{configure} script for a software package, create a 1063file called @file{configure.ac} that contains invocations of the 1064Autoconf macros that test the system features your package needs or can 1065use. Autoconf macros already exist to check for many features; see 1066@ref{Existing Tests}, for their descriptions. For most other features, 1067you can use Autoconf template macros to produce custom checks; see 1068@ref{Writing Tests}, for information about them. For especially tricky 1069or specialized features, @file{configure.ac} might need to contain some 1070hand-crafted shell commands; see @ref{Portable Shell, , Portable Shell 1071Programming}. The @command{autoscan} program can give you a good start 1072in writing @file{configure.ac} (@pxref{autoscan Invocation}, for more 1073information). 1074 1075Previous versions of Autoconf promoted the name @file{configure.in}, 1076which is somewhat ambiguous (the tool needed to process this file is not 1077described by its extension), and introduces a slight confusion with 1078@file{config.h.in} and so on (for which @samp{.in} means ``to be 1079processed by @command{configure}''). Using @file{configure.ac} is now 1080preferred. 1081 1082@menu 1083* Shell Script Compiler:: Autoconf as solution of a problem 1084* Autoconf Language:: Programming in Autoconf 1085* Autoconf Input Layout:: Standard organization of @file{configure.ac} 1086@end menu 1087 1088@node Shell Script Compiler 1089@subsection A Shell Script Compiler 1090 1091Just as for any other computer language, in order to properly program 1092@file{configure.ac} in Autoconf you must understand @emph{what} problem 1093the language tries to address and @emph{how} it does so. 1094 1095The problem Autoconf addresses is that the world is a mess. After all, 1096you are using Autoconf in order to have your package compile easily on 1097all sorts of different systems, some of them being extremely hostile. 1098Autoconf itself bears the price for these differences: @command{configure} 1099must run on all those systems, and thus @command{configure} must limit itself 1100to their lowest common denominator of features. 1101 1102Naturally, you might then think of shell scripts; who needs 1103@command{autoconf}? A set of properly written shell functions is enough to 1104make it easy to write @command{configure} scripts by hand. Sigh! 1105Unfortunately, even in 2008, where shells without any function support are 1106far and few between, there are pitfalls to avoid when making use of them. 1107Also, finding a Bourne shell that accepts shell functions is not trivial, 1108even though there is almost always one on interesting porting targets. 1109 1110So, what is really needed is some kind of compiler, @command{autoconf}, 1111that takes an Autoconf program, @file{configure.ac}, and transforms it 1112into a portable shell script, @command{configure}. 1113 1114How does @command{autoconf} perform this task? 1115 1116There are two obvious possibilities: creating a brand new language or 1117extending an existing one. The former option is attractive: all 1118sorts of optimizations could easily be implemented in the compiler and 1119many rigorous checks could be performed on the Autoconf program 1120(e.g., rejecting any non-portable construct). Alternatively, you can 1121extend an existing language, such as the @code{sh} (Bourne shell) 1122language. 1123 1124Autoconf does the latter: it is a layer on top of @code{sh}. It was 1125therefore most convenient to implement @command{autoconf} as a macro 1126expander: a program that repeatedly performs @dfn{macro expansions} on 1127text input, replacing macro calls with macro bodies and producing a pure 1128@code{sh} script in the end. Instead of implementing a dedicated 1129Autoconf macro expander, it is natural to use an existing 1130general-purpose macro language, such as M4, and implement the extensions 1131as a set of M4 macros. 1132 1133 1134@node Autoconf Language 1135@subsection The Autoconf Language 1136@cindex quotation 1137 1138The Autoconf language differs from many other computer 1139languages because it treats actual code the same as plain text. Whereas 1140in C, for instance, data and instructions have different syntactic 1141status, in Autoconf their status is rigorously the same. Therefore, we 1142need a means to distinguish literal strings from text to be expanded: 1143quotation. 1144 1145When calling macros that take arguments, there must not be any white 1146space between the macro name and the open parenthesis. 1147 1148@example 1149AC_INIT ([oops], [1.0]) # incorrect 1150AC_INIT([hello], [1.0]) # good 1151@end example 1152 1153Arguments should 1154be enclosed within the quote characters @samp{[} and @samp{]}, and be 1155separated by commas. Any leading blanks or newlines in arguments are ignored, 1156unless they are quoted. You should always quote an argument that 1157might contain a macro name, comma, parenthesis, or a leading blank or 1158newline. This rule applies recursively for every macro 1159call, including macros called from other macros. For more details on 1160quoting rules, see @ref{Programming in M4}. 1161 1162For instance: 1163 1164@example 1165AC_CHECK_HEADER([stdio.h], 1166 [AC_DEFINE([HAVE_STDIO_H], [1], 1167 [Define to 1 if you have <stdio.h>.])], 1168 [AC_MSG_ERROR([sorry, can't do anything for you])]) 1169@end example 1170 1171@noindent 1172is quoted properly. You may safely simplify its quotation to: 1173 1174@example 1175AC_CHECK_HEADER([stdio.h], 1176 [AC_DEFINE([HAVE_STDIO_H], 1, 1177 [Define to 1 if you have <stdio.h>.])], 1178 [AC_MSG_ERROR([sorry, can't do anything for you])]) 1179@end example 1180 1181@noindent 1182because @samp{1} cannot contain a macro call. Here, the argument of 1183@code{AC_MSG_ERROR} must be quoted; otherwise, its comma would be 1184interpreted as an argument separator. Also, the second and third arguments 1185of @samp{AC_CHECK_HEADER} must be quoted, since they contain 1186macro calls. The three arguments @samp{HAVE_STDIO_H}, @samp{stdio.h}, 1187and @samp{Define to 1 if you have <stdio.h>.} do not need quoting, but 1188if you unwisely defined a macro with a name like @samp{Define} or 1189@samp{stdio} then they would need quoting. Cautious Autoconf users 1190would keep the quotes, but many Autoconf users find such precautions 1191annoying, and would rewrite the example as follows: 1192 1193@example 1194AC_CHECK_HEADER(stdio.h, 1195 [AC_DEFINE(HAVE_STDIO_H, 1, 1196 [Define to 1 if you have <stdio.h>.])], 1197 [AC_MSG_ERROR([sorry, can't do anything for you])]) 1198@end example 1199 1200@noindent 1201This is safe, so long as you adopt good naming conventions and do not 1202define macros with names like @samp{HAVE_STDIO_H}, @samp{stdio}, or 1203@samp{h}. Though it is also safe here to omit the quotes around 1204@samp{Define to 1 if you have <stdio.h>.} this is not recommended, as 1205message strings are more likely to inadvertently contain commas. 1206 1207The following example is wrong and dangerous, as it is underquoted: 1208 1209@example 1210AC_CHECK_HEADER(stdio.h, 1211 AC_DEFINE(HAVE_STDIO_H, 1, 1212 Define to 1 if you have <stdio.h>.), 1213 AC_MSG_ERROR([sorry, can't do anything for you])) 1214@end example 1215 1216In other cases, you may have to use text that also resembles a macro 1217call. You must quote that text even when it is not passed as a macro 1218argument. For example, these two approaches in @file{configure.ac} 1219(quoting just the potential problems, or quoting the entire line) will 1220protect your script in case autoconf ever adds a macro @code{AC_DC}: 1221 1222@example 1223echo "Hard rock was here! --[AC_DC]" 1224[echo "Hard rock was here! --AC_DC"] 1225@end example 1226 1227@noindent 1228which results in this text in @file{configure}: 1229 1230@example 1231echo "Hard rock was here! --AC_DC" 1232echo "Hard rock was here! --AC_DC" 1233@end example 1234 1235@noindent 1236When you use the same text in a macro argument, you must therefore have 1237an extra quotation level (since one is stripped away by the macro 1238substitution). In general, then, it is a good idea to @emph{use double 1239quoting for all literal string arguments}, either around just the 1240problematic portions, or over the entire argument: 1241 1242@example 1243AC_MSG_WARN([[AC_DC] stinks --Iron Maiden]) 1244AC_MSG_WARN([[AC_DC stinks --Iron Maiden]]) 1245@end example 1246 1247However, the above example triggers a warning about a possibly 1248unexpanded macro when running @command{autoconf}, because it collides 1249with the namespace of macros reserved for the Autoconf language. To be 1250really safe, you can use additional escaping (either a quadrigraph, or 1251creative shell constructs) to silence that particular warning: 1252 1253@example 1254echo "Hard rock was here! --AC""_DC" 1255AC_MSG_WARN([[AC@@&t@@_DC stinks --Iron Maiden]]) 1256@end example 1257 1258You are now able to understand one of the constructs of Autoconf that 1259has been continually misunderstood@enddots{} The rule of thumb is that 1260@emph{whenever you expect macro expansion, expect quote expansion}; 1261i.e., expect one level of quotes to be lost. For instance: 1262 1263@example 1264AC_COMPILE_IFELSE(AC_LANG_SOURCE([char b[10];]), [], 1265 [AC_MSG_ERROR([you lose])]) 1266@end example 1267 1268@noindent 1269is incorrect: here, the first argument of @code{AC_LANG_SOURCE} is 1270@samp{char b[10];} and is expanded once, which results in 1271@samp{char b10;}; and the @code{AC_LANG_SOURCE} is also expanded prior 1272to being passed to @code{AC_COMPILE_IFELSE}. (There was an idiom common 1273in Autoconf's past to 1274address this issue via the M4 @code{changequote} primitive, but do not 1275use it!) Let's take a closer look: the author meant the first argument 1276to be understood as a literal, and therefore it must be quoted twice; 1277likewise, the intermediate @code{AC_LANG_SOURCE} macro should be quoted 1278once so that it is only expanded after the rest of the body of 1279@code{AC_COMPILE_IFELSE} is in place: 1280 1281@example 1282AC_COMPILE_IFELSE([AC_LANG_SOURCE([[char b[10];]])], [], 1283 [AC_MSG_ERROR([you lose])]) 1284@end example 1285 1286@noindent 1287Voil@`a, you actually produce @samp{char b[10];} this time! 1288 1289On the other hand, descriptions (e.g., the last parameter of 1290@code{AC_DEFINE} or @code{AS_HELP_STRING}) are not literals---they 1291are subject to line breaking, for example---and should not be double quoted. 1292Even if these descriptions are short and are not actually broken, double 1293quoting them yields weird results. 1294 1295Some macros take optional arguments, which this documentation represents 1296as @ovar{arg} (not to be confused with the quote characters). You may 1297just leave them empty, or use @samp{[]} to make the emptiness of the 1298argument explicit, or you may simply omit the trailing commas. The 1299three lines below are equivalent: 1300 1301@example 1302AC_CHECK_HEADERS([stdio.h], [], [], []) 1303AC_CHECK_HEADERS([stdio.h],,,) 1304AC_CHECK_HEADERS([stdio.h]) 1305@end example 1306 1307It is best to put each macro call on its own line in 1308@file{configure.ac}. Most of the macros don't add extra newlines; they 1309rely on the newline after the macro call to terminate the commands. 1310This approach makes the generated @command{configure} script a little 1311easier to read by not inserting lots of blank lines. It is generally 1312safe to set shell variables on the same line as a macro call, because 1313the shell allows assignments without intervening newlines. 1314 1315You can include comments in @file{configure.ac} files by starting them 1316with the @samp{#}. For example, it is helpful to begin 1317@file{configure.ac} files with a line like this: 1318 1319@example 1320# Process this file with autoconf to produce a configure script. 1321@end example 1322 1323@node Autoconf Input Layout 1324@subsection Standard @file{configure.ac} Layout 1325 1326The order in which @file{configure.ac} calls the Autoconf macros is not 1327important, with a few exceptions. Every @file{configure.ac} must 1328contain a call to @code{AC_INIT} before the checks, and a call to 1329@code{AC_OUTPUT} at the end (@pxref{Output}). Additionally, some macros 1330rely on other macros having been called first, because they check 1331previously set values of some variables to decide what to do. These 1332macros are noted in the individual descriptions (@pxref{Existing 1333Tests}), and they also warn you when @command{configure} is created if they 1334are called out of order. 1335 1336To encourage consistency, here is a suggested order for calling the 1337Autoconf macros. Generally speaking, the things near the end of this 1338list are those that could depend on things earlier in it. For example, 1339library functions could be affected by types and libraries. 1340 1341@display 1342@group 1343Autoconf requirements 1344@code{AC_INIT(@var{package}, @var{version}, @var{bug-report-address})} 1345information on the package 1346checks for programs 1347checks for libraries 1348checks for header files 1349checks for types 1350checks for structures 1351checks for compiler characteristics 1352checks for library functions 1353checks for system services 1354@code{AC_CONFIG_FILES(@r{[}@var{file@dots{}}@r{]})} 1355@code{AC_OUTPUT} 1356@end group 1357@end display 1358 1359 1360@node autoscan Invocation 1361@section Using @command{autoscan} to Create @file{configure.ac} 1362@cindex @command{autoscan} 1363 1364The @command{autoscan} program can help you create and/or maintain a 1365@file{configure.ac} file for a software package. @command{autoscan} 1366examines source files in the directory tree rooted at a directory given 1367as a command line argument, or the current directory if none is given. 1368It searches the source files for common portability problems and creates 1369a file @file{configure.scan} which is a preliminary @file{configure.ac} 1370for that package, and checks a possibly existing @file{configure.ac} for 1371completeness. 1372 1373When using @command{autoscan} to create a @file{configure.ac}, you 1374should manually examine @file{configure.scan} before renaming it to 1375@file{configure.ac}; it probably needs some adjustments. 1376Occasionally, @command{autoscan} outputs a macro in the wrong order 1377relative to another macro, so that @command{autoconf} produces a warning; 1378you need to move such macros manually. Also, if you want the package to 1379use a configuration header file, you must add a call to 1380@code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}). You might 1381also have to change or add some @code{#if} directives to your program in 1382order to make it work with Autoconf (@pxref{ifnames Invocation}, for 1383information about a program that can help with that job). 1384 1385When using @command{autoscan} to maintain a @file{configure.ac}, simply 1386consider adding its suggestions. The file @file{autoscan.log} 1387contains detailed information on why a macro is requested. 1388 1389@command{autoscan} uses several data files (installed along with Autoconf) 1390to determine which macros to output when it finds particular symbols in 1391a package's source files. These data files all have the same format: 1392each line consists of a symbol, one or more blanks, and the Autoconf macro to 1393output if that symbol is encountered. Lines starting with @samp{#} are 1394comments. 1395 1396@command{autoscan} accepts the following options: 1397 1398@table @option 1399@item --help 1400@itemx -h 1401Print a summary of the command line options and exit. 1402 1403@item --version 1404@itemx -V 1405Print the version number of Autoconf and exit. 1406 1407@item --verbose 1408@itemx -v 1409Print the names of the files it examines and the potentially interesting 1410symbols it finds in them. This output can be voluminous. 1411 1412@item --debug 1413@itemx -d 1414Don't remove temporary files. 1415 1416@item --include=@var{dir} 1417@itemx -I @var{dir} 1418Append @var{dir} to the include path. Multiple invocations accumulate. 1419 1420@item --prepend-include=@var{dir} 1421@itemx -B @var{dir} 1422Prepend @var{dir} to the include path. Multiple invocations accumulate. 1423@end table 1424 1425@node ifnames Invocation 1426@section Using @command{ifnames} to List Conditionals 1427@cindex @command{ifnames} 1428 1429@command{ifnames} can help you write @file{configure.ac} for a software 1430package. It prints the identifiers that the package already uses in C 1431preprocessor conditionals. If a package has already been set up to have 1432some portability, @command{ifnames} can thus help you figure out what its 1433@command{configure} needs to check for. It may help fill in some gaps in a 1434@file{configure.ac} generated by @command{autoscan} (@pxref{autoscan 1435Invocation}). 1436 1437@command{ifnames} scans all of the C source files named on the command line 1438(or the standard input, if none are given) and writes to the standard 1439output a sorted list of all the identifiers that appear in those files 1440in @code{#if}, @code{#elif}, @code{#ifdef}, or @code{#ifndef} 1441directives. It prints each identifier on a line, followed by a 1442space-separated list of the files in which that identifier occurs. 1443 1444@noindent 1445@command{ifnames} accepts the following options: 1446 1447@table @option 1448@item --help 1449@itemx -h 1450Print a summary of the command line options and exit. 1451 1452@item --version 1453@itemx -V 1454Print the version number of Autoconf and exit. 1455@end table 1456 1457@node autoconf Invocation 1458@section Using @command{autoconf} to Create @command{configure} 1459@cindex @command{autoconf} 1460 1461To create @command{configure} from @file{configure.ac}, run the 1462@command{autoconf} program with no arguments. @command{autoconf} processes 1463@file{configure.ac} with the M4 macro processor, using the 1464Autoconf macros. If you give @command{autoconf} an argument, it reads that 1465file instead of @file{configure.ac} and writes the configuration script 1466to the standard output instead of to @command{configure}. If you give 1467@command{autoconf} the argument @option{-}, it reads from the standard 1468input instead of @file{configure.ac} and writes the configuration script 1469to the standard output. 1470 1471The Autoconf macros are defined in several files. Some of the files are 1472distributed with Autoconf; @command{autoconf} reads them first. Then it 1473looks for the optional file @file{acsite.m4} in the directory that 1474contains the distributed Autoconf macro files, and for the optional file 1475@file{aclocal.m4} in the current directory. Those files can contain 1476your site's or the package's own Autoconf macro definitions 1477(@pxref{Writing Autoconf Macros}, for more information). If a macro is 1478defined in more than one of the files that @command{autoconf} reads, the 1479last definition it reads overrides the earlier ones. 1480 1481@command{autoconf} accepts the following options: 1482 1483@table @option 1484@item --help 1485@itemx -h 1486Print a summary of the command line options and exit. 1487 1488@item --version 1489@itemx -V 1490Print the version number of Autoconf and exit. 1491 1492@item --verbose 1493@itemx -v 1494Report processing steps. 1495 1496@item --debug 1497@itemx -d 1498Don't remove the temporary files. 1499 1500@item --force 1501@itemx -f 1502Remake @file{configure} even if newer than its input files. 1503 1504@item --include=@var{dir} 1505@itemx -I @var{dir} 1506Append @var{dir} to the include path. Multiple invocations accumulate. 1507 1508@item --prepend-include=@var{dir} 1509@itemx -B @var{dir} 1510Prepend @var{dir} to the include path. Multiple invocations accumulate. 1511 1512@item --output=@var{file} 1513@itemx -o @var{file} 1514Save output (script or trace) to @var{file}. The file @option{-} stands 1515for the standard output. 1516 1517@item --warnings=@var{category} 1518@itemx -W @var{category} 1519@evindex WARNINGS 1520Report the warnings related to @var{category} (which can actually be a 1521comma separated list). @xref{Reporting Messages}, macro 1522@code{AC_DIAGNOSE}, for a comprehensive list of categories. Special 1523values include: 1524 1525@table @samp 1526@item all 1527report all the warnings 1528 1529@item none 1530report none 1531 1532@item error 1533treats warnings as errors 1534 1535@item no-@var{category} 1536disable warnings falling into @var{category} 1537@end table 1538 1539Warnings about @samp{syntax} are enabled by default, and the environment 1540variable @env{WARNINGS}, a comma separated list of categories, is 1541honored as well. Passing @option{-W @var{category}} actually behaves as if 1542you had passed @option{--warnings syntax,$WARNINGS,@var{category}}. To 1543disable the defaults and @env{WARNINGS}, and then 1544enable warnings about obsolete constructs, use @option{-W 1545none,obsolete}. 1546 1547@cindex Back trace 1548@cindex Macro invocation stack 1549Because @command{autoconf} uses @command{autom4te} behind the scenes, it 1550displays a back trace for errors, but not for warnings; if you want 1551them, just pass @option{-W error}. @xref{autom4te Invocation}, for some 1552examples. 1553 1554@item --trace=@var{macro}[:@var{format}] 1555@itemx -t @var{macro}[:@var{format}] 1556Do not create the @command{configure} script, but list the calls to 1557@var{macro} according to the @var{format}. Multiple @option{--trace} 1558arguments can be used to list several macros. Multiple @option{--trace} 1559arguments for a single macro are not cumulative; instead, you should 1560just make @var{format} as long as needed. 1561 1562The @var{format} is a regular string, with newlines if desired, and 1563several special escape codes. It defaults to @samp{$f:$l:$n:$%}; see 1564@ref{autom4te Invocation}, for details on the @var{format}. 1565 1566@item --initialization 1567@itemx -i 1568By default, @option{--trace} does not trace the initialization of the 1569Autoconf macros (typically the @code{AC_DEFUN} definitions). This 1570results in a noticeable speedup, but can be disabled by this option. 1571@end table 1572 1573 1574It is often necessary to check the content of a @file{configure.ac} 1575file, but parsing it yourself is extremely fragile and error-prone. It 1576is suggested that you rely upon @option{--trace} to scan 1577@file{configure.ac}. For instance, to find the list of variables that 1578are substituted, use: 1579 1580@example 1581@group 1582$ @kbd{autoconf -t AC_SUBST} 1583configure.ac:2:AC_SUBST:ECHO_C 1584configure.ac:2:AC_SUBST:ECHO_N 1585configure.ac:2:AC_SUBST:ECHO_T 1586@i{More traces deleted} 1587@end group 1588@end example 1589 1590@noindent 1591The example below highlights the difference between @samp{$@@}, 1592@samp{$*}, and @samp{$%}. 1593 1594@example 1595@group 1596$ @kbd{cat configure.ac} 1597AC_DEFINE(This, is, [an 1598[example]]) 1599$ @kbd{autoconf -t 'AC_DEFINE:@@: $@@} 1600*: $* 1601%: $%' 1602@@: [This],[is],[an 1603[example]] 1604*: This,is,an 1605[example] 1606%: This:is:an [example] 1607@end group 1608@end example 1609 1610@noindent 1611The @var{format} gives you a lot of freedom: 1612 1613@example 1614@group 1615$ @kbd{autoconf -t 'AC_SUBST:$$ac_subst@{"$1"@} = "$f:$l";'} 1616$ac_subst@{"ECHO_C"@} = "configure.ac:2"; 1617$ac_subst@{"ECHO_N"@} = "configure.ac:2"; 1618$ac_subst@{"ECHO_T"@} = "configure.ac:2"; 1619@i{More traces deleted} 1620@end group 1621@end example 1622 1623@noindent 1624A long @var{separator} can be used to improve the readability of complex 1625structures, and to ease their parsing (for instance when no single 1626character is suitable as a separator): 1627 1628@example 1629@group 1630$ @kbd{autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*'} 1631ACLOCAL|:::::|aclocal|:::::|$missing_dir 1632AUTOCONF|:::::|autoconf|:::::|$missing_dir 1633AUTOMAKE|:::::|automake|:::::|$missing_dir 1634@i{More traces deleted} 1635@end group 1636@end example 1637 1638@node autoreconf Invocation 1639@section Using @command{autoreconf} to Update @command{configure} Scripts 1640@cindex @command{autoreconf} 1641 1642Installing the various components of the GNU Build System can be 1643tedious: running @command{autopoint} for Gettext, @command{automake} for 1644@file{Makefile.in} etc.@: in each directory. It may be needed either 1645because some tools such as @command{automake} have been updated on your 1646system, or because some of the sources such as @file{configure.ac} have 1647been updated, or finally, simply in order to install the GNU Build 1648System in a fresh tree. 1649 1650@command{autoreconf} runs @command{autoconf}, @command{autoheader}, 1651@command{aclocal}, @command{automake}, @command{libtoolize}, and 1652@command{autopoint} (when appropriate) repeatedly to update the 1653GNU Build System in the specified directories and their 1654subdirectories (@pxref{Subdirectories}). By default, it only remakes 1655those files that are older than their sources. The environment variables 1656@env{AUTOM4TE}, @env{AUTOCONF}, @env{AUTOHEADER}, @env{AUTOMAKE}, 1657@env{ACLOCAL}, @env{AUTOPOINT}, @env{LIBTOOLIZE}, @env{M4}, and @env{MAKE} 1658may be used to override the invocation of the respective tools. 1659 1660If you install a new version of some tool, you can make 1661@command{autoreconf} remake @emph{all} of the files by giving it the 1662@option{--force} option. 1663 1664@xref{Automatic Remaking}, for Make rules to automatically 1665rebuild @command{configure} scripts when their source files change. That 1666method handles the timestamps of configuration header templates 1667properly, but does not pass @option{--autoconf-dir=@var{dir}} or 1668@option{--localdir=@var{dir}}. 1669 1670@cindex Gettext 1671@cindex @command{autopoint} 1672Gettext supplies the @command{autopoint} command to add translation 1673infrastructure to a source package. If you use @command{autopoint}, 1674your @file{configure.ac} should invoke both @code{AM_GNU_GETTEXT} and 1675@code{AM_GNU_GETTEXT_VERSION(@var{gettext-version})}. @xref{autopoint 1676Invocation, , Invoking the @code{autopoint} Program, gettext, 1677GNU @code{gettext} utilities}, for further details. 1678 1679@noindent 1680@command{autoreconf} accepts the following options: 1681 1682@table @option 1683@item --help 1684@itemx -h 1685Print a summary of the command line options and exit. 1686 1687@item --version 1688@itemx -V 1689Print the version number of Autoconf and exit. 1690 1691@item --verbose 1692@itemx -v 1693Print the name of each directory @command{autoreconf} examines and the 1694commands it runs. If given two or more times, pass @option{--verbose} 1695to subordinate tools that support it. 1696 1697@item --debug 1698@itemx -d 1699Don't remove the temporary files. 1700 1701@item --force 1702@itemx -f 1703Remake even @file{configure} scripts and configuration headers that are 1704newer than their input files (@file{configure.ac} and, if present, 1705@file{aclocal.m4}). 1706 1707@item --install 1708@itemx -i 1709Install the missing auxiliary files in the package. By default, files 1710are copied; this can be changed with @option{--symlink}. 1711 1712If deemed appropriate, this option triggers calls to 1713@samp{automake --add-missing}, 1714@samp{libtoolize}, @samp{autopoint}, etc. 1715 1716@item --no-recursive 1717Do not rebuild files in subdirectories to configure (see @ref{Subdirectories}, 1718macro @code{AC_CONFIG_SUBDIRS}). 1719 1720@item --symlink 1721@itemx -s 1722When used with @option{--install}, install symbolic links to the missing 1723auxiliary files instead of copying them. 1724 1725@item --make 1726@itemx -m 1727When the directories were configured, update the configuration by 1728running @samp{./config.status --recheck && ./config.status}, and then 1729run @samp{make}. 1730 1731@item --include=@var{dir} 1732@itemx -I @var{dir} 1733Append @var{dir} to the include path. Multiple invocations accumulate. 1734Passed on to @command{aclocal}, @command{autoconf} and 1735@command{autoheader} internally. 1736 1737@item --prepend-include=@var{dir} 1738@itemx -B @var{dir} 1739Prepend @var{dir} to the include path. Multiple invocations accumulate. 1740Passed on to @command{autoconf} and @command{autoheader} internally. 1741 1742@item --warnings=@var{category} 1743@itemx -W @var{category} 1744@evindex WARNINGS 1745Report the warnings related to @var{category} (which can actually be a 1746comma separated list). 1747 1748@table @samp 1749@item cross 1750related to cross compilation issues. 1751 1752@item obsolete 1753report the uses of obsolete constructs. 1754 1755@item portability 1756portability issues 1757 1758@item syntax 1759dubious syntactic constructs. 1760 1761@item all 1762report all the warnings 1763 1764@item none 1765report none 1766 1767@item error 1768treats warnings as errors 1769 1770@item no-@var{category} 1771disable warnings falling into @var{category} 1772@end table 1773 1774Warnings about @samp{syntax} are enabled by default, and the environment 1775variable @env{WARNINGS}, a comma separated list of categories, is 1776honored as well. Passing @option{-W @var{category}} actually behaves as if 1777you had passed @option{--warnings syntax,$WARNINGS,@var{category}}. To 1778disable the defaults and @env{WARNINGS}, and then 1779enable warnings about obsolete constructs, use @option{-W 1780none,obsolete}. 1781@end table 1782 1783If you want @command{autoreconf} to pass flags that are not listed here 1784on to @command{aclocal}, set @code{ACLOCAL_AMFLAGS} in your @file{Makefile.am}. 1785Due to a limitation in the Autoconf implementation these flags currently 1786must be set on a single line in @file{Makefile.am}, without any 1787backslash-newlines. 1788 1789@c ========================================= Initialization and Output Files. 1790 1791@node Setup 1792@chapter Initialization and Output Files 1793 1794Autoconf-generated @command{configure} scripts need some information about 1795how to initialize, such as how to find the package's source files and 1796about the output files to produce. The following sections describe the 1797initialization and the creation of output files. 1798 1799@menu 1800* Initializing configure:: Option processing etc. 1801* Versioning:: Dealing with Autoconf versions 1802* Notices:: Copyright, version numbers in @command{configure} 1803* Input:: Where Autoconf should find files 1804* Output:: Outputting results from the configuration 1805* Configuration Actions:: Preparing the output based on results 1806* Configuration Files:: Creating output files 1807* Makefile Substitutions:: Using output variables in makefiles 1808* Configuration Headers:: Creating a configuration header file 1809* Configuration Commands:: Running arbitrary instantiation commands 1810* Configuration Links:: Links depending on the configuration 1811* Subdirectories:: Configuring independent packages together 1812* Default Prefix:: Changing the default installation prefix 1813@end menu 1814 1815@node Initializing configure 1816@section Initializing @command{configure} 1817 1818Every @command{configure} script must call @code{AC_INIT} before doing 1819anything else that produces output. Calls to silent macros, such as 1820@code{AC_DEFUN}, may also occur prior to @code{AC_INIT}, although these 1821are generally used via @file{aclocal.m4}, since that is implicitly 1822included before the start of @file{configure.ac}. The only other 1823required macro is @code{AC_OUTPUT} (@pxref{Output}). 1824 1825@anchor{AC_INIT} 1826@defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report}, @ 1827 @ovar{tarname}, @ovar{url}) 1828@acindex{INIT} 1829Process any command-line arguments and perform initialization 1830and verification. 1831 1832Set the name of the @var{package} and its @var{version}. These are 1833typically used in @option{--version} support, including that of 1834@command{configure}. The optional argument @var{bug-report} should be 1835the email to which users should send bug reports. The package 1836@var{tarname} differs from @var{package}: the latter designates the full 1837package name (e.g., @samp{GNU Autoconf}), while the former is meant for 1838distribution tar ball names (e.g., @samp{autoconf}). It defaults to 1839@var{package} with @samp{GNU } stripped, lower-cased, and all characters 1840other than alphanumerics and underscores are changed to @samp{-}. If 1841provided, @var{url} should be the home page for the package. 1842 1843The arguments of @code{AC_INIT} must be static, i.e., there should not 1844be any shell computation, quotes, or newlines, but they can be computed 1845by M4. This is because the package information strings are expanded at 1846M4 time into several contexts, and must give the same text at shell time 1847whether used in single-quoted strings, double-quoted strings, quoted 1848here-documents, or unquoted here-documents. It is permissible to use 1849@code{m4_esyscmd} or @code{m4_esyscmd_s} for computing a version string 1850that changes with every commit to a version control system (in fact, 1851Autoconf does just that, for all builds of the development tree made 1852between releases). 1853 1854The following M4 macros (e.g., @code{AC_PACKAGE_NAME}), output variables 1855(e.g., @code{PACKAGE_NAME}), and preprocessor symbols (e.g., 1856@code{PACKAGE_NAME}), are defined by @code{AC_INIT}: 1857 1858@table @asis 1859@item @code{AC_PACKAGE_NAME}, @code{PACKAGE_NAME} 1860@acindex{PACKAGE_NAME} 1861@ovindex PACKAGE_NAME 1862@cvindex PACKAGE_NAME 1863Exactly @var{package}. 1864 1865@item @code{AC_PACKAGE_TARNAME}, @code{PACKAGE_TARNAME} 1866@acindex{PACKAGE_TARNAME} 1867@ovindex PACKAGE_TARNAME 1868@cvindex PACKAGE_TARNAME 1869Exactly @var{tarname}, possibly generated from @var{package}. 1870 1871@item @code{AC_PACKAGE_VERSION}, @code{PACKAGE_VERSION} 1872@acindex{PACKAGE_VERSION} 1873@ovindex PACKAGE_VERSION 1874@cvindex PACKAGE_VERSION 1875Exactly @var{version}. 1876 1877@item @code{AC_PACKAGE_STRING}, @code{PACKAGE_STRING} 1878@acindex{PACKAGE_STRING} 1879@ovindex PACKAGE_STRING 1880@cvindex PACKAGE_STRING 1881Exactly @samp{@var{package} @var{version}}. 1882 1883@item @code{AC_PACKAGE_BUGREPORT}, @code{PACKAGE_BUGREPORT} 1884@acindex{PACKAGE_BUGREPORT} 1885@ovindex PACKAGE_BUGREPORT 1886@cvindex PACKAGE_BUGREPORT 1887Exactly @var{bug-report}, if one was provided. Typically an email 1888address, or URL to a bug management web page. 1889 1890@item @code{AC_PACKAGE_URL}, @code{PACKAGE_URL} 1891@acindex{PACKAGE_URL} 1892@ovindex PACKAGE_URL 1893@cvindex PACKAGE_URL 1894Exactly @var{url}, if one was provided. If @var{url} was empty, but 1895@var{package} begins with @samp{GNU }, then this defaults to 1896@samp{http://@/www.gnu.org/@/software/@/@var{tarname}/}, otherwise, no URL is 1897assumed. 1898@end table 1899@end defmac 1900 1901If your @command{configure} script does its own option processing, it 1902should inspect @samp{$@@} or @samp{$*} immediately after calling 1903@code{AC_INIT}, because other Autoconf macros liberally use the 1904@command{set} command to process strings, and this has the side effect 1905of updating @samp{$@@} and @samp{$*}. However, we suggest that you use 1906standard macros like @code{AC_ARG_ENABLE} instead of attempting to 1907implement your own option processing. @xref{Site Configuration}. 1908 1909@node Versioning 1910@section Dealing with Autoconf versions 1911@cindex Autoconf version 1912@cindex version, Autoconf 1913 1914The following optional macros can be used to help choose the minimum 1915version of Autoconf that can successfully compile a given 1916@file{configure.ac}. 1917 1918@defmac AC_PREREQ (@var{version}) 1919@acindex{PREREQ} 1920@cindex Version 1921Ensure that a recent enough version of Autoconf is being used. If the 1922version of Autoconf being used to create @command{configure} is 1923earlier than @var{version}, print an error message to the standard 1924error output and exit with failure (exit status is 63). For example: 1925 1926@example 1927AC_PREREQ([@value{VERSION}]) 1928@end example 1929 1930This macro may be used before @code{AC_INIT}. 1931@end defmac 1932 1933@defmac AC_AUTOCONF_VERSION 1934@acindex{AUTOCONF_VERSION} 1935This macro was introduced in Autoconf 2.62. It identifies the version 1936of Autoconf that is currently parsing the input file, in a format 1937suitable for @code{m4_version_compare} (@pxref{m4_version_compare}); in 1938other words, for this release of Autoconf, its value is 1939@samp{@value{VERSION}}. One potential use of this macro is for writing 1940conditional fallbacks based on when a feature was added to Autoconf, 1941rather than using @code{AC_PREREQ} to require the newer version of 1942Autoconf. However, remember that the Autoconf philosophy favors feature 1943checks over version checks. 1944 1945You should not expand this macro directly; use 1946@samp{m4_defn([AC_AUTOCONF_VERSION])} instead. This is because some 1947users might 1948have a beta version of Autoconf installed, with arbitrary letters 1949included in its version string. This means it is possible for the 1950version string to contain the name of a defined macro, such that 1951expanding @code{AC_AUTOCONF_VERSION} would trigger the expansion of that 1952macro during rescanning, and change the version string to be different 1953than what you intended to check. 1954@end defmac 1955 1956@node Notices 1957@section Notices in @command{configure} 1958@cindex Notices in @command{configure} 1959 1960The following macros manage version numbers for @command{configure} 1961scripts. Using them is optional. 1962 1963@defmac AC_COPYRIGHT (@var{copyright-notice}) 1964@acindex{COPYRIGHT} 1965@cindex Copyright Notice 1966State that, in addition to the Free Software Foundation's copyright on 1967the Autoconf macros, parts of your @command{configure} are covered by the 1968@var{copyright-notice}. 1969 1970The @var{copyright-notice} shows up in both the head of 1971@command{configure} and in @samp{configure --version}. 1972@end defmac 1973 1974 1975@defmac AC_REVISION (@var{revision-info}) 1976@acindex{REVISION} 1977@cindex Revision 1978Copy revision stamp @var{revision-info} into the @command{configure} 1979script, with any dollar signs or double-quotes removed. This macro lets 1980you put a revision stamp from @file{configure.ac} into @command{configure} 1981without RCS or CVS changing it when you check in 1982@command{configure}. That way, you can determine easily which revision of 1983@file{configure.ac} a particular @command{configure} corresponds to. 1984 1985For example, this line in @file{configure.ac}: 1986 1987@c The @w prevents RCS from changing the example in the manual. 1988@example 1989AC_REVISION([@w{$}Revision: 1.30 $]) 1990@end example 1991 1992@noindent 1993produces this in @command{configure}: 1994 1995@example 1996#!/bin/sh 1997# From configure.ac Revision: 1.30 1998@end example 1999@end defmac 2000 2001 2002@node Input 2003@section Finding @command{configure} Input 2004 2005@anchor{AC_CONFIG_SRCDIR} 2006@defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir}) 2007@acindex{CONFIG_SRCDIR} 2008@var{unique-file-in-source-dir} is some file that is in the package's 2009source directory; @command{configure} checks for this file's existence to 2010make sure that the directory that it is told contains the source code in 2011fact does. Occasionally people accidentally specify the wrong directory 2012with @option{--srcdir}; this is a safety check. @xref{configure 2013Invocation}, for more information. 2014@end defmac 2015 2016 2017@c FIXME: Remove definitively once --install explained. 2018@c 2019@c Small packages may store all their macros in @code{aclocal.m4}. As the 2020@c set of macros grows, or for maintenance reasons, a maintainer may prefer 2021@c to split the macros in several files. In this case, Autoconf must be 2022@c told which files to load, and in which order. 2023@c 2024@c @defmac AC_INCLUDE (@var{file}@dots{}) 2025@c @acindex{INCLUDE} 2026@c @c FIXME: There is no longer shell globbing. 2027@c Read the macro definitions that appear in the listed files. A list of 2028@c space-separated file names or shell globbing patterns is expected. The 2029@c files are read in the order they're listed. 2030@c 2031@c Because the order of definition of macros is important (only the last 2032@c definition of a macro is used), beware that it is @code{AC_INIT} that 2033@c loads @file{acsite.m4} and @file{aclocal.m4}. Note that 2034@c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within 2035@c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in 2036@c the latter case, non-macro lines from included files may end up in the 2037@c @file{configure} script, whereas in the former case, they'd be discarded 2038@c just like any text that appear before @code{AC_INIT}. 2039@c @end defmac 2040 2041Packages that do manual configuration or use the @command{install} program 2042might need to tell @command{configure} where to find some other shell 2043scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places 2044it looks are correct for most cases. 2045 2046@defmac AC_CONFIG_AUX_DIR (@var{dir}) 2047@acindex{CONFIG_AUX_DIR} 2048Use the auxiliary build tools (e.g., @file{install-sh}, 2049@file{config.sub}, @file{config.guess}, Cygnus @command{configure}, 2050Automake and Libtool scripts, etc.)@: that are in directory @var{dir}. 2051These are auxiliary files used in configuration. @var{dir} can be 2052either absolute or relative to @file{@var{srcdir}}. The default is 2053@file{@var{srcdir}} or @file{@var{srcdir}/..} or 2054@file{@var{srcdir}/../..}, whichever is the first that contains 2055@file{install-sh}. The other files are not checked for, so that using 2056@code{AC_PROG_INSTALL} does not automatically require distributing the 2057other auxiliary files. It checks for @file{install.sh} also, but that 2058name is obsolete because some @command{make} have a rule that creates 2059@file{install} from it if there is no makefile. 2060 2061The auxiliary directory is commonly named @file{build-aux}. 2062If you need portability to DOS variants, do not name the 2063auxiliary directory @file{aux}. @xref{File System Conventions}. 2064@end defmac 2065 2066@defmac AC_REQUIRE_AUX_FILE (@var{file}) 2067@acindex{REQUIRE_AUX_FILE} 2068Declares that @var{file} is expected in the directory defined above. In 2069Autoconf proper, this macro does nothing: its sole purpose is to be 2070traced by third-party tools to produce a list of expected auxiliary 2071files. For instance it is called by macros like @code{AC_PROG_INSTALL} 2072(@pxref{Particular Programs}) or @code{AC_CANONICAL_BUILD} 2073(@pxref{Canonicalizing}) to register the auxiliary files they need. 2074@end defmac 2075 2076Similarly, packages that use @command{aclocal} should declare where 2077local macros can be found using @code{AC_CONFIG_MACRO_DIR}. 2078 2079@defmac AC_CONFIG_MACRO_DIR (@var{dir}) 2080@acindex{CONFIG_MACRO_DIR} 2081Specify @var{dir} as the location of additional local Autoconf macros. 2082This macro is intended for use by future versions of commands like 2083@command{autoreconf} that trace macro calls. It should be called 2084directly from @file{configure.ac} so that tools that install macros for 2085@command{aclocal} can find the macros' declarations. 2086 2087Note that if you use @command{aclocal} from Automake to generate 2088@file{aclocal.m4}, you must also set @code{ACLOCAL_AMFLAGS = -I 2089@var{dir}} in your top-level @file{Makefile.am}. Due to a limitation in 2090the Autoconf implementation of @command{autoreconf}, these include 2091directives currently must be set on a single line in @file{Makefile.am}, 2092without any backslash-newlines. 2093@end defmac 2094 2095 2096@node Output 2097@section Outputting Files 2098@cindex Outputting files 2099 2100Every Autoconf script, e.g., @file{configure.ac}, should finish by 2101calling @code{AC_OUTPUT}. That is the macro that generates and runs 2102@file{config.status}, which in turn creates the makefiles and any 2103other files resulting from configuration. This is the only required 2104macro besides @code{AC_INIT} (@pxref{Input}). 2105 2106@anchor{AC_OUTPUT} 2107@defmac AC_OUTPUT 2108@acindex{OUTPUT} 2109@cindex Instantiation 2110Generate @file{config.status} and launch it. Call this macro once, at 2111the end of @file{configure.ac}. 2112 2113@file{config.status} performs all the configuration actions: all the 2114output files (see @ref{Configuration Files}, macro 2115@code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers}, 2116macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration 2117Commands}, macro @code{AC_CONFIG_COMMANDS}), links (see 2118@ref{Configuration Links}, macro @code{AC_CONFIG_LINKS}), subdirectories 2119to configure (see @ref{Subdirectories}, macro @code{AC_CONFIG_SUBDIRS}) 2120are honored. 2121 2122The location of your @code{AC_OUTPUT} invocation is the exact point 2123where configuration actions are taken: any code afterwards is 2124executed by @command{configure} once @command{config.status} was run. If 2125you want to bind actions to @command{config.status} itself 2126(independently of whether @command{configure} is being run), see 2127@ref{Configuration Commands, , Running Arbitrary Configuration 2128Commands}. 2129@end defmac 2130 2131Historically, the usage of @code{AC_OUTPUT} was somewhat different. 2132@xref{Obsolete Macros}, for a description of the arguments that 2133@code{AC_OUTPUT} used to support. 2134 2135 2136If you run @command{make} in subdirectories, you should run it using the 2137@command{make} variable @code{MAKE}. Most versions of @command{make} set 2138@code{MAKE} to the name of the @command{make} program plus any options it 2139was given. (But many do not include in it the values of any variables 2140set on the command line, so those are not passed on automatically.) 2141Some old versions of @command{make} do not set this variable. The 2142following macro allows you to use it even with those versions. 2143 2144@anchor{AC_PROG_MAKE_SET} 2145@defmac AC_PROG_MAKE_SET 2146@acindex{PROG_MAKE_SET} 2147@ovindex SET_MAKE 2148If the Make command, @code{$MAKE} if set or else @samp{make}, predefines 2149@code{$(MAKE)}, define output variable @code{SET_MAKE} to be empty. 2150Otherwise, define @code{SET_MAKE} to a macro definition that sets 2151@code{$(MAKE)}, such as @samp{MAKE=make}. Calls @code{AC_SUBST} for 2152@code{SET_MAKE}. 2153@end defmac 2154 2155If you use this macro, place a line like this in each @file{Makefile.in} 2156that runs @command{MAKE} on other directories: 2157 2158@example 2159@@SET_MAKE@@ 2160@end example 2161 2162 2163 2164@node Configuration Actions 2165@section Performing Configuration Actions 2166@cindex Configuration actions 2167 2168@file{configure} is designed so that it appears to do everything itself, 2169but there is actually a hidden slave: @file{config.status}. 2170@file{configure} is in charge of examining your system, but it is 2171@file{config.status} that actually takes the proper actions based on the 2172results of @file{configure}. The most typical task of 2173@file{config.status} is to @emph{instantiate} files. 2174 2175@acindex{CONFIG_@var{ITEMS}} 2176This section describes the common behavior of the four standard 2177instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS}, 2178@code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}. They all 2179have this prototype: 2180 2181@c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something 2182@c awful. 2183@example 2184AC_CONFIG_@var{ITEMS}(@var{tag}@dots{}, @r{[}@var{commands}@r{]}, @r{[}@var{init-cmds}@r{]}) 2185@end example 2186 2187@noindent 2188where the arguments are: 2189 2190@table @var 2191@item tag@dots{} 2192A blank-or-newline-separated list of tags, which are typically the names of 2193the files to instantiate. 2194 2195You are encouraged to use literals as @var{tags}. In particular, you 2196should avoid 2197 2198@example 2199@dots{} && my_foos="$my_foos fooo" 2200@dots{} && my_foos="$my_foos foooo" 2201AC_CONFIG_@var{ITEMS}([$my_foos]) 2202@end example 2203 2204@noindent 2205and use this instead: 2206 2207@example 2208@dots{} && AC_CONFIG_@var{ITEMS}([fooo]) 2209@dots{} && AC_CONFIG_@var{ITEMS}([foooo]) 2210@end example 2211 2212The macros @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use 2213special @var{tag} values: they may have the form @samp{@var{output}} or 2214@samp{@var{output}:@var{inputs}}. The file @var{output} is instantiated 2215from its templates, @var{inputs} (defaulting to @samp{@var{output}.in}). 2216 2217@samp{AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk])}, 2218for example, asks for 2219the creation of the file @file{Makefile} that contains the expansion of the 2220output variables in the concatenation of @file{boiler/top.mk} and 2221@file{boiler/bot.mk}. 2222 2223The special value @samp{-} might be used to denote the standard output 2224when used in @var{output}, or the standard input when used in the 2225@var{inputs}. You most probably don't need to use this in 2226@file{configure.ac}, but it is convenient when using the command line 2227interface of @file{./config.status}, see @ref{config.status Invocation}, 2228for more details. 2229 2230The @var{inputs} may be absolute or relative file names. In the latter 2231case they are first looked for in the build tree, and then in the source 2232tree. Input files should be text files, and a line length below 2000 2233bytes should be safe. 2234 2235@item commands 2236Shell commands output literally into @file{config.status}, and 2237associated with a tag that the user can use to tell @file{config.status} 2238which commands to run. The commands are run each time a @var{tag} 2239request is given to @file{config.status}, typically each time the file 2240@file{@var{tag}} is created. 2241 2242The variables set during the execution of @command{configure} are 2243@emph{not} available here: you first need to set them via the 2244@var{init-cmds}. Nonetheless the following variables are precomputed: 2245 2246@table @code 2247@item srcdir 2248@vrindex srcdir 2249The name of the top source directory, assuming that the working 2250directory is the top build directory. This 2251is what the @command{configure} option @option{--srcdir} sets. 2252 2253@item ac_top_srcdir 2254@vrindex ac_top_srcdir 2255The name of the top source directory, assuming that the working 2256directory is the current build directory. 2257 2258@item ac_top_build_prefix 2259@vrindex ac_top_build_prefix 2260The name of the top build directory, assuming that the working 2261directory is the current build directory. 2262It can be empty, or else ends with a slash, so that you may concatenate 2263it. 2264 2265@item ac_srcdir 2266@vrindex ac_srcdir 2267The name of the corresponding source directory, assuming that the 2268working directory is the current build directory. 2269 2270@item tmp 2271@vrindex tmp 2272The name of a temporary directory within the build tree, which you 2273can use if you need to create additional temporary files. The 2274directory is cleaned up when @command{config.status} is done or 2275interrupted. Please use package-specific file name prefixes to 2276avoid clashing with files that @command{config.status} may use 2277internally. 2278@end table 2279 2280@noindent 2281The @dfn{current} directory refers to the directory (or 2282pseudo-directory) containing the input part of @var{tags}. For 2283instance, running 2284 2285@example 2286AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [@dots{}], [@dots{}]) 2287@end example 2288 2289@noindent 2290 with @option{--srcdir=../package} produces the following values: 2291 2292@example 2293# Argument of --srcdir 2294srcdir='../package' 2295# Reversing deep/dir 2296ac_top_build_prefix='../../' 2297# Concatenation of $ac_top_build_prefix and srcdir 2298ac_top_srcdir='../../../package' 2299# Concatenation of $ac_top_srcdir and deep/dir 2300ac_srcdir='../../../package/deep/dir' 2301@end example 2302 2303@noindent 2304independently of @samp{in/in.in}. 2305 2306@item init-cmds 2307Shell commands output @emph{unquoted} near the beginning of 2308@file{config.status}, and executed each time @file{config.status} runs 2309(regardless of the tag). Because they are unquoted, for example, 2310@samp{$var} is output as the value of @code{var}. @var{init-cmds} 2311is typically used by @file{configure} to give @file{config.status} some 2312variables it needs to run the @var{commands}. 2313 2314You should be extremely cautious in your variable names: all the 2315@var{init-cmds} share the same name space and may overwrite each other 2316in unpredictable ways. Sorry@enddots{} 2317@end table 2318 2319All these macros can be called multiple times, with different 2320@var{tag} values, of course! 2321 2322 2323@node Configuration Files 2324@section Creating Configuration Files 2325@cindex Creating configuration files 2326@cindex Configuration file creation 2327 2328Be sure to read the previous section, @ref{Configuration Actions}. 2329 2330@anchor{AC_CONFIG_FILES} 2331@defmac AC_CONFIG_FILES (@var{file}@dots{}, @ovar{cmds}, @ovar{init-cmds}) 2332@acindex{CONFIG_FILES} 2333Make @code{AC_OUTPUT} create each @file{@var{file}} by copying an input 2334file (by default @file{@var{file}.in}), substituting the output variable 2335values. 2336@c Before we used to have this feature, which was later rejected 2337@c because it complicates the writing of makefiles: 2338@c If the file would be unchanged, it is left untouched, to preserve 2339@c timestamp. 2340This macro is one of the instantiating macros; see @ref{Configuration 2341Actions}. @xref{Makefile Substitutions}, for more information on using 2342output variables. @xref{Setting Output Variables}, for more information 2343on creating them. This macro creates the directory that the file is in 2344if it doesn't exist. Usually, makefiles are created this way, 2345but other files, such as @file{.gdbinit}, can be specified as well. 2346 2347Typical calls to @code{AC_CONFIG_FILES} look like this: 2348 2349@example 2350AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile]) 2351AC_CONFIG_FILES([autoconf], [chmod +x autoconf]) 2352@end example 2353 2354You can override an input file name by appending to @var{file} a 2355colon-separated list of input files. Examples: 2356 2357@example 2358AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk] 2359 [lib/Makefile:boiler/lib.mk]) 2360@end example 2361 2362@noindent 2363Doing this allows you to keep your file names acceptable to 2364DOS variants, or 2365to prepend and/or append boilerplate to the file. 2366@end defmac 2367 2368 2369 2370@node Makefile Substitutions 2371@section Substitutions in Makefiles 2372@cindex Substitutions in makefiles 2373@cindex Makefile substitutions 2374 2375Each subdirectory in a distribution that contains something to be 2376compiled or installed should come with a file @file{Makefile.in}, from 2377which @command{configure} creates a file @file{Makefile} in that directory. 2378To create @file{Makefile}, @command{configure} performs a simple variable 2379substitution, replacing occurrences of @samp{@@@var{variable}@@} in 2380@file{Makefile.in} with the value that @command{configure} has determined 2381for that variable. Variables that are substituted into output files in 2382this way are called @dfn{output variables}. They are ordinary shell 2383variables that are set in @command{configure}. To make @command{configure} 2384substitute a particular variable into the output files, the macro 2385@code{AC_SUBST} must be called with that variable name as an argument. 2386Any occurrences of @samp{@@@var{variable}@@} for other variables are 2387left unchanged. @xref{Setting Output Variables}, for more information 2388on creating output variables with @code{AC_SUBST}. 2389 2390A software package that uses a @command{configure} script should be 2391distributed with a file @file{Makefile.in}, but no makefile; that 2392way, the user has to properly configure the package for the local system 2393before compiling it. 2394 2395@xref{Makefile Conventions, , Makefile Conventions, standards, The 2396GNU Coding Standards}, for more information on what to put in 2397makefiles. 2398 2399@menu 2400* Preset Output Variables:: Output variables that are always set 2401* Installation Directory Variables:: Other preset output variables 2402* Changed Directory Variables:: Warnings about @file{datarootdir} 2403* Build Directories:: Supporting multiple concurrent compiles 2404* Automatic Remaking:: Makefile rules for configuring 2405@end menu 2406 2407@node Preset Output Variables 2408@subsection Preset Output Variables 2409@cindex Output variables 2410 2411Some output variables are preset by the Autoconf macros. Some of the 2412Autoconf macros set additional output variables, which are mentioned in 2413the descriptions for those macros. @xref{Output Variable Index}, for a 2414complete list of output variables. @xref{Installation Directory 2415Variables}, for the list of the preset ones related to installation 2416directories. Below are listed the other preset ones, many of which are 2417precious variables (@pxref{Setting Output Variables}, 2418@code{AC_ARG_VAR}). 2419 2420The preset variables which are available during @file{config.status} 2421(@pxref{Configuration Actions}) may also be used during 2422@command{configure} tests. For example, it is permissible to reference 2423@samp{$srcdir} when constructing a list of directories to pass via 2424option @option{-I} during a compiler feature check. When used in this 2425manner, coupled with the fact that @command{configure} is always run 2426from the top build directory, it is sufficient to use just 2427@samp{$srcdir} instead of @samp{$top_srcdir}. 2428 2429@c Just say no to ASCII sorting! We're humans, not computers. 2430@c These variables are listed as they would be in a dictionary: 2431@c actor 2432@c Actress 2433@c actress 2434 2435@defvar CFLAGS 2436@evindex CFLAGS 2437@ovindex CFLAGS 2438Debugging and optimization options for the C compiler. If it is not set 2439in the environment when @command{configure} runs, the default value is set 2440when you call @code{AC_PROG_CC} (or empty if you don't). @command{configure} 2441uses this variable when compiling or linking programs to test for C features. 2442 2443If a compiler option affects only the behavior of the preprocessor 2444(e.g., @option{-D@var{name}}), it should be put into @code{CPPFLAGS} 2445instead. If it affects only the linker (e.g., @option{-L@var{directory}}), 2446it should be put into @code{LDFLAGS} instead. If it 2447affects only the compiler proper, @code{CFLAGS} is the natural home for 2448it. If an option affects multiple phases of the compiler, though, 2449matters get tricky. One approach to put such options directly into 2450@code{CC}, e.g., @code{CC='gcc -m64'}. Another is to put them into both 2451@code{CPPFLAGS} and @code{LDFLAGS}, but not into @code{CFLAGS}. 2452 2453However, remember that some @file{Makefile} variables are reserved by 2454the GNU Coding Standards for the use of the ``user''---the person 2455building the package. For instance, @code{CFLAGS} is one such variable. 2456 2457Sometimes package developers are tempted to set user variables such as 2458@code{CFLAGS} because it appears to make their job easier. However, the 2459package itself should never set a user variable, particularly not to 2460include switches that are required for proper compilation of the 2461package. Since these variables are documented as being for the package 2462builder, that person rightfully expects to be able to override any of 2463these variables at build time. If the package developer needs to add 2464switches without interfering with the user, the proper way to do that is 2465to introduce an additional variable. Automake makes this easy by 2466introducing @code{AM_CFLAGS} (@pxref{Flag Variables Ordering, , , 2467automake, GNU Automake}), but the concept is the same even if 2468Automake is not used. 2469@end defvar 2470 2471@defvar configure_input 2472@ovindex configure_input 2473A comment saying that the file was generated automatically by 2474@command{configure} and giving the name of the input file. 2475@code{AC_OUTPUT} adds a comment line containing this variable to the top 2476of every makefile it creates. For other files, you should 2477reference this variable in a comment at the top of each input file. For 2478example, an input shell script should begin like this: 2479 2480@example 2481#!/bin/sh 2482# @@configure_input@@ 2483@end example 2484 2485@noindent 2486The presence of that line also reminds people editing the file that it 2487needs to be processed by @command{configure} in order to be used. 2488@end defvar 2489 2490@defvar CPPFLAGS 2491@evindex CPPFLAGS 2492@ovindex CPPFLAGS 2493Preprocessor options for the C, C++, Objective C, and Objective C++ 2494preprocessors and compilers. If 2495it is not set in the environment when @command{configure} runs, the default 2496value is empty. @command{configure} uses this variable when preprocessing 2497or compiling programs to test for C, C++, Objective C, and Objective C++ 2498features. 2499 2500This variable's contents should contain options like @option{-I}, 2501@option{-D}, and @option{-U} that affect only the behavior of the 2502preprocessor. Please see the explanation of @code{CFLAGS} for what you 2503can do if an option affects other phases of the compiler as well. 2504 2505Currently, @command{configure} always links as part of a single 2506invocation of the compiler that also preprocesses and compiles, so it 2507uses this variable also when linking programs. However, it is unwise to 2508depend on this behavior because the GNU Coding Standards do 2509not require it and many packages do not use @code{CPPFLAGS} when linking 2510programs. 2511 2512@xref{Special Chars in Variables}, for limitations that @code{CPPFLAGS} 2513might run into. 2514@end defvar 2515 2516@defvar CXXFLAGS 2517@evindex CXXFLAGS 2518@ovindex CXXFLAGS 2519Debugging and optimization options for the C++ compiler. It acts like 2520@code{CFLAGS}, but for C++ instead of C. 2521@end defvar 2522 2523@defvar DEFS 2524@ovindex DEFS 2525@option{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADERS} 2526is called, @command{configure} replaces @samp{@@DEFS@@} with 2527@option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}). This 2528variable is not defined while @command{configure} is performing its tests, 2529only when creating the output files. @xref{Setting Output Variables}, for 2530how to check the results of previous tests. 2531@end defvar 2532 2533@defvar ECHO_C 2534@defvarx ECHO_N 2535@defvarx ECHO_T 2536@ovindex ECHO_C 2537@ovindex ECHO_N 2538@ovindex ECHO_T 2539How does one suppress the trailing newline from @command{echo} for 2540question-answer message pairs? These variables provide a way: 2541 2542@example 2543echo $ECHO_N "And the winner is... $ECHO_C" 2544sleep 100000000000 2545echo "$@{ECHO_T@}dead." 2546@end example 2547 2548@noindent 2549Some old and uncommon @command{echo} implementations offer no means to 2550achieve this, in which case @code{ECHO_T} is set to tab. You might not 2551want to use it. 2552@end defvar 2553 2554@defvar ERLCFLAGS 2555@evindex ERLCFLAGS 2556@ovindex ERLCFLAGS 2557Debugging and optimization options for the Erlang compiler. If it is not set 2558in the environment when @command{configure} runs, the default value is empty. 2559@command{configure} uses this variable when compiling 2560programs to test for Erlang features. 2561@end defvar 2562 2563@defvar FCFLAGS 2564@evindex FCFLAGS 2565@ovindex FCFLAGS 2566Debugging and optimization options for the Fortran compiler. If it 2567is not set in the environment when @command{configure} runs, the default 2568value is set when you call @code{AC_PROG_FC} (or empty if you don't). 2569@command{configure} uses this variable when compiling or linking 2570programs to test for Fortran features. 2571@end defvar 2572 2573@defvar FFLAGS 2574@evindex FFLAGS 2575@ovindex FFLAGS 2576Debugging and optimization options for the Fortran 77 compiler. If it 2577is not set in the environment when @command{configure} runs, the default 2578value is set when you call @code{AC_PROG_F77} (or empty if you don't). 2579@command{configure} uses this variable when compiling or linking 2580programs to test for Fortran 77 features. 2581@end defvar 2582 2583@defvar LDFLAGS 2584@evindex LDFLAGS 2585@ovindex LDFLAGS 2586Options for the linker. If it is not set 2587in the environment when @command{configure} runs, the default value is empty. 2588@command{configure} uses this variable when linking programs to test for 2589C, C++, Objective C, Objective C++, Fortran, and Go features. 2590 2591This variable's contents should contain options like @option{-s} and 2592@option{-L} that affect only the behavior of the linker. Please see the 2593explanation of @code{CFLAGS} for what you can do if an option also 2594affects other phases of the compiler. 2595 2596Don't use this variable to pass library names 2597(@option{-l}) to the linker; use @code{LIBS} instead. 2598@end defvar 2599 2600@defvar LIBS 2601@evindex LIBS 2602@ovindex LIBS 2603@option{-l} options to pass to the linker. The default value is empty, 2604but some Autoconf macros may prepend extra libraries to this variable if 2605those libraries are found and provide necessary functions, see 2606@ref{Libraries}. @command{configure} uses this variable when linking 2607programs to test for C, C++, Objective C, Objective C++, Fortran, and Go 2608features. 2609@end defvar 2610 2611@defvar OBJCFLAGS 2612@evindex OBJCFLAGS 2613@ovindex OBJCFLAGS 2614Debugging and optimization options for the Objective C compiler. It 2615acts like @code{CFLAGS}, but for Objective C instead of C. 2616@end defvar 2617 2618@defvar OBJCXXFLAGS 2619@evindex OBJCXXFLAGS 2620@ovindex OBJCXXFLAGS 2621Debugging and optimization options for the Objective C++ compiler. It 2622acts like @code{CXXFLAGS}, but for Objective C++ instead of C++. 2623@end defvar 2624 2625@defvar GOFLAGS 2626@evindex GOFLAGS 2627@ovindex GOFLAGS 2628Debugging and optimization options for the Go compiler. It acts like 2629@code{CFLAGS}, but for Go instead of C. 2630@end defvar 2631 2632@defvar builddir 2633@ovindex builddir 2634Rigorously equal to @samp{.}. Added for symmetry only. 2635@end defvar 2636 2637@defvar abs_builddir 2638@ovindex abs_builddir 2639Absolute name of @code{builddir}. 2640@end defvar 2641 2642@defvar top_builddir 2643@ovindex top_builddir 2644The relative name of the top level of the current build tree. In the 2645top-level directory, this is the same as @code{builddir}. 2646@end defvar 2647 2648@defvar top_build_prefix 2649@ovindex top_build_prefix 2650The relative name of the top level of the current build tree with final 2651slash if nonempty. This is the same as @code{top_builddir}, except that 2652it contains zero or more runs of @code{../}, so it should not be 2653appended with a slash for concatenation. This helps for @command{make} 2654implementations that otherwise do not treat @file{./file} and @file{file} 2655as equal in the toplevel build directory. 2656@end defvar 2657 2658@defvar abs_top_builddir 2659@ovindex abs_top_builddir 2660Absolute name of @code{top_builddir}. 2661@end defvar 2662 2663@defvar srcdir 2664@ovindex srcdir 2665The name of the directory that contains the source code for 2666that makefile. 2667@end defvar 2668 2669@defvar abs_srcdir 2670@ovindex abs_srcdir 2671Absolute name of @code{srcdir}. 2672@end defvar 2673 2674@defvar top_srcdir 2675@ovindex top_srcdir 2676The name of the top-level source code directory for the 2677package. In the top-level directory, this is the same as @code{srcdir}. 2678@end defvar 2679 2680@defvar abs_top_srcdir 2681@ovindex abs_top_srcdir 2682Absolute name of @code{top_srcdir}. 2683@end defvar 2684 2685@node Installation Directory Variables 2686@subsection Installation Directory Variables 2687@cindex Installation directories 2688@cindex Directories, installation 2689 2690The following variables specify the directories for 2691package installation, see @ref{Directory Variables, , Variables for 2692Installation Directories, standards, The GNU Coding 2693Standards}, for more information. Each variable corresponds to an 2694argument of @command{configure}; trailing slashes are stripped so that 2695expressions such as @samp{$@{prefix@}/lib} expand with only one slash 2696between directory names. See the end of this section for 2697details on when and how to use these variables. 2698 2699@defvar bindir 2700@ovindex bindir 2701The directory for installing executables that users run. 2702@end defvar 2703 2704@defvar datadir 2705@ovindex datadir 2706The directory for installing idiosyncratic read-only 2707architecture-independent data. 2708@end defvar 2709 2710@defvar datarootdir 2711@ovindex datarootdir 2712The root of the directory tree for read-only architecture-independent 2713data files. 2714@end defvar 2715 2716@defvar docdir 2717@ovindex docdir 2718The directory for installing documentation files (other than Info and 2719man). 2720@end defvar 2721 2722@defvar dvidir 2723@ovindex dvidir 2724The directory for installing documentation files in DVI format. 2725@end defvar 2726 2727@defvar exec_prefix 2728@ovindex exec_prefix 2729The installation prefix for architecture-dependent files. By default 2730it's the same as @code{prefix}. You should avoid installing anything 2731directly to @code{exec_prefix}. However, the default value for 2732directories containing architecture-dependent files should be relative 2733to @code{exec_prefix}. 2734@end defvar 2735 2736@defvar htmldir 2737@ovindex htmldir 2738The directory for installing HTML documentation. 2739@end defvar 2740 2741@defvar includedir 2742@ovindex includedir 2743The directory for installing C header files. 2744@end defvar 2745 2746@defvar infodir 2747@ovindex infodir 2748The directory for installing documentation in Info format. 2749@end defvar 2750 2751@defvar libdir 2752@ovindex libdir 2753The directory for installing object code libraries. 2754@end defvar 2755 2756@defvar libexecdir 2757@ovindex libexecdir 2758The directory for installing executables that other programs run. 2759@end defvar 2760 2761@defvar localedir 2762@ovindex localedir 2763The directory for installing locale-dependent but 2764architecture-independent data, such as message catalogs. This directory 2765usually has a subdirectory per locale. 2766@end defvar 2767 2768@defvar localstatedir 2769@ovindex localstatedir 2770The directory for installing modifiable single-machine data. 2771@end defvar 2772 2773@defvar mandir 2774@ovindex mandir 2775The top-level directory for installing documentation in man format. 2776@end defvar 2777 2778@defvar oldincludedir 2779@ovindex oldincludedir 2780The directory for installing C header files for non-GCC compilers. 2781@end defvar 2782 2783@defvar pdfdir 2784@ovindex pdfdir 2785The directory for installing PDF documentation. 2786@end defvar 2787 2788@defvar prefix 2789@ovindex prefix 2790The common installation prefix for all files. If @code{exec_prefix} 2791is defined to a different value, @code{prefix} is used only for 2792architecture-independent files. 2793@end defvar 2794 2795@defvar psdir 2796@ovindex psdir 2797The directory for installing PostScript documentation. 2798@end defvar 2799 2800@defvar sbindir 2801@ovindex sbindir 2802The directory for installing executables that system 2803administrators run. 2804@end defvar 2805 2806@defvar sharedstatedir 2807@ovindex sharedstatedir 2808The directory for installing modifiable architecture-independent data. 2809@end defvar 2810 2811@defvar sysconfdir 2812@ovindex sysconfdir 2813The directory for installing read-only single-machine data. 2814@end defvar 2815 2816 2817Most of these variables have values that rely on @code{prefix} or 2818@code{exec_prefix}. It is deliberate that the directory output 2819variables keep them unexpanded: typically @samp{@@datarootdir@@} is 2820replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}, and 2821@samp{@@datadir@@} is replaced by @samp{$@{datarootdir@}}. 2822 2823This behavior is mandated by the GNU Coding Standards, so that when 2824the user runs: 2825 2826@table @samp 2827@item make 2828she can still specify a different prefix from the one specified to 2829@command{configure}, in which case, if needed, the package should hard 2830code dependencies corresponding to the make-specified prefix. 2831 2832@item make install 2833she can specify a different installation location, in which case the 2834package @emph{must} still depend on the location which was compiled in 2835(i.e., never recompile when @samp{make install} is run). This is an 2836extremely important feature, as many people may decide to install all 2837the files of a package grouped together, and then install links from 2838the final locations to there. 2839@end table 2840 2841In order to support these features, it is essential that 2842@code{datarootdir} remains defined as @samp{$@{prefix@}/share}, 2843so that its value can be expanded based 2844on the current value of @code{prefix}. 2845 2846A corollary is that you should not use these variables except in 2847makefiles. For instance, instead of trying to evaluate @code{datadir} 2848in @file{configure} and hard-coding it in makefiles using 2849e.g., @samp{AC_DEFINE_UNQUOTED([DATADIR], ["$datadir"], [Data directory.])}, 2850you should add 2851@option{-DDATADIR='$(datadir)'} to your makefile's definition of 2852@code{CPPFLAGS} (@code{AM_CPPFLAGS} if you are also using Automake). 2853 2854Similarly, you should not rely on @code{AC_CONFIG_FILES} to replace 2855@code{bindir} and friends in your shell scripts and other files; instead, 2856let @command{make} manage their replacement. For instance Autoconf 2857ships templates of its shell scripts ending with @samp{.in}, and uses a 2858makefile snippet similar to the following to build scripts like 2859@command{autoheader} and @command{autom4te}: 2860 2861@example 2862@group 2863edit = sed \ 2864 -e 's|@@bindir[@@]|$(bindir)|g' \ 2865 -e 's|@@pkgdatadir[@@]|$(pkgdatadir)|g' \ 2866 -e 's|@@prefix[@@]|$(prefix)|g' 2867@end group 2868 2869@group 2870autoheader autom4te: Makefile 2871 rm -f $@@ $@@.tmp 2872 srcdir=''; \ 2873 test -f ./$@@.in || srcdir=$(srcdir)/; \ 2874 $(edit) $$@{srcdir@}$@@.in >$@@.tmp 2875@c $$ restore font-lock 2876 chmod +x $@@.tmp 2877 chmod a-w $@@.tmp 2878 mv $@@.tmp $@@ 2879@end group 2880 2881@group 2882autoheader: $(srcdir)/autoheader.in 2883autom4te: $(srcdir)/autom4te.in 2884@end group 2885@end example 2886 2887Some details are noteworthy: 2888 2889@table @asis 2890@item @samp{@@bindir[@@]} 2891The brackets prevent @command{configure} from replacing 2892@samp{@@bindir@@} in the Sed expression itself. 2893Brackets are preferable to a backslash here, since 2894Posix says @samp{\@@} is not portable. 2895 2896@item @samp{$(bindir)} 2897Don't use @samp{@@bindir@@}! Use the matching makefile variable 2898instead. 2899 2900@item @samp{$(pkgdatadir)} 2901The example takes advantage of the variable @samp{$(pkgdatadir)} 2902provided by Automake; it is equivalent to @samp{$(datadir)/$(PACKAGE)}. 2903 2904@item @samp{/} 2905Don't use @samp{/} in the Sed expressions that replace file names since 2906most likely the 2907variables you use, such as @samp{$(bindir)}, contain @samp{/}. 2908Use a shell metacharacter instead, such as @samp{|}. 2909 2910@item special characters 2911File names, file name components, and the value of @code{VPATH} should 2912not contain shell metacharacters or white 2913space. @xref{Special Chars in Variables}. 2914 2915@item dependency on @file{Makefile} 2916Since @code{edit} uses values that depend on the configuration specific 2917values (@code{prefix}, etc.)@: and not only on @code{VERSION} and so forth, 2918the output depends on @file{Makefile}, not @file{configure.ac}. 2919 2920@item @samp{$@@} 2921The main rule is generic, and uses @samp{$@@} extensively to 2922avoid the need for multiple copies of the rule. 2923 2924@item Separated dependencies and single suffix rules 2925You can't use them! The above snippet cannot be (portably) rewritten 2926as: 2927 2928@example 2929autoconf autoheader: Makefile 2930@group 2931.in: 2932 rm -f $@@ $@@.tmp 2933 $(edit) $< >$@@.tmp 2934 chmod +x $@@.tmp 2935 mv $@@.tmp $@@ 2936@end group 2937@end example 2938 2939@xref{Single Suffix Rules}, for details. 2940 2941@item @samp{$(srcdir)} 2942Be sure to specify the name of the source directory, 2943otherwise the package won't support separated builds. 2944@end table 2945 2946For the more specific installation of Erlang libraries, the following variables 2947are defined: 2948 2949@defvar ERLANG_INSTALL_LIB_DIR 2950@ovindex ERLANG_INSTALL_LIB_DIR 2951@acindex{ERLANG_SUBST_INSTALL_LIB_DIR} 2952The common parent directory of Erlang library installation directories. 2953This variable is set by calling the @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR} 2954macro in @file{configure.ac}. 2955@end defvar 2956 2957@defvar ERLANG_INSTALL_LIB_DIR_@var{library} 2958@ovindex ERLANG_INSTALL_LIB_DIR_@var{library} 2959@acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR} 2960The installation directory for Erlang library @var{library}. 2961This variable is set by using the 2962@samp{AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR} 2963macro in @file{configure.ac}. 2964@end defvar 2965 2966@xref{Erlang Libraries}, for details. 2967 2968 2969@node Changed Directory Variables 2970@subsection Changed Directory Variables 2971@cindex @file{datarootdir} 2972 2973In Autoconf 2.60, the set of directory variables has changed, and the 2974defaults of some variables have been adjusted 2975(@pxref{Installation Directory Variables}) to changes in the 2976GNU Coding Standards. Notably, @file{datadir}, @file{infodir}, and 2977@file{mandir} are now expressed in terms of @file{datarootdir}. If you are 2978upgrading from an earlier Autoconf version, you may need to adjust your files 2979to ensure that the directory variables are substituted correctly 2980(@pxref{Defining Directories}), and that a definition of @file{datarootdir} is 2981in place. For example, in a @file{Makefile.in}, adding 2982 2983@example 2984datarootdir = @@datarootdir@@ 2985@end example 2986 2987@noindent 2988is usually sufficient. If you use Automake to create @file{Makefile.in}, 2989it will add this for you. 2990 2991To help with the transition, Autoconf warns about files that seem to use 2992@code{datarootdir} without defining it. In some cases, it then expands 2993the value of @code{$datarootdir} in substitutions of the directory 2994variables. The following example shows such a warning: 2995 2996@example 2997$ @kbd{cat configure.ac} 2998AC_INIT 2999AC_CONFIG_FILES([Makefile]) 3000AC_OUTPUT 3001$ @kbd{cat Makefile.in} 3002prefix = @@prefix@@ 3003datadir = @@datadir@@ 3004$ @kbd{autoconf} 3005$ @kbd{configure} 3006configure: creating ./config.status 3007config.status: creating Makefile 3008config.status: WARNING: 3009 Makefile.in seems to ignore the --datarootdir setting 3010$ @kbd{cat Makefile} 3011prefix = /usr/local 3012datadir = $@{prefix@}/share 3013@end example 3014 3015Usually one can easily change the file to accommodate both older and newer 3016Autoconf releases: 3017 3018@example 3019$ @kbd{cat Makefile.in} 3020prefix = @@prefix@@ 3021datarootdir = @@datarootdir@@ 3022datadir = @@datadir@@ 3023$ @kbd{configure} 3024configure: creating ./config.status 3025config.status: creating Makefile 3026$ @kbd{cat Makefile} 3027prefix = /usr/local 3028datarootdir = $@{prefix@}/share 3029datadir = $@{datarootdir@} 3030@end example 3031 3032@acindex{DATAROOTDIR_CHECKED} 3033In some cases, however, the checks may not be able to detect that a suitable 3034initialization of @code{datarootdir} is in place, or they may fail to detect 3035that such an initialization is necessary in the output file. If, after 3036auditing your package, there are still spurious @file{configure} warnings about 3037@code{datarootdir}, you may add the line 3038 3039@example 3040AC_DEFUN([AC_DATAROOTDIR_CHECKED]) 3041@end example 3042 3043@noindent 3044to your @file{configure.ac} to disable the warnings. This is an exception 3045to the usual rule that you should not define a macro whose name begins with 3046@code{AC_} (@pxref{Macro Names}). 3047 3048 3049 3050@node Build Directories 3051@subsection Build Directories 3052@cindex Build directories 3053@cindex Directories, build 3054 3055You can support compiling a software package for several architectures 3056simultaneously from the same copy of the source code. The object files 3057for each architecture are kept in their own directory. 3058 3059To support doing this, @command{make} uses the @code{VPATH} variable to 3060find the files that are in the source directory. GNU Make 3061can do this. Most other recent @command{make} programs can do this as 3062well, though they may have difficulties and it is often simpler to 3063recommend GNU @command{make} (@pxref{VPATH and Make}). Older 3064@command{make} programs do not support @code{VPATH}; when using them, the 3065source code must be in the same directory as the object files. 3066 3067If you are using GNU Automake, the remaining details in this 3068section are already covered for you, based on the contents of your 3069@file{Makefile.am}. But if you are using Autoconf in isolation, then 3070supporting @code{VPATH} requires the following in your 3071@file{Makefile.in}: 3072 3073@example 3074srcdir = @@srcdir@@ 3075VPATH = @@srcdir@@ 3076@end example 3077 3078Do not set @code{VPATH} to the value of another variable (@pxref{Variables 3079listed in VPATH}. 3080 3081@command{configure} substitutes the correct value for @code{srcdir} when 3082it produces @file{Makefile}. 3083 3084Do not use the @command{make} variable @code{$<}, which expands to the 3085file name of the file in the source directory (found with @code{VPATH}), 3086except in implicit rules. (An implicit rule is one such as @samp{.c.o}, 3087which tells how to create a @file{.o} file from a @file{.c} file.) Some 3088versions of @command{make} do not set @code{$<} in explicit rules; they 3089expand it to an empty value. 3090 3091Instead, Make command lines should always refer to source 3092files by prefixing them with @samp{$(srcdir)/}. For example: 3093 3094@example 3095time.info: time.texinfo 3096 $(MAKEINFO) '$(srcdir)/time.texinfo' 3097@end example 3098 3099@node Automatic Remaking 3100@subsection Automatic Remaking 3101@cindex Automatic remaking 3102@cindex Remaking automatically 3103 3104You can put rules like the following in the top-level @file{Makefile.in} 3105for a package to automatically update the configuration information when 3106you change the configuration files. This example includes all of the 3107optional files, such as @file{aclocal.m4} and those related to 3108configuration header files. Omit from the @file{Makefile.in} rules for 3109any of these files that your package does not use. 3110 3111The @samp{$(srcdir)/} prefix is included because of limitations in the 3112@code{VPATH} mechanism. 3113 3114The @file{stamp-} files are necessary because the timestamps of 3115@file{config.h.in} and @file{config.h} are not changed if remaking 3116them does not change their contents. This feature avoids unnecessary 3117recompilation. You should include the file @file{stamp-h.in} in your 3118package's distribution, so that @command{make} considers 3119@file{config.h.in} up to date. Don't use @command{touch} 3120(@pxref{touch, , Limitations of Usual Tools}); instead, use 3121@command{echo} (using 3122@command{date} would cause needless differences, hence CVS 3123conflicts, etc.). 3124 3125@example 3126@group 3127$(srcdir)/configure: configure.ac aclocal.m4 3128 cd '$(srcdir)' && autoconf 3129 3130# autoheader might not change config.h.in, so touch a stamp file. 3131$(srcdir)/config.h.in: stamp-h.in 3132$(srcdir)/stamp-h.in: configure.ac aclocal.m4 3133 cd '$(srcdir)' && autoheader 3134 echo timestamp > '$(srcdir)/stamp-h.in' 3135 3136config.h: stamp-h 3137stamp-h: config.h.in config.status 3138 ./config.status 3139 3140Makefile: Makefile.in config.status 3141 ./config.status 3142 3143config.status: configure 3144 ./config.status --recheck 3145@end group 3146@end example 3147 3148@noindent 3149(Be careful if you copy these lines directly into your makefile, as you 3150need to convert the indented lines to start with the tab character.) 3151 3152In addition, you should use 3153 3154@example 3155AC_CONFIG_FILES([stamp-h], [echo timestamp > stamp-h]) 3156@end example 3157 3158@noindent 3159so @file{config.status} ensures that @file{config.h} is considered up to 3160date. @xref{Output}, for more information about @code{AC_OUTPUT}. 3161 3162@xref{config.status Invocation}, for more examples of handling 3163configuration-related dependencies. 3164 3165@node Configuration Headers 3166@section Configuration Header Files 3167@cindex Configuration Header 3168@cindex @file{config.h} 3169 3170When a package contains more than a few tests that define C preprocessor 3171symbols, the command lines to pass @option{-D} options to the compiler 3172can get quite long. This causes two problems. One is that the 3173@command{make} output is hard to visually scan for errors. More 3174seriously, the command lines can exceed the length limits of some 3175operating systems. As an alternative to passing @option{-D} options to 3176the compiler, @command{configure} scripts can create a C header file 3177containing @samp{#define} directives. The @code{AC_CONFIG_HEADERS} 3178macro selects this kind of output. Though it can be called anywhere 3179between @code{AC_INIT} and @code{AC_OUTPUT}, it is customary to call 3180it right after @code{AC_INIT}. 3181 3182The package should @samp{#include} the configuration header file before 3183any other header files, to prevent inconsistencies in declarations (for 3184example, if it redefines @code{const}). 3185 3186To provide for VPATH builds, remember to pass the C compiler a @option{-I.} 3187option (or @option{-I..}; whichever directory contains @file{config.h}). 3188Even if you use @samp{#include "config.h"}, the preprocessor searches only 3189the directory of the currently read file, i.e., the source directory, not 3190the build directory. 3191 3192With the appropriate @option{-I} option, you can use 3193@samp{#include <config.h>}. Actually, it's a good habit to use it, 3194because in the rare case when the source directory contains another 3195@file{config.h}, the build directory should be searched first. 3196 3197 3198@defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds}) 3199@acindex{CONFIG_HEADERS} 3200@cvindex HAVE_CONFIG_H 3201This macro is one of the instantiating macros; see @ref{Configuration 3202Actions}. Make @code{AC_OUTPUT} create the file(s) in the 3203blank-or-newline-separated list @var{header} containing C preprocessor 3204@code{#define} statements, and replace @samp{@@DEFS@@} in generated 3205files with @option{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}. 3206The usual name for @var{header} is @file{config.h}. 3207 3208If @var{header} already exists and its contents are identical to what 3209@code{AC_OUTPUT} would put in it, it is left alone. Doing this allows 3210making some changes in the configuration without needlessly causing 3211object files that depend on the header file to be recompiled. 3212 3213Usually the input file is named @file{@var{header}.in}; however, you can 3214override the input file name by appending to @var{header} a 3215colon-separated list of input files. For example, you might need to make 3216the input file name acceptable to DOS variants: 3217 3218@example 3219AC_CONFIG_HEADERS([config.h:config.hin]) 3220@end example 3221 3222@end defmac 3223 3224@defmac AH_HEADER 3225@ahindex{HEADER} 3226This macro is defined as the name of the first declared config header 3227and undefined if no config headers have been declared up to this point. 3228A third-party macro may, for example, require use of a config header 3229without invoking AC_CONFIG_HEADERS twice, like this: 3230 3231@example 3232AC_CONFIG_COMMANDS_PRE( 3233 [m4_ifndef([AH_HEADER], [AC_CONFIG_HEADERS([config.h])])]) 3234@end example 3235 3236@end defmac 3237 3238@xref{Configuration Actions}, for more details on @var{header}. 3239 3240@menu 3241* Header Templates:: Input for the configuration headers 3242* autoheader Invocation:: How to create configuration templates 3243* Autoheader Macros:: How to specify CPP templates 3244@end menu 3245 3246@node Header Templates 3247@subsection Configuration Header Templates 3248@cindex Configuration Header Template 3249@cindex Header templates 3250@cindex @file{config.h.in} 3251 3252Your distribution should contain a template file that looks as you want 3253the final header file to look, including comments, with @code{#undef} 3254statements which are used as hooks. For example, suppose your 3255@file{configure.ac} makes these calls: 3256 3257@example 3258AC_CONFIG_HEADERS([conf.h]) 3259AC_CHECK_HEADERS([unistd.h]) 3260@end example 3261 3262@noindent 3263Then you could have code like the following in @file{conf.h.in}. 3264The @file{conf.h} created by @command{configure} defines @samp{HAVE_UNISTD_H} 3265to 1, if and only if the system has @file{unistd.h}. 3266 3267@example 3268@group 3269/* Define as 1 if you have unistd.h. */ 3270#undef HAVE_UNISTD_H 3271@end group 3272@end example 3273 3274The format of the template file is stricter than what the C preprocessor 3275is required to accept. A directive line should contain only whitespace, 3276@samp{#undef}, and @samp{HAVE_UNISTD_H}. The use of @samp{#define} 3277instead of @samp{#undef}, or of comments on the same line as 3278@samp{#undef}, is strongly discouraged. Each hook should only be listed 3279once. Other preprocessor lines, such as @samp{#ifdef} or 3280@samp{#include}, are copied verbatim from the template into the 3281generated header. 3282 3283Since it is a tedious task to keep a template header up to date, you may 3284use @command{autoheader} to generate it, see @ref{autoheader Invocation}. 3285 3286During the instantiation of the header, each @samp{#undef} line in the 3287template file for each symbol defined by @samp{AC_DEFINE} is changed to an 3288appropriate @samp{#define}. If the corresponding @samp{AC_DEFINE} has not 3289been executed during the @command{configure} run, the @samp{#undef} line is 3290commented out. (This is important, e.g., for @samp{_POSIX_SOURCE}: 3291on many systems, it can be implicitly defined by the compiler, and 3292undefining it in the header would then break compilation of subsequent 3293headers.) 3294 3295Currently, @emph{all} remaining @samp{#undef} lines in the header 3296template are commented out, whether or not there was a corresponding 3297@samp{AC_DEFINE} for the macro name; but this behavior is not guaranteed 3298for future releases of Autoconf. 3299 3300Generally speaking, since you should not use @samp{#define}, and you 3301cannot guarantee whether a @samp{#undef} directive in the header 3302template will be converted to a @samp{#define} or commented out in the 3303generated header file, the template file cannot be used for conditional 3304definition effects. Consequently, if you need to use the construct 3305 3306@example 3307@group 3308#ifdef THIS 3309# define THAT 3310#endif 3311@end group 3312@end example 3313 3314@noindent 3315you must place it outside of the template. 3316If you absolutely need to hook it to the config header itself, please put 3317the directives to a separate file, and @samp{#include} that file from the 3318config header template. If you are using @command{autoheader}, you would 3319probably use @samp{AH_BOTTOM} to append the @samp{#include} directive. 3320 3321 3322@node autoheader Invocation 3323@subsection Using @command{autoheader} to Create @file{config.h.in} 3324@cindex @command{autoheader} 3325 3326The @command{autoheader} program can create a template file of C 3327@samp{#define} statements for @command{configure} to use. 3328It searches for the first invocation of @code{AC_CONFIG_HEADERS} in 3329@file{configure} sources to determine the name of the template. 3330(If the first call of @code{AC_CONFIG_HEADERS} specifies more than one 3331input file name, @command{autoheader} uses the first one.) 3332 3333It is recommended that only one input file is used. If you want to append 3334a boilerplate code, it is preferable to use 3335@samp{AH_BOTTOM([#include <conf_post.h>])}. 3336File @file{conf_post.h} is not processed during the configuration then, 3337which make things clearer. Analogically, @code{AH_TOP} can be used to 3338prepend a boilerplate code. 3339 3340In order to do its job, @command{autoheader} needs you to document all 3341of the symbols that you might use. Typically this is done via an 3342@code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED} call whose first argument 3343is a literal symbol and whose third argument describes the symbol 3344(@pxref{Defining Symbols}). Alternatively, you can use 3345@code{AH_TEMPLATE} (@pxref{Autoheader Macros}), or you can supply a 3346suitable input file for a subsequent configuration header file. 3347Symbols defined by Autoconf's builtin tests are already documented properly; 3348you need to document only those that you 3349define yourself. 3350 3351You might wonder why @command{autoheader} is needed: after all, why 3352would @command{configure} need to ``patch'' a @file{config.h.in} to 3353produce a @file{config.h} instead of just creating @file{config.h} from 3354scratch? Well, when everything rocks, the answer is just that we are 3355wasting our time maintaining @command{autoheader}: generating 3356@file{config.h} directly is all that is needed. When things go wrong, 3357however, you'll be thankful for the existence of @command{autoheader}. 3358 3359The fact that the symbols are documented is important in order to 3360@emph{check} that @file{config.h} makes sense. The fact that there is a 3361well-defined list of symbols that should be defined (or not) is 3362also important for people who are porting packages to environments where 3363@command{configure} cannot be run: they just have to @emph{fill in the 3364blanks}. 3365 3366But let's come back to the point: the invocation of @command{autoheader}@dots{} 3367 3368If you give @command{autoheader} an argument, it uses that file instead 3369of @file{configure.ac} and writes the header file to the standard output 3370instead of to @file{config.h.in}. If you give @command{autoheader} an 3371argument of @option{-}, it reads the standard input instead of 3372@file{configure.ac} and writes the header file to the standard output. 3373 3374@command{autoheader} accepts the following options: 3375 3376@table @option 3377@item --help 3378@itemx -h 3379Print a summary of the command line options and exit. 3380 3381@item --version 3382@itemx -V 3383Print the version number of Autoconf and exit. 3384 3385@item --verbose 3386@itemx -v 3387Report processing steps. 3388 3389@item --debug 3390@itemx -d 3391Don't remove the temporary files. 3392 3393@item --force 3394@itemx -f 3395Remake the template file even if newer than its input files. 3396 3397@item --include=@var{dir} 3398@itemx -I @var{dir} 3399Append @var{dir} to the include path. Multiple invocations accumulate. 3400 3401@item --prepend-include=@var{dir} 3402@itemx -B @var{dir} 3403Prepend @var{dir} to the include path. Multiple invocations accumulate. 3404 3405@item --warnings=@var{category} 3406@itemx -W @var{category} 3407@evindex WARNINGS 3408Report the warnings related to @var{category} (which can actually be a 3409comma separated list). Current categories include: 3410 3411@table @samp 3412@item obsolete 3413report the uses of obsolete constructs 3414 3415@item all 3416report all the warnings 3417 3418@item none 3419report none 3420 3421@item error 3422treats warnings as errors 3423 3424@item no-@var{category} 3425disable warnings falling into @var{category} 3426@end table 3427 3428@end table 3429 3430 3431 3432@node Autoheader Macros 3433@subsection Autoheader Macros 3434@cindex Autoheader macros 3435 3436@command{autoheader} scans @file{configure.ac} and figures out which C 3437preprocessor symbols it might define. It knows how to generate 3438templates for symbols defined by @code{AC_CHECK_HEADERS}, 3439@code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional 3440symbol, you must define a template for it. If there are missing 3441templates, @command{autoheader} fails with an error message. 3442 3443The template for a @var{symbol} is created 3444by @command{autoheader} from 3445the @var{description} argument to an @code{AC_DEFINE}; 3446see @ref{Defining Symbols}. 3447 3448For special needs, you can use the following macros. 3449 3450 3451@defmac AH_TEMPLATE (@var{key}, @var{description}) 3452@ahindex{TEMPLATE} 3453Tell @command{autoheader} to generate a template for @var{key}. This macro 3454generates standard templates just like @code{AC_DEFINE} when a 3455@var{description} is given. 3456 3457For example: 3458 3459@example 3460AH_TEMPLATE([CRAY_STACKSEG_END], 3461 [Define to one of _getb67, GETB67, getb67 3462 for Cray-2 and Cray-YMP systems. This 3463 function is required for alloca.c support 3464 on those systems.]) 3465@end example 3466 3467@noindent 3468generates the following template, with the description properly 3469justified. 3470 3471@example 3472/* Define to one of _getb67, GETB67, getb67 for Cray-2 and 3473 Cray-YMP systems. This function is required for alloca.c 3474 support on those systems. */ 3475#undef CRAY_STACKSEG_END 3476@end example 3477@end defmac 3478 3479 3480@defmac AH_VERBATIM (@var{key}, @var{template}) 3481@ahindex{VERBATIM} 3482Tell @command{autoheader} to include the @var{template} as-is in the header 3483template file. This @var{template} is associated with the @var{key}, 3484which is used to sort all the different templates and guarantee their 3485uniqueness. It should be a symbol that can be defined via @code{AC_DEFINE}. 3486@end defmac 3487 3488 3489@defmac AH_TOP (@var{text}) 3490@ahindex{TOP} 3491Include @var{text} at the top of the header template file. 3492@end defmac 3493 3494 3495@defmac AH_BOTTOM (@var{text}) 3496@ahindex{BOTTOM} 3497Include @var{text} at the bottom of the header template file. 3498@end defmac 3499 3500 3501Please note that @var{text} gets included ``verbatim'' to the template file, 3502not to the resulting config header, so it can easily get mangled when the 3503template is processed. There is rarely a need for something other than 3504 3505@example 3506AH_BOTTOM([#include <custom.h>]) 3507@end example 3508 3509 3510 3511@node Configuration Commands 3512@section Running Arbitrary Configuration Commands 3513@cindex Configuration commands 3514@cindex Commands for configuration 3515 3516You can execute arbitrary commands before, during, and after 3517@file{config.status} is run. The three following macros accumulate the 3518commands to run when they are called multiple times. 3519@code{AC_CONFIG_COMMANDS} replaces the obsolete macro 3520@code{AC_OUTPUT_COMMANDS}; see @ref{Obsolete Macros}, for details. 3521 3522@anchor{AC_CONFIG_COMMANDS} 3523@defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds}) 3524@acindex{CONFIG_COMMANDS} 3525Specify additional shell commands to run at the end of 3526@file{config.status}, and shell commands to initialize any variables 3527from @command{configure}. Associate the commands with @var{tag}. 3528Since typically the @var{cmds} create a file, @var{tag} should 3529naturally be the name of that file. If needed, the directory hosting 3530@var{tag} is created. This macro is one of the instantiating macros; 3531see @ref{Configuration Actions}. 3532 3533Here is an unrealistic example: 3534@example 3535fubar=42 3536AC_CONFIG_COMMANDS([fubar], 3537 [echo this is extra $fubar, and so on.], 3538 [fubar=$fubar]) 3539@end example 3540 3541Here is a better one: 3542@example 3543AC_CONFIG_COMMANDS([timestamp], [date >timestamp]) 3544@end example 3545@end defmac 3546 3547The following two macros look similar, but in fact they are not of the same 3548breed: they are executed directly by @file{configure}, so you cannot use 3549@file{config.status} to rerun them. 3550 3551@c Yet it is good to leave them here. The user sees them together and 3552@c decides which best fits their needs. 3553 3554@defmac AC_CONFIG_COMMANDS_PRE (@var{cmds}) 3555@acindex{CONFIG_COMMANDS_PRE} 3556Execute the @var{cmds} right before creating @file{config.status}. 3557 3558This macro presents the last opportunity to call @code{AC_SUBST}, 3559@code{AC_DEFINE}, or @code{AC_CONFIG_@var{ITEMS}} macros. 3560@end defmac 3561 3562@defmac AC_CONFIG_COMMANDS_POST (@var{cmds}) 3563@acindex{CONFIG_COMMANDS_POST} 3564Execute the @var{cmds} right after creating @file{config.status}. 3565@end defmac 3566 3567 3568 3569 3570@node Configuration Links 3571@section Creating Configuration Links 3572@cindex Configuration links 3573@cindex Links for configuration 3574 3575You may find it convenient to create links whose destinations depend upon 3576results of tests. One can use @code{AC_CONFIG_COMMANDS} but the 3577creation of relative symbolic links can be delicate when the package is 3578built in a directory different from the source directory. 3579 3580@anchor{AC_CONFIG_LINKS} 3581@defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @ 3582 @ovar{init-cmds}) 3583@acindex{CONFIG_LINKS} 3584@cindex Links 3585Make @code{AC_OUTPUT} link each of the existing files @var{source} to 3586the corresponding link name @var{dest}. Makes a symbolic link if 3587possible, otherwise a hard link if possible, otherwise a copy. The 3588@var{dest} and @var{source} names should be relative to the top level 3589source or build directory. This macro is one of the instantiating 3590macros; see @ref{Configuration Actions}. 3591 3592For example, this call: 3593 3594@example 3595AC_CONFIG_LINKS([host.h:config/$machine.h 3596 object.h:config/$obj_format.h]) 3597@end example 3598 3599@noindent 3600creates in the current directory @file{host.h} as a link to 3601@file{@var{srcdir}/config/$machine.h}, and @file{object.h} as a 3602link to @file{@var{srcdir}/config/$obj_format.h}. 3603 3604The tempting value @samp{.} for @var{dest} is invalid: it makes it 3605impossible for @samp{config.status} to guess the links to establish. 3606 3607One can then run: 3608@example 3609./config.status host.h object.h 3610@end example 3611@noindent 3612to create the links. 3613@end defmac 3614 3615 3616 3617@node Subdirectories 3618@section Configuring Other Packages in Subdirectories 3619@cindex Configure subdirectories 3620@cindex Subdirectory configure 3621 3622In most situations, calling @code{AC_OUTPUT} is sufficient to produce 3623makefiles in subdirectories. However, @command{configure} scripts 3624that control more than one independent package can use 3625@code{AC_CONFIG_SUBDIRS} to run @command{configure} scripts for other 3626packages in subdirectories. 3627 3628@defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{}) 3629@acindex{CONFIG_SUBDIRS} 3630@ovindex subdirs 3631Make @code{AC_OUTPUT} run @command{configure} in each subdirectory 3632@var{dir} in the given blank-or-newline-separated list. Each @var{dir} should 3633be a literal, i.e., please do not use: 3634 3635@example 3636@c If you change this example, adjust tests/torture.at:Non-literal AC_CONFIG_SUBDIRS. 3637if test "x$package_foo_enabled" = xyes; then 3638 my_subdirs="$my_subdirs foo" 3639fi 3640AC_CONFIG_SUBDIRS([$my_subdirs]) 3641@end example 3642 3643@noindent 3644because this prevents @samp{./configure --help=recursive} from 3645displaying the options of the package @code{foo}. Instead, you should 3646write: 3647 3648@example 3649if test "x$package_foo_enabled" = xyes; then 3650 AC_CONFIG_SUBDIRS([foo]) 3651fi 3652@end example 3653 3654If a given @var{dir} is not found at @command{configure} run time, a 3655warning is reported; if the subdirectory is optional, write: 3656 3657@example 3658if test -d "$srcdir/foo"; then 3659 AC_CONFIG_SUBDIRS([foo]) 3660fi 3661@end example 3662 3663@c NB: Yes, below we mean configure.in, not configure.ac. 3664If a given @var{dir} contains @command{configure.gnu}, it is run instead 3665of @command{configure}. This is for packages that might use a 3666non-Autoconf script @command{Configure}, which can't be called through a 3667wrapper @command{configure} since it would be the same file on 3668case-insensitive file systems. Likewise, if a @var{dir} contains 3669@file{configure.in} but no @command{configure}, the Cygnus 3670@command{configure} script found by @code{AC_CONFIG_AUX_DIR} is used. 3671 3672The subdirectory @command{configure} scripts are given the same command 3673line options that were given to this @command{configure} script, with minor 3674changes if needed, which include: 3675 3676@itemize @minus 3677@item 3678adjusting a relative name for the cache file; 3679 3680@item 3681adjusting a relative name for the source directory; 3682 3683@item 3684propagating the current value of @code{$prefix}, including if it was 3685defaulted, and if the default values of the top level and of the subdirectory 3686@file{configure} differ. 3687@end itemize 3688 3689This macro also sets the output variable @code{subdirs} to the list of 3690directories @samp{@var{dir} @dots{}}. Make rules can use 3691this variable to determine which subdirectories to recurse into. 3692 3693This macro may be called multiple times. 3694@end defmac 3695 3696@node Default Prefix 3697@section Default Prefix 3698@cindex Install prefix 3699@cindex Prefix for install 3700 3701By default, @command{configure} sets the prefix for files it installs to 3702@file{/usr/local}. The user of @command{configure} can select a different 3703prefix using the @option{--prefix} and @option{--exec-prefix} options. 3704There are two ways to change the default: when creating 3705@command{configure}, and when running it. 3706 3707Some software packages might want to install in a directory other than 3708@file{/usr/local} by default. To accomplish that, use the 3709@code{AC_PREFIX_DEFAULT} macro. 3710 3711@defmac AC_PREFIX_DEFAULT (@var{prefix}) 3712@acindex{PREFIX_DEFAULT} 3713Set the default installation prefix to @var{prefix} instead of 3714@file{/usr/local}. 3715@end defmac 3716 3717It may be convenient for users to have @command{configure} guess the 3718installation prefix from the location of a related program that they 3719have already installed. If you wish to do that, you can call 3720@code{AC_PREFIX_PROGRAM}. 3721 3722@anchor{AC_PREFIX_PROGRAM} 3723@defmac AC_PREFIX_PROGRAM (@var{program}) 3724@acindex{PREFIX_PROGRAM} 3725If the user did not specify an installation prefix (using the 3726@option{--prefix} option), guess a value for it by looking for 3727@var{program} in @env{PATH}, the way the shell does. If @var{program} 3728is found, set the prefix to the parent of the directory containing 3729@var{program}, else default the prefix as described above 3730(@file{/usr/local} or @code{AC_PREFIX_DEFAULT}). For example, if 3731@var{program} is @code{gcc} and the @env{PATH} contains 3732@file{/usr/local/gnu/bin/gcc}, set the prefix to @file{/usr/local/gnu}. 3733@end defmac 3734 3735 3736 3737@c ======================================================== Existing tests 3738 3739@node Existing Tests 3740@chapter Existing Tests 3741 3742These macros test for particular system features that packages might 3743need or want to use. If you need to test for a kind of feature that 3744none of these macros check for, you can probably do it by calling 3745primitive test macros with appropriate arguments (@pxref{Writing 3746Tests}). 3747 3748These tests print messages telling the user which feature they're 3749checking for, and what they find. They cache their results for future 3750@command{configure} runs (@pxref{Caching Results}). 3751 3752Some of these macros set output variables. @xref{Makefile 3753Substitutions}, for how to get their values. The phrase ``define 3754@var{name}'' is used below as a shorthand to mean ``define the C 3755preprocessor symbol @var{name} to the value 1''. @xref{Defining 3756Symbols}, for how to get those symbol definitions into your program. 3757 3758@menu 3759* Common Behavior:: Macros' standard schemes 3760* Alternative Programs:: Selecting between alternative programs 3761* Files:: Checking for the existence of files 3762* Libraries:: Library archives that might be missing 3763* Library Functions:: C library functions that might be missing 3764* Header Files:: Header files that might be missing 3765* Declarations:: Declarations that may be missing 3766* Structures:: Structures or members that might be missing 3767* Types:: Types that might be missing 3768* Compilers and Preprocessors:: Checking for compiling programs 3769* System Services:: Operating system services 3770* Posix Variants:: Special kludges for specific Posix variants 3771* Erlang Libraries:: Checking for the existence of Erlang libraries 3772@end menu 3773 3774@node Common Behavior 3775@section Common Behavior 3776@cindex Common autoconf behavior 3777 3778Much effort has been expended to make Autoconf easy to learn. The most 3779obvious way to reach this goal is simply to enforce standard interfaces 3780and behaviors, avoiding exceptions as much as possible. Because of 3781history and inertia, unfortunately, there are still too many exceptions 3782in Autoconf; nevertheless, this section describes some of the common 3783rules. 3784 3785@menu 3786* Standard Symbols:: Symbols defined by the macros 3787* Default Includes:: Includes used by the generic macros 3788@end menu 3789 3790@node Standard Symbols 3791@subsection Standard Symbols 3792@cindex Standard symbols 3793 3794All the generic macros that @code{AC_DEFINE} a symbol as a result of 3795their test transform their @var{argument} values to a standard alphabet. 3796First, @var{argument} is converted to upper case and any asterisks 3797(@samp{*}) are each converted to @samp{P}. Any remaining characters 3798that are not alphanumeric are converted to underscores. 3799 3800For instance, 3801 3802@example 3803AC_CHECK_TYPES([struct $Expensive*]) 3804@end example 3805 3806@noindent 3807defines the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check 3808succeeds. 3809 3810 3811@node Default Includes 3812@subsection Default Includes 3813@cindex Default includes 3814@cindex Includes, default 3815 3816Several tests depend upon a set of header files. Since these headers 3817are not universally available, tests actually have to provide a set of 3818protected includes, such as: 3819 3820@example 3821@group 3822#ifdef TIME_WITH_SYS_TIME 3823# include <sys/time.h> 3824# include <time.h> 3825#else 3826# ifdef HAVE_SYS_TIME_H 3827# include <sys/time.h> 3828# else 3829# include <time.h> 3830# endif 3831#endif 3832@end group 3833@end example 3834 3835@noindent 3836Unless you know exactly what you are doing, you should avoid using 3837unconditional includes, and check the existence of the headers you 3838include beforehand (@pxref{Header Files}). 3839 3840Most generic macros use the following macro to provide the default set 3841of includes: 3842 3843@defmac AC_INCLUDES_DEFAULT (@ovar{include-directives}) 3844@acindex{INCLUDES_DEFAULT} 3845Expand to @var{include-directives} if defined, otherwise to: 3846 3847@example 3848@group 3849#include <stdio.h> 3850#ifdef HAVE_SYS_TYPES_H 3851# include <sys/types.h> 3852#endif 3853#ifdef HAVE_SYS_STAT_H 3854# include <sys/stat.h> 3855#endif 3856#ifdef STDC_HEADERS 3857# include <stdlib.h> 3858# include <stddef.h> 3859#else 3860# ifdef HAVE_STDLIB_H 3861# include <stdlib.h> 3862# endif 3863#endif 3864#ifdef HAVE_STRING_H 3865# if !defined STDC_HEADERS && defined HAVE_MEMORY_H 3866# include <memory.h> 3867# endif 3868# include <string.h> 3869#endif 3870#ifdef HAVE_STRINGS_H 3871# include <strings.h> 3872#endif 3873#ifdef HAVE_INTTYPES_H 3874# include <inttypes.h> 3875#endif 3876#ifdef HAVE_STDINT_H 3877# include <stdint.h> 3878#endif 3879#ifdef HAVE_UNISTD_H 3880# include <unistd.h> 3881#endif 3882@end group 3883@end example 3884 3885If the default includes are used, then check for the presence of these 3886headers and their compatibility, i.e., you don't need to run 3887@code{AC_HEADER_STDC}, nor check for @file{stdlib.h} etc. 3888 3889These headers are checked for in the same order as they are included. 3890For instance, on some systems @file{string.h} and @file{strings.h} both 3891exist, but conflict. Then @code{HAVE_STRING_H} is defined, not 3892@code{HAVE_STRINGS_H}. 3893@end defmac 3894 3895@node Alternative Programs 3896@section Alternative Programs 3897@cindex Programs, checking 3898 3899These macros check for the presence or behavior of particular programs. 3900They are used to choose between several alternative programs and to 3901decide what to do once one has been chosen. If there is no macro 3902specifically defined to check for a program you need, and you don't need 3903to check for any special properties of it, then you can use one of the 3904general program-check macros. 3905 3906@menu 3907* Particular Programs:: Special handling to find certain programs 3908* Generic Programs:: How to find other programs 3909@end menu 3910 3911@node Particular Programs 3912@subsection Particular Program Checks 3913 3914These macros check for particular programs---whether they exist, and 3915in some cases whether they support certain features. 3916 3917@defmac AC_PROG_AWK 3918@acindex{PROG_AWK} 3919@ovindex AWK 3920@caindex prog_AWK 3921Check for @code{gawk}, @code{mawk}, @code{nawk}, and @code{awk}, in that 3922order, and set output variable @code{AWK} to the first one that is found. 3923It tries @code{gawk} first because that is reported to be the 3924best implementation. The result can be overridden by setting the 3925variable @code{AWK} or the cache variable @code{ac_cv_prog_AWK}. 3926 3927Using this macro is sufficient to avoid the pitfalls of traditional 3928@command{awk} (@pxref{awk, , Limitations of Usual Tools}). 3929@end defmac 3930 3931@defmac AC_PROG_GREP 3932@acindex{PROG_GREP} 3933@ovindex GREP 3934@caindex prog_GREP 3935Look for the best available @code{grep} or @code{ggrep} that accepts the 3936longest input lines possible, and that supports multiple @option{-e} options. 3937Set the output variable @code{GREP} to whatever is chosen. 3938@xref{grep, , Limitations of Usual Tools}, for more information about 3939portability problems with the @command{grep} command family. The result 3940can be overridden by setting the @code{GREP} variable and is cached in the 3941@code{ac_cv_path_GREP} variable. 3942@end defmac 3943 3944@defmac AC_PROG_EGREP 3945@acindex{PROG_EGREP} 3946@ovindex EGREP 3947@caindex prog_EGREP 3948Check whether @code{$GREP -E} works, or else look for the best available 3949@code{egrep} or @code{gegrep} that accepts the longest input lines possible. 3950Set the output variable @code{EGREP} to whatever is chosen. The result 3951can be overridden by setting the @code{EGREP} variable and is cached in the 3952@code{ac_cv_path_EGREP} variable. 3953@end defmac 3954 3955@defmac AC_PROG_FGREP 3956@acindex{PROG_FGREP} 3957@ovindex FGREP 3958@caindex prog_FGREP 3959Check whether @code{$GREP -F} works, or else look for the best available 3960@code{fgrep} or @code{gfgrep} that accepts the longest input lines possible. 3961Set the output variable @code{FGREP} to whatever is chosen. The result 3962can be overridden by setting the @code{FGREP} variable and is cached in the 3963@code{ac_cv_path_FGREP} variable. 3964@end defmac 3965 3966@defmac AC_PROG_INSTALL 3967@acindex{PROG_INSTALL} 3968@ovindex INSTALL 3969@ovindex INSTALL_PROGRAM 3970@ovindex INSTALL_DATA 3971@ovindex INSTALL_SCRIPT 3972@caindex path_install 3973Set output variable @code{INSTALL} to the name of a BSD-compatible 3974@command{install} program, if one is found in the current @env{PATH}. 3975Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c}, 3976checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its 3977default directories) to determine @var{dir} (@pxref{Output}). Also set 3978the variables @code{INSTALL_PROGRAM} and @code{INSTALL_SCRIPT} to 3979@samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}. 3980 3981@samp{@@INSTALL@@} is special, as its value may vary for different 3982configuration files. 3983 3984This macro screens out various instances of @command{install} known not to 3985work. It prefers to find a C program rather than a shell script, for 3986speed. Instead of @file{install-sh}, it can also use @file{install.sh}, 3987but that name is obsolete because some @command{make} programs have a rule 3988that creates @file{install} from it if there is no makefile. Further, this 3989macro requires @command{install} to be able to install multiple files into a 3990target directory in a single invocation. 3991 3992Autoconf comes with a copy of @file{install-sh} that you can use. If 3993you use @code{AC_PROG_INSTALL}, you must include either 3994@file{install-sh} or @file{install.sh} in your distribution; otherwise 3995@command{configure} produces an error message saying it can't find 3996them---even if the system you're on has a good @command{install} program. 3997This check is a safety measure to prevent you from accidentally leaving 3998that file out, which would prevent your package from installing on 3999systems that don't have a BSD-compatible @command{install} program. 4000 4001If you need to use your own installation program because it has features 4002not found in standard @command{install} programs, there is no reason to use 4003@code{AC_PROG_INSTALL}; just put the file name of your program into your 4004@file{Makefile.in} files. 4005 4006The result of the test can be overridden by setting the variable 4007@code{INSTALL} or the cache variable @code{ac_cv_path_install}. 4008@end defmac 4009 4010@defmac AC_PROG_MKDIR_P 4011@acindex{PROG_MKDIR_P} 4012@ovindex MKDIR_P 4013@caindex path_mkdir 4014Set output variable @code{MKDIR_P} to a program that ensures that for 4015each argument, a directory named by this argument exists, creating it 4016and its parent directories if needed, and without race conditions when 4017two instances of the program attempt to make the same directory at 4018nearly the same time. 4019 4020This macro uses the @samp{mkdir -p} command if possible. Otherwise, it 4021falls back on invoking @command{install-sh} with the @option{-d} option, 4022so your package should 4023contain @file{install-sh} as described under @code{AC_PROG_INSTALL}. 4024An @file{install-sh} file that predates Autoconf 2.60 or Automake 1.10 4025is vulnerable to race conditions, so if you want to support parallel 4026installs from 4027different packages into the same directory you need to make sure you 4028have an up-to-date @file{install-sh}. In particular, be careful about 4029using @samp{autoreconf -if} if your Automake predates Automake 1.10. 4030 4031This macro is related to the @code{AS_MKDIR_P} macro (@pxref{Programming 4032in M4sh}), but it sets an output variable intended for use in other 4033files, whereas @code{AS_MKDIR_P} is intended for use in scripts like 4034@command{configure}. Also, @code{AS_MKDIR_P} does not accept options, 4035but @code{MKDIR_P} supports the @option{-m} option, e.g., a makefile 4036might invoke @code{$(MKDIR_P) -m 0 dir} to create an inaccessible 4037directory, and conversely a makefile should use @code{$(MKDIR_P) -- 4038$(FOO)} if @var{FOO} might yield a value that begins with @samp{-}. 4039Finally, @code{AS_MKDIR_P} does not check for race condition 4040vulnerability, whereas @code{AC_PROG_MKDIR_P} does. 4041 4042@samp{@@MKDIR_P@@} is special, as its value may vary for different 4043configuration files. 4044 4045The result of the test can be overridden by setting the variable 4046@code{MKDIR_P} or the cache variable @code{ac_cv_path_mkdir}. 4047@end defmac 4048 4049@anchor{AC_PROG_LEX} 4050@defmac AC_PROG_LEX 4051@acindex{PROG_LEX} 4052@ovindex LEX 4053@ovindex LEXLIB 4054@cvindex YYTEXT_POINTER 4055@ovindex LEX_OUTPUT_ROOT 4056@caindex prog_LEX 4057If @code{flex} is found, set output variable @code{LEX} to @samp{flex} 4058and @code{LEXLIB} to @option{-lfl}, if that library is in a standard 4059place. Otherwise set @code{LEX} to @samp{lex} and @code{LEXLIB} to 4060@option{-ll}, if found. If neither variant is available, set @code{LEX} 4061to @samp{:}; for packages that ship the generated @file{file.yy.c} 4062alongside the source @file{file.l}, this default allows users without a 4063lexer generator to still build the package even if the timestamp for 4064@file{file.l} is inadvertently changed. 4065 4066Define @code{YYTEXT_POINTER} if @code{yytext} defaults to @samp{char *} instead 4067of to @samp{char []}. Also set output variable @code{LEX_OUTPUT_ROOT} to 4068the base of the file name that the lexer generates; usually 4069@file{lex.yy}, but sometimes something else. These results vary 4070according to whether @code{lex} or @code{flex} is being used. 4071 4072You are encouraged to use Flex in your sources, since it is both more 4073pleasant to use than plain Lex and the C source it produces is portable. 4074In order to ensure portability, however, you must either provide a 4075function @code{yywrap} or, if you don't use it (e.g., your scanner has 4076no @samp{#include}-like feature), simply include a @samp{%noyywrap} 4077statement in the scanner's source. Once this done, the scanner is 4078portable (unless @emph{you} felt free to use nonportable constructs) and 4079does not depend on any library. In this case, and in this case only, it 4080is suggested that you use this Autoconf snippet: 4081 4082@example 4083AC_PROG_LEX 4084if test "x$LEX" != xflex; then 4085 LEX="$SHELL $missing_dir/missing flex" 4086 AC_SUBST([LEX_OUTPUT_ROOT], [lex.yy]) 4087 AC_SUBST([LEXLIB], ['']) 4088fi 4089@end example 4090 4091The shell script @command{missing} can be found in the Automake 4092distribution. 4093 4094Remember that the user may have supplied an alternate location in 4095@env{LEX}, so if Flex is required, it is better to check that the user 4096provided something sufficient by parsing the output of @samp{$LEX 4097--version} than by simply relying on @code{test "x$LEX" = xflex}. 4098 4099To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes 4100(indirectly) this macro twice, which causes an annoying but benign 4101``@code{AC_PROG_LEX} invoked multiple times'' warning. Future versions 4102of Automake will fix this issue; meanwhile, just ignore this message. 4103 4104As part of running the test, this macro may delete any file in the 4105configuration directory named @file{lex.yy.c} or @file{lexyy.c}. 4106 4107The result of this test can be influenced by setting the variable 4108@code{LEX} or the cache variable @code{ac_cv_prog_LEX}. 4109@end defmac 4110 4111@anchor{AC_PROG_LN_S} 4112@defmac AC_PROG_LN_S 4113@acindex{PROG_LN_S} 4114@ovindex LN_S 4115If @samp{ln -s} works on the current file system (the operating system 4116and file system support symbolic links), set the output variable 4117@code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set 4118@code{LN_S} to @samp{ln}, and otherwise set it to @samp{cp -pR}. 4119 4120If you make a link in a directory other than the current directory, its 4121meaning depends on whether @samp{ln} or @samp{ln -s} is used. To safely 4122create links using @samp{$(LN_S)}, either find out which form is used 4123and adjust the arguments, or always invoke @code{ln} in the directory 4124where the link is to be created. 4125 4126In other words, it does not work to do: 4127@example 4128$(LN_S) foo /x/bar 4129@end example 4130 4131Instead, do: 4132 4133@example 4134(cd /x && $(LN_S) foo bar) 4135@end example 4136@end defmac 4137 4138@defmac AC_PROG_RANLIB 4139@acindex{PROG_RANLIB} 4140@ovindex RANLIB 4141@c @caindex prog_RANLIB 4142@c @caindex prog_ac_ct_RANLIB 4143Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib} 4144is found, and otherwise to @samp{:} (do nothing). 4145@end defmac 4146 4147@defmac AC_PROG_SED 4148@acindex{PROG_SED} 4149@ovindex SED 4150@caindex path_SED 4151Set output variable @code{SED} to a Sed implementation that conforms to 4152Posix and does not have arbitrary length limits. Report an error if no 4153acceptable Sed is found. @xref{sed, , Limitations of Usual Tools}, for more 4154information about portability problems with Sed. 4155 4156The result of this test can be overridden by setting the @code{SED} variable 4157and is cached in the @code{ac_cv_path_SED} variable. 4158@end defmac 4159 4160@defmac AC_PROG_YACC 4161@acindex{PROG_YACC} 4162@evindex YACC 4163@evindex YFLAGS 4164@ovindex YACC 4165@caindex prog_YACC 4166If @code{bison} is found, set output variable @code{YACC} to @samp{bison 4167-o y.tab.c}. Otherwise, if @code{byacc} is found, set @code{YACC} to 4168@samp{byacc}. Otherwise set @code{YACC} to @samp{yacc}. 4169The result of this test can be influenced by setting the variable 4170@code{YACC} or the cache variable @code{ac_cv_prog_YACC}. 4171@end defmac 4172 4173@node Generic Programs 4174@subsection Generic Program and File Checks 4175 4176These macros are used to find programs not covered by the ``particular'' 4177test macros. If you need to check the behavior of a program as well as 4178find out whether it is present, you have to write your own test for it 4179(@pxref{Writing Tests}). By default, these macros use the environment 4180variable @env{PATH}. If you need to check for a program that might not 4181be in the user's @env{PATH}, you can pass a modified path to use 4182instead, like this: 4183 4184@example 4185AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd], 4186 [$PATH$PATH_SEPARATOR/usr/libexec$PATH_SEPARATOR]dnl 4187[/usr/sbin$PATH_SEPARATOR/usr/etc$PATH_SEPARATOR/etc]) 4188@end example 4189 4190You are strongly encouraged to declare the @var{variable} passed to 4191@code{AC_CHECK_PROG} etc.@: as precious. @xref{Setting Output Variables}, 4192@code{AC_ARG_VAR}, for more details. 4193 4194@anchor{AC_CHECK_PROG} 4195@defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @ 4196 @var{value-if-found}, @ovar{value-if-not-found}, @dvar{path, $PATH}, @ 4197 @ovar{reject}) 4198@acindex{CHECK_PROG} 4199@caindex prog_@var{variable} 4200Check whether program @var{prog-to-check-for} exists in @var{path}. If 4201it is found, set @var{variable} to @var{value-if-found}, otherwise to 4202@var{value-if-not-found}, if given. Always pass over @var{reject} (an 4203absolute file name) even if it is the first found in the search path; in 4204that case, set @var{variable} using the absolute file name of the 4205@var{prog-to-check-for} found that is not @var{reject}. If 4206@var{variable} was already set, do nothing. Calls @code{AC_SUBST} for 4207@var{variable}. The result of this test can be overridden by setting the 4208@var{variable} variable or the cache variable 4209@code{ac_cv_prog_@var{variable}}. 4210@end defmac 4211 4212@anchor{AC_CHECK_PROGS} 4213@defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @ 4214 @ovar{value-if-not-found}, @dvar{path, $PATH}) 4215@acindex{CHECK_PROGS} 4216@caindex prog_@var{variable} 4217Check for each program in the blank-separated list 4218@var{progs-to-check-for} existing in the @var{path}. If one is found, set 4219@var{variable} to the name of that program. Otherwise, continue 4220checking the next program in the list. If none of the programs in the 4221list are found, set @var{variable} to @var{value-if-not-found}; if 4222@var{value-if-not-found} is not specified, the value of @var{variable} 4223is not changed. Calls @code{AC_SUBST} for @var{variable}. The result of 4224this test can be overridden by setting the @var{variable} variable or the 4225cache variable @code{ac_cv_prog_@var{variable}}. 4226@end defmac 4227 4228@defmac AC_CHECK_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @ 4229 @ovar{value-if-not-found}, @dvar{path, $PATH}) 4230@acindex{CHECK_TARGET_TOOL} 4231Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for} 4232with a prefix of the target type as determined by 4233@code{AC_CANONICAL_TARGET}, followed by a dash (@pxref{Canonicalizing}). 4234If the tool cannot be found with a prefix, and if the build and target 4235types are equal, then it is also searched for without a prefix. 4236 4237As noted in @ref{Specifying Target Triplets}, the 4238target is rarely specified, because most of the time it is the same 4239as the host: it is the type of system for which any compiler tool in 4240the package produces code. What this macro looks for is, 4241for example, @emph{a tool @r{(assembler, linker, etc.)}@: that the 4242compiler driver @r{(@command{gcc} for the GNU C Compiler)} 4243uses to produce objects, archives or executables}. 4244@end defmac 4245 4246@defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for}, @ 4247 @ovar{value-if-not-found}, @dvar{path, $PATH}) 4248@acindex{CHECK_TOOL} 4249@c @caindex prog_@var{VARIABLE} 4250@c @caindex prog_ac_ct_@var{VARIABLE} 4251Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for} 4252with a prefix of the host type as specified by @option{--host}, followed by a 4253dash. For example, if the user runs 4254@samp{configure --build=x86_64-gnu --host=i386-gnu}, then this call: 4255@example 4256AC_CHECK_TOOL([RANLIB], [ranlib], [:]) 4257@end example 4258@noindent 4259sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in 4260@var{path}, or otherwise to @samp{ranlib} if that program exists in 4261@var{path}, or to @samp{:} if neither program exists. 4262 4263When cross-compiling, this macro will issue a warning if no program 4264prefixed with the host type could be found. 4265For more information, see @ref{Specifying Target Triplets}. 4266@end defmac 4267 4268@defmac AC_CHECK_TARGET_TOOLS (@var{variable}, @var{progs-to-check-for}, @ 4269 @ovar{value-if-not-found}, @dvar{path, $PATH}) 4270@acindex{CHECK_TARGET_TOOLS} 4271Like @code{AC_CHECK_TARGET_TOOL}, each of the tools in the list 4272@var{progs-to-check-for} are checked with a prefix of the target type as 4273determined by @code{AC_CANONICAL_TARGET}, followed by a dash 4274(@pxref{Canonicalizing}). If none of the tools can be found with a 4275prefix, and if the build and target types are equal, then the first one 4276without a prefix is used. If a tool is found, set @var{variable} to 4277the name of that program. If none of the tools in the list are found, 4278set @var{variable} to @var{value-if-not-found}; if @var{value-if-not-found} 4279is not specified, the value of @var{variable} is not changed. Calls 4280@code{AC_SUBST} for @var{variable}. 4281@end defmac 4282 4283@defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @ 4284 @ovar{value-if-not-found}, @dvar{path, $PATH}) 4285@acindex{CHECK_TOOLS} 4286Like @code{AC_CHECK_TOOL}, each of the tools in the list 4287@var{progs-to-check-for} are checked with a prefix of the host type as 4288determined by @code{AC_CANONICAL_HOST}, followed by a dash 4289(@pxref{Canonicalizing}). If none of the tools can be found with a 4290prefix, then the first one without a prefix is used. If a tool is found, 4291set @var{variable} to the name of that program. If none of the tools in 4292the list are found, set @var{variable} to @var{value-if-not-found}; if 4293@var{value-if-not-found} is not specified, the value of @var{variable} 4294is not changed. Calls @code{AC_SUBST} for @var{variable}. 4295 4296When cross-compiling, this macro will issue a warning if no program 4297prefixed with the host type could be found. 4298For more information, see @ref{Specifying Target Triplets}. 4299@end defmac 4300 4301@anchor{AC_PATH_PROG} 4302@defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for}, @ 4303 @ovar{value-if-not-found}, @dvar{path, $PATH}) 4304@acindex{PATH_PROG} 4305@caindex path_@var{variable} 4306Like @code{AC_CHECK_PROG}, but set @var{variable} to the absolute 4307name of @var{prog-to-check-for} if found. The result of this test 4308can be overridden by setting the @var{variable} variable. A positive 4309result of this test is cached in the @code{ac_cv_path_@var{variable}} 4310variable. 4311@end defmac 4312 4313@anchor{AC_PATH_PROGS} 4314@defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for}, @ 4315 @ovar{value-if-not-found}, @dvar{path, $PATH}) 4316@acindex{PATH_PROGS} 4317@caindex path_@var{variable} 4318Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for} 4319are found, set @var{variable} to the absolute name of the program 4320found. The result of this test can be overridden by setting the 4321@var{variable} variable. A positive result of this test is cached in 4322the @code{ac_cv_path_@var{variable}} variable. 4323@end defmac 4324 4325@defmac AC_PATH_PROGS_FEATURE_CHECK (@var{variable}, @ 4326 @var{progs-to-check-for}, @var{feature-test}, @ 4327 @ovar{action-if-not-found}, @dvar{path, $PATH}) 4328@acindex{PATH_PROGS_FEATURE_CHECK} 4329@caindex path_@var{variable} 4330@vrindex ac_path_@var{variable} 4331@vrindex ac_path_@var{variable}_found 4332This macro was introduced in Autoconf 2.62. If @var{variable} is not 4333empty, then set the cache variable @code{ac_cv_path_@var{variable}} to 4334its value. Otherwise, check for each program in the blank-separated 4335list @var{progs-to-check-for} existing in @var{path}. For each program 4336found, execute @var{feature-test} with @code{ac_path_@var{variable}} 4337set to the absolute name of the candidate program. If no invocation of 4338@var{feature-test} sets the shell variable 4339@code{ac_cv_path_@var{variable}}, then @var{action-if-not-found} is 4340executed. @var{feature-test} will be run even when 4341@code{ac_cv_path_@var{variable}} is set, to provide the ability to 4342choose a better candidate found later in @var{path}; to accept the 4343current setting and bypass all further checks, @var{feature-test} can 4344execute @code{ac_path_@var{variable}_found=:}. 4345 4346Note that this macro has some subtle differences from 4347@code{AC_CHECK_PROGS}. It is designed to be run inside 4348@code{AC_CACHE_VAL}, therefore, it should have no side effects. In 4349particular, @var{variable} is not set to the final value of 4350@code{ac_cv_path_@var{variable}}, nor is @code{AC_SUBST} automatically 4351run. Also, on failure, any action can be performed, whereas 4352@code{AC_CHECK_PROGS} only performs 4353@code{@var{variable}=@var{value-if-not-found}}. 4354 4355Here is an example, similar to what Autoconf uses in its own configure 4356script. It will search for an implementation of @command{m4} that 4357supports the @code{indir} builtin, even if it goes by the name 4358@command{gm4} or is not the first implementation on @env{PATH}. 4359 4360@example 4361AC_CACHE_CHECK([for m4 that supports indir], [ac_cv_path_M4], 4362 [AC_PATH_PROGS_FEATURE_CHECK([M4], [m4 gm4], 4363 [[m4out=`echo 'changequote([,])indir([divnum])' | $ac_path_M4` 4364 test "x$m4out" = x0 \ 4365 && ac_cv_path_M4=$ac_path_M4 ac_path_M4_found=:]], 4366 [AC_MSG_ERROR([could not find m4 that supports indir])])]) 4367AC_SUBST([M4], [$ac_cv_path_M4]) 4368@end example 4369@end defmac 4370 4371@defmac AC_PATH_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @ 4372 @ovar{value-if-not-found}, @dvar{path, $PATH}) 4373@acindex{PATH_TARGET_TOOL} 4374Like @code{AC_CHECK_TARGET_TOOL}, but set @var{variable} to the absolute 4375name of the program if it is found. 4376@end defmac 4377 4378@defmac AC_PATH_TOOL (@var{variable}, @var{prog-to-check-for}, @ 4379 @ovar{value-if-not-found}, @dvar{path, $PATH}) 4380@acindex{PATH_TOOL} 4381Like @code{AC_CHECK_TOOL}, but set @var{variable} to the absolute 4382name of the program if it is found. 4383 4384When cross-compiling, this macro will issue a warning if no program 4385prefixed with the host type could be found. 4386For more information, see @ref{Specifying Target Triplets}. 4387@end defmac 4388 4389 4390@node Files 4391@section Files 4392@cindex File, checking 4393 4394You might also need to check for the existence of files. Before using 4395these macros, ask yourself whether a runtime test might not be a better 4396solution. Be aware that, like most Autoconf macros, they test a feature 4397of the host machine, and therefore, they die when cross-compiling. 4398 4399@defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @ 4400 @ovar{action-if-not-found}) 4401@acindex{CHECK_FILE} 4402@caindex file_@var{file} 4403Check whether file @var{file} exists on the native system. If it is 4404found, execute @var{action-if-found}, otherwise do 4405@var{action-if-not-found}, if given. The result of this test is cached 4406in the @code{ac_cv_file_@var{file}} variable, with characters not 4407suitable for a variable name mapped to underscores. 4408@end defmac 4409 4410@defmac AC_CHECK_FILES (@var{files}, @ovar{action-if-found}, @ 4411 @ovar{action-if-not-found}) 4412@acindex{CHECK_FILES} 4413@caindex file_@var{file} 4414Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}. 4415Additionally, defines @samp{HAVE_@var{file}} (@pxref{Standard Symbols}) 4416for each file found. The results of each test are cached in the 4417@code{ac_cv_file_@var{file}} variable, with characters not suitable for 4418a variable name mapped to underscores. 4419@end defmac 4420 4421 4422@node Libraries 4423@section Library Files 4424@cindex Library, checking 4425 4426The following macros check for the presence of certain C, C++, Fortran, 4427or Go library archive files. 4428 4429@anchor{AC_CHECK_LIB} 4430@defmac AC_CHECK_LIB (@var{library}, @var{function}, @ 4431 @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries}) 4432@acindex{CHECK_LIB} 4433@caindex lib_@var{library}_@var{function} 4434Test whether the library @var{library} is available by trying to link 4435a test program that calls function @var{function} with the library. 4436@var{function} should be a function provided by the library. 4437Use the base 4438name of the library; e.g., to check for @option{-lmp}, use @samp{mp} as 4439the @var{library} argument. 4440 4441@var{action-if-found} is a list of shell commands to run if the link 4442with the library succeeds; @var{action-if-not-found} is a list of shell 4443commands to run if the link fails. If @var{action-if-found} is not 4444specified, the default action prepends @option{-l@var{library}} to 4445@code{LIBS} and defines @samp{HAVE_LIB@var{library}} (in all 4446capitals). This macro is intended to support building @code{LIBS} in 4447a right-to-left (least-dependent to most-dependent) fashion such that 4448library dependencies are satisfied as a natural side effect of 4449consecutive tests. Linkers are sensitive to library ordering 4450so the order in which @code{LIBS} is generated is important to reliable 4451detection of libraries. 4452 4453If linking with @var{library} results in unresolved symbols that would 4454be resolved by linking with additional libraries, give those libraries 4455as the @var{other-libraries} argument, separated by spaces: 4456e.g., @option{-lXt -lX11}. Otherwise, this macro may fail to detect 4457that @var{library} is present, because linking the test program can 4458fail with unresolved symbols. The @var{other-libraries} argument 4459should be limited to cases where it is desirable to test for one library 4460in the presence of another that is not already in @code{LIBS}. 4461 4462@code{AC_CHECK_LIB} requires some care in usage, and should be avoided 4463in some common cases. Many standard functions like @code{gethostbyname} 4464appear in the standard C library on some hosts, and in special libraries 4465like @code{nsl} on other hosts. On some hosts the special libraries 4466contain variant implementations that you may not want to use. These 4467days it is normally better to use @code{AC_SEARCH_LIBS([gethostbyname], 4468[nsl])} instead of @code{AC_CHECK_LIB([nsl], [gethostbyname])}. 4469 4470The result of this test is cached in the 4471@code{ac_cv_lib_@var{library}_@var{function}} variable. 4472@end defmac 4473 4474@anchor{AC_SEARCH_LIBS} 4475@defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}, @ 4476 @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries}) 4477@acindex{SEARCH_LIBS} 4478@caindex search_@var{function} 4479Search for a library defining @var{function} if it's not already 4480available. This equates to calling 4481@samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])])} first with 4482no libraries, then for each library listed in @var{search-libs}. 4483 4484Prepend @option{-l@var{library}} to @code{LIBS} for the first library found 4485to contain @var{function}, and run @var{action-if-found}. If the 4486function is not found, run @var{action-if-not-found}. 4487 4488If linking with @var{library} results in unresolved symbols that would 4489be resolved by linking with additional libraries, give those libraries 4490as the @var{other-libraries} argument, separated by spaces: 4491e.g., @option{-lXt -lX11}. Otherwise, this macro fails to detect 4492that @var{function} is present, because linking the test program 4493always fails with unresolved symbols. 4494 4495The result of this test is cached in the 4496@code{ac_cv_search_@var{function}} variable as @samp{none required} if 4497@var{function} is already available, as @samp{no} if no library 4498containing @var{function} was found, otherwise as the 4499@option{-l@var{library}} option that needs to be prepended to @code{LIBS}. 4500@end defmac 4501 4502 4503 4504@node Library Functions 4505@section Library Functions 4506 4507The following macros check for particular C library functions. 4508If there is no macro specifically defined to check for a function you need, 4509and you don't need to check for any special properties of 4510it, then you can use one of the general function-check macros. 4511 4512@menu 4513* Function Portability:: Pitfalls with usual functions 4514* Particular Functions:: Special handling to find certain functions 4515* Generic Functions:: How to find other functions 4516@end menu 4517 4518@node Function Portability 4519@subsection Portability of C Functions 4520@cindex Portability of C functions 4521@cindex C function portability 4522 4523Most usual functions can either be missing, or be buggy, or be limited 4524on some architectures. This section tries to make an inventory of these 4525portability issues. By definition, this list always requires 4526additions. A much more complete list is maintained by the Gnulib 4527project (@pxref{Gnulib}), covering @ref{Function Substitutes, , 4528Current Posix Functions, gnulib, GNU gnulib}, @ref{Legacy Function 4529Substitutes, , Legacy Functions, gnulib, GNU gnulib}, and @ref{Glibc 4530Function Substitutes, , Glibc Functions, gnulib, GNU gnulib}. Please 4531help us keep the gnulib list as complete as possible. 4532 4533@table @asis 4534@item @code{exit} 4535@c @fuindex exit 4536@prindex @code{exit} 4537On ancient hosts, @code{exit} returned @code{int}. 4538This is because @code{exit} predates @code{void}, and there was a long 4539tradition of it returning @code{int}. 4540 4541On current hosts, the problem more likely is that @code{exit} is not 4542declared, due to C++ problems of some sort or another. For this reason 4543we suggest that test programs not invoke @code{exit}, but return from 4544@code{main} instead. 4545 4546@item @code{free} 4547@c @fuindex free 4548@prindex @code{free} 4549The C standard says a call @code{free (NULL)} does nothing, but 4550some old systems don't support this (e.g., NextStep). 4551 4552@item @code{isinf} 4553@itemx @code{isnan} 4554@c @fuindex isinf 4555@c @fuindex isnan 4556@prindex @code{isinf} 4557@prindex @code{isnan} 4558The C99 standard says that @code{isinf} and @code{isnan} are 4559macros. On some systems just macros are available 4560(e.g., HP-UX and Solaris 10), on 4561some systems both macros and functions (e.g., glibc 2.3.2), and on some 4562systems only functions (e.g., IRIX 6 and Solaris 9). In some cases 4563these functions are declared in nonstandard headers like 4564@code{<sunmath.h>} and defined in non-default libraries like 4565@option{-lm} or @option{-lsunmath}. 4566 4567The C99 @code{isinf} and @code{isnan} macros work correctly with 4568@code{long double} arguments, but pre-C99 systems that use functions 4569typically assume @code{double} arguments. On such a system, 4570@code{isinf} incorrectly returns true for a finite @code{long double} 4571argument that is outside the range of @code{double}. 4572 4573The best workaround for these issues is to use gnulib modules 4574@code{isinf} and @code{isnan} (@pxref{Gnulib}). But a lighter weight 4575solution involves code like the following. 4576 4577@smallexample 4578#include <math.h> 4579 4580#ifndef isnan 4581# define isnan(x) \ 4582 (sizeof (x) == sizeof (long double) ? isnan_ld (x) \ 4583 : sizeof (x) == sizeof (double) ? isnan_d (x) \ 4584 : isnan_f (x)) 4585static inline int isnan_f (float x) @{ return x != x; @} 4586static inline int isnan_d (double x) @{ return x != x; @} 4587static inline int isnan_ld (long double x) @{ return x != x; @} 4588#endif 4589 4590#ifndef isinf 4591# define isinf(x) \ 4592 (sizeof (x) == sizeof (long double) ? isinf_ld (x) \ 4593 : sizeof (x) == sizeof (double) ? isinf_d (x) \ 4594 : isinf_f (x)) 4595static inline int isinf_f (float x) 4596@{ return !isnan (x) && isnan (x - x); @} 4597static inline int isinf_d (double x) 4598@{ return !isnan (x) && isnan (x - x); @} 4599static inline int isinf_ld (long double x) 4600@{ return !isnan (x) && isnan (x - x); @} 4601#endif 4602@end smallexample 4603 4604Use @code{AC_C_INLINE} (@pxref{C Compiler}) so that this code works on 4605compilers that lack the @code{inline} keyword. Some optimizing 4606compilers mishandle these definitions, but systems with that bug 4607typically have many other floating point corner-case compliance problems 4608anyway, so it's probably not worth worrying about. 4609 4610@item @code{malloc} 4611@c @fuindex malloc 4612@prindex @code{malloc} 4613The C standard says a call @code{malloc (0)} is implementation 4614dependent. It can return either @code{NULL} or a new non-null pointer. 4615The latter is more common (e.g., the GNU C Library) but is by 4616no means universal. @code{AC_FUNC_MALLOC} 4617can be used to insist on non-@code{NULL} (@pxref{Particular Functions}). 4618 4619@item @code{putenv} 4620@c @fuindex putenv 4621@prindex @code{putenv} 4622Posix prefers @code{setenv} to @code{putenv}; among other things, 4623@code{putenv} is not required of all Posix implementations, but 4624@code{setenv} is. 4625 4626Posix specifies that @code{putenv} puts the given string directly in 4627@code{environ}, but some systems make a copy of it instead (e.g., 4628glibc 2.0, or BSD). And when a copy is made, @code{unsetenv} might 4629not free it, causing a memory leak (e.g., FreeBSD 4). 4630 4631On some systems @code{putenv ("FOO")} removes @samp{FOO} from the 4632environment, but this is not standard usage and it dumps core 4633on some systems (e.g., AIX). 4634 4635On MinGW, a call @code{putenv ("FOO=")} removes @samp{FOO} from the 4636environment, rather than inserting it with an empty value. 4637 4638@item @code{realloc} 4639@c @fuindex realloc 4640@prindex @code{realloc} 4641The C standard says a call @code{realloc (NULL, size)} is equivalent 4642to @code{malloc (size)}, but some old systems don't support this (e.g., 4643NextStep). 4644 4645@item @code{signal} handler 4646@c @fuindex signal 4647@prindex @code{signal} 4648@prindex @code{sigaction} 4649Normally @code{signal} takes a handler function with a return type of 4650@code{void}, but some old systems required @code{int} instead. Any 4651actual @code{int} value returned is not used; this is only a 4652difference in the function prototype demanded. 4653 4654All systems we know of in current use return @code{void}. The 4655@code{int} was to support K&R C, where of course @code{void} is not 4656available. The obsolete macro @code{AC_TYPE_SIGNAL} 4657(@pxref{AC_TYPE_SIGNAL}) can be used to establish the correct type in 4658all cases. 4659 4660In most cases, it is more robust to use @code{sigaction} when it is 4661available, rather than @code{signal}. 4662 4663@item @code{snprintf} 4664@c @fuindex snprintf 4665@prindex @code{snprintf} 4666@c @fuindex vsnprintf 4667@prindex @code{vsnprintf} 4668The C99 standard says that if the output array isn't big enough 4669and if no other errors occur, @code{snprintf} and @code{vsnprintf} 4670truncate the output and return the number of bytes that ought to have 4671been produced. Some older systems return the truncated length (e.g., 4672GNU C Library 2.0.x or IRIX 6.5), some a negative value 4673(e.g., earlier GNU C Library versions), and some the buffer 4674length without truncation (e.g., 32-bit Solaris 7). Also, some buggy 4675older systems ignore the length and overrun the buffer (e.g., 64-bit 4676Solaris 7). 4677 4678@item @code{sprintf} 4679@c @fuindex sprintf 4680@prindex @code{sprintf} 4681@c @fuindex vsprintf 4682@prindex @code{vsprintf} 4683The C standard says @code{sprintf} and @code{vsprintf} return the 4684number of bytes written. On some ancient systems (SunOS 4 for 4685instance) they return the buffer pointer instead, but these no 4686longer need to be worried about. 4687 4688@item @code{sscanf} 4689@c @fuindex sscanf 4690@prindex @code{sscanf} 4691On various old systems, e.g., HP-UX 9, @code{sscanf} requires 4692that its 4693input string be writable (though it doesn't actually change it). This 4694can be a problem when using @command{gcc} since it normally puts 4695constant strings in read-only memory (@pxref{Incompatibilities, 4696Incompatibilities of GCC, , gcc, Using and 4697Porting the GNU Compiler Collection}). Apparently in some cases even 4698having format strings read-only can be a problem. 4699 4700@item @code{strerror_r} 4701@c @fuindex strerror_r 4702@prindex @code{strerror_r} 4703Posix specifies that @code{strerror_r} returns an @code{int}, but many 4704systems (e.g., GNU C Library version 2.2.4) provide a 4705different version returning a @code{char *}. @code{AC_FUNC_STRERROR_R} 4706can detect which is in use (@pxref{Particular Functions}). 4707 4708@item @code{strnlen} 4709@c @fuindex strnlen 4710@prindex @code{strnlen} 4711AIX 4.3 provides a broken version which produces the 4712following results: 4713 4714@example 4715strnlen ("foobar", 0) = 0 4716strnlen ("foobar", 1) = 3 4717strnlen ("foobar", 2) = 2 4718strnlen ("foobar", 3) = 1 4719strnlen ("foobar", 4) = 0 4720strnlen ("foobar", 5) = 6 4721strnlen ("foobar", 6) = 6 4722strnlen ("foobar", 7) = 6 4723strnlen ("foobar", 8) = 6 4724strnlen ("foobar", 9) = 6 4725@end example 4726 4727@item @code{sysconf} 4728@c @fuindex sysconf 4729@prindex @code{sysconf} 4730@code{_SC_PAGESIZE} is standard, but some older systems (e.g., HP-UX 47319) have @code{_SC_PAGE_SIZE} instead. This can be tested with 4732@code{#ifdef}. 4733 4734@item @code{unlink} 4735@c @fuindex unlink 4736@prindex @code{unlink} 4737The Posix spec says that @code{unlink} causes the given file to be 4738removed only after there are no more open file handles for it. Some 4739non-Posix hosts have trouble with this requirement, though, 4740and some DOS variants even corrupt the file system. 4741 4742@item @code{unsetenv} 4743@c @fuindex unsetenv 4744@prindex @code{unsetenv} 4745On MinGW, @code{unsetenv} is not available, but a variable @samp{FOO} 4746can be removed with a call @code{putenv ("FOO=")}, as described under 4747@code{putenv} above. 4748 4749@item @code{va_copy} 4750@c @fuindex va_copy 4751@prindex @code{va_copy} 4752The C99 standard provides @code{va_copy} for copying 4753@code{va_list} variables. It may be available in older environments 4754too, though possibly as @code{__va_copy} (e.g., @command{gcc} in strict 4755pre-C99 mode). These can be tested with @code{#ifdef}. A fallback to 4756@code{memcpy (&dst, &src, sizeof (va_list))} gives maximum 4757portability. 4758 4759@item @code{va_list} 4760@c @fuindex va_list 4761@prindex @code{va_list} 4762@code{va_list} is not necessarily just a pointer. It can be a 4763@code{struct} (e.g., @command{gcc} on Alpha), which means @code{NULL} is 4764not portable. Or it can be an array (e.g., @command{gcc} in some 4765PowerPC configurations), which means as a function parameter it can be 4766effectively call-by-reference and library routines might modify the 4767value back in the caller (e.g., @code{vsnprintf} in the GNU C Library 47682.1). 4769 4770@item Signed @code{>>} 4771Normally the C @code{>>} right shift of a signed type replicates the 4772high bit, giving a so-called ``arithmetic'' shift. But care should be 4773taken since Standard C doesn't require that behavior. On those 4774few processors without a native arithmetic shift (for instance Cray 4775vector systems) zero bits may be shifted in, the same as a shift of an 4776unsigned type. 4777 4778@item Integer @code{/} 4779C divides signed integers by truncating their quotient toward zero, 4780yielding the same result as Fortran. However, before C99 the standard 4781allowed C implementations to take the floor or ceiling of the quotient 4782in some cases. Hardly any implementations took advantage of this 4783freedom, though, and it's probably not worth worrying about this issue 4784nowadays. 4785@end table 4786 4787 4788@node Particular Functions 4789@subsection Particular Function Checks 4790@cindex Function, checking 4791 4792These macros check for particular C functions---whether they exist, and 4793in some cases how they respond when given certain arguments. 4794 4795@anchor{AC_FUNC_ALLOCA} 4796@defmac AC_FUNC_ALLOCA 4797@acindex{FUNC_ALLOCA} 4798@cvindex C_ALLOCA 4799@cvindex HAVE_ALLOCA_H 4800@ovindex ALLOCA 4801@c @fuindex alloca 4802@prindex @code{alloca} 4803@hdrindex{alloca.h} 4804@c @caindex working_alloca_h 4805Check how to get @code{alloca}. Tries to get a builtin version by 4806checking for @file{alloca.h} or the predefined C preprocessor macros 4807@code{__GNUC__} and @code{_AIX}. If this macro finds @file{alloca.h}, 4808it defines @code{HAVE_ALLOCA_H}. 4809 4810If those attempts fail, it looks for the function in the standard C 4811library. If any of those methods succeed, it defines 4812@code{HAVE_ALLOCA}. Otherwise, it sets the output variable 4813@code{ALLOCA} to @samp{$@{LIBOBJDIR@}alloca.o} and defines 4814@code{C_ALLOCA} (so programs can periodically call @samp{alloca (0)} to 4815garbage collect). This variable is separate from @code{LIBOBJS} so 4816multiple programs can share the value of @code{ALLOCA} without needing 4817to create an actual library, in case only some of them use the code in 4818@code{LIBOBJS}. The @samp{$@{LIBOBJDIR@}} prefix serves the same 4819purpose as in @code{LIBOBJS} (@pxref{AC_LIBOBJ vs LIBOBJS}). 4820 4821This macro does not try to get @code{alloca} from the System V R3 4822@file{libPW} or the System V R4 @file{libucb} because those libraries 4823contain some incompatible functions that cause trouble. Some versions 4824do not even contain @code{alloca} or contain a buggy version. If you 4825still want to use their @code{alloca}, use @code{ar} to extract 4826@file{alloca.o} from them instead of compiling @file{alloca.c}. 4827 4828Source files that use @code{alloca} should start with a piece of code 4829like the following, to declare it properly. 4830 4831@example 4832@group 4833#ifdef STDC_HEADERS 4834# include <stdlib.h> 4835# include <stddef.h> 4836#else 4837# ifdef HAVE_STDLIB_H 4838# include <stdlib.h> 4839# endif 4840#endif 4841#ifdef HAVE_ALLOCA_H 4842# include <alloca.h> 4843#elif !defined alloca 4844# ifdef __GNUC__ 4845# define alloca __builtin_alloca 4846# elif defined _AIX 4847# define alloca __alloca 4848# elif defined _MSC_VER 4849# include <malloc.h> 4850# define alloca _alloca 4851# elif !defined HAVE_ALLOCA 4852# ifdef __cplusplus 4853extern "C" 4854# endif 4855void *alloca (size_t); 4856# endif 4857#endif 4858@end group 4859@end example 4860@end defmac 4861 4862@defmac AC_FUNC_CHOWN 4863@acindex{FUNC_CHOWN} 4864@cvindex HAVE_CHOWN 4865@c @fuindex chown 4866@prindex @code{chown} 4867@caindex func_chown_works 4868If the @code{chown} function is available and works (in particular, it 4869should accept @option{-1} for @code{uid} and @code{gid}), define 4870@code{HAVE_CHOWN}. The result of this macro is cached in the 4871@code{ac_cv_func_chown_works} variable. 4872@end defmac 4873 4874@anchor{AC_FUNC_CLOSEDIR_VOID} 4875@defmac AC_FUNC_CLOSEDIR_VOID 4876@acindex{FUNC_CLOSEDIR_VOID} 4877@cvindex CLOSEDIR_VOID 4878@c @fuindex closedir 4879@prindex @code{closedir} 4880@caindex func_closedir_void 4881If the @code{closedir} function does not return a meaningful value, 4882define @code{CLOSEDIR_VOID}. Otherwise, callers ought to check its 4883return value for an error indicator. 4884 4885Currently this test is implemented by running a test program. When 4886cross compiling the pessimistic assumption that @code{closedir} does not 4887return a meaningful value is made. 4888 4889The result of this macro is cached in the @code{ac_cv_func_closedir_void} 4890variable. 4891 4892This macro is obsolescent, as @code{closedir} returns a meaningful value 4893on current systems. New programs need not use this macro. 4894@end defmac 4895 4896@defmac AC_FUNC_ERROR_AT_LINE 4897@acindex{FUNC_ERROR_AT_LINE} 4898@c @fuindex error_at_line 4899@prindex @code{error_at_line} 4900@caindex lib_error_at_line 4901If the @code{error_at_line} function is not found, require an 4902@code{AC_LIBOBJ} replacement of @samp{error}. 4903 4904The result of this macro is cached in the @code{ac_cv_lib_error_at_line} 4905variable. 4906 4907The @code{AC_FUNC_ERROR_AT_LINE} macro is obsolescent. New programs 4908should use Gnulib's @code{error} module. @xref{Gnulib}. 4909@end defmac 4910 4911@defmac AC_FUNC_FNMATCH 4912@acindex{FUNC_FNMATCH} 4913@c @fuindex fnmatch 4914@prindex @code{fnmatch} 4915@caindex func_fnmatch_works 4916If the @code{fnmatch} function conforms to Posix, define 4917@code{HAVE_FNMATCH}. Detect common implementation bugs, for example, 4918the bugs in Solaris 2.4. 4919 4920Unlike the other specific 4921@code{AC_FUNC} macros, @code{AC_FUNC_FNMATCH} does not replace a 4922broken/missing @code{fnmatch}. This is for historical reasons. 4923See @code{AC_REPLACE_FNMATCH} below. 4924 4925The result of this macro is cached in the @code{ac_cv_func_fnmatch_works} 4926variable. 4927 4928This macro is obsolescent. New programs should use Gnulib's 4929@code{fnmatch-posix} module. @xref{Gnulib}. 4930@end defmac 4931 4932@defmac AC_FUNC_FNMATCH_GNU 4933@acindex{FUNC_FNMATCH_GNU} 4934@c @fuindex fnmatch 4935@prindex @code{fnmatch} 4936@caindex func_fnmatch_gnu 4937Behave like @code{AC_REPLACE_FNMATCH} (@emph{replace}) but also test 4938whether @code{fnmatch} supports GNU extensions. Detect common 4939implementation bugs, for example, the bugs in the GNU C 4940Library 2.1. 4941 4942The result of this macro is cached in the @code{ac_cv_func_fnmatch_gnu} 4943variable. 4944 4945This macro is obsolescent. New programs should use Gnulib's 4946@code{fnmatch-gnu} module. @xref{Gnulib}. 4947@end defmac 4948 4949@anchor{AC_FUNC_FORK} 4950@defmac AC_FUNC_FORK 4951@acindex{FUNC_FORK} 4952@cvindex HAVE_VFORK_H 4953@cvindex HAVE_WORKING_FORK 4954@cvindex HAVE_WORKING_VFORK 4955@cvindex vfork 4956@c @fuindex fork 4957@prindex @code{fork} 4958@c @fuindex vfork 4959@prindex @code{vfork} 4960@hdrindex{vfork.h} 4961@c @caindex func_fork 4962@c @caindex func_fork_works 4963This macro checks for the @code{fork} and @code{vfork} functions. If a 4964working @code{fork} is found, define @code{HAVE_WORKING_FORK}. This macro 4965checks whether @code{fork} is just a stub by trying to run it. 4966 4967If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working 4968@code{vfork} is found, define @code{HAVE_WORKING_VFORK}. Otherwise, 4969define @code{vfork} to be @code{fork} for backward compatibility with 4970previous versions of @command{autoconf}. This macro checks for several known 4971errors in implementations of @code{vfork} and considers the system to not 4972have a working @code{vfork} if it detects any of them. It is not considered 4973to be an implementation error if a child's invocation of @code{signal} 4974modifies the parent's signal handler, since child processes rarely change 4975their signal handlers. 4976 4977Since this macro defines @code{vfork} only for backward compatibility with 4978previous versions of @command{autoconf} you're encouraged to define it 4979yourself in new code: 4980@example 4981@group 4982#ifndef HAVE_WORKING_VFORK 4983# define vfork fork 4984#endif 4985@end group 4986@end example 4987 4988The results of this macro are cached in the @code{ac_cv_func_fork_works} 4989and @code{ac_cv_func_vfork_works} variables. In order to override the 4990test, you also need to set the @code{ac_cv_func_fork} and 4991@code{ac_cv_func_vfork} variables. 4992@end defmac 4993 4994@defmac AC_FUNC_FSEEKO 4995@acindex{FUNC_FSEEKO} 4996@cvindex _LARGEFILE_SOURCE 4997@cvindex HAVE_FSEEKO 4998@c @fuindex fseeko 4999@prindex @code{fseeko} 5000@c @fuindex ftello 5001@prindex @code{ftello} 5002@c @caindex sys_largefile_source 5003If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}. 5004Define @code{_LARGEFILE_SOURCE} if necessary to make the prototype 5005visible on some systems (e.g., glibc 2.2). Otherwise linkage problems 5006may occur when compiling with @code{AC_SYS_LARGEFILE} on 5007largefile-sensitive systems where @code{off_t} does not default to a 500864bit entity. All systems with @code{fseeko} also supply @code{ftello}. 5009@end defmac 5010 5011@defmac AC_FUNC_GETGROUPS 5012@acindex{FUNC_GETGROUPS} 5013@cvindex HAVE_GETGROUPS 5014@ovindex GETGROUPS_LIBS 5015@c @fuindex getgroups 5016@prindex @code{getgroups} 5017@caindex func_getgroups_works 5018If the @code{getgroups} function is available and works (unlike on 5019Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define 5020@code{HAVE_GETGROUPS}. Set @code{GETGROUPS_LIBS} to any libraries 5021needed to get that function. This macro runs @code{AC_TYPE_GETGROUPS}. 5022@end defmac 5023 5024@anchor{AC_FUNC_GETLOADAVG} 5025@defmac AC_FUNC_GETLOADAVG 5026@acindex{FUNC_GETLOADAVG} 5027@cvindex SVR4 5028@cvindex DGUX 5029@cvindex UMAX 5030@cvindex UMAX4_3 5031@cvindex HAVE_NLIST_H 5032@cvindex NLIST_NAME_UNION 5033@cvindex GETLOADAVG_PRIVILEGED 5034@cvindex NEED_SETGID 5035@cvindex C_GETLOADAVG 5036@ovindex LIBOBJS 5037@ovindex NEED_SETGID 5038@ovindex KMEM_GROUP 5039@ovindex GETLOADAVG_LIBS 5040@c @fuindex getloadavg 5041@prindex @code{getloadavg} 5042Check how to get the system load averages. To perform its tests 5043properly, this macro needs the file @file{getloadavg.c}; therefore, be 5044sure to set the @code{AC_LIBOBJ} replacement directory properly (see 5045@ref{Generic Functions}, @code{AC_CONFIG_LIBOBJ_DIR}). 5046 5047If the system has the @code{getloadavg} function, define 5048@code{HAVE_GETLOADAVG}, and set @code{GETLOADAVG_LIBS} to any libraries 5049necessary to get that function. Also add @code{GETLOADAVG_LIBS} to 5050@code{LIBS}. Otherwise, require an @code{AC_LIBOBJ} replacement for 5051@samp{getloadavg} with source code in @file{@var{dir}/getloadavg.c}, and 5052possibly define several other C preprocessor macros and output 5053variables: 5054 5055@enumerate 5056@item 5057Define @code{C_GETLOADAVG}. 5058 5059@item 5060Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on 5061those systems. 5062 5063@item 5064@hdrindex{nlist.h} 5065If @file{nlist.h} is found, define @code{HAVE_NLIST_H}. 5066 5067@item 5068If @samp{struct nlist} has an @samp{n_un.n_name} member, define 5069@code{HAVE_STRUCT_NLIST_N_UN_N_NAME}. The obsolete symbol 5070@code{NLIST_NAME_UNION} is still defined, but do not depend upon it. 5071 5072@item 5073Programs may need to be installed set-group-ID (or set-user-ID) for 5074@code{getloadavg} to work. In this case, define 5075@code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID} 5076to @samp{true} (and otherwise to @samp{false}), and set 5077@code{KMEM_GROUP} to the name of the group that should own the installed 5078program. 5079@end enumerate 5080 5081The @code{AC_FUNC_GETLOADAVG} macro is obsolescent. New programs should 5082use Gnulib's @code{getloadavg} module. @xref{Gnulib}. 5083@end defmac 5084 5085@anchor{AC_FUNC_GETMNTENT} 5086@defmac AC_FUNC_GETMNTENT 5087@acindex{FUNC_GETMNTENT} 5088@cvindex HAVE_GETMNTENT 5089@c @fuindex getmntent 5090@prindex @code{getmntent} 5091@caindex search_getmntent 5092Check for @code{getmntent} in the standard C library, and then in the 5093@file{sun}, @file{seq}, and @file{gen} libraries, for UNICOS, 5094IRIX 4, PTX, and UnixWare, respectively. Then, if 5095@code{getmntent} is available, define @code{HAVE_GETMNTENT} and set 5096@code{ac_cv_func_getmntent} to @code{yes}. Otherwise set 5097@code{ac_cv_func_getmntent} to @code{no}. 5098 5099The result of this macro can be overridden by setting the cache variable 5100@code{ac_cv_search_getmntent}. 5101@end defmac 5102 5103@defmac AC_FUNC_GETPGRP 5104@acindex{FUNC_GETPGRP} 5105@cvindex GETPGRP_VOID 5106@c @fuindex getpgid 5107@c @fuindex getpgrp 5108@prindex @code{getpgid} 5109@prindex @code{getpgrp} 5110@caindex func_getpgrp_void 5111Define @code{GETPGRP_VOID} if it is an error to pass 0 to 5112@code{getpgrp}; this is the Posix behavior. On older BSD 5113systems, you must pass 0 to @code{getpgrp}, as it takes an argument and 5114behaves like Posix's @code{getpgid}. 5115 5116@example 5117#ifdef GETPGRP_VOID 5118 pid = getpgrp (); 5119#else 5120 pid = getpgrp (0); 5121#endif 5122@end example 5123 5124This macro does not check whether 5125@code{getpgrp} exists at all; if you need to work in that situation, 5126first call @code{AC_CHECK_FUNC} for @code{getpgrp}. 5127 5128The result of this macro is cached in the @code{ac_cv_func_getpgrp_void} 5129variable. 5130 5131This macro is obsolescent, as current systems have a @code{getpgrp} 5132whose signature conforms to Posix. New programs need not use this macro. 5133@end defmac 5134 5135@defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK 5136@acindex{FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK} 5137@cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK 5138@c @fuindex lstat 5139@prindex @code{lstat} 5140@caindex func_lstat_dereferences_slashed_symlink 5141If @file{link} is a symbolic link, then @code{lstat} should treat 5142@file{link/} the same as @file{link/.}. However, many older 5143@code{lstat} implementations incorrectly ignore trailing slashes. 5144 5145It is safe to assume that if @code{lstat} incorrectly ignores 5146trailing slashes, then other symbolic-link-aware functions like 5147@code{unlink} also incorrectly ignore trailing slashes. 5148 5149If @code{lstat} behaves properly, define 5150@code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an 5151@code{AC_LIBOBJ} replacement of @code{lstat}. 5152 5153The result of this macro is cached in the 5154@code{ac_cv_func_lstat_dereferences_slashed_symlink} variable. 5155 5156The @code{AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK} macro is obsolescent. 5157New programs should use Gnulib's @code{lstat} module. @xref{Gnulib}. 5158@end defmac 5159 5160@defmac AC_FUNC_MALLOC 5161@acindex{FUNC_MALLOC} 5162@cvindex HAVE_MALLOC 5163@cvindex malloc 5164@c @fuindex malloc 5165@prindex @code{malloc} 5166@caindex func_malloc_0_nonnull 5167If the @code{malloc} function is compatible with the GNU C 5168library @code{malloc} (i.e., @samp{malloc (0)} returns a valid 5169pointer), define @code{HAVE_MALLOC} to 1. Otherwise define 5170@code{HAVE_MALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for 5171@samp{malloc}, and define @code{malloc} to @code{rpl_malloc} so that the 5172native @code{malloc} is not used in the main project. 5173 5174Typically, the replacement file @file{malloc.c} should look like (note 5175the @samp{#undef malloc}): 5176 5177@verbatim 5178#include <config.h> 5179#undef malloc 5180 5181#include <sys/types.h> 5182 5183void *malloc (); 5184 5185/* Allocate an N-byte block of memory from the heap. 5186 If N is zero, allocate a 1-byte block. */ 5187 5188void * 5189rpl_malloc (size_t n) 5190{ 5191 if (n == 0) 5192 n = 1; 5193 return malloc (n); 5194} 5195@end verbatim 5196 5197The result of this macro is cached in the 5198@code{ac_cv_func_malloc_0_nonnull} variable. 5199@end defmac 5200 5201@defmac AC_FUNC_MBRTOWC 5202@acindex{FUNC_MBRTOWC} 5203@cvindex HAVE_MBRTOWC 5204@c @fuindex mbrtowc 5205@prindex @code{mbrtowc} 5206@caindex func_mbrtowc 5207Define @code{HAVE_MBRTOWC} to 1 if the function @code{mbrtowc} and the 5208type @code{mbstate_t} are properly declared. 5209 5210The result of this macro is cached in the @code{ac_cv_func_mbrtowc} 5211variable. 5212@end defmac 5213 5214@defmac AC_FUNC_MEMCMP 5215@acindex{FUNC_MEMCMP} 5216@ovindex LIBOBJS 5217@c @fuindex memcmp 5218@prindex @code{memcmp} 5219@caindex func_memcmp_working 5220If the @code{memcmp} function is not available, or does not work on 52218-bit data (like the one on SunOS 4.1.3), or fails when comparing 16 5222bytes or more and with at least one buffer not starting on a 4-byte 5223boundary (such as the one on NeXT x86 OpenStep), require an 5224@code{AC_LIBOBJ} replacement for @samp{memcmp}. 5225 5226The result of this macro is cached in the 5227@code{ac_cv_func_memcmp_working} variable. 5228 5229This macro is obsolescent, as current systems have a working 5230@code{memcmp}. New programs need not use this macro. 5231@end defmac 5232 5233@defmac AC_FUNC_MKTIME 5234@acindex{FUNC_MKTIME} 5235@ovindex LIBOBJS 5236@c @fuindex mktime 5237@prindex @code{mktime} 5238@caindex func_working_mktime 5239If the @code{mktime} function is not available, or does not work 5240correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}. 5241For the purposes of this test, @code{mktime} should conform to the 5242Posix standard and should be the inverse of 5243@code{localtime}. 5244 5245The result of this macro is cached in the 5246@code{ac_cv_func_working_mktime} variable. 5247 5248The @code{AC_FUNC_MKTIME} macro is obsolescent. New programs should 5249use Gnulib's @code{mktime} module. @xref{Gnulib}. 5250@end defmac 5251 5252@anchor{AC_FUNC_MMAP} 5253@defmac AC_FUNC_MMAP 5254@acindex{FUNC_MMAP} 5255@cvindex HAVE_MMAP 5256@c @fuindex mmap 5257@prindex @code{mmap} 5258@caindex func_mmap_fixed_mapped 5259If the @code{mmap} function exists and works correctly, define 5260@code{HAVE_MMAP}. This checks only private fixed mapping of already-mapped 5261memory. 5262 5263The result of this macro is cached in the 5264@code{ac_cv_func_mmap_fixed_mapped} variable. 5265@end defmac 5266 5267@defmac AC_FUNC_OBSTACK 5268@acindex{FUNC_OBSTACK} 5269@cvindex HAVE_OBSTACK 5270@cindex obstack 5271@caindex func_obstack 5272If the obstacks are found, define @code{HAVE_OBSTACK}, else require an 5273@code{AC_LIBOBJ} replacement for @samp{obstack}. 5274 5275The result of this macro is cached in the @code{ac_cv_func_obstack} 5276variable. 5277@end defmac 5278 5279@defmac AC_FUNC_REALLOC 5280@acindex{FUNC_REALLOC} 5281@cvindex HAVE_REALLOC 5282@cvindex realloc 5283@c @fuindex realloc 5284@prindex @code{realloc} 5285@caindex func_realloc_0_nonnull 5286If the @code{realloc} function is compatible with the GNU C 5287library @code{realloc} (i.e., @samp{realloc (NULL, 0)} returns a 5288valid pointer), define @code{HAVE_REALLOC} to 1. Otherwise define 5289@code{HAVE_REALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for 5290@samp{realloc}, and define @code{realloc} to @code{rpl_realloc} so that 5291the native @code{realloc} is not used in the main project. See 5292@code{AC_FUNC_MALLOC} for details. 5293 5294The result of this macro is cached in the 5295@code{ac_cv_func_realloc_0_nonnull} variable. 5296@end defmac 5297 5298@defmac AC_FUNC_SELECT_ARGTYPES 5299@acindex{FUNC_SELECT_ARGTYPES} 5300@cvindex SELECT_TYPE_ARG1 5301@cvindex SELECT_TYPE_ARG234 5302@cvindex SELECT_TYPE_ARG5 5303@c @fuindex select 5304@prindex @code{select} 5305@c @caindex func_select_args 5306Determines the correct type to be passed for each of the 5307@code{select} function's arguments, and defines those types 5308in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and 5309@code{SELECT_TYPE_ARG5} respectively. @code{SELECT_TYPE_ARG1} defaults 5310to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *}, 5311and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}. 5312 5313This macro is obsolescent, as current systems have a @code{select} whose 5314signature conforms to Posix. New programs need not use this macro. 5315@end defmac 5316 5317@defmac AC_FUNC_SETPGRP 5318@acindex{FUNC_SETPGRP} 5319@cvindex SETPGRP_VOID 5320@c @fuindex setpgrp 5321@prindex @code{setpgrp} 5322@caindex func_setpgrp_void 5323If @code{setpgrp} takes no argument (the Posix version), define 5324@code{SETPGRP_VOID}. Otherwise, it is the BSD version, which takes 5325two process IDs as arguments. This macro does not check whether 5326@code{setpgrp} exists at all; if you need to work in that situation, 5327first call @code{AC_CHECK_FUNC} for @code{setpgrp}. 5328 5329The result of this macro is cached in the @code{ac_cv_func_setpgrp_void} 5330variable. 5331 5332This macro is obsolescent, as current systems have a @code{setpgrp} 5333whose signature conforms to Posix. New programs need not use this macro. 5334@end defmac 5335 5336@defmac AC_FUNC_STAT 5337@defmacx AC_FUNC_LSTAT 5338@acindex{FUNC_STAT} 5339@acindex{FUNC_LSTAT} 5340@cvindex HAVE_STAT_EMPTY_STRING_BUG 5341@cvindex HAVE_LSTAT_EMPTY_STRING_BUG 5342@c @fuindex stat 5343@prindex @code{stat} 5344@c @fuindex lstat 5345@prindex @code{lstat} 5346@caindex func_stat_empty_string_bug 5347@caindex func_lstat_empty_string_bug 5348Determine whether @code{stat} or @code{lstat} have the bug that it 5349succeeds when given the zero-length file name as argument. The @code{stat} 5350and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do 5351this. 5352 5353If it does, then define @code{HAVE_STAT_EMPTY_STRING_BUG} (or 5354@code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ} 5355replacement of it. 5356 5357The results of these macros are cached in the 5358@code{ac_cv_func_stat_empty_string_bug} and the 5359@code{ac_cv_func_lstat_empty_string_bug} variables, respectively. 5360 5361These macros are obsolescent, as no current systems have the bug. 5362New programs need not use these macros. 5363@end defmac 5364 5365@anchor{AC_FUNC_STRCOLL} 5366@defmac AC_FUNC_STRCOLL 5367@acindex{FUNC_STRCOLL} 5368@cvindex HAVE_STRCOLL 5369@c @fuindex strcoll 5370@prindex @code{strcoll} 5371@caindex func_strcoll_works 5372If the @code{strcoll} function exists and works correctly, define 5373@code{HAVE_STRCOLL}. This does a bit more than 5374@samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect 5375definitions of @code{strcoll} that should not be used. 5376 5377The result of this macro is cached in the @code{ac_cv_func_strcoll_works} 5378variable. 5379@end defmac 5380 5381@defmac AC_FUNC_STRERROR_R 5382@acindex{FUNC_STRERROR_R} 5383@cvindex HAVE_STRERROR_R 5384@cvindex HAVE_DECL_STRERROR_R 5385@cvindex STRERROR_R_CHAR_P 5386@c @fuindex strerror_r 5387@caindex func_strerror_r_char_p 5388@prindex @code{strerror_r} 5389If @code{strerror_r} is available, define @code{HAVE_STRERROR_R}, and if 5390it is declared, define @code{HAVE_DECL_STRERROR_R}. If it returns a 5391@code{char *} message, define @code{STRERROR_R_CHAR_P}; otherwise it 5392returns an @code{int} error number. The Thread-Safe Functions option of 5393Posix requires @code{strerror_r} to return @code{int}, but 5394many systems (including, for example, version 2.2.4 of the GNU C 5395Library) return a @code{char *} value that is not necessarily equal to 5396the buffer argument. 5397 5398The result of this macro is cached in the 5399@code{ac_cv_func_strerror_r_char_p} variable. 5400@end defmac 5401 5402@anchor{AC_FUNC_STRFTIME} 5403@defmac AC_FUNC_STRFTIME 5404@acindex{FUNC_STRFTIME} 5405@cvindex HAVE_STRFTIME 5406@c @fuindex strftime 5407@prindex @code{strftime} 5408Check for @code{strftime} in the @file{intl} library, for SCO Unix. 5409Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}. 5410 5411This macro is obsolescent, as no current systems require the @file{intl} 5412library for @code{strftime}. New programs need not use this macro. 5413@end defmac 5414 5415@defmac AC_FUNC_STRTOD 5416@acindex{FUNC_STRTOD} 5417@ovindex POW_LIB 5418@c @fuindex strtod 5419@prindex @code{strtod} 5420@caindex func_strtod 5421@caindex func_pow 5422If the @code{strtod} function does not exist or doesn't work correctly, 5423ask for an @code{AC_LIBOBJ} replacement of @samp{strtod}. In this case, 5424because @file{strtod.c} is likely to need @samp{pow}, set the output 5425variable @code{POW_LIB} to the extra library needed. 5426 5427This macro caches its result in the @code{ac_cv_func_strtod} variable 5428and depends upon the result in the @code{ac_cv_func_pow} variable. 5429 5430The @code{AC_FUNC_STRTOD} macro is obsolescent. New programs should 5431use Gnulib's @code{strtod} module. @xref{Gnulib}. 5432@end defmac 5433 5434@defmac AC_FUNC_STRTOLD 5435@acindex{FUNC_STRTOLD} 5436@cvindex HAVE_STRTOLD 5437@prindex @code{strtold} 5438@caindex func_strtold 5439If the @code{strtold} function exists and conforms to C99, define 5440@code{HAVE_STRTOLD}. 5441 5442This macro caches its result in the @code{ac_cv_func_strtold} variable. 5443@end defmac 5444 5445@defmac AC_FUNC_STRNLEN 5446@acindex{FUNC_STRNLEN} 5447@cvindex HAVE_STRNLEN 5448@c @fuindex strnlen 5449@prindex @code{strnlen} 5450@caindex func_strnlen_working 5451If the @code{strnlen} function is not available, or is buggy (like the one 5452from AIX 4.3), require an @code{AC_LIBOBJ} replacement for it. 5453 5454This macro caches its result in the @code{ac_cv_func_strnlen_working} 5455variable. 5456@end defmac 5457 5458@anchor{AC_FUNC_UTIME_NULL} 5459@defmac AC_FUNC_UTIME_NULL 5460@acindex{FUNC_UTIME_NULL} 5461@cvindex HAVE_UTIME_NULL 5462@c @fuindex utime 5463@prindex @code{utime} 5464@caindex func_utime_null 5465If @samp{utime (@var{file}, NULL)} sets @var{file}'s timestamp to 5466the present, define @code{HAVE_UTIME_NULL}. 5467 5468This macro caches its result in the @code{ac_cv_func_utime_null} 5469variable. 5470 5471This macro is obsolescent, as all current systems have a @code{utime} 5472that behaves this way. New programs need not use this macro. 5473@end defmac 5474 5475@anchor{AC_FUNC_VPRINTF} 5476@defmac AC_FUNC_VPRINTF 5477@acindex{FUNC_VPRINTF} 5478@cvindex HAVE_VPRINTF 5479@cvindex HAVE_DOPRNT 5480@c @fuindex vprintf 5481@prindex @code{vprintf} 5482@c @fuindex vsprintf 5483@prindex @code{vsprintf} 5484If @code{vprintf} is found, define @code{HAVE_VPRINTF}. Otherwise, if 5485@code{_doprnt} is found, define @code{HAVE_DOPRNT}. (If @code{vprintf} 5486is available, you may assume that @code{vfprintf} and @code{vsprintf} 5487are also available.) 5488 5489This macro is obsolescent, as all current systems have @code{vprintf}. 5490New programs need not use this macro. 5491@end defmac 5492 5493@defmac AC_REPLACE_FNMATCH 5494@acindex{REPLACE_FNMATCH} 5495@c @fuindex fnmatch 5496@prindex @code{fnmatch} 5497@hdrindex{fnmatch.h} 5498@caindex func_fnmatch_works 5499If the @code{fnmatch} function does not conform to Posix (see 5500@code{AC_FUNC_FNMATCH}), ask for its @code{AC_LIBOBJ} replacement. 5501 5502The files @file{fnmatch.c}, @file{fnmatch_loop.c}, and @file{fnmatch_.h} 5503in the @code{AC_LIBOBJ} replacement directory are assumed to contain a 5504copy of the source code of GNU @code{fnmatch}. If necessary, 5505this source code is compiled as an @code{AC_LIBOBJ} replacement, and the 5506@file{fnmatch_.h} file is linked to @file{fnmatch.h} so that it can be 5507included in place of the system @code{<fnmatch.h>}. 5508 5509This macro caches its result in the @code{ac_cv_func_fnmatch_works} 5510variable. 5511 5512This macro is obsolescent, as it assumes the use of particular source 5513files. New programs should use Gnulib's @code{fnmatch-posix} module, 5514which provides this macro along with the source files. @xref{Gnulib}. 5515@end defmac 5516 5517 5518 5519@node Generic Functions 5520@subsection Generic Function Checks 5521 5522These macros are used to find functions not covered by the ``particular'' 5523test macros. If the functions might be in libraries other than the 5524default C library, first call @code{AC_CHECK_LIB} for those libraries. 5525If you need to check the behavior of a function as well as find out 5526whether it is present, you have to write your own test for 5527it (@pxref{Writing Tests}). 5528 5529@anchor{AC_CHECK_FUNC} 5530@defmac AC_CHECK_FUNC (@var{function}, @ovar{action-if-found}, @ 5531 @ovar{action-if-not-found}) 5532@acindex{CHECK_FUNC} 5533@caindex func_@var{function} 5534If C function @var{function} is available, run shell commands 5535@var{action-if-found}, otherwise @var{action-if-not-found}. If you just 5536want to define a symbol if the function is available, consider using 5537@code{AC_CHECK_FUNCS} instead. This macro checks for functions with C 5538linkage even when @code{AC_LANG(C++)} has been called, since C is more 5539standardized than C++. (@pxref{Language Choice}, for more information 5540about selecting the language for checks.) 5541 5542This macro caches its result in the @code{ac_cv_func_@var{function}} 5543variable. 5544@end defmac 5545 5546@anchor{AC_CHECK_FUNCS} 5547@defmac AC_CHECK_FUNCS (@var{function}@dots{}, @ovar{action-if-found}, @ 5548 @ovar{action-if-not-found}) 5549@acindex{CHECK_FUNCS} 5550@cvindex HAVE_@var{function} 5551For each @var{function} enumerated in the blank-or-newline-separated argument 5552list, define @code{HAVE_@var{function}} (in all capitals) if it is available. 5553If @var{action-if-found} is given, it is additional shell code to 5554execute when one of the functions is found. You can give it a value of 5555@samp{break} to break out of the loop on the first match. If 5556@var{action-if-not-found} is given, it is executed when one of the 5557functions is not found. 5558 5559Results are cached for each @var{function} as in @code{AC_CHECK_FUNC}. 5560@end defmac 5561 5562@defmac AC_CHECK_FUNCS_ONCE (@var{function}@dots{}) 5563@acindex{CHECK_FUNCS_ONCE} 5564@cvindex HAVE_@var{function} 5565For each @var{function} enumerated in the blank-or-newline-separated argument 5566list, define @code{HAVE_@var{function}} (in all capitals) if it is available. 5567This is a once-only variant of @code{AC_CHECK_FUNCS}. It generates the 5568checking code at most once, so that @command{configure} is smaller and 5569faster; but the checks cannot be conditionalized and are always done once, 5570early during the @command{configure} run. 5571@end defmac 5572 5573@sp 1 5574 5575Autoconf follows a philosophy that was formed over the years by those 5576who have struggled for portability: isolate the portability issues in 5577specific files, and then program as if you were in a Posix 5578environment. Some functions may be missing or unfixable, and your 5579package must be ready to replace them. 5580 5581Suitable replacements for many such problem functions are available from 5582Gnulib (@pxref{Gnulib}). 5583 5584@defmac AC_LIBOBJ (@var{function}) 5585@acindex{LIBOBJ} 5586@ovindex LIBOBJS 5587Specify that @samp{@var{function}.c} must be included in the executables 5588to replace a missing or broken implementation of @var{function}. 5589 5590@vrindex ac_objext 5591Technically, it adds @samp{@var{function}.$ac_objext} to the output 5592variable @code{LIBOBJS} if it is not already in, and calls 5593@code{AC_LIBSOURCE} for @samp{@var{function}.c}. You should not 5594directly change @code{LIBOBJS}, since this is not traceable. 5595@end defmac 5596 5597@defmac AC_LIBSOURCE (@var{file}) 5598@acindex{LIBSOURCE} 5599Specify that @var{file} might be needed to compile the project. If you 5600need to know what files might be needed by a @file{configure.ac}, you 5601should trace @code{AC_LIBSOURCE}. @var{file} must be a literal. 5602 5603This macro is called automatically from @code{AC_LIBOBJ}, but you must 5604call it explicitly if you pass a shell variable to @code{AC_LIBOBJ}. In 5605that case, since shell variables cannot be traced statically, you must 5606pass to @code{AC_LIBSOURCE} any possible files that the shell variable 5607might cause @code{AC_LIBOBJ} to need. For example, if you want to pass 5608a variable @code{$foo_or_bar} to @code{AC_LIBOBJ} that holds either 5609@code{"foo"} or @code{"bar"}, you should do: 5610 5611@example 5612AC_LIBSOURCE([foo.c]) 5613AC_LIBSOURCE([bar.c]) 5614AC_LIBOBJ([$foo_or_bar]) 5615@end example 5616 5617@noindent 5618There is usually a way to avoid this, however, and you are encouraged to 5619simply call @code{AC_LIBOBJ} with literal arguments. 5620 5621Note that this macro replaces the obsolete @code{AC_LIBOBJ_DECL}, with 5622slightly different semantics: the old macro took the function name, 5623e.g., @code{foo}, as its argument rather than the file name. 5624@end defmac 5625 5626@defmac AC_LIBSOURCES (@var{files}) 5627@acindex{LIBSOURCES} 5628Like @code{AC_LIBSOURCE}, but accepts one or more @var{files} in a 5629comma-separated M4 list. Thus, the above example might be rewritten: 5630 5631@example 5632AC_LIBSOURCES([foo.c, bar.c]) 5633AC_LIBOBJ([$foo_or_bar]) 5634@end example 5635@end defmac 5636 5637@defmac AC_CONFIG_LIBOBJ_DIR (@var{directory}) 5638@acindex{CONFIG_LIBOBJ_DIR} 5639Specify that @code{AC_LIBOBJ} replacement files are to be found in 5640@var{directory}, a name relative to the top level of the 5641source tree. The replacement directory defaults to @file{.}, the top 5642level directory, and the most typical value is @file{lib}, corresponding 5643to @samp{AC_CONFIG_LIBOBJ_DIR([lib])}. 5644 5645@command{configure} might need to know the replacement directory for the 5646following reasons: (i) some checks use the replacement files, (ii) some 5647macros bypass broken system headers by installing links to the 5648replacement headers (iii) when used in conjunction with Automake, 5649within each makefile, @var{directory} is used as a relative path 5650from @code{$(top_srcdir)} to each object named in @code{LIBOBJS} and 5651@code{LTLIBOBJS}, etc. 5652@end defmac 5653 5654@sp 1 5655 5656It is common to merely check for the existence of a function, and ask 5657for its @code{AC_LIBOBJ} replacement if missing. The following macro is 5658a convenient shorthand. 5659 5660@defmac AC_REPLACE_FUNCS (@var{function}@dots{}) 5661@acindex{REPLACE_FUNCS} 5662@cvindex HAVE_@var{function} 5663@ovindex LIBOBJS 5664Like @code{AC_CHECK_FUNCS}, but uses @samp{AC_LIBOBJ(@var{function})} as 5665@var{action-if-not-found}. You can declare your replacement function by 5666enclosing the prototype in @samp{#ifndef HAVE_@var{function}}. If the 5667system has the function, it probably declares it in a header file you 5668should be including, so you shouldn't redeclare it lest your declaration 5669conflict. 5670@end defmac 5671 5672@node Header Files 5673@section Header Files 5674@cindex Header, checking 5675 5676The following macros check for the presence of certain C header files. 5677If there is no macro specifically defined to check for a header file you need, 5678and you don't need to check for any special properties of 5679it, then you can use one of the general header-file check macros. 5680 5681@menu 5682* Header Portability:: Collected knowledge on common headers 5683* Particular Headers:: Special handling to find certain headers 5684* Generic Headers:: How to find other headers 5685@end menu 5686 5687@node Header Portability 5688@subsection Portability of Headers 5689@cindex Portability of headers 5690@cindex Header portability 5691 5692This section documents some collected knowledge about common headers, 5693and the problems they cause. By definition, this list always requires 5694additions. A much more complete list is maintained by the Gnulib 5695project (@pxref{Gnulib}), covering @ref{Header File Substitutes, , 5696Posix Headers, gnulib, GNU gnulib} and @ref{Glibc Header File 5697Substitutes, , Glibc Headers, gnulib, GNU gnulib}. Please help us keep 5698the gnulib list as complete as possible. 5699 5700@table @asis 5701 5702@item @file{limits.h} 5703C99 says that @file{limits.h} defines @code{LLONG_MIN}, 5704@code{LLONG_MAX}, and @code{ULLONG_MAX}, but many almost-C99 5705environments (e.g., default GCC 4.0.2 + glibc 2.4) do not 5706define them. 5707 5708@item @file{inttypes.h} vs.@: @file{stdint.h} 5709@hdrindex{inttypes.h} 5710@hdrindex{stdint.h} 5711The C99 standard says that @file{inttypes.h} includes 5712@file{stdint.h}, so there's no need to include @file{stdint.h} 5713separately in a standard environment. Some implementations have 5714@file{inttypes.h} but not @file{stdint.h} (e.g., Solaris 7), but we don't 5715know of any implementation that has @file{stdint.h} but not 5716@file{inttypes.h}. 5717 5718@item @file{linux/irda.h} 5719@hdrindex{linux/irda.h} 5720It requires @file{linux/types.h} and @file{sys/socket.h}. 5721 5722@item @file{linux/random.h} 5723@hdrindex{linux/random.h} 5724It requires @file{linux/types.h}. 5725 5726@item @file{net/if.h} 5727@hdrindex{net/if.h} 5728On Darwin, this file requires that @file{sys/socket.h} be included 5729beforehand. One should run: 5730 5731@example 5732AC_CHECK_HEADERS([sys/socket.h]) 5733AC_CHECK_HEADERS([net/if.h], [], [], 5734[#include <stdio.h> 5735#ifdef STDC_HEADERS 5736# include <stdlib.h> 5737# include <stddef.h> 5738#else 5739# ifdef HAVE_STDLIB_H 5740# include <stdlib.h> 5741# endif 5742#endif 5743#ifdef HAVE_SYS_SOCKET_H 5744# include <sys/socket.h> 5745#endif 5746]) 5747@end example 5748 5749@item @file{netinet/if_ether.h} 5750@hdrindex{netinet/if_ether.h} 5751On Darwin, this file requires that @file{stdio.h} and 5752@file{sys/socket.h} be included beforehand. One should run: 5753 5754@example 5755AC_CHECK_HEADERS([sys/socket.h]) 5756AC_CHECK_HEADERS([netinet/if_ether.h], [], [], 5757[#include <stdio.h> 5758#ifdef STDC_HEADERS 5759# include <stdlib.h> 5760# include <stddef.h> 5761#else 5762# ifdef HAVE_STDLIB_H 5763# include <stdlib.h> 5764# endif 5765#endif 5766#ifdef HAVE_SYS_SOCKET_H 5767# include <sys/socket.h> 5768#endif 5769]) 5770@end example 5771 5772@item @file{stdint.h} 5773See above, item @file{inttypes.h} vs.@: @file{stdint.h}. 5774 5775@item @file{stdlib.h} 5776@hdrindex{stdlib.h} 5777On many systems (e.g., Darwin), @file{stdio.h} is a prerequisite. 5778 5779@item @file{sys/mount.h} 5780@hdrindex{sys/mount.h} 5781On FreeBSD 4.8 on ia32 and using gcc version 2.95.4, 5782@file{sys/params.h} is a prerequisite. 5783 5784@item @file{sys/ptem.h} 5785@hdrindex{sys/ptem.h} 5786On Solaris 8, @file{sys/stream.h} is a prerequisite. 5787 5788@item @file{sys/socket.h} 5789@hdrindex{sys/socket.h} 5790On Darwin, @file{stdlib.h} is a prerequisite. 5791 5792@item @file{sys/ucred.h} 5793@hdrindex{sys/ucred.h} 5794On Tru64 5.1, @file{sys/types.h} is a prerequisite. 5795 5796@item @file{X11/extensions/scrnsaver.h} 5797@hdrindex{X11/extensions/scrnsaver.h} 5798Using XFree86, this header requires @file{X11/Xlib.h}, which is probably 5799so required that you might not even consider looking for it. 5800 5801@example 5802AC_CHECK_HEADERS([X11/extensions/scrnsaver.h], [], [], 5803[[#include <X11/Xlib.h> 5804]]) 5805@end example 5806@end table 5807 5808 5809@node Particular Headers 5810@subsection Particular Header Checks 5811 5812These macros check for particular system header files---whether they 5813exist, and in some cases whether they declare certain symbols. 5814 5815@defmac AC_CHECK_HEADER_STDBOOL 5816@acindex{CHECK_HEADER_STDBOOL} 5817@cvindex HAVE__BOOL 5818@hdrindex{stdbool.h} 5819@caindex header_stdbool_h 5820Check whether @file{stdbool.h} exists and conforms to C99, and cache the 5821result in the @code{ac_cv_header_stdbool_h} variable. If the type 5822@code{_Bool} is defined, define @code{HAVE__BOOL} to 1. 5823 5824This macro is intended for use by Gnulib (@pxref{Gnulib}) and other 5825packages that supply a substitute @file{stdbool.h} on platforms lacking 5826a conforming one. The @code{AC_HEADER_STDBOOL} macro is better for code 5827that explicitly checks for @file{stdbool.h}. 5828@end defmac 5829 5830@defmac AC_HEADER_ASSERT 5831@acindex{HEADER_ASSERT} 5832@cvindex NDEBUG 5833@hdrindex{assert.h} 5834Check whether to enable assertions in the style of @file{assert.h}. 5835Assertions are enabled by default, but the user can override this by 5836invoking @command{configure} with the @option{--disable-assert} option. 5837@end defmac 5838 5839@anchor{AC_HEADER_DIRENT} 5840@defmac AC_HEADER_DIRENT 5841@acindex{HEADER_DIRENT} 5842@cvindex HAVE_DIRENT_H 5843@cvindex HAVE_NDIR_H 5844@cvindex HAVE_SYS_DIR_H 5845@cvindex HAVE_SYS_NDIR_H 5846@hdrindex{dirent.h} 5847@hdrindex{sys/ndir.h} 5848@hdrindex{sys/dir.h} 5849@hdrindex{ndir.h} 5850Check for the following header files. For the first one that is 5851found and defines @samp{DIR}, define the listed C preprocessor macro: 5852 5853@multitable {@file{sys/ndir.h}} {@code{HAVE_SYS_NDIR_H}} 5854@item @file{dirent.h} @tab @code{HAVE_DIRENT_H} 5855@item @file{sys/ndir.h} @tab @code{HAVE_SYS_NDIR_H} 5856@item @file{sys/dir.h} @tab @code{HAVE_SYS_DIR_H} 5857@item @file{ndir.h} @tab @code{HAVE_NDIR_H} 5858@end multitable 5859 5860The directory-library declarations in your source code should look 5861something like the following: 5862 5863@example 5864@group 5865#include <sys/types.h> 5866#ifdef HAVE_DIRENT_H 5867# include <dirent.h> 5868# define NAMLEN(dirent) strlen ((dirent)->d_name) 5869#else 5870# define dirent direct 5871# define NAMLEN(dirent) ((dirent)->d_namlen) 5872# ifdef HAVE_SYS_NDIR_H 5873# include <sys/ndir.h> 5874# endif 5875# ifdef HAVE_SYS_DIR_H 5876# include <sys/dir.h> 5877# endif 5878# ifdef HAVE_NDIR_H 5879# include <ndir.h> 5880# endif 5881#endif 5882@end group 5883@end example 5884 5885Using the above declarations, the program would declare variables to be 5886of type @code{struct dirent}, not @code{struct direct}, and would access 5887the length of a directory entry name by passing a pointer to a 5888@code{struct dirent} to the @code{NAMLEN} macro. 5889 5890This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries. 5891 5892This macro is obsolescent, as all current systems with directory 5893libraries have @code{<dirent.h>}. New programs need not use this macro. 5894 5895Also see @code{AC_STRUCT_DIRENT_D_INO} and 5896@code{AC_STRUCT_DIRENT_D_TYPE} (@pxref{Particular Structures}). 5897@end defmac 5898 5899@anchor{AC_HEADER_MAJOR} 5900@defmac AC_HEADER_MAJOR 5901@acindex{HEADER_MAJOR} 5902@cvindex MAJOR_IN_MKDEV 5903@cvindex MAJOR_IN_SYSMACROS 5904@hdrindex{sys/mkdev.h} 5905@hdrindex{sys/sysmacros.h} 5906If @file{sys/types.h} does not define @code{major}, @code{minor}, and 5907@code{makedev}, but @file{sys/mkdev.h} does, define 5908@code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define 5909@code{MAJOR_IN_SYSMACROS}. 5910@end defmac 5911 5912@defmac AC_HEADER_RESOLV 5913@acindex{HEADER_RESOLV} 5914@cvindex HAVE_RESOLV_H 5915@hdrindex{resolv.h} 5916Checks for header @file{resolv.h}, checking for prerequisites first. 5917To properly use @file{resolv.h}, your code should contain something like 5918the following: 5919 5920@verbatim 5921#ifdef HAVE_SYS_TYPES_H 5922# include <sys/types.h> 5923#endif 5924#ifdef HAVE_NETINET_IN_H 5925# include <netinet/in.h> /* inet_ functions / structs */ 5926#endif 5927#ifdef HAVE_ARPA_NAMESER_H 5928# include <arpa/nameser.h> /* DNS HEADER struct */ 5929#endif 5930#ifdef HAVE_NETDB_H 5931# include <netdb.h> 5932#endif 5933#include <resolv.h> 5934@end verbatim 5935@end defmac 5936 5937@anchor{AC_HEADER_STAT} 5938@defmac AC_HEADER_STAT 5939@acindex{HEADER_STAT} 5940@cvindex STAT_MACROS_BROKEN 5941@hdrindex{sys/stat.h} 5942If the macros @code{S_ISDIR}, @code{S_ISREG}, etc.@: defined in 5943@file{sys/stat.h} do not work properly (returning false positives), 5944define @code{STAT_MACROS_BROKEN}. This is the case on Tektronix UTekV, 5945Amdahl UTS and Motorola System V/88. 5946 5947This macro is obsolescent, as no current systems have the bug. 5948New programs need not use this macro. 5949@end defmac 5950 5951@defmac AC_HEADER_STDBOOL 5952@acindex{HEADER_STDBOOL} 5953@cvindex HAVE_STDBOOL_H 5954@cvindex HAVE__BOOL 5955@hdrindex{stdbool.h} 5956@caindex header_stdbool_h 5957If @file{stdbool.h} exists and conforms to C99, define 5958@code{HAVE_STDBOOL_H} to 1; if the type @code{_Bool} is defined, define 5959@code{HAVE__BOOL} to 1. To fulfill the C99 requirements, your 5960program could contain the following code: 5961 5962@example 5963@group 5964#ifdef HAVE_STDBOOL_H 5965# include <stdbool.h> 5966#else 5967# ifndef HAVE__BOOL 5968# ifdef __cplusplus 5969typedef bool _Bool; 5970# else 5971# define _Bool signed char 5972# endif 5973# endif 5974# define bool _Bool 5975# define false 0 5976# define true 1 5977# define __bool_true_false_are_defined 1 5978#endif 5979@end group 5980@end example 5981 5982Alternatively you can use the @samp{stdbool} package of Gnulib 5983(@pxref{Gnulib}). It simplifies your code so that it can say just 5984@code{#include <stdbool.h>}, and it adds support for less-common 5985platforms. 5986 5987This macro caches its result in the @code{ac_cv_header_stdbool_h} 5988variable. 5989 5990This macro differs from @code{AC_CHECK_HEADER_STDBOOL} only in that it 5991defines @code{HAVE_STDBOOL_H} whereas @code{AC_CHECK_HEADER_STDBOOL} 5992does not. 5993@end defmac 5994 5995@anchor{AC_HEADER_STDC} 5996@defmac AC_HEADER_STDC 5997@acindex{HEADER_STDC} 5998@cvindex STDC_HEADERS 5999@hdrindex{stdlib.h} 6000@hdrindex{stdarg.h} 6001@hdrindex{string.h} 6002@hdrindex{float.h} 6003@hdrindex{ctype.h} 6004@caindex header_stdc 6005Define @code{STDC_HEADERS} if the system has C header files 6006conforming to ANSI C89 (ISO C90). 6007Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h}, 6008@file{string.h}, and @file{float.h}; if the system has those, it 6009probably has the rest of the C89 header files. This macro also 6010checks whether @file{string.h} declares @code{memchr} (and thus 6011presumably the other @code{mem} functions), whether @file{stdlib.h} 6012declare @code{free} (and thus presumably @code{malloc} and other related 6013functions), and whether the @file{ctype.h} macros work on characters 6014with the high bit set, as the C standard requires. 6015 6016If you use this macro, your code can refer to @code{STDC_HEADERS} to 6017determine whether the system has conforming header files (and probably C 6018library functions). 6019 6020This macro caches its result in the @code{ac_cv_header_stdc} variable. 6021 6022This macro is obsolescent, as current systems have conforming header 6023files. New programs need not use this macro. 6024 6025@hdrindex{string.h} 6026@hdrindex{strings.h} 6027Nowadays @file{string.h} is part of the C standard and declares functions like 6028@code{strcpy}, and @file{strings.h} is standardized by Posix and declares 6029BSD functions like @code{bcopy}; but 6030historically, string functions were a major sticking point in this area. 6031If you still want to worry about portability to ancient systems without 6032standard headers, there is so much variation 6033that it is probably easier to declare the functions you use than to 6034figure out exactly what the system header files declare. Some ancient systems 6035contained a mix of functions from the C standard and from BSD; 6036some were mostly standard but lacked @samp{memmove}; some defined the 6037BSD functions as macros in @file{string.h} or 6038@file{strings.h}; some had only the BSD functions but 6039@file{string.h}; some declared the memory functions in @file{memory.h}, 6040some in @file{string.h}; etc. It is probably sufficient to check for 6041one string function and one memory function; if the library had the 6042standard versions of those then it probably had most of the others. 6043If you put the following in @file{configure.ac}: 6044 6045@example 6046# This example is obsolescent. 6047# Nowadays you can omit these macro calls. 6048AC_HEADER_STDC 6049AC_CHECK_FUNCS([strchr memcpy]) 6050@end example 6051 6052@noindent 6053then, in your code, you can use declarations like this: 6054 6055@example 6056@group 6057/* This example is obsolescent. 6058 Nowadays you can just #include <string.h>. */ 6059#ifdef STDC_HEADERS 6060# include <string.h> 6061#else 6062# ifndef HAVE_STRCHR 6063# define strchr index 6064# define strrchr rindex 6065# endif 6066char *strchr (), *strrchr (); 6067# ifndef HAVE_MEMCPY 6068# define memcpy(d, s, n) bcopy ((s), (d), (n)) 6069# define memmove(d, s, n) bcopy ((s), (d), (n)) 6070# endif 6071#endif 6072@end group 6073@end example 6074 6075@noindent 6076If you use a function like @code{memchr}, @code{memset}, @code{strtok}, 6077or @code{strspn}, which have no BSD equivalent, then macros don't 6078suffice to port to ancient hosts; you must provide an implementation of 6079each function. An easy 6080way to incorporate your implementations only when needed (since the ones 6081in system C libraries may be hand optimized) is to, taking @code{memchr} 6082for example, put it in @file{memchr.c} and use 6083@samp{AC_REPLACE_FUNCS([memchr])}. 6084@end defmac 6085 6086@defmac AC_HEADER_SYS_WAIT 6087@acindex{HEADER_SYS_WAIT} 6088@cvindex HAVE_SYS_WAIT_H 6089@hdrindex{sys/wait.h} 6090@caindex header_sys_wait_h 6091If @file{sys/wait.h} exists and is compatible with Posix, define 6092@code{HAVE_SYS_WAIT_H}. Incompatibility can occur if @file{sys/wait.h} 6093does not exist, or if it uses the old BSD @code{union wait} instead 6094of @code{int} to store a status value. If @file{sys/wait.h} is not 6095Posix compatible, then instead of including it, define the 6096Posix macros with their usual interpretations. Here is an 6097example: 6098 6099@example 6100@group 6101#include <sys/types.h> 6102#ifdef HAVE_SYS_WAIT_H 6103# include <sys/wait.h> 6104#endif 6105#ifndef WEXITSTATUS 6106# define WEXITSTATUS(stat_val) ((unsigned int) (stat_val) >> 8) 6107#endif 6108#ifndef WIFEXITED 6109# define WIFEXITED(stat_val) (((stat_val) & 255) == 0) 6110#endif 6111@end group 6112@end example 6113 6114@noindent 6115This macro caches its result in the @code{ac_cv_header_sys_wait_h} 6116variable. 6117 6118This macro is obsolescent, as current systems are compatible with Posix. 6119New programs need not use this macro. 6120@end defmac 6121 6122@cvindex _POSIX_VERSION 6123@hdrindex{unistd.h} 6124@code{_POSIX_VERSION} is defined when @file{unistd.h} is included on 6125Posix systems. If there is no @file{unistd.h}, it is definitely 6126not a Posix system. However, some non-Posix systems do 6127have @file{unistd.h}. 6128 6129The way to check whether the system supports Posix is: 6130 6131@example 6132@group 6133#ifdef HAVE_UNISTD_H 6134# include <sys/types.h> 6135# include <unistd.h> 6136#endif 6137 6138#ifdef _POSIX_VERSION 6139/* Code for Posix systems. */ 6140#endif 6141@end group 6142@end example 6143 6144@anchor{AC_HEADER_TIME} 6145@defmac AC_HEADER_TIME 6146@acindex{HEADER_TIME} 6147@cvindex TIME_WITH_SYS_TIME 6148@hdrindex{time.h} 6149@hdrindex{sys/time.h} 6150@caindex header_time 6151If a program may include both @file{time.h} and @file{sys/time.h}, 6152define @code{TIME_WITH_SYS_TIME}. On some ancient systems, 6153@file{sys/time.h} included @file{time.h}, but @file{time.h} was not 6154protected against multiple inclusion, so programs could not explicitly 6155include both files. This macro is useful in programs that use, for 6156example, @code{struct timeval} as well as 6157@code{struct tm}. It is best used in conjunction with 6158@code{HAVE_SYS_TIME_H}, which can be checked for using 6159@code{AC_CHECK_HEADERS([sys/time.h])}. 6160 6161@example 6162@group 6163#ifdef TIME_WITH_SYS_TIME 6164# include <sys/time.h> 6165# include <time.h> 6166#else 6167# ifdef HAVE_SYS_TIME_H 6168# include <sys/time.h> 6169# else 6170# include <time.h> 6171# endif 6172#endif 6173@end group 6174@end example 6175 6176@noindent 6177This macro caches its result in the @code{ac_cv_header_time} variable. 6178 6179This macro is obsolescent, as current systems can include both files 6180when they exist. New programs need not use this macro. 6181@end defmac 6182 6183 6184@defmac AC_HEADER_TIOCGWINSZ 6185@acindex{HEADER_TIOCGWINSZ} 6186@cvindex GWINSZ_IN_SYS_IOCTL 6187@hdrindex{sys/ioctl.h} 6188@hdrindex{termios.h} 6189@c FIXME: I need clarifications from Jim. 6190If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then 6191define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be 6192found in @file{<termios.h>}. 6193 6194Use: 6195 6196@example 6197@group 6198#ifdef HAVE_TERMIOS_H 6199# include <termios.h> 6200#endif 6201 6202#ifdef GWINSZ_IN_SYS_IOCTL 6203# include <sys/ioctl.h> 6204#endif 6205@end group 6206@end example 6207@end defmac 6208 6209@node Generic Headers 6210@subsection Generic Header Checks 6211 6212These macros are used to find system header files not covered by the 6213``particular'' test macros. If you need to check the contents of a header 6214as well as find out whether it is present, you have to write your own 6215test for it (@pxref{Writing Tests}). 6216 6217@anchor{AC_CHECK_HEADER} 6218@defmac AC_CHECK_HEADER (@var{header-file}, @ovar{action-if-found}, @ 6219 @ovar{action-if-not-found}, @ovar{includes}) 6220@acindex{CHECK_HEADER} 6221@caindex header_@var{header-file} 6222If the system header file @var{header-file} is compilable, execute shell 6223commands @var{action-if-found}, otherwise execute 6224@var{action-if-not-found}. If you just want to define a symbol if the 6225header file is available, consider using @code{AC_CHECK_HEADERS} 6226instead. 6227 6228@var{includes} is decoded to determine the appropriate include 6229directives. If omitted or empty, @file{configure} will check for both header 6230existence (with the preprocessor) and usability (with the compiler), 6231using @code{AC_INCLUDES_DEFAULT} for the compile test. If 6232there is a discrepancy between the results, a warning is issued to the 6233user, and the compiler results are favored (@pxref{Present But 6234Cannot Be Compiled}). In general, favoring the compiler results means 6235that a header will be treated as not found even though the file exists, 6236because you did not provide enough prerequisites. 6237 6238Providing a non-empty @var{includes} argument allows the code to provide 6239any prerequisites prior to including the header under test; it is common 6240to use the argument @code{AC_INCLUDES_DEFAULT} (@pxref{Default 6241Includes}). With an explicit fourth argument, no preprocessor test is 6242needed. As a special case, an @var{includes} of exactly @samp{-} 6243triggers the older preprocessor check, which merely determines existence 6244of the file in the preprocessor search path; this should only be used as 6245a last resort (it is safer to determine the actual prerequisites and 6246perform a compiler check, or else use @code{AC_PREPROC_IFELSE} to make 6247it obvious that only a preprocessor check is desired). 6248 6249This macro caches its result in the @code{ac_cv_header_@var{header-file}} 6250variable, with characters not suitable for a variable name mapped to 6251underscores. 6252@end defmac 6253 6254@anchor{AC_CHECK_HEADERS} 6255@defmac AC_CHECK_HEADERS (@var{header-file}@dots{}, @ 6256 @ovar{action-if-found}, @ovar{action-if-not-found}, @ 6257 @ovar{includes}) 6258@acindex{CHECK_HEADERS} 6259@cvindex HAVE_@var{header} 6260@caindex header_@var{header-file} 6261For each given system header file @var{header-file} in the 6262blank-separated argument list that exists, define 6263@code{HAVE_@var{header-file}} (in all capitals). If @var{action-if-found} 6264is given, it is additional shell code to execute when one of the header 6265files is found. You can give it a value of @samp{break} to break out of 6266the loop on the first match. If @var{action-if-not-found} is given, it 6267is executed when one of the header files is not found. 6268 6269@var{includes} is interpreted as in @code{AC_CHECK_HEADER}, in order to 6270choose the set of preprocessor directives supplied before the header 6271under test. 6272 6273This macro caches its result in the @code{ac_cv_header_@var{header-file}} 6274variable, with characters not suitable for a variable name mapped to 6275underscores. 6276@end defmac 6277 6278Previous versions of Autoconf merely checked whether the header was 6279accepted by the preprocessor. This was changed because the old test was 6280inappropriate for typical uses. Headers are typically used to compile, 6281not merely to preprocess, and the old behavior sometimes accepted 6282headers that clashed at compile-time (@pxref{Present But Cannot Be 6283Compiled}). If you need to check whether a header is preprocessable, 6284you can use @code{AC_PREPROC_IFELSE} (@pxref{Running the Preprocessor}). 6285 6286Actually requiring a header to compile improves the robustness of the 6287test, but it also requires 6288that you make sure that headers that must be included before the 6289@var{header-file} be part of the @var{includes}, (@pxref{Default 6290Includes}). If looking for @file{bar.h}, which requires that 6291@file{foo.h} be included before if it exists, we suggest the following 6292scheme: 6293 6294@verbatim 6295AC_CHECK_HEADERS([foo.h]) 6296AC_CHECK_HEADERS([bar.h], [], [], 6297[#ifdef HAVE_FOO_H 6298# include <foo.h> 6299#endif 6300]) 6301@end verbatim 6302 6303The following variant generates smaller, faster @command{configure} 6304files if you do not need the full power of @code{AC_CHECK_HEADERS}. 6305 6306@defmac AC_CHECK_HEADERS_ONCE (@var{header-file}@dots{}) 6307@acindex{CHECK_HEADERS_ONCE} 6308@cvindex HAVE_@var{header} 6309For each given system header file @var{header-file} in the 6310blank-separated argument list that exists, define 6311@code{HAVE_@var{header-file}} (in all capitals). 6312This is a once-only variant of @code{AC_CHECK_HEADERS}. It generates the 6313checking code at most once, so that @command{configure} is smaller and 6314faster; but the checks cannot be conditionalized and are always done once, 6315early during the @command{configure} run. Thus, this macro is only safe 6316for checking headers that do not have prerequisites beyond what 6317@code{AC_INCLUDES_DEFAULT} provides. 6318@end defmac 6319 6320@node Declarations 6321@section Declarations 6322@cindex Declaration, checking 6323 6324The following macros check for the declaration of variables and 6325functions. If there is no macro specifically defined to check for a 6326symbol you need, then you can use the general macros (@pxref{Generic 6327Declarations}) or, for more complex tests, you may use 6328@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}). 6329 6330@menu 6331* Particular Declarations:: Macros to check for certain declarations 6332* Generic Declarations:: How to find other declarations 6333@end menu 6334 6335@node Particular Declarations 6336@subsection Particular Declaration Checks 6337 6338There are no specific macros for declarations. 6339 6340@node Generic Declarations 6341@subsection Generic Declaration Checks 6342 6343These macros are used to find declarations not covered by the ``particular'' 6344test macros. 6345 6346@defmac AC_CHECK_DECL (@var{symbol}, @ovar{action-if-found}, @ 6347 @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT}) 6348@acindex{CHECK_DECL} 6349@caindex have_decl_@var{symbol} 6350If @var{symbol} (a function, variable, or constant) is not declared in 6351@var{includes} and a declaration is needed, run the shell commands 6352@var{action-if-not-found}, otherwise @var{action-if-found}. 6353@var{includes} is a series of include directives, defaulting to 6354@code{AC_INCLUDES_DEFAULT} (@pxref{Default Includes}), which are used 6355prior to the declaration under test. 6356 6357This macro actually tests whether @var{symbol} is defined as a macro or 6358can be used as an r-value, not whether it is really declared, because it 6359is much safer to avoid introducing extra declarations when they are not 6360needed. In order to facilitate use of C++ and overloaded function 6361declarations, it is possible to specify function argument types in 6362parentheses for types which can be zero-initialized: 6363 6364@example 6365AC_CHECK_DECL([basename(char *)]) 6366@end example 6367 6368This macro caches its result in the @code{ac_cv_have_decl_@var{symbol}} 6369variable, with characters not suitable for a variable name mapped to 6370underscores. 6371@end defmac 6372 6373@anchor{AC_CHECK_DECLS} 6374@defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @ 6375 @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT}) 6376@acindex{CHECK_DECLS} 6377@cvindex HAVE_DECL_@var{symbol} 6378@caindex have_decl_@var{symbol} 6379For each of the @var{symbols} (@emph{comma}-separated list with optional 6380function argument types for C++ overloads), define 6381@code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if 6382@var{symbol} is declared, otherwise to @samp{0}. If 6383@var{action-if-not-found} is given, it is additional shell code to 6384execute when one of the function declarations is needed, otherwise 6385@var{action-if-found} is executed. 6386 6387@var{includes} is a series of include directives, defaulting to 6388@code{AC_INCLUDES_DEFAULT} (@pxref{Default Includes}), which are used 6389prior to the declarations under test. 6390 6391This macro uses an M4 list as first argument: 6392@example 6393AC_CHECK_DECLS([strdup]) 6394AC_CHECK_DECLS([strlen]) 6395AC_CHECK_DECLS([malloc, realloc, calloc, free]) 6396AC_CHECK_DECLS([j0], [], [], [[#include <math.h>]]) 6397AC_CHECK_DECLS([[basename(char *)], [dirname(char *)]]) 6398@end example 6399 6400Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not 6401declared, @code{HAVE_DECL_@var{symbol}} is defined to @samp{0} instead 6402of leaving @code{HAVE_DECL_@var{symbol}} undeclared. When you are 6403@emph{sure} that the check was performed, use 6404@code{HAVE_DECL_@var{symbol}} in @code{#if}: 6405 6406@example 6407#if !HAVE_DECL_SYMBOL 6408extern char *symbol; 6409#endif 6410@end example 6411 6412@noindent 6413If the test may have not been performed, however, because it is safer 6414@emph{not} to declare a symbol than to use a declaration that conflicts 6415with the system's one, you should use: 6416 6417@example 6418#if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC 6419void *malloc (size_t *s); 6420#endif 6421@end example 6422 6423@noindent 6424You fall into the second category only in extreme situations: either 6425your files may be used without being configured, or they are used during 6426the configuration. In most cases the traditional approach is enough. 6427 6428This macro caches its results in @code{ac_cv_have_decl_@var{symbol}} 6429variables, with characters not suitable for a variable name mapped to 6430underscores. 6431@end defmac 6432 6433@defmac AC_CHECK_DECLS_ONCE (@var{symbols}) 6434@acindex{CHECK_DECLS_ONCE} 6435@cvindex HAVE_DECL_@var{symbol} 6436For each of the @var{symbols} (@emph{comma}-separated list), define 6437@code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if 6438@var{symbol} is declared in the default include files, otherwise to 6439@samp{0}. This is a once-only variant of @code{AC_CHECK_DECLS}. It 6440generates the checking code at most once, so that @command{configure} is 6441smaller and faster; but the checks cannot be conditionalized and are 6442always done once, early during the @command{configure} run. 6443@end defmac 6444 6445 6446@node Structures 6447@section Structures 6448@cindex Structure, checking 6449 6450The following macros check for the presence of certain members in C 6451structures. If there is no macro specifically defined to check for a 6452member you need, then you can use the general structure-member macros 6453(@pxref{Generic Structures}) or, for more complex tests, you may use 6454@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}). 6455 6456@menu 6457* Particular Structures:: Macros to check for certain structure members 6458* Generic Structures:: How to find other structure members 6459@end menu 6460 6461@node Particular Structures 6462@subsection Particular Structure Checks 6463 6464The following macros check for certain structures or structure members. 6465 6466@defmac AC_STRUCT_DIRENT_D_INO 6467@acindex{STRUCT_DIRENT_D_INO} 6468@cvindex HAVE_STRUCT_DIRENT_D_INO 6469@c @caindex header_dirent_dirent_h 6470@c @caindex member_struct_dirent_d_ino 6471Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular 6472Headers}). Then, if @code{struct dirent} contains a @code{d_ino} 6473member, define @code{HAVE_STRUCT_DIRENT_D_INO}. 6474 6475@code{HAVE_STRUCT_DIRENT_D_INO} indicates only the presence of 6476@code{d_ino}, not whether its contents are always reliable. 6477Traditionally, a zero @code{d_ino} indicated a deleted directory entry, 6478though current systems hide this detail from the user and never return 6479zero @code{d_ino} values. 6480Many current systems report an incorrect @code{d_ino} for a directory 6481entry that is a mount point. 6482@end defmac 6483 6484@defmac AC_STRUCT_DIRENT_D_TYPE 6485@acindex{STRUCT_DIRENT_D_TYPE} 6486@cvindex HAVE_STRUCT_DIRENT_D_TYPE 6487@c @caindex header_dirent_dirent_h 6488@c @caindex member_struct_dirent_d_type 6489Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular 6490Headers}). Then, if @code{struct dirent} contains a @code{d_type} 6491member, define @code{HAVE_STRUCT_DIRENT_D_TYPE}. 6492@end defmac 6493 6494@anchor{AC_STRUCT_ST_BLOCKS} 6495@defmac AC_STRUCT_ST_BLOCKS 6496@acindex{STRUCT_ST_BLOCKS} 6497@cvindex HAVE_STRUCT_STAT_ST_BLOCKS 6498@cvindex HAVE_ST_BLOCKS 6499@ovindex LIBOBJS 6500@caindex member_struct_stat_st_blocks 6501If @code{struct stat} contains an @code{st_blocks} member, define 6502@code{HAVE_STRUCT_STAT_ST_BLOCKS}. Otherwise, require an 6503@code{AC_LIBOBJ} replacement of @samp{fileblocks}. The former name, 6504@code{HAVE_ST_BLOCKS} is to be avoided, as its support will cease in the 6505future. 6506 6507This macro caches its result in the @code{ac_cv_member_struct_stat_st_blocks} 6508variable. 6509@end defmac 6510 6511@defmac AC_STRUCT_TM 6512@acindex{STRUCT_TM} 6513@cvindex TM_IN_SYS_TIME 6514@hdrindex{time.h} 6515@hdrindex{sys/time.h} 6516If @file{time.h} does not define @code{struct tm}, define 6517@code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h} 6518had better define @code{struct tm}. 6519 6520This macro is obsolescent, as @file{time.h} defines @code{struct tm} in 6521current systems. New programs need not use this macro. 6522@end defmac 6523 6524@anchor{AC_STRUCT_TIMEZONE} 6525@defmac AC_STRUCT_TIMEZONE 6526@acindex{STRUCT_TIMEZONE} 6527@cvindex HAVE_DECL_TZNAME 6528@cvindex HAVE_STRUCT_TM_TM_ZONE 6529@cvindex HAVE_TM_ZONE 6530@cvindex HAVE_TZNAME 6531@c @caindex member_struct_tm_tm_zone 6532@c @caindex struct_tm 6533Figure out how to get the current timezone. If @code{struct tm} has a 6534@code{tm_zone} member, define @code{HAVE_STRUCT_TM_TM_ZONE} (and the 6535obsoleted @code{HAVE_TM_ZONE}). Otherwise, if the external array 6536@code{tzname} is found, define @code{HAVE_TZNAME}; if it is declared, 6537define @code{HAVE_DECL_TZNAME}. 6538@end defmac 6539 6540@node Generic Structures 6541@subsection Generic Structure Checks 6542 6543These macros are used to find structure members not covered by the 6544``particular'' test macros. 6545 6546@defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @ 6547 @ovar{action-if-found}, @ovar{action-if-not-found}, @ 6548 @dvar{includes, AC_INCLUDES_DEFAULT}) 6549@acindex{CHECK_MEMBER} 6550@caindex member_@var{aggregate}_@var{member} 6551Check whether @var{member} is a member of the aggregate @var{aggregate}. 6552If no @var{includes} are specified, the default includes are used 6553(@pxref{Default Includes}). 6554 6555@example 6556AC_CHECK_MEMBER([struct passwd.pw_gecos], [], 6557 [AC_MSG_ERROR([we need `passwd.pw_gecos'])], 6558 [[#include <pwd.h>]]) 6559@end example 6560 6561You can use this macro for submembers: 6562 6563@example 6564AC_CHECK_MEMBER(struct top.middle.bot) 6565@end example 6566 6567This macro caches its result in the 6568@code{ac_cv_member_@var{aggregate}_@var{member}} variable, with 6569characters not suitable for a variable name mapped to underscores. 6570@end defmac 6571 6572@anchor{AC_CHECK_MEMBERS} 6573@defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @ 6574 @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT}) 6575@acindex{CHECK_MEMBERS} 6576@cvindex HAVE_@var{aggregate}_@var{member} 6577Check for the existence of each @samp{@var{aggregate}.@var{member}} of 6578@var{members} using the previous macro. When @var{member} belongs to 6579@var{aggregate}, define @code{HAVE_@var{aggregate}_@var{member}} (in all 6580capitals, with spaces and dots replaced by underscores). If 6581@var{action-if-found} is given, it is executed for each of the found 6582members. If @var{action-if-not-found} is given, it is executed for each 6583of the members that could not be found. 6584 6585@var{includes} is a series of include directives, defaulting to 6586@code{AC_INCLUDES_DEFAULT} (@pxref{Default Includes}), which are used 6587prior to the members under test. 6588 6589This macro uses M4 lists: 6590@example 6591AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize]) 6592@end example 6593@end defmac 6594 6595 6596@node Types 6597@section Types 6598@cindex Types 6599@cindex C types 6600 6601The following macros check for C types, either builtin or typedefs. If 6602there is no macro specifically defined to check for a type you need, and 6603you don't need to check for any special properties of it, then you can 6604use a general type-check macro. 6605 6606@menu 6607* Particular Types:: Special handling to find certain types 6608* Generic Types:: How to find other types 6609@end menu 6610 6611@node Particular Types 6612@subsection Particular Type Checks 6613 6614@hdrindex{sys/types.h} 6615@hdrindex{stdlib.h} 6616@hdrindex{stdint.h} 6617@hdrindex{inttypes.h} 6618These macros check for particular C types in @file{sys/types.h}, 6619@file{stdlib.h}, @file{stdint.h}, @file{inttypes.h} and others, if they 6620exist. 6621 6622The Gnulib @code{stdint} module is an alternate way to define many of 6623these symbols; it is useful if you prefer your code to assume a 6624C99-or-better environment. @xref{Gnulib}. 6625 6626@anchor{AC_TYPE_GETGROUPS} 6627@defmac AC_TYPE_GETGROUPS 6628@acindex{TYPE_GETGROUPS} 6629@cvindex GETGROUPS_T 6630@caindex type_getgroups 6631Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int} 6632is the base type of the array argument to @code{getgroups}. 6633 6634This macro caches the base type in the @code{ac_cv_type_getgroups} 6635variable. 6636@end defmac 6637 6638@defmac AC_TYPE_INT8_T 6639@acindex{TYPE_INT8_T} 6640@cvindex HAVE_INT8_T 6641@cvindex int8_t 6642@caindex c_int8_t 6643If @file{stdint.h} or @file{inttypes.h} does not define the type 6644@code{int8_t}, define @code{int8_t} to a signed 6645integer type that is exactly 8 bits wide and that uses two's complement 6646representation, if such a type exists. 6647If you are worried about porting to hosts that lack such a type, you can 6648use the results of this macro in C89-or-later code as follows: 6649 6650@example 6651#if HAVE_STDINT_H 6652# include <stdint.h> 6653#endif 6654#if defined INT8_MAX || defined int8_t 6655 @emph{code using int8_t} 6656#else 6657 @emph{complicated alternative using >8-bit 'signed char'} 6658#endif 6659@end example 6660 6661This macro caches the type in the @code{ac_cv_c_int8_t} variable. 6662@end defmac 6663 6664@defmac AC_TYPE_INT16_T 6665@acindex{TYPE_INT16_T} 6666@cvindex HAVE_INT16_T 6667@cvindex int16_t 6668@caindex c_int16_t 6669This is like @code{AC_TYPE_INT8_T}, except for 16-bit integers. 6670@end defmac 6671 6672@defmac AC_TYPE_INT32_T 6673@acindex{TYPE_INT32_T} 6674@cvindex HAVE_INT32_T 6675@cvindex int32_t 6676@caindex c_int32_t 6677This is like @code{AC_TYPE_INT8_T}, except for 32-bit integers. 6678@end defmac 6679 6680@defmac AC_TYPE_INT64_T 6681@acindex{TYPE_INT64_T} 6682@cvindex HAVE_INT64_T 6683@cvindex int64_t 6684@caindex c_int64_t 6685This is like @code{AC_TYPE_INT8_T}, except for 64-bit integers. 6686@end defmac 6687 6688@defmac AC_TYPE_INTMAX_T 6689@acindex{TYPE_INTMAX_T} 6690@cvindex HAVE_INTMAX_T 6691@cvindex intmax_t 6692@c @caindex type_intmax_t 6693If @file{stdint.h} or @file{inttypes.h} defines the type @code{intmax_t}, 6694define @code{HAVE_INTMAX_T}. Otherwise, define @code{intmax_t} to the 6695widest signed integer type. 6696@end defmac 6697 6698@defmac AC_TYPE_INTPTR_T 6699@acindex{TYPE_INTPTR_T} 6700@cvindex HAVE_INTPTR_T 6701@cvindex intptr_t 6702@c @caindex type_intptr_t 6703If @file{stdint.h} or @file{inttypes.h} defines the type @code{intptr_t}, 6704define @code{HAVE_INTPTR_T}. Otherwise, define @code{intptr_t} to a 6705signed integer type wide enough to hold a pointer, if such a type 6706exists. 6707@end defmac 6708 6709@defmac AC_TYPE_LONG_DOUBLE 6710@acindex{TYPE_LONG_DOUBLE} 6711@cvindex HAVE_LONG_DOUBLE 6712@caindex type_long_double 6713If the C compiler supports a working @code{long double} type, define 6714@code{HAVE_LONG_DOUBLE}. The @code{long double} type might have the 6715same range and precision as @code{double}. 6716 6717This macro caches its result in the @code{ac_cv_type_long_double} 6718variable. 6719 6720This macro is obsolescent, as current C compilers support @code{long 6721double}. New programs need not use this macro. 6722@end defmac 6723 6724@defmac AC_TYPE_LONG_DOUBLE_WIDER 6725@acindex{TYPE_LONG_DOUBLE_WIDER} 6726@cvindex HAVE_LONG_DOUBLE_WIDER 6727@caindex type_long_double_wider 6728If the C compiler supports a working @code{long double} type with more 6729range or precision than the @code{double} type, define 6730@code{HAVE_LONG_DOUBLE_WIDER}. 6731 6732This macro caches its result in the @code{ac_cv_type_long_double_wider} 6733variable. 6734@end defmac 6735 6736@defmac AC_TYPE_LONG_LONG_INT 6737@acindex{TYPE_LONG_LONG_INT} 6738@cvindex HAVE_LONG_LONG_INT 6739@caindex type_long_long_int 6740If the C compiler supports a working @code{long long int} type, define 6741@code{HAVE_LONG_LONG_INT}. However, this test does not test 6742@code{long long int} values in preprocessor @code{#if} expressions, 6743because too many compilers mishandle such expressions. 6744@xref{Preprocessor Arithmetic}. 6745 6746This macro caches its result in the @code{ac_cv_type_long_long_int} 6747variable. 6748@end defmac 6749 6750@defmac AC_TYPE_MBSTATE_T 6751@acindex{TYPE_MBSTATE_T} 6752@cvindex mbstate_t 6753@hdrindex{wchar.h} 6754@caindex type_mbstate_t 6755Define @code{HAVE_MBSTATE_T} if @code{<wchar.h>} declares the 6756@code{mbstate_t} type. Also, define @code{mbstate_t} to be a type if 6757@code{<wchar.h>} does not declare it. 6758 6759This macro caches its result in the @code{ac_cv_type_mbstate_t} 6760variable. 6761@end defmac 6762 6763@anchor{AC_TYPE_MODE_T} 6764@defmac AC_TYPE_MODE_T 6765@acindex{TYPE_MODE_T} 6766@cvindex mode_t 6767@caindex type_mode_t 6768Define @code{mode_t} to a suitable type, if standard headers do not 6769define it. 6770 6771This macro caches its result in the @code{ac_cv_type_mode_t} variable. 6772@end defmac 6773 6774@anchor{AC_TYPE_OFF_T} 6775@defmac AC_TYPE_OFF_T 6776@acindex{TYPE_OFF_T} 6777@cvindex off_t 6778@caindex type_off_t 6779Define @code{off_t} to a suitable type, if standard headers do not 6780define it. 6781 6782This macro caches its result in the @code{ac_cv_type_off_t} variable. 6783@end defmac 6784 6785@anchor{AC_TYPE_PID_T} 6786@defmac AC_TYPE_PID_T 6787@acindex{TYPE_PID_T} 6788@cvindex pid_t 6789@caindex type_pid_t 6790Define @code{pid_t} to a suitable type, if standard headers do not 6791define it. 6792 6793This macro caches its result in the @code{ac_cv_type_pid_t} variable. 6794@end defmac 6795 6796@anchor{AC_TYPE_SIZE_T} 6797@defmac AC_TYPE_SIZE_T 6798@acindex{TYPE_SIZE_T} 6799@cvindex size_t 6800@caindex type_size_t 6801Define @code{size_t} to a suitable type, if standard headers do not 6802define it. 6803 6804This macro caches its result in the @code{ac_cv_type_size_t} variable. 6805@end defmac 6806 6807@defmac AC_TYPE_SSIZE_T 6808@acindex{TYPE_SSIZE_T} 6809@cvindex ssize_t 6810@caindex type_ssize_t 6811Define @code{ssize_t} to a suitable type, if standard headers do not 6812define it. 6813 6814This macro caches its result in the @code{ac_cv_type_ssize_t} variable. 6815@end defmac 6816 6817@anchor{AC_TYPE_UID_T} 6818@defmac AC_TYPE_UID_T 6819@acindex{TYPE_UID_T} 6820@cvindex uid_t 6821@cvindex gid_t 6822@caindex type_uid_t 6823Define @code{uid_t} and @code{gid_t} to suitable types, if standard 6824headers do not define them. 6825 6826This macro caches its result in the @code{ac_cv_type_uid_t} variable. 6827@end defmac 6828 6829@defmac AC_TYPE_UINT8_T 6830@acindex{TYPE_UINT8_T} 6831@cvindex HAVE_UINT8_T 6832@cvindex uint8_t 6833@caindex c_uint8_t 6834If @file{stdint.h} or @file{inttypes.h} does not define the type 6835@code{uint8_t}, define @code{uint8_t} to an 6836unsigned integer type that is exactly 8 bits wide, if such a type 6837exists. 6838This is like @code{AC_TYPE_INT8_T}, except for unsigned integers. 6839@end defmac 6840 6841@defmac AC_TYPE_UINT16_T 6842@acindex{TYPE_UINT16_T} 6843@cvindex HAVE_UINT16_T 6844@cvindex uint16_t 6845@caindex c_uint16_t 6846This is like @code{AC_TYPE_UINT8_T}, except for 16-bit integers. 6847@end defmac 6848 6849@defmac AC_TYPE_UINT32_T 6850@acindex{TYPE_UINT32_T} 6851@cvindex HAVE_UINT32_T 6852@cvindex uint32_t 6853@caindex c_uint32_t 6854This is like @code{AC_TYPE_UINT8_T}, except for 32-bit integers. 6855@end defmac 6856 6857@defmac AC_TYPE_UINT64_T 6858@acindex{TYPE_UINT64_T} 6859@cvindex HAVE_UINT64_T 6860@cvindex uint64_t 6861@caindex c_uint64_t 6862This is like @code{AC_TYPE_UINT8_T}, except for 64-bit integers. 6863@end defmac 6864 6865@defmac AC_TYPE_UINTMAX_T 6866@acindex{TYPE_UINTMAX_T} 6867@cvindex HAVE_UINTMAX_T 6868@cvindex uintmax_t 6869@c @caindex type_uintmax_t 6870If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintmax_t}, 6871define @code{HAVE_UINTMAX_T}. Otherwise, define @code{uintmax_t} to the 6872widest unsigned integer type. 6873@end defmac 6874 6875@defmac AC_TYPE_UINTPTR_T 6876@acindex{TYPE_UINTPTR_T} 6877@cvindex HAVE_UINTPTR_T 6878@cvindex uintptr_t 6879@c @caindex type_uintptr_t 6880If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintptr_t}, 6881define @code{HAVE_UINTPTR_T}. Otherwise, define @code{uintptr_t} to an 6882unsigned integer type wide enough to hold a pointer, if such a type 6883exists. 6884@end defmac 6885 6886@defmac AC_TYPE_UNSIGNED_LONG_LONG_INT 6887@acindex{TYPE_UNSIGNED_LONG_LONG_INT} 6888@cvindex HAVE_UNSIGNED_LONG_LONG_INT 6889@caindex type_unsigned_long_long_int 6890If the C compiler supports a working @code{unsigned long long int} type, 6891define @code{HAVE_UNSIGNED_LONG_LONG_INT}. However, this test does not test 6892@code{unsigned long long int} values in preprocessor @code{#if} expressions, 6893because too many compilers mishandle such expressions. 6894@xref{Preprocessor Arithmetic}. 6895 6896This macro caches its result in the @code{ac_cv_type_unsigned_long_long_int} 6897variable. 6898@end defmac 6899 6900@node Generic Types 6901@subsection Generic Type Checks 6902 6903These macros are used to check for types not covered by the ``particular'' 6904test macros. 6905 6906@defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @ 6907 @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT}) 6908@acindex{CHECK_TYPE} 6909@caindex type_@var{type} 6910Check whether @var{type} is defined. It may be a compiler builtin type 6911or defined by the @var{includes}. @var{includes} is a series of include 6912directives, defaulting to @code{AC_INCLUDES_DEFAULT} (@pxref{Default 6913Includes}), which are used prior to the type under test. 6914 6915In C, @var{type} must be a type-name, so that the expression @samp{sizeof 6916(@var{type})} is valid (but @samp{sizeof ((@var{type}))} is not). The 6917same test is applied when compiling for C++, which means that in C++ 6918@var{type} should be a type-id and should not be an anonymous 6919@samp{struct} or @samp{union}. 6920 6921This macro caches its result in the @code{ac_cv_type_@var{type}} 6922variable, with @samp{*} mapped to @samp{p} and other characters not 6923suitable for a variable name mapped to underscores. 6924@end defmac 6925 6926 6927@defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @ 6928 @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT}) 6929@acindex{CHECK_TYPES} 6930@cvindex HAVE_@var{type} 6931For each @var{type} of the @var{types} that is defined, define 6932@code{HAVE_@var{type}} (in all capitals). Each @var{type} must follow 6933the rules of @code{AC_CHECK_TYPE}. If no @var{includes} are 6934specified, the default includes are used (@pxref{Default Includes}). If 6935@var{action-if-found} is given, it is additional shell code to execute 6936when one of the types is found. If @var{action-if-not-found} is given, 6937it is executed when one of the types is not found. 6938 6939This macro uses M4 lists: 6940@example 6941AC_CHECK_TYPES([ptrdiff_t]) 6942AC_CHECK_TYPES([unsigned long long int, uintmax_t]) 6943AC_CHECK_TYPES([float_t], [], [], [[#include <math.h>]]) 6944@end example 6945 6946@end defmac 6947 6948Autoconf, up to 2.13, used to provide to another version of 6949@code{AC_CHECK_TYPE}, broken by design. In order to keep backward 6950compatibility, a simple heuristic, quite safe but not totally, is 6951implemented. In case of doubt, read the documentation of the former 6952@code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}. 6953 6954 6955@node Compilers and Preprocessors 6956@section Compilers and Preprocessors 6957@cindex Compilers 6958@cindex Preprocessors 6959 6960@ovindex EXEEXT 6961All the tests for compilers (@code{AC_PROG_CC}, @code{AC_PROG_CXX}, 6962@code{AC_PROG_F77}) define the output variable @code{EXEEXT} based on 6963the output of the compiler, typically to the empty string if 6964Posix and @samp{.exe} if a DOS variant. 6965 6966@ovindex OBJEXT 6967They also define the output variable @code{OBJEXT} based on the 6968output of the compiler, after @file{.c} files have been excluded, typically 6969to @samp{o} if Posix, @samp{obj} if a DOS variant. 6970 6971If the compiler being used does not produce executables, the tests fail. If 6972the executables can't be run, and cross-compilation is not enabled, they 6973fail too. @xref{Manual Configuration}, for more on support for cross 6974compiling. 6975 6976@menu 6977* Specific Compiler Characteristics:: Some portability issues 6978* Generic Compiler Characteristics:: Language independent tests and features 6979* C Compiler:: Checking its characteristics 6980* C++ Compiler:: Likewise 6981* Objective C Compiler:: Likewise 6982* Objective C++ Compiler:: Likewise 6983* Erlang Compiler and Interpreter:: Likewise 6984* Fortran Compiler:: Likewise 6985* Go Compiler:: Likewise 6986@end menu 6987 6988@node Specific Compiler Characteristics 6989@subsection Specific Compiler Characteristics 6990 6991Some compilers exhibit different behaviors. 6992 6993@table @asis 6994@item Static/Dynamic Expressions 6995Autoconf relies on a trick to extract one bit of information from the C 6996compiler: using negative array sizes. For instance the following 6997excerpt of a C source demonstrates how to test whether @samp{int} objects are 4 6998bytes wide: 6999 7000@example 7001static int test_array[sizeof (int) == 4 ? 1 : -1]; 7002@end example 7003 7004@noindent 7005To our knowledge, there is a single compiler that does not support this 7006trick: the HP C compilers (the real ones, not only the 7007``bundled'') on HP-UX 11.00. 7008They incorrectly reject the above program with the diagnostic 7009``Variable-length arrays cannot have static storage.'' 7010This bug comes from HP compilers' mishandling of @code{sizeof (int)}, 7011not from the @code{? 1 : -1}, and 7012Autoconf works around this problem by casting @code{sizeof (int)} to 7013@code{long int} before comparing it. 7014@end table 7015 7016@node Generic Compiler Characteristics 7017@subsection Generic Compiler Characteristics 7018 7019@anchor{AC_CHECK_SIZEOF} 7020@defmac AC_CHECK_SIZEOF (@var{type-or-expr}, @ovar{unused}, @ 7021 @dvar{includes, AC_INCLUDES_DEFAULT}) 7022@acindex{CHECK_SIZEOF} 7023@cvindex SIZEOF_@var{type-or-expr} 7024@caindex sizeof_@var{type-or-expr} 7025Define @code{SIZEOF_@var{type-or-expr}} (@pxref{Standard Symbols}) to be 7026the size in bytes of @var{type-or-expr}, which may be either a type or 7027an expression returning a value that has a size. If the expression 7028@samp{sizeof (@var{type-or-expr})} is invalid, the result is 0. 7029@var{includes} is a series of include directives, defaulting to 7030@code{AC_INCLUDES_DEFAULT} (@pxref{Default Includes}), which are used 7031prior to the expression under test. 7032 7033This macro now works even when cross-compiling. The @var{unused} 7034argument was used when cross-compiling. 7035 7036For example, the call 7037 7038@example 7039@c If you change this example, adjust tests/semantics.at:AC_CHECK_SIZEOF struct. 7040AC_CHECK_SIZEOF([int *]) 7041@end example 7042 7043@noindent 7044defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems. 7045 7046This macro caches its result in the @code{ac_cv_sizeof_@var{type-or-expr}} 7047variable, with @samp{*} mapped to @samp{p} and other characters not 7048suitable for a variable name mapped to underscores. 7049@end defmac 7050 7051@defmac AC_CHECK_ALIGNOF (@var{type}, @dvar{includes, AC_INCLUDES_DEFAULT}) 7052@acindex{CHECK_ALIGNOF} 7053@cvindex ALIGNOF_@var{type} 7054@caindex alignof_@var{type-or-expr} 7055Define @code{ALIGNOF_@var{type}} (@pxref{Standard Symbols}) to be the 7056alignment in bytes of @var{type}. @samp{@var{type} y;} must be valid as 7057a structure member declaration. If @samp{type} is unknown, the result 7058is 0. If no @var{includes} are specified, the default includes are used 7059(@pxref{Default Includes}). 7060 7061This macro caches its result in the @code{ac_cv_alignof_@var{type-or-expr}} 7062variable, with @samp{*} mapped to @samp{p} and other characters not 7063suitable for a variable name mapped to underscores. 7064@end defmac 7065 7066@defmac AC_COMPUTE_INT (@var{var}, @var{expression}, @ 7067 @dvar{includes, AC_INCLUDES_DEFAULT}, @ovar{action-if-fails}) 7068@acindex{COMPUTE_INT} 7069Store into the shell variable @var{var} the value of the integer 7070@var{expression}. The 7071value should fit in an initializer in a C variable of type @code{signed 7072long}. To support cross compilation (in which case, the macro only works on 7073hosts that use twos-complement arithmetic), it should be possible to evaluate 7074the expression at compile-time. If no @var{includes} are specified, the 7075default includes are used (@pxref{Default Includes}). 7076 7077Execute @var{action-if-fails} if the value cannot be determined correctly. 7078@end defmac 7079 7080@defmac AC_LANG_WERROR 7081@acindex{LANG_WERROR} 7082Normally Autoconf ignores warnings generated by the compiler, linker, and 7083preprocessor. If this macro is used, warnings count as fatal 7084errors for the current language. This macro is useful when the 7085results of configuration are used where warnings are unacceptable; for 7086instance, if parts of a program are built with the GCC 7087@option{-Werror} 7088option. If the whole program is built using @option{-Werror} it is 7089often simpler to put @option{-Werror} in the compiler flags (@code{CFLAGS}, 7090etc.). 7091@end defmac 7092 7093@defmac AC_OPENMP 7094@acindex{OPENMP} 7095@cvindex _OPENMP 7096@ovindex OPENMP_CFLAGS 7097@ovindex OPENMP_CXXFLAGS 7098@ovindex OPENMP_FFLAGS 7099@ovindex OPENMP_FCFLAGS 7100@caindex prog_c_openmp 7101@caindex prog_cxx_openmp 7102@caindex prog_f77_openmp 7103@caindex prog_fc_openmp 7104@uref{http://@/www.openmp.org/, OpenMP} specifies extensions of C, C++, 7105and Fortran that simplify optimization of shared memory parallelism, 7106which is a common problem on multicore CPUs. 7107 7108If the current language is C, the macro @code{AC_OPENMP} sets the 7109variable @code{OPENMP_CFLAGS} to the C compiler flags needed for 7110supporting OpenMP@. @code{OPENMP_CFLAGS} is set to empty if the 7111compiler already supports OpenMP, if it has no way to activate OpenMP 7112support, or if the user rejects OpenMP support by invoking 7113@samp{configure} with the @samp{--disable-openmp} option. 7114 7115@code{OPENMP_CFLAGS} needs to be used when compiling programs, when 7116preprocessing program source, and when linking programs. Therefore you 7117need to add @code{$(OPENMP_CFLAGS)} to the @code{CFLAGS} of C programs 7118that use OpenMP@. If you preprocess OpenMP-specific C code, you also 7119need to add @code{$(OPENMP_CFLAGS)} to @code{CPPFLAGS}. The presence of 7120OpenMP support is revealed at compile time by the preprocessor macro 7121@code{_OPENMP}. 7122 7123Linking a program with @code{OPENMP_CFLAGS} typically adds one more 7124shared library to the program's dependencies, so its use is recommended 7125only on programs that actually require OpenMP. 7126 7127If the current language is C++, @code{AC_OPENMP} sets the variable 7128@code{OPENMP_CXXFLAGS}, suitably for the C++ compiler. The same remarks 7129hold as for C. 7130 7131If the current language is Fortran 77 or Fortran, @code{AC_OPENMP} sets 7132the variable @code{OPENMP_FFLAGS} or @code{OPENMP_FCFLAGS}, 7133respectively. Similar remarks as for C hold, except that 7134@code{CPPFLAGS} is not used for Fortran, and no preprocessor macro 7135signals OpenMP support. 7136 7137For portability, it is best to avoid spaces between @samp{#} and 7138@samp{pragma omp}. That is, write @samp{#pragma omp}, not 7139@samp{# pragma omp}. The Sun WorkShop 6.2 C compiler chokes on the 7140latter. 7141 7142This macro caches its result in the @code{ac_cv_prog_c_openmp}, 7143@code{ac_cv_prog_cxx_openmp}, @code{ac_cv_prog_f77_openmp}, or 7144@code{ac_cv_prog_fc_openmp} variable, depending on the current language. 7145@end defmac 7146 7147@node C Compiler 7148@subsection C Compiler Characteristics 7149 7150The following macros provide ways to find and exercise a C Compiler. 7151There are a few constructs that ought to be avoided, but do not deserve 7152being checked for, since they can easily be worked around. 7153 7154@table @asis 7155@item Don't use lines containing solitary backslashes 7156They tickle a bug in the HP-UX C compiler (checked on 7157HP-UX 10.20, 715811.00, and 11i). When given the following source: 7159 7160@example 7161#ifdef __STDC__ 7162/\ 7163* A comment with backslash-newlines in it. %@{ %@} *\ 7164\ 7165/ 7166char str[] = "\\ 7167" A string with backslash-newlines in it %@{ %@} \\ 7168""; 7169char apostrophe = '\\ 7170\ 7171'\ 7172'; 7173#endif 7174@end example 7175 7176@noindent 7177the compiler incorrectly fails with the diagnostics ``Non-terminating 7178comment at end of file'' and ``Missing @samp{#endif} at end of file.'' 7179Removing the lines with solitary backslashes solves the problem. 7180 7181@item Don't compile several files at once if output matters to you 7182Some compilers, such as HP's, report names of files being 7183compiled when given more than one file operand. For instance: 7184 7185@example 7186$ @kbd{cc a.c b.c} 7187a.c: 7188b.c: 7189@end example 7190 7191@noindent 7192This can cause problems if you observe the output of the compiler to 7193detect failures. Invoking @samp{cc -c a.c && cc -c b.c && cc -o c a.o 7194b.o} solves the issue. 7195 7196@item Don't rely on @code{#error} failing 7197The IRIX C compiler does not fail when #error is preprocessed; it 7198simply emits a diagnostic and continues, exiting successfully. So, 7199instead of an error directive like @code{#error "Unsupported word size"} 7200it is more portable to use an invalid directive like @code{#Unsupported 7201word size} in Autoconf tests. In ordinary source code, @code{#error} is 7202OK, since installers with inadequate compilers like IRIX can simply 7203examine these compilers' diagnostic output. 7204 7205@item Don't rely on correct @code{#line} support 7206On Solaris, @command{c89} (at least Sun C 5.3 through 5.8) 7207diagnoses @code{#line} directives whose line 7208numbers are greater than 32767. Nothing in Posix 7209makes this invalid. That is why Autoconf stopped issuing 7210@code{#line} directives. 7211@end table 7212 7213@defmac AC_PROG_CC (@ovar{compiler-search-list}) 7214@acindex{PROG_CC} 7215@evindex CC 7216@evindex CFLAGS 7217@ovindex CC 7218@ovindex CFLAGS 7219@caindex prog_cc_c89 7220Determine a C compiler to use. If @code{CC} is not already set in the 7221environment, check for @code{gcc} and @code{cc}, then for other C 7222compilers. Set output variable @code{CC} to the name of the compiler 7223found. 7224 7225This macro may, however, be invoked with an optional first argument 7226which, if specified, must be a blank-separated list of C compilers to 7227search for. This just gives the user an opportunity to specify an 7228alternative search list for the C compiler. For example, if you didn't 7229like the default order, then you could invoke @code{AC_PROG_CC} like 7230this: 7231 7232@example 7233AC_PROG_CC([gcc cl cc]) 7234@end example 7235 7236If the C compiler does not handle function prototypes correctly by 7237default, try to add an option to output variable @code{CC} to make it 7238so. This macro tries various options that select standard-conformance 7239modes on various systems. 7240 7241After calling this macro you can check whether the C compiler has been 7242set to accept ANSI C89 (ISO C90); if not, the shell 7243variable 7244@code{ac_cv_prog_cc_c89} is set to @samp{no}. See also 7245@code{AC_C_PROTOTYPES} below. 7246 7247If using the GNU C compiler, set shell variable @code{GCC} to 7248@samp{yes}. If output variable @code{CFLAGS} was not already set, set 7249it to @option{-g -O2} for the GNU C compiler (@option{-O2} on systems 7250where GCC does not accept @option{-g}), or @option{-g} for 7251other compilers. If your package does not like this default, then it is 7252acceptable to insert the line @samp{: $@{CFLAGS=""@}} after @code{AC_INIT} 7253and before @code{AC_PROG_CC} to select an empty default instead. 7254 7255Many Autoconf macros use a compiler, and thus call 7256@samp{AC_REQUIRE([AC_PROG_CC])} to ensure that the compiler has been 7257determined before the body of the outermost @code{AC_DEFUN} macro. 7258Although @code{AC_PROG_CC} is safe to directly expand multiple times, it 7259performs certain checks (such as the proper value of @env{EXEEXT}) only 7260on the first invocation. Therefore, care must be used when invoking 7261this macro from within another macro rather than at the top level 7262(@pxref{Expanded Before Required}). 7263@end defmac 7264 7265@anchor{AC_PROG_CC_C_O} 7266@defmac AC_PROG_CC_C_O 7267@acindex{PROG_CC_C_O} 7268@cvindex NO_MINUS_C_MINUS_O 7269@caindex prog_cc_@var{compiler}_c_o 7270If the C compiler does not accept the @option{-c} and @option{-o} options 7271simultaneously, define @code{NO_MINUS_C_MINUS_O}. This macro actually 7272tests both the compiler found by @code{AC_PROG_CC}, and, if different, 7273the first @code{cc} in the path. The test fails if one fails. This 7274macro was created for GNU Make to choose the default C compilation 7275rule. 7276 7277For the compiler @var{compiler}, this macro caches its result in the 7278@code{ac_cv_prog_cc_@var{compiler}_c_o} variable. 7279@end defmac 7280 7281 7282@defmac AC_PROG_CPP 7283@acindex{PROG_CPP} 7284@evindex CPP 7285@ovindex CPP 7286Set output variable @code{CPP} to a command that runs the 7287C preprocessor. If @samp{$CC -E} doesn't work, @file{/lib/cpp} is used. 7288It is only portable to run @code{CPP} on files with a @file{.c} 7289extension. 7290 7291Some preprocessors don't indicate missing include files by the error 7292status. For such preprocessors an internal variable is set that causes 7293other macros to check the standard error from the preprocessor and 7294consider the test failed if any warnings have been reported. 7295For most preprocessors, though, warnings do not cause include-file 7296tests to fail unless @code{AC_PROG_CPP_WERROR} is also specified. 7297@end defmac 7298 7299@defmac AC_PROG_CPP_WERROR 7300@acindex{PROG_CPP_WERROR} 7301@ovindex CPP 7302This acts like @code{AC_PROG_CPP}, except it treats warnings from the 7303preprocessor as errors even if the preprocessor exit status indicates 7304success. This is useful for avoiding headers that generate mandatory 7305warnings, such as deprecation notices. 7306@end defmac 7307 7308 7309The following macros check for C compiler or machine architecture 7310features. To check for characteristics not listed here, use 7311@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or 7312@code{AC_RUN_IFELSE} (@pxref{Runtime}). 7313 7314@defmac AC_PROG_CC_STDC 7315@acindex{PROG_CC_STDC} 7316@caindex prog_cc_stdc 7317If the C compiler cannot compile ISO Standard C (currently 7318C99), try to add an option to output variable @code{CC} to make it work. 7319If the compiler does not support C99, fall back to supporting 7320ANSI C89 (ISO C90). 7321 7322After calling this macro you can check whether the C compiler has been 7323set to accept Standard C; if not, the shell variable 7324@code{ac_cv_prog_cc_stdc} is set to @samp{no}. 7325@end defmac 7326 7327@defmac AC_PROG_CC_C89 7328@acindex{PROG_CC_C89} 7329@caindex prog_cc_c89 7330If the C compiler is not in ANSI C89 (ISO C90) mode by 7331default, try to add an option to output variable @code{CC} to make it 7332so. This macro tries various options that select ANSI C89 on 7333some system or another, preferring extended functionality modes over 7334strict conformance modes. It considers the compiler to be in 7335ANSI C89 mode if it handles function prototypes correctly. 7336 7337After calling this macro you can check whether the C compiler has been 7338set to accept ANSI C89; if not, the shell variable 7339@code{ac_cv_prog_cc_c89} is set to @samp{no}. 7340 7341This macro is called automatically by @code{AC_PROG_CC}. 7342@end defmac 7343 7344@defmac AC_PROG_CC_C99 7345@acindex{PROG_CC_C99} 7346@caindex prog_cc_c99 7347If the C compiler is not in C99 mode by default, try to add an 7348option to output variable @code{CC} to make it so. This macro tries 7349various options that select C99 on some system or another, preferring 7350extended functionality modes over strict conformance modes. It 7351considers the compiler to be in C99 mode if it handles @code{_Bool}, 7352@code{//} comments, flexible array members, @code{inline}, signed and 7353unsigned @code{long long int}, mixed code and declarations, named 7354initialization of structs, 7355@code{restrict}, @code{va_copy}, varargs macros, variable declarations 7356in @code{for} loops, and variable length arrays. 7357 7358After calling this macro you can check whether the C compiler has been 7359set to accept C99; if not, the shell variable 7360@code{ac_cv_prog_cc_c99} is set to @samp{no}. 7361@end defmac 7362 7363@defmac AC_C_BACKSLASH_A 7364@acindex{C_BACKSLASH_A} 7365@cvindex HAVE_C_BACKSLASH_A 7366Define @samp{HAVE_C_BACKSLASH_A} to 1 if the C compiler understands 7367@samp{\a}. 7368 7369This macro is obsolescent, as current C compilers understand @samp{\a}. 7370New programs need not use this macro. 7371@end defmac 7372 7373@anchor{AC_C_BIGENDIAN} 7374@defmac AC_C_BIGENDIAN (@ovar{action-if-true}, @ovar{action-if-false}, @ 7375 @ovar{action-if-unknown}, @ovar{action-if-universal}) 7376@acindex{C_BIGENDIAN} 7377@cvindex WORDS_BIGENDIAN 7378@cindex Endianness 7379If words are stored with the most significant byte first (like Motorola 7380and SPARC CPUs), execute @var{action-if-true}. If words are stored with 7381the least significant byte first (like Intel and VAX CPUs), execute 7382@var{action-if-false}. 7383 7384This macro runs a test-case if endianness cannot be determined from the 7385system header files. When cross-compiling, the test-case is not run but 7386grep'ed for some magic values. @var{action-if-unknown} is executed if 7387the latter case fails to determine the byte sex of the host system. 7388 7389In some cases a single run of a compiler can generate code for multiple 7390architectures. This can happen, for example, when generating Mac OS X 7391universal binary files, which work on both PowerPC and Intel 7392architectures. In this case, the different variants might be for 7393different architectures whose endiannesses differ. If 7394@command{configure} detects this, it executes @var{action-if-universal} 7395instead of @var{action-if-unknown}. 7396 7397The default for @var{action-if-true} is to define 7398@samp{WORDS_BIGENDIAN}. The default for @var{action-if-false} is to do 7399nothing. The default for @var{action-if-unknown} is to 7400abort configure and tell the installer how to bypass this test. 7401And finally, the default for @var{action-if-universal} is to ensure that 7402@samp{WORDS_BIGENDIAN} is defined if and only if a universal build is 7403detected and the current code is big-endian; this default works only if 7404@command{autoheader} is used (@pxref{autoheader Invocation}). 7405 7406If you use this macro without specifying @var{action-if-universal}, you 7407should also use @code{AC_CONFIG_HEADERS}; otherwise 7408@samp{WORDS_BIGENDIAN} may be set incorrectly for Mac OS X universal 7409binary files. 7410@end defmac 7411 7412@anchor{AC_C_CONST} 7413@defmac AC_C_CONST 7414@acindex{C_CONST} 7415@cvindex const 7416@caindex c_const 7417If the C compiler does not fully support the @code{const} keyword, 7418define @code{const} to be empty. Some C compilers that do 7419not define @code{__STDC__} do support @code{const}; some compilers that 7420define @code{__STDC__} do not completely support @code{const}. Programs 7421can simply use @code{const} as if every C compiler supported it; for 7422those that don't, the makefile or configuration header file 7423defines it as empty. 7424 7425Occasionally installers use a C++ compiler to compile C code, typically 7426because they lack a C compiler. This causes problems with @code{const}, 7427because C and C++ treat @code{const} differently. For example: 7428 7429@example 7430const int foo; 7431@end example 7432 7433@noindent 7434is valid in C but not in C++. These differences unfortunately cannot be 7435papered over by defining @code{const} to be empty. 7436 7437If @command{autoconf} detects this situation, it leaves @code{const} alone, 7438as this generally yields better results in practice. However, using a 7439C++ compiler to compile C code is not recommended or supported, and 7440installers who run into trouble in this area should get a C compiler 7441like GCC to compile their C code. 7442 7443This macro caches its result in the @code{ac_cv_c_const} variable. 7444 7445This macro is obsolescent, as current C compilers support @code{const}. 7446New programs need not use this macro. 7447@end defmac 7448 7449@defmac AC_C_RESTRICT 7450@acindex{C_RESTRICT} 7451@cvindex restrict 7452@caindex c_restrict 7453If the C compiler recognizes a variant spelling for the @code{restrict} 7454keyword (@code{__restrict}, @code{__restrict__}, or @code{_Restrict}), 7455then define @code{restrict} to that; this is more likely to do the right 7456thing with compilers that support language variants where plain 7457@code{restrict} is not a keyword. Otherwise, if the C compiler 7458recognizes the @code{restrict} keyword, don't do anything. 7459Otherwise, define @code{restrict} to be empty. 7460Thus, programs may simply use @code{restrict} as if every C compiler 7461supported it; for those that do not, the makefile 7462or configuration header defines it away. 7463 7464Although support in C++ for the @code{restrict} keyword is not 7465required, several C++ compilers do accept the keyword. 7466This macro works for them, too. 7467 7468This macro caches @samp{no} in the @code{ac_cv_c_restrict} variable 7469if @code{restrict} is not supported, and a supported spelling otherwise. 7470@end defmac 7471 7472@defmac AC_C_VOLATILE 7473@acindex{C_VOLATILE} 7474@cvindex volatile 7475If the C compiler does not understand the keyword @code{volatile}, 7476define @code{volatile} to be empty. Programs can simply use 7477@code{volatile} as if every C compiler supported it; for those that do 7478not, the makefile or configuration header defines it as 7479empty. 7480 7481If the correctness of your program depends on the semantics of 7482@code{volatile}, simply defining it to be empty does, in a sense, break 7483your code. However, given that the compiler does not support 7484@code{volatile}, you are at its mercy anyway. At least your 7485program compiles, when it wouldn't before. 7486@xref{Volatile Objects}, for more about @code{volatile}. 7487 7488In general, the @code{volatile} keyword is a standard C feature, so 7489you might expect that @code{volatile} is available only when 7490@code{__STDC__} is defined. However, Ultrix 4.3's native compiler does 7491support volatile, but does not define @code{__STDC__}. 7492 7493This macro is obsolescent, as current C compilers support @code{volatile}. 7494New programs need not use this macro. 7495@end defmac 7496 7497@anchor{AC_C_INLINE} 7498@defmac AC_C_INLINE 7499@acindex{C_INLINE} 7500@cvindex inline 7501If the C compiler supports the keyword @code{inline}, do nothing. 7502Otherwise define @code{inline} to @code{__inline__} or @code{__inline} 7503if it accepts one of those, otherwise define @code{inline} to be empty. 7504@end defmac 7505 7506@anchor{AC_C_CHAR_UNSIGNED} 7507@defmac AC_C_CHAR_UNSIGNED 7508@acindex{C_CHAR_UNSIGNED} 7509@cvindex __CHAR_UNSIGNED__ 7510If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__}, 7511unless the C compiler predefines it. 7512 7513These days, using this macro is not necessary. The same information can 7514be determined by this portable alternative, thus avoiding the use of 7515preprocessor macros in the namespace reserved for the implementation. 7516 7517@example 7518#include <limits.h> 7519#if CHAR_MIN == 0 7520# define CHAR_UNSIGNED 1 7521#endif 7522@end example 7523@end defmac 7524 7525@defmac AC_C_STRINGIZE 7526@acindex{C_STRINGIZE} 7527@cvindex HAVE_STRINGIZE 7528If the C preprocessor supports the stringizing operator, define 7529@code{HAVE_STRINGIZE}. The stringizing operator is @samp{#} and is 7530found in macros such as this: 7531 7532@example 7533#define x(y) #y 7534@end example 7535 7536This macro is obsolescent, as current C compilers support the 7537stringizing operator. New programs need not use this macro. 7538@end defmac 7539 7540@defmac AC_C_FLEXIBLE_ARRAY_MEMBER 7541@acindex{C_FLEXIBLE_ARRAY_MEMBER} 7542@cvindex FLEXIBLE_ARRAY_MEMBER 7543If the C compiler supports flexible array members, define 7544@code{FLEXIBLE_ARRAY_MEMBER} to nothing; otherwise define it to 1. 7545That way, a declaration like this: 7546 7547@example 7548struct s 7549 @{ 7550 size_t n_vals; 7551 double val[FLEXIBLE_ARRAY_MEMBER]; 7552 @}; 7553@end example 7554 7555@noindent 7556will let applications use the ``struct hack'' even with compilers that 7557do not support flexible array members. To allocate and use such an 7558object, you can use code like this: 7559 7560@example 7561size_t i; 7562size_t n = compute_value_count (); 7563struct s *p = 7564 malloc (offsetof (struct s, val) 7565 + n * sizeof (double)); 7566p->n_vals = n; 7567for (i = 0; i < n; i++) 7568 p->val[i] = compute_value (i); 7569@end example 7570@end defmac 7571 7572@defmac AC_C_VARARRAYS 7573@acindex{C_VARARRAYS} 7574@cvindex HAVE_C_VARARRAYS 7575If the C compiler supports variable-length arrays, define 7576@code{HAVE_C_VARARRAYS}. A variable-length array is an array of automatic 7577storage duration whose length is determined at run time, when the array 7578is declared. 7579@end defmac 7580 7581@defmac AC_C_TYPEOF 7582@acindex{C_TYPEOF} 7583@cvindex HAVE_TYPEOF 7584@cvindex typeof 7585If the C compiler supports GCC's @code{typeof} syntax either 7586directly or 7587through a different spelling of the keyword (e.g., @code{__typeof__}), 7588define @code{HAVE_TYPEOF}. If the support is available only through a 7589different spelling, define @code{typeof} to that spelling. 7590@end defmac 7591 7592@defmac AC_C_PROTOTYPES 7593@acindex{C_PROTOTYPES} 7594@cvindex PROTOTYPES 7595@cvindex __PROTOTYPES 7596@cvindex PARAMS 7597If function prototypes are understood by the compiler (as determined by 7598@code{AC_PROG_CC}), define @code{PROTOTYPES} and @code{__PROTOTYPES}. 7599Defining @code{__PROTOTYPES} is for the benefit of 7600header files that cannot use macros that infringe on user name space. 7601 7602This macro is obsolescent, as current C compilers support prototypes. 7603New programs need not use this macro. 7604@end defmac 7605 7606@anchor{AC_PROG_GCC_TRADITIONAL} 7607@defmac AC_PROG_GCC_TRADITIONAL 7608@acindex{PROG_GCC_TRADITIONAL} 7609@ovindex CC 7610Add @option{-traditional} to output variable @code{CC} if using the 7611GNU C compiler and @code{ioctl} does not work properly without 7612@option{-traditional}. That usually happens when the fixed header files 7613have not been installed on an old system. 7614 7615This macro is obsolescent, since current versions of the GNU C 7616compiler fix the header files automatically when installed. 7617@end defmac 7618 7619 7620@node C++ Compiler 7621@subsection C++ Compiler Characteristics 7622 7623 7624@defmac AC_PROG_CXX (@ovar{compiler-search-list}) 7625@acindex{PROG_CXX} 7626@evindex CXX 7627@evindex CXXFLAGS 7628@ovindex CXX 7629@ovindex CXXFLAGS 7630Determine a C++ compiler to use. Check whether the environment variable 7631@code{CXX} or @code{CCC} (in that order) is set; if so, then set output 7632variable @code{CXX} to its value. 7633 7634Otherwise, if the macro is invoked without an argument, then search for 7635a C++ compiler under the likely names (first @code{g++} and @code{c++} 7636then other names). If none of those checks succeed, then as a last 7637resort set @code{CXX} to @code{g++}. 7638 7639This macro may, however, be invoked with an optional first argument 7640which, if specified, must be a blank-separated list of C++ compilers to 7641search for. This just gives the user an opportunity to specify an 7642alternative search list for the C++ compiler. For example, if you 7643didn't like the default order, then you could invoke @code{AC_PROG_CXX} 7644like this: 7645 7646@example 7647AC_PROG_CXX([gcc cl KCC CC cxx cc++ xlC aCC c++ g++]) 7648@end example 7649 7650If using the GNU C++ compiler, set shell variable @code{GXX} to 7651@samp{yes}. If output variable @code{CXXFLAGS} was not already set, set 7652it to @option{-g -O2} for the GNU C++ compiler (@option{-O2} on 7653systems where G++ does not accept @option{-g}), or @option{-g} for other 7654compilers. If your package does not like this default, then it is 7655acceptable to insert the line @samp{: $@{CXXFLAGS=""@}} after @code{AC_INIT} 7656and before @code{AC_PROG_CXX} to select an empty default instead. 7657 7658@end defmac 7659 7660@defmac AC_PROG_CXXCPP 7661@acindex{PROG_CXXCPP} 7662@evindex CXXCPP 7663@ovindex CXXCPP 7664Set output variable @code{CXXCPP} to a command that runs the C++ 7665preprocessor. If @samp{$CXX -E} doesn't work, @file{/lib/cpp} is used. 7666It is portable to run @code{CXXCPP} only on files with a @file{.c}, 7667@file{.C}, @file{.cc}, or @file{.cpp} extension. 7668 7669Some preprocessors don't indicate missing include files by the error 7670status. For such preprocessors an internal variable is set that causes 7671other macros to check the standard error from the preprocessor and 7672consider the test failed if any warnings have been reported. However, 7673it is not known whether such broken preprocessors exist for C++. 7674@end defmac 7675 7676@defmac AC_PROG_CXX_C_O 7677@acindex{PROG_CXX_C_O} 7678@cvindex CXX_NO_MINUS_C_MINUS_O 7679Test whether the C++ compiler accepts the options @option{-c} and 7680@option{-o} simultaneously, and define @code{CXX_NO_MINUS_C_MINUS_O}, 7681if it does not. 7682@end defmac 7683 7684 7685@node Objective C Compiler 7686@subsection Objective C Compiler Characteristics 7687 7688 7689@defmac AC_PROG_OBJC (@ovar{compiler-search-list}) 7690@acindex{PROG_OBJC} 7691@evindex OBJC 7692@evindex OBJCFLAGS 7693@ovindex OBJC 7694@ovindex OBJCFLAGS 7695Determine an Objective C compiler to use. If @code{OBJC} is not already 7696set in the environment, check for Objective C compilers. Set output 7697variable @code{OBJC} to the name of the compiler found. 7698 7699This macro may, however, be invoked with an optional first argument 7700which, if specified, must be a blank-separated list of Objective C compilers to 7701search for. This just gives the user an opportunity to specify an 7702alternative search list for the Objective C compiler. For example, if you 7703didn't like the default order, then you could invoke @code{AC_PROG_OBJC} 7704like this: 7705 7706@example 7707AC_PROG_OBJC([gcc objcc objc]) 7708@end example 7709 7710If using the GNU Objective C compiler, set shell variable 7711@code{GOBJC} to @samp{yes}. If output variable @code{OBJCFLAGS} was not 7712already set, set it to @option{-g -O2} for the GNU Objective C 7713compiler (@option{-O2} on systems where @command{gcc} does not accept 7714@option{-g}), or @option{-g} for other compilers. 7715@end defmac 7716 7717@defmac AC_PROG_OBJCPP 7718@acindex{PROG_OBJCPP} 7719@evindex OBJCPP 7720@ovindex OBJCPP 7721Set output variable @code{OBJCPP} to a command that runs the Objective C 7722preprocessor. If @samp{$OBJC -E} doesn't work, @file{/lib/cpp} is used. 7723@end defmac 7724 7725 7726@node Objective C++ Compiler 7727@subsection Objective C++ Compiler Characteristics 7728 7729 7730@defmac AC_PROG_OBJCXX (@ovar{compiler-search-list}) 7731@acindex{PROG_OBJCXX} 7732@evindex OBJCXX 7733@evindex OBJCXXFLAGS 7734@ovindex OBJCXX 7735@ovindex OBJCXXFLAGS 7736Determine an Objective C++ compiler to use. If @code{OBJCXX} is not already 7737set in the environment, check for Objective C++ compilers. Set output 7738variable @code{OBJCXX} to the name of the compiler found. 7739 7740This macro may, however, be invoked with an optional first argument 7741which, if specified, must be a blank-separated list of Objective C++ compilers 7742to search for. This just gives the user an opportunity to specify an 7743alternative search list for the Objective C++ compiler. For example, if you 7744didn't like the default order, then you could invoke @code{AC_PROG_OBJCXX} 7745like this: 7746 7747@example 7748AC_PROG_OBJCXX([gcc g++ objcc++ objcxx]) 7749@end example 7750 7751If using the GNU Objective C++ compiler, set shell variable 7752@code{GOBJCXX} to @samp{yes}. If output variable @code{OBJCXXFLAGS} was not 7753already set, set it to @option{-g -O2} for the GNU Objective C++ 7754compiler (@option{-O2} on systems where @command{gcc} does not accept 7755@option{-g}), or @option{-g} for other compilers. 7756@end defmac 7757 7758@defmac AC_PROG_OBJCXXCPP 7759@acindex{PROG_OBJCXXCPP} 7760@evindex OBJCXXCPP 7761@ovindex OBJCXXCPP 7762Set output variable @code{OBJCXXCPP} to a command that runs the Objective C++ 7763preprocessor. If @samp{$OBJCXX -E} doesn't work, @file{/lib/cpp} is used. 7764@end defmac 7765 7766 7767@node Erlang Compiler and Interpreter 7768@subsection Erlang Compiler and Interpreter Characteristics 7769@cindex Erlang 7770 7771Autoconf defines the following macros for determining paths to the essential 7772Erlang/OTP programs: 7773 7774@defmac AC_ERLANG_PATH_ERLC (@ovar{value-if-not-found}, @dvar{path, $PATH}) 7775@acindex{ERLANG_PATH_ERLC} 7776@evindex ERLC 7777@evindex ERLCFLAGS 7778@ovindex ERLC 7779@ovindex ERLCFLAGS 7780Determine an Erlang compiler to use. If @code{ERLC} is not already set in the 7781environment, check for @command{erlc}. Set output variable @code{ERLC} to the 7782complete path of the compiler command found. In addition, if @code{ERLCFLAGS} 7783is not set in the environment, set it to an empty value. 7784 7785The two optional arguments have the same meaning as the two last arguments of 7786macro @code{AC_PATH_PROG} for looking for the @command{erlc} program. For 7787example, to look for @command{erlc} only in the @file{/usr/lib/erlang/bin} 7788directory: 7789 7790@example 7791AC_ERLANG_PATH_ERLC([not found], [/usr/lib/erlang/bin]) 7792@end example 7793@end defmac 7794 7795@defmac AC_ERLANG_NEED_ERLC (@dvar{path, $PATH}) 7796@acindex{ERLANG_NEED_ERLC} 7797A simplified variant of the @code{AC_ERLANG_PATH_ERLC} macro, that prints an 7798error message and exits the @command{configure} script if the @command{erlc} 7799program is not found. 7800@end defmac 7801 7802@defmac AC_ERLANG_PATH_ERL (@ovar{value-if-not-found}, @dvar{path, $PATH}) 7803@acindex{ERLANG_PATH_ERL} 7804@evindex ERL 7805@ovindex ERL 7806Determine an Erlang interpreter to use. If @code{ERL} is not already 7807set in the 7808environment, check for @command{erl}. Set output variable @code{ERL} to the 7809complete path of the interpreter command found. 7810 7811The two optional arguments have the same meaning as the two last arguments of 7812macro @code{AC_PATH_PROG} for looking for the @command{erl} program. For 7813example, to look for @command{erl} only in the @file{/usr/lib/erlang/bin} 7814directory: 7815 7816@example 7817AC_ERLANG_PATH_ERL([not found], [/usr/lib/erlang/bin]) 7818@end example 7819@end defmac 7820 7821@defmac AC_ERLANG_NEED_ERL (@dvar{path, $PATH}) 7822@acindex{ERLANG_NEED_ERL} 7823A simplified variant of the @code{AC_ERLANG_PATH_ERL} macro, that prints an 7824error message and exits the @command{configure} script if the @command{erl} 7825program is not found. 7826@end defmac 7827 7828 7829@node Fortran Compiler 7830@subsection Fortran Compiler Characteristics 7831@cindex Fortran 7832@cindex F77 7833 7834The Autoconf Fortran support is divided into two categories: legacy 7835Fortran 77 macros (@code{F77}), and modern Fortran macros (@code{FC}). 7836The former are intended for traditional Fortran 77 code, and have output 7837variables like @code{F77}, @code{FFLAGS}, and @code{FLIBS}. The latter 7838are for newer programs that can (or must) compile under the newer 7839Fortran standards, and have output variables like @code{FC}, 7840@code{FCFLAGS}, and @code{FCLIBS}. 7841 7842Except for the macros @code{AC_FC_SRCEXT}, @code{AC_FC_FREEFORM}, 7843@code{AC_FC_FIXEDFORM}, and @code{AC_FC_LINE_LENGTH} (see below), the 7844@code{FC} and @code{F77} macros behave almost identically, and so they 7845are documented together in this section. 7846 7847 7848@defmac AC_PROG_F77 (@ovar{compiler-search-list}) 7849@acindex{PROG_F77} 7850@evindex F77 7851@evindex FFLAGS 7852@ovindex F77 7853@ovindex FFLAGS 7854@caindex f77_compiler_gnu 7855@caindex prog_f77_g 7856Determine a Fortran 77 compiler to use. If @code{F77} is not already 7857set in the environment, then check for @code{g77} and @code{f77}, and 7858then some other names. Set the output variable @code{F77} to the name 7859of the compiler found. 7860 7861This macro may, however, be invoked with an optional first argument 7862which, if specified, must be a blank-separated list of Fortran 77 7863compilers to search for. This just gives the user an opportunity to 7864specify an alternative search list for the Fortran 77 compiler. For 7865example, if you didn't like the default order, then you could invoke 7866@code{AC_PROG_F77} like this: 7867 7868@example 7869AC_PROG_F77([fl32 f77 fort77 xlf g77 f90 xlf90]) 7870@end example 7871 7872If using @code{g77} (the GNU Fortran 77 compiler), then 7873set the shell variable @code{G77} to @samp{yes}. 7874If the output variable @code{FFLAGS} was not already set in the 7875environment, then set it to @option{-g -02} for @code{g77} (or @option{-O2} 7876where @code{g77} does not accept @option{-g}). Otherwise, set 7877@code{FFLAGS} to @option{-g} for all other Fortran 77 compilers. 7878 7879The result of the GNU test is cached in the 7880@code{ac_cv_f77_compiler_gnu} variable, acceptance of @option{-g} in the 7881@code{ac_cv_prog_f77_g} variable. 7882@end defmac 7883 7884@defmac AC_PROG_FC (@ovar{compiler-search-list}, @ovar{dialect}) 7885@acindex{PROG_FC} 7886@evindex FC 7887@evindex FCFLAGS 7888@ovindex FC 7889@ovindex FCFLAGS 7890@caindex fc_compiler_gnu 7891@caindex prog_fc_g 7892Determine a Fortran compiler to use. If @code{FC} is not already set in 7893the environment, then @code{dialect} is a hint to indicate what Fortran 7894dialect to search for; the default is to search for the newest available 7895dialect. Set the output variable @code{FC} to the name of the compiler 7896found. 7897 7898By default, newer dialects are preferred over older dialects, but if 7899@code{dialect} is specified then older dialects are preferred starting 7900with the specified dialect. @code{dialect} can currently be one of 7901Fortran 77, Fortran 90, or Fortran 95. However, this is only a hint of 7902which compiler @emph{name} to prefer (e.g., @code{f90} or @code{f95}), 7903and no attempt is made to guarantee that a particular language standard 7904is actually supported. Thus, it is preferable that you avoid the 7905@code{dialect} option, and use AC_PROG_FC only for code compatible with 7906the latest Fortran standard. 7907 7908This macro may, alternatively, be invoked with an optional first argument 7909which, if specified, must be a blank-separated list of Fortran 7910compilers to search for, just as in @code{AC_PROG_F77}. 7911 7912If using @code{gfortran} or @code{g77} (the GNU Fortran compilers), then 7913set the shell variable @code{GFC} to @samp{yes}. 7914If the output variable @code{FCFLAGS} was not already set in the 7915environment, then set it to @option{-g -02} for GNU @code{g77} (or 7916@option{-O2} where @code{g77} does not accept @option{-g}). Otherwise, 7917set @code{FCFLAGS} to @option{-g} for all other Fortran compilers. 7918 7919The result of the GNU test is cached in the @code{ac_cv_fc_compiler_gnu} 7920variable, acceptance of @option{-g} in the @code{ac_cv_prog_fc_g} 7921variable. 7922@end defmac 7923 7924@defmac AC_PROG_F77_C_O 7925@defmacx AC_PROG_FC_C_O 7926@acindex{PROG_F77_C_O} 7927@acindex{PROG_FC_C_O} 7928@cvindex F77_NO_MINUS_C_MINUS_O 7929@cvindex FC_NO_MINUS_C_MINUS_O 7930@caindex prog_f77_c_o 7931@caindex prog_fc_c_o 7932Test whether the Fortran compiler accepts the options @option{-c} and 7933@option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} or 7934@code{FC_NO_MINUS_C_MINUS_O}, respectively, if it does not. 7935 7936The result of the test is cached in the @code{ac_cv_prog_f77_c_o} or 7937@code{ac_cv_prog_fc_c_o} variable, respectively. 7938@end defmac 7939 7940The following macros check for Fortran compiler characteristics. 7941To check for characteristics not listed here, use 7942@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or 7943@code{AC_RUN_IFELSE} (@pxref{Runtime}), making sure to first set the 7944current language to Fortran 77 or Fortran via @code{AC_LANG([Fortran 77])} 7945or @code{AC_LANG(Fortran)} (@pxref{Language Choice}). 7946 7947 7948@defmac AC_F77_LIBRARY_LDFLAGS 7949@defmacx AC_FC_LIBRARY_LDFLAGS 7950@acindex{F77_LIBRARY_LDFLAGS} 7951@ovindex FLIBS 7952@acindex{FC_LIBRARY_LDFLAGS} 7953@ovindex FCLIBS 7954@caindex prog_f77_v 7955@caindex prog_fc_v 7956@caindex f77_libs 7957@caindex fc_libs 7958Determine the linker flags (e.g., @option{-L} and @option{-l}) for the 7959@dfn{Fortran intrinsic and runtime libraries} that are required to 7960successfully link a Fortran program or shared library. The output 7961variable @code{FLIBS} or @code{FCLIBS} is set to these flags (which 7962should be included after @code{LIBS} when linking). 7963 7964This macro is intended to be used in those situations when it is 7965necessary to mix, e.g., C++ and Fortran source code in a single 7966program or shared library (@pxref{Mixing Fortran 77 With C and C++, , , 7967automake, GNU Automake}). 7968 7969For example, if object files from a C++ and Fortran compiler must be 7970linked together, then the C++ compiler/linker must be used for linking 7971(since special C++-ish things need to happen at link time like calling 7972global constructors, instantiating templates, enabling exception 7973support, etc.). 7974 7975However, the Fortran intrinsic and runtime libraries must be linked in 7976as well, but the C++ compiler/linker doesn't know by default how to add 7977these Fortran 77 libraries. Hence, this macro was created to determine 7978these Fortran libraries. 7979 7980The macros @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or 7981@code{AC_F77_MAIN} and @code{AC_FC_MAIN} are probably also necessary to 7982link C/C++ with Fortran; see below. Further, it is highly recommended 7983that you use @code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}) 7984because the complex defines that the function wrapper macros create 7985may not work with C/C++ compiler drivers. 7986 7987These macros internally compute the flag needed to verbose linking 7988output and cache it in @code{ac_cv_prog_f77_v} or @code{ac_cv_prog_fc_v} 7989variables, respectively. The computed linker flags are cached in 7990@code{ac_cv_f77_libs} or @code{ac_cv_fc_libs}, respectively. 7991@end defmac 7992 7993@defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @dvar{action-if-not-found, @ 7994 AC_MSG_FAILURE}) 7995@defmacx AC_FC_DUMMY_MAIN (@ovar{action-if-found}, @dvar{action-if-not-found, @ 7996 AC_MSG_FAILURE}) 7997@acindex{F77_DUMMY_MAIN} 7998@cvindex F77_DUMMY_MAIN 7999@acindex{FC_DUMMY_MAIN} 8000@cvindex FC_DUMMY_MAIN 8001@caindex f77_dummy_main 8002@caindex fc_dummy_main 8003With many compilers, the Fortran libraries detected by 8004@code{AC_F77_LIBRARY_LDFLAGS} or @code{AC_FC_LIBRARY_LDFLAGS} provide 8005their own @code{main} entry function that initializes things like 8006Fortran I/O, and which then calls a user-provided entry function named 8007(say) @code{MAIN__} to run the user's program. The 8008@code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or 8009@code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros figure out how to deal with 8010this interaction. 8011 8012When using Fortran for purely numerical functions (no I/O, etc.)@: often 8013one prefers to provide one's own @code{main} and skip the Fortran 8014library initializations. In this case, however, one may still need to 8015provide a dummy @code{MAIN__} routine in order to prevent linking errors 8016on some systems. @code{AC_F77_DUMMY_MAIN} or @code{AC_FC_DUMMY_MAIN} 8017detects whether any such routine is @emph{required} for linking, and 8018what its name is; the shell variable @code{F77_DUMMY_MAIN} or 8019@code{FC_DUMMY_MAIN} holds this name, @code{unknown} when no solution 8020was found, and @code{none} when no such dummy main is needed. 8021 8022By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} or 8023@code{FC_DUMMY_MAIN} to the name of this routine (e.g., @code{MAIN__}) 8024@emph{if} it is required. @var{action-if-not-found} defaults to 8025exiting with an error. 8026 8027In order to link with Fortran routines, the user's C/C++ program should 8028then include the following code to define the dummy main if it is 8029needed: 8030 8031@example 8032@c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage. 8033#ifdef F77_DUMMY_MAIN 8034# ifdef __cplusplus 8035 extern "C" 8036# endif 8037 int F77_DUMMY_MAIN () @{ return 1; @} 8038#endif 8039@end example 8040 8041(Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.) 8042 8043Note that this macro is called automatically from @code{AC_F77_WRAPPERS} 8044or @code{AC_FC_WRAPPERS}; there is generally no need to call it 8045explicitly unless one wants to change the default actions. 8046 8047The result of this macro is cached in the @code{ac_cv_f77_dummy_main} or 8048@code{ac_cv_fc_dummy_main} variable, respectively. 8049@end defmac 8050 8051@defmac AC_F77_MAIN 8052@defmacx AC_FC_MAIN 8053@acindex{F77_MAIN} 8054@cvindex F77_MAIN 8055@acindex{FC_MAIN} 8056@cvindex FC_MAIN 8057@caindex f77_main 8058@caindex fc_main 8059As discussed above, many Fortran libraries allow you to provide an entry 8060point called (say) @code{MAIN__} instead of the usual @code{main}, which 8061is then called by a @code{main} function in the Fortran libraries that 8062initializes things like Fortran I/O@. The 8063@code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros detect whether it is 8064@emph{possible} to utilize such an alternate main function, and defines 8065@code{F77_MAIN} and @code{FC_MAIN} to the name of the function. (If no 8066alternate main function name is found, @code{F77_MAIN} and @code{FC_MAIN} are 8067simply defined to @code{main}.) 8068 8069Thus, when calling Fortran routines from C that perform things like I/O, 8070one should use this macro and declare the "main" function like so: 8071 8072@example 8073@c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage. 8074#ifdef __cplusplus 8075 extern "C" 8076#endif 8077int F77_MAIN (int argc, char *argv[]); 8078@end example 8079 8080(Again, replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.) 8081 8082The result of this macro is cached in the @code{ac_cv_f77_main} or 8083@code{ac_cv_fc_main} variable, respectively. 8084@end defmac 8085 8086@defmac AC_F77_WRAPPERS 8087@defmacx AC_FC_WRAPPERS 8088@acindex{F77_WRAPPERS} 8089@cvindex F77_FUNC 8090@cvindex F77_FUNC_ 8091@acindex{FC_WRAPPERS} 8092@cvindex FC_FUNC 8093@cvindex FC_FUNC_ 8094@caindex f77_mangling 8095@caindex fc_mangling 8096Defines C macros @code{F77_FUNC (name, NAME)}, @code{FC_FUNC (name, NAME)}, 8097@code{F77_FUNC_(name, NAME)}, and @code{FC_FUNC_(name, NAME)} to properly 8098mangle the names of C/C++ identifiers, and identifiers with underscores, 8099respectively, so that they match the name-mangling scheme used by the 8100Fortran compiler. 8101 8102Fortran is case-insensitive, and in order to achieve this the Fortran 8103compiler converts all identifiers into a canonical case and format. To 8104call a Fortran subroutine from C or to write a C function that is 8105callable from Fortran, the C program must explicitly use identifiers in 8106the format expected by the Fortran compiler. In order to do this, one 8107simply wraps all C identifiers in one of the macros provided by 8108@code{AC_F77_WRAPPERS} or @code{AC_FC_WRAPPERS}. For example, suppose 8109you have the following Fortran 77 subroutine: 8110 8111@example 8112@c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage. 8113 subroutine foobar (x, y) 8114 double precision x, y 8115 y = 3.14159 * x 8116 return 8117 end 8118@end example 8119 8120You would then declare its prototype in C or C++ as: 8121 8122@example 8123@c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage. 8124#define FOOBAR_F77 F77_FUNC (foobar, FOOBAR) 8125#ifdef __cplusplus 8126extern "C" /* prevent C++ name mangling */ 8127#endif 8128void FOOBAR_F77 (double *x, double *y); 8129@end example 8130 8131Note that we pass both the lowercase and uppercase versions of the 8132function name to @code{F77_FUNC} so that it can select the right one. 8133Note also that all parameters to Fortran 77 routines are passed as 8134pointers (@pxref{Mixing Fortran 77 With C and C++, , , automake, GNU 8135Automake}). 8136 8137(Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.) 8138 8139Although Autoconf tries to be intelligent about detecting the 8140name-mangling scheme of the Fortran compiler, there may be Fortran 8141compilers that it doesn't support yet. In this case, the above code 8142generates a compile-time error, but some other behavior 8143(e.g., disabling Fortran-related features) can be induced by checking 8144whether @code{F77_FUNC} or @code{FC_FUNC} is defined. 8145 8146Now, to call that routine from a C program, we would do something like: 8147 8148@example 8149@c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage. 8150@{ 8151 double x = 2.7183, y; 8152 FOOBAR_F77 (&x, &y); 8153@} 8154@end example 8155 8156If the Fortran identifier contains an underscore (e.g., @code{foo_bar}), 8157you should use @code{F77_FUNC_} or @code{FC_FUNC_} instead of 8158@code{F77_FUNC} or @code{FC_FUNC} (with the same arguments). This is 8159because some Fortran compilers mangle names differently if they contain 8160an underscore. 8161 8162The name mangling scheme is encoded in the @code{ac_cv_f77_mangling} or 8163@code{ac_cv_fc_mangling} cache variable, respectively, and also used for 8164the @code{AC_F77_FUNC} and @code{AC_FC_FUNC} macros described below. 8165@end defmac 8166 8167@defmac AC_F77_FUNC (@var{name}, @ovar{shellvar}) 8168@defmacx AC_FC_FUNC (@var{name}, @ovar{shellvar}) 8169@acindex{F77_FUNC} 8170@acindex{FC_FUNC} 8171Given an identifier @var{name}, set the shell variable @var{shellvar} to 8172hold the mangled version @var{name} according to the rules of the 8173Fortran linker (see also @code{AC_F77_WRAPPERS} or 8174@code{AC_FC_WRAPPERS}). @var{shellvar} is optional; if it is not 8175supplied, the shell variable is simply @var{name}. The purpose of 8176this macro is to give the caller a way to access the name-mangling 8177information other than through the C preprocessor as above, for example, 8178to call Fortran routines from some language other than C/C++. 8179@end defmac 8180 8181@defmac AC_FC_SRCEXT (@var{ext}, @ovar{action-if-success}, @ 8182 @dvar{action-if-failure, AC_MSG_FAILURE}) 8183@defmacx AC_FC_PP_SRCEXT (@var{ext}, @ovar{action-if-success}, @ 8184 @dvar{action-if-failure, AC_MSG_FAILURE}) 8185@acindex{FC_SRCEXT} 8186@acindex{FC_PP_SRCEXT} 8187@caindex fc_srcext_@var{ext} 8188@caindex fc_pp_srcext_@var{ext} 8189By default, the @code{FC} macros perform their tests using a @file{.f} 8190extension for source-code files. Some compilers, however, only enable 8191newer language features for appropriately named files, e.g., Fortran 90 8192features only for @file{.f90} files, or preprocessing only with 8193@file{.F} files or maybe other upper-case extensions. On the other 8194hand, some other compilers expect all source files to end in @file{.f} 8195and require special flags to support other file name extensions. The 8196@code{AC_FC_SRCEXT} and @code{AC_FC_PP_SRCEXT} macros deal with these 8197issues. 8198 8199The @code{AC_FC_SRCEXT} macro tries to get the @code{FC} compiler to 8200accept files ending with the extension @file{.@var{ext}} (i.e., 8201@var{ext} does @emph{not} contain the dot). If any special compiler 8202flags are needed for this, it stores them in the output variable 8203@code{FCFLAGS_@var{ext}}. This extension and these flags are then used 8204for all subsequent @code{FC} tests (until @code{AC_FC_SRCEXT} or 8205@code{AC_FC_PP_SRCEXT} is called another time). 8206 8207For example, you would use @code{AC_FC_SRCEXT(f90)} to employ the 8208@file{.f90} extension in future tests, and it would set the 8209@code{FCFLAGS_f90} output variable with any extra flags that are needed 8210to compile such files. 8211 8212Similarly, the @code{AC_FC_PP_SRCEXT} macro tries to get the @code{FC} 8213compiler to preprocess and compile files with the extension 8214@file{.@var{ext}}. When both @command{fpp} and @command{cpp} style 8215preprocessing are provided, the former is preferred, as the latter may 8216treat continuation lines, @code{//} tokens, and white space differently 8217from what some Fortran dialects expect. Conversely, if you do not want 8218files to be preprocessed, use only lower-case characters in the file 8219name extension. Like with @code{AC_FC_SRCEXT(f90)}, any needed flags 8220are stored in the @code{FCFLAGS_@var{ext}} variable. 8221 8222The @code{FCFLAGS_@var{ext}} flags can @emph{not} be simply absorbed 8223into @code{FCFLAGS}, for two reasons based on the limitations of some 8224compilers. First, only one @code{FCFLAGS_@var{ext}} can be used at a 8225time, so files with different extensions must be compiled separately. 8226Second, @code{FCFLAGS_@var{ext}} must appear @emph{immediately} before 8227the source-code file name when compiling. So, continuing the example 8228above, you might compile a @file{foo.f90} file in your makefile with the 8229command: 8230 8231@example 8232foo.o: foo.f90 8233 $(FC) -c $(FCFLAGS) $(FCFLAGS_f90) '$(srcdir)/foo.f90' 8234@end example 8235 8236If @code{AC_FC_SRCEXT} or @code{AC_FC_PP_SRCEXT} succeeds in compiling 8237files with the @var{ext} extension, it calls @var{action-if-success} 8238(defaults to nothing). If it fails, and cannot find a way to make the 8239@code{FC} compiler accept such files, it calls @var{action-if-failure} 8240(defaults to exiting with an error message). 8241 8242The @code{AC_FC_SRCEXT} and @code{AC_FC_PP_SRCEXT} macros cache their 8243results in @code{ac_cv_fc_srcext_@var{ext}} and 8244@code{ac_cv_fc_pp_srcext_@var{ext}} variables, respectively. 8245@end defmac 8246 8247@defmac AC_FC_PP_DEFINE (@ovar{action-if-success}, @dvar{action-if-failure, @ 8248 AC_MSG_FAILURE}) 8249@acindex{FC_PP_DEFINE} 8250@caindex fc_pp_define 8251 8252Find a flag to specify defines for preprocessed Fortran. Not all 8253Fortran compilers use @option{-D}. Substitute @code{FC_DEFINE} with 8254the result and call @var{action-if-success} (defaults to nothing) if 8255successful, and @var{action-if-failure} (defaults to failing with an 8256error message) if not. 8257 8258This macro calls @code{AC_FC_PP_SRCEXT([F])} in order to learn how to 8259preprocess a @file{conftest.F} file, but restores a previously used 8260Fortran source file extension afterwards again. 8261 8262The result of this test is cached in the @code{ac_cv_fc_pp_define} 8263variable. 8264@end defmac 8265 8266@defmac AC_FC_FREEFORM (@ovar{action-if-success}, @dvar{action-if-failure, @ 8267 AC_MSG_FAILURE}) 8268@acindex{FC_FREEFORM} 8269@caindex fc_freeform 8270 8271Try to ensure that the Fortran compiler (@code{$FC}) allows free-format 8272source code (as opposed to the older fixed-format style from Fortran 827377). If necessary, it may add some additional flags to @code{FCFLAGS}. 8274 8275This macro is most important if you are using the default @file{.f} 8276extension, since many compilers interpret this extension as indicating 8277fixed-format source unless an additional flag is supplied. If you 8278specify a different extension with @code{AC_FC_SRCEXT}, such as 8279@file{.f90}, then @code{AC_FC_FREEFORM} ordinarily succeeds without 8280modifying @code{FCFLAGS}. For extensions which the compiler does not 8281know about, the flag set by the @code{AC_FC_SRCEXT} macro might let 8282the compiler assume Fortran 77 by default, however. 8283 8284If @code{AC_FC_FREEFORM} succeeds in compiling free-form source, it 8285calls @var{action-if-success} (defaults to nothing). If it fails, it 8286calls @var{action-if-failure} (defaults to exiting with an error 8287message). 8288 8289The result of this test, or @samp{none} or @samp{unknown}, is cached in 8290the @code{ac_cv_fc_freeform} variable. 8291@end defmac 8292 8293@defmac AC_FC_FIXEDFORM (@ovar{action-if-success}, @dvar{action-if-failure, @ 8294 AC_MSG_FAILURE}) 8295@acindex{FC_FIXEDFORM} 8296@caindex fc_fixedform 8297 8298Try to ensure that the Fortran compiler (@code{$FC}) allows the old 8299fixed-format source code (as opposed to free-format style). If 8300necessary, it may add some additional flags to @code{FCFLAGS}. 8301 8302This macro is needed for some compilers alias names like @command{xlf95} 8303which assume free-form source code by default, and in case you want to 8304use fixed-form source with an extension like @file{.f90} which many 8305compilers interpret as free-form by default. If you specify a different 8306extension with @code{AC_FC_SRCEXT}, such as @file{.f}, then 8307@code{AC_FC_FIXEDFORM} ordinarily succeeds without modifying 8308@code{FCFLAGS}. 8309 8310If @code{AC_FC_FIXEDFORM} succeeds in compiling fixed-form source, it 8311calls @var{action-if-success} (defaults to nothing). If it fails, it 8312calls @var{action-if-failure} (defaults to exiting with an error 8313message). 8314 8315The result of this test, or @samp{none} or @samp{unknown}, is cached in 8316the @code{ac_cv_fc_fixedform} variable. 8317@end defmac 8318 8319@defmac AC_FC_LINE_LENGTH (@ovar{length}, @ovar{action-if-success}, @ 8320 @dvar{action-if-failure, AC_MSG_FAILURE}) 8321@acindex{FC_LINE_LENGTH} 8322@caindex fc_line_length 8323 8324Try to ensure that the Fortran compiler (@code{$FC}) accepts long source 8325code lines. The @var{length} argument may be given as 80, 132, or 8326unlimited, and defaults to 132. Note that line lengths above 254 8327columns are not portable, and some compilers do not accept more than 132 8328columns at least for fixed format source. If necessary, it may add some 8329additional flags to @code{FCFLAGS}. 8330 8331If @code{AC_FC_LINE_LENGTH} succeeds in compiling fixed-form source, it 8332calls @var{action-if-success} (defaults to nothing). If it fails, it 8333calls @var{action-if-failure} (defaults to exiting with an error 8334message). 8335 8336The result of this test, or @samp{none} or @samp{unknown}, is cached in 8337the @code{ac_cv_fc_line_length} variable. 8338@end defmac 8339 8340@defmac AC_FC_CHECK_BOUNDS (@ovar{action-if-success}, @ 8341 @dvar{action-if-failure, AC_MSG_FAILURE}) 8342@acindex{FC_CHECK_BOUNDS} 8343@caindex fc_check_bounds 8344 8345The @code{AC_FC_CHECK_BOUNDS} macro tries to enable array bounds checking 8346in the Fortran compiler. If successful, the @var{action-if-success} 8347is called and any needed flags are added to @code{FCFLAGS}. Otherwise, 8348@var{action-if-failure} is called, which defaults to failing with an error 8349message. The macro currently requires Fortran 90 or a newer dialect. 8350 8351The result of the macro is cached in the @code{ac_cv_fc_check_bounds} 8352variable. 8353@end defmac 8354 8355@defmac AC_F77_IMPLICIT_NONE (@ovar{action-if-success}, @ 8356 @dvar{action-if-failure, AC_MSG_FAILURE}) 8357@defmacx AC_FC_IMPLICIT_NONE (@ovar{action-if-success}, @ 8358 @dvar{action-if-failure, AC_MSG_FAILURE}) 8359@acindex{F77_IMPLICIT_NONE} 8360@acindex{FC_IMPLICIT_NONE} 8361@caindex f77_implicit_none 8362@caindex fc_implicit_none 8363 8364Try to disallow implicit declarations in the Fortran compiler. If 8365successful, @var{action-if-success} is called and any needed flags 8366are added to @code{FFLAGS} or @code{FCFLAGS}, respectively. Otherwise, 8367@var{action-if-failure} is called, which defaults to failing with an error 8368message. 8369 8370The result of these macros are cached in the 8371@code{ac_cv_f77_implicit_none} and @code{ac_cv_fc_implicit_none} 8372variables, respectively. 8373@end defmac 8374 8375@defmac AC_FC_MODULE_EXTENSION 8376@acindex{FC_MODULE_EXTENSION} 8377@caindex fc_module_ext 8378@ovindex FC_MODEXT 8379 8380Find the Fortran 90 module file name extension. Most Fortran 90 8381compilers store module information in files separate from the object 8382files. The module files are usually named after the name of the module 8383rather than the source file name, with characters possibly turned to 8384upper case, plus an extension, often @file{.mod}. 8385 8386Not all compilers use module files at all, or by default. The Cray 8387Fortran compiler requires @option{-e m} in order to store and search 8388module information in @file{.mod} files rather than in object files. 8389Likewise, the Fujitsu Fortran compilers uses the @option{-Am} option to 8390indicate how module information is stored. 8391 8392The @code{AC_FC_MODULE_EXTENSION} macro computes the module extension 8393without the leading dot, and stores that in the @code{FC_MODEXT} 8394variable. If the compiler does not produce module files, or the 8395extension cannot be determined, @code{FC_MODEXT} is empty. Typically, 8396the result of this macro may be used in cleanup @command{make} rules as 8397follows: 8398 8399@example 8400clean-modules: 8401 -test -z "$(FC_MODEXT)" || rm -f *.$(FC_MODEXT) 8402@end example 8403 8404The extension, or @samp{unknown}, is cached in the 8405@code{ac_cv_fc_module_ext} variable. 8406@end defmac 8407 8408@defmac AC_FC_MODULE_FLAG (@ovar{action-if-success}, @ 8409 @dvar{action-if-failure, AC_MSG_FAILURE}) 8410@acindex{FC_MODULE_FLAG} 8411@caindex fc_module_flag 8412@ovindex FC_MODINC 8413@ovindex ac_empty 8414 8415Find the compiler flag to include Fortran 90 module information from 8416another directory, and store that in the @code{FC_MODINC} variable. 8417Call @var{action-if-success} (defaults to nothing) if successful, and 8418set @code{FC_MODINC} to empty and call @var{action-if-failure} (defaults 8419to exiting with an error message) if not. 8420 8421Most Fortran 90 compilers provide a way to specify module directories. 8422Some have separate flags for the directory to write module files to, 8423and directories to search them in, whereas others only allow writing to 8424the current directory or to the first directory specified in the include 8425path. Further, with some compilers, the module search path and the 8426preprocessor search path can only be modified with the same flag. Thus, 8427for portability, write module files to the current directory only and 8428list that as first directory in the search path. 8429 8430There may be no whitespace between @code{FC_MODINC} and the following 8431directory name, but @code{FC_MODINC} may contain trailing white space. 8432For example, if you use Automake and would like to search @file{../lib} 8433for module files, you can use the following: 8434 8435@example 8436AM_FCFLAGS = $(FC_MODINC). $(FC_MODINC)../lib 8437@end example 8438 8439Inside @command{configure} tests, you can use: 8440 8441@example 8442if test -n "$FC_MODINC"; then 8443 FCFLAGS="$FCFLAGS $FC_MODINC. $FC_MODINC../lib" 8444fi 8445@end example 8446 8447The flag is cached in the @code{ac_cv_fc_module_flag} variable. 8448The substituted value of @code{FC_MODINC} may refer to the 8449@code{ac_empty} dummy placeholder empty variable, to avoid losing 8450the significant trailing whitespace in a @file{Makefile}. 8451@end defmac 8452 8453@defmac AC_FC_MODULE_OUTPUT_FLAG (@ovar{action-if-success}, @ 8454 @dvar{action-if-failure, AC_MSG_FAILURE}) 8455@acindex{FC_MODULE_OUTPUT_FLAG} 8456@caindex fc_module_output_flag 8457@ovindex FC_MODOUT 8458 8459Find the compiler flag to write Fortran 90 module information to 8460another directory, and store that in the @code{FC_MODOUT} variable. 8461Call @var{action-if-success} (defaults to nothing) if successful, and 8462set @code{FC_MODOUT} to empty and call @var{action-if-failure} (defaults 8463to exiting with an error message) if not. 8464 8465Not all Fortran 90 compilers write module files, and of those that do, 8466not all allow writing to a directory other than the current one, nor 8467do all have separate flags for writing and reading; see the description 8468of @code{AC_FC_MODULE_FLAG} above. If you need to be able to write to 8469another directory, for maximum portability use @code{FC_MODOUT} before 8470any @code{FC_MODINC} and include both the current directory and the one 8471you write to in the search path: 8472 8473@example 8474AM_FCFLAGS = $(FC_MODOUT)../mod $(FC_MODINC)../mod $(FC_MODINC). @dots{} 8475@end example 8476 8477The flag is cached in the @code{ac_cv_fc_module_output_flag} variable. 8478The substituted value of @code{FC_MODOUT} may refer to the 8479@code{ac_empty} dummy placeholder empty variable, to avoid losing 8480the significant trailing whitespace in a @file{Makefile}. 8481@end defmac 8482 8483 8484@node Go Compiler 8485@subsection Go Compiler Characteristics 8486@cindex Go 8487 8488Autoconf provides basic support for the Go programming language when 8489using the @code{gccgo} compiler (there is currently no support for the 8490@code{6g} and @code{8g} compilers). 8491 8492@defmac AC_PROG_GO (@ovar{compiler-search-list}) 8493Find the Go compiler to use. Check whether the environment variable 8494@code{GOC} is set; if so, then set output variable @code{GOC} to its 8495value. 8496 8497Otherwise, if the macro is invoked without an argument, then search for 8498a Go compiler named @code{gccgo}. If it is not found, then as a last 8499resort set @code{GOC} to @code{gccgo}. 8500 8501This macro may be invoked with an optional first argument which, if 8502specified, must be a blank-separated list of Go compilers to search for. 8503 8504If output variable @code{GOFLAGS} was not already set, set it to 8505@option{-g -O2}. If your package does not like this default, 8506@code{GOFLAGS} may be set before @code{AC_PROG_GO}. 8507@end defmac 8508 8509 8510@node System Services 8511@section System Services 8512 8513The following macros check for operating system services or capabilities. 8514 8515@anchor{AC_PATH_X} 8516@defmac AC_PATH_X 8517@acindex{PATH_X} 8518@evindex XMKMF 8519@cindex X Window System 8520Try to locate the X Window System include files and libraries. If the 8521user gave the command line options @option{--x-includes=@var{dir}} and 8522@option{--x-libraries=@var{dir}}, use those directories. 8523 8524If either or both were not given, get the missing values by running 8525@code{xmkmf} (or an executable pointed to by the @code{XMKMF} 8526environment variable) on a trivial @file{Imakefile} and examining the 8527makefile that it produces. Setting @code{XMKMF} to @samp{false} 8528disables this method. 8529 8530If this method fails to find the X Window System, @command{configure} 8531looks for the files in several directories where they often reside. 8532If either method is successful, set the shell variables 8533@code{x_includes} and @code{x_libraries} to their locations, unless they 8534are in directories the compiler searches by default. 8535 8536If both methods fail, or the user gave the command line option 8537@option{--without-x}, set the shell variable @code{no_x} to @samp{yes}; 8538otherwise set it to the empty string. 8539@end defmac 8540 8541@anchor{AC_PATH_XTRA} 8542@defmac AC_PATH_XTRA 8543@acindex{PATH_XTRA} 8544@ovindex X_CFLAGS 8545@ovindex X_LIBS 8546@ovindex X_EXTRA_LIBS 8547@ovindex X_PRE_LIBS 8548@cvindex X_DISPLAY_MISSING 8549An enhanced version of @code{AC_PATH_X}. It adds the C compiler flags 8550that X needs to output variable @code{X_CFLAGS}, and the X linker flags 8551to @code{X_LIBS}. Define @code{X_DISPLAY_MISSING} if X is not 8552available. 8553 8554This macro also checks for special libraries that some systems need in 8555order to compile X programs. It adds any that the system needs to 8556output variable @code{X_EXTRA_LIBS}. And it checks for special X11R6 8557libraries that need to be linked with before @option{-lX11}, and adds 8558any found to the output variable @code{X_PRE_LIBS}. 8559 8560@c This is an incomplete kludge. Make a real way to do it. 8561@c If you need to check for other X functions or libraries yourself, then 8562@c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to 8563@c @code{LIBS} temporarily, like this: (FIXME - add example) 8564@end defmac 8565 8566@anchor{AC_SYS_INTERPRETER} 8567@defmac AC_SYS_INTERPRETER 8568@acindex{SYS_INTERPRETER} 8569Check whether the system supports starting scripts with a line of the 8570form @samp{#!/bin/sh} to select the interpreter to use for the script. 8571After running this macro, shell code in @file{configure.ac} can check 8572the shell variable @code{interpval}; it is set to @samp{yes} 8573if the system supports @samp{#!}, @samp{no} if not. 8574@end defmac 8575 8576@defmac AC_SYS_LARGEFILE 8577@acindex{SYS_LARGEFILE} 8578@cvindex _FILE_OFFSET_BITS 8579@cvindex _LARGE_FILES 8580@ovindex CC 8581@cindex Large file support 8582@cindex LFS 8583Arrange for 64-bit file offsets, known as 8584@uref{http://@/www.unix-systems@/.org/@/version2/@/whatsnew/@/lfs20mar.html, 8585large-file support}. On some hosts, one must use special compiler 8586options to build programs that can access large files. Append any such 8587options to the output variable @code{CC}. Define 8588@code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary. 8589 8590Large-file support can be disabled by configuring with the 8591@option{--disable-largefile} option. 8592 8593If you use this macro, check that your program works even when 8594@code{off_t} is wider than @code{long int}, since this is common when 8595large-file support is enabled. For example, it is not correct to print 8596an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld", 8597(long int) X)}. 8598 8599The LFS introduced the @code{fseeko} and @code{ftello} functions to 8600replace their C counterparts @code{fseek} and @code{ftell} that do not 8601use @code{off_t}. Take care to use @code{AC_FUNC_FSEEKO} to make their 8602prototypes available when using them and large-file support is 8603enabled. 8604@end defmac 8605 8606@anchor{AC_SYS_LONG_FILE_NAMES} 8607@defmac AC_SYS_LONG_FILE_NAMES 8608@acindex{SYS_LONG_FILE_NAMES} 8609@cvindex HAVE_LONG_FILE_NAMES 8610If the system supports file names longer than 14 characters, define 8611@code{HAVE_LONG_FILE_NAMES}. 8612@end defmac 8613 8614@defmac AC_SYS_POSIX_TERMIOS 8615@acindex{SYS_POSIX_TERMIOS} 8616@cindex Posix termios headers 8617@cindex termios Posix headers 8618@caindex sys_posix_termios 8619Check to see if the Posix termios headers and functions are available on the 8620system. If so, set the shell variable @code{ac_cv_sys_posix_termios} to 8621@samp{yes}. If not, set the variable to @samp{no}. 8622@end defmac 8623 8624@node Posix Variants 8625@section Posix Variants 8626 8627The following macro makes it possible to use features of Posix that are 8628extensions to C, as well as platform extensions not defined by Posix. 8629 8630@anchor{AC_USE_SYSTEM_EXTENSIONS} 8631@defmac AC_USE_SYSTEM_EXTENSIONS 8632@acindex{USE_SYSTEM_EXTENSIONS} 8633@cvindex _ALL_SOURCE 8634@cvindex _GNU_SOURCE 8635@cvindex _MINIX 8636@cvindex _POSIX_1_SOURCE 8637@cvindex _POSIX_PTHREAD_SEMANTICS 8638@cvindex _POSIX_SOURCE 8639@cvindex _TANDEM_SOURCE 8640@cvindex __EXTENSIONS__ 8641This macro was introduced in Autoconf 2.60. If possible, enable 8642extensions to C or Posix on hosts that normally disable the extensions, 8643typically due to standards-conformance namespace issues. This should be 8644called before any macros that run the C compiler. The following 8645preprocessor macros are defined where appropriate: 8646 8647@table @code 8648@item _GNU_SOURCE 8649Enable extensions on GNU/Linux. 8650@item __EXTENSIONS__ 8651Enable general extensions on Solaris. 8652@item _POSIX_PTHREAD_SEMANTICS 8653Enable threading extensions on Solaris. 8654@item _TANDEM_SOURCE 8655Enable extensions for the HP NonStop platform. 8656@item _ALL_SOURCE 8657Enable extensions for AIX 3, and for Interix. 8658@item _POSIX_SOURCE 8659Enable Posix functions for Minix. 8660@item _POSIX_1_SOURCE 8661Enable additional Posix functions for Minix. 8662@item _MINIX 8663Identify Minix platform. This particular preprocessor macro is 8664obsolescent, and may be removed in a future release of Autoconf. 8665@end table 8666@end defmac 8667 8668 8669@node Erlang Libraries 8670@section Erlang Libraries 8671@cindex Erlang, Library, checking 8672 8673The following macros check for an installation of Erlang/OTP, and for the 8674presence of certain Erlang libraries. All those macros require the 8675configuration of an Erlang interpreter and an Erlang compiler 8676(@pxref{Erlang Compiler and Interpreter}). 8677 8678@defmac AC_ERLANG_SUBST_ERTS_VER 8679@acindex{ERLANG_SUBST_ERTS_VER} 8680@ovindex ERLANG_ERTS_VER 8681Set the output variable @code{ERLANG_ERTS_VER} to the version of the 8682Erlang runtime system (as returned by Erlang's 8683@code{erlang:system_info(version)} function). The result of this test 8684is cached if caching is enabled when running @command{configure}. The 8685@code{ERLANG_ERTS_VER} variable is not intended to be used for testing 8686for features of specific ERTS versions, but to be used for substituting 8687the ERTS version in Erlang/OTP release resource files (@code{.rel} 8688files), as shown below. 8689@end defmac 8690 8691@defmac AC_ERLANG_SUBST_ROOT_DIR 8692@acindex{ERLANG_SUBST_ROOT_DIR} 8693@ovindex ERLANG_ROOT_DIR 8694Set the output variable @code{ERLANG_ROOT_DIR} to the path to the base 8695directory in which Erlang/OTP is installed (as returned by Erlang's 8696@code{code:root_dir/0} function). The result of this test is cached if 8697caching is enabled when running @command{configure}. 8698@end defmac 8699 8700@defmac AC_ERLANG_SUBST_LIB_DIR 8701@acindex{ERLANG_SUBST_LIB_DIR} 8702@ovindex ERLANG_LIB_DIR 8703Set the output variable @code{ERLANG_LIB_DIR} to the path of the library 8704directory of Erlang/OTP (as returned by Erlang's 8705@code{code:lib_dir/0} function), which subdirectories each contain an installed 8706Erlang/OTP library. The result of this test is cached if caching is enabled 8707when running @command{configure}. 8708@end defmac 8709 8710@defmac AC_ERLANG_CHECK_LIB (@var{library}, @ovar{action-if-found}, @ 8711 @ovar{action-if-not-found}) 8712@acindex{ERLANG_CHECK_LIB} 8713@ovindex ERLANG_LIB_DIR_@var{library} 8714@ovindex ERLANG_LIB_VER_@var{library} 8715Test whether the Erlang/OTP library @var{library} is installed by 8716calling Erlang's @code{code:lib_dir/1} function. The result of this 8717test is cached if caching is enabled when running @command{configure}. 8718@var{action-if-found} is a list of shell commands to run if the library 8719is installed; @var{action-if-not-found} is a list of shell commands to 8720run if it is not. Additionally, if the library is installed, the output 8721variable @samp{ERLANG_LIB_DIR_@var{library}} is set to the path to the 8722library installation directory, and the output variable 8723@samp{ERLANG_LIB_VER_@var{library}} is set to the version number that is 8724part of the subdirectory name, if it is in the standard form 8725(@code{@var{library}-@var{version}}). If the directory name does not 8726have a version part, @samp{ERLANG_LIB_VER_@var{library}} is set to the 8727empty string. If the library is not installed, 8728@samp{ERLANG_LIB_DIR_@var{library}} and 8729@samp{ERLANG_LIB_VER_@var{library}} are set to @code{"not found"}. For 8730example, to check if library @code{stdlib} is installed: 8731 8732@example 8733AC_ERLANG_CHECK_LIB([stdlib], 8734 [echo "stdlib version \"$ERLANG_LIB_VER_stdlib\"" 8735 echo "is installed in \"$ERLANG_LIB_DIR_stdlib\""], 8736 [AC_MSG_ERROR([stdlib was not found!])]) 8737@end example 8738 8739The @samp{ERLANG_LIB_VER_@var{library}} variables (set by 8740@code{AC_ERLANG_CHECK_LIB}) and the @code{ERLANG_ERTS_VER} variable (set 8741by @code{AC_ERLANG_SUBST_ERTS_VER}) are not intended to be used for 8742testing for features of specific versions of libraries or of the Erlang 8743runtime system. Those variables are intended to be substituted in 8744Erlang release resource files (@code{.rel} files). For instance, to 8745generate a @file{example.rel} file for an application depending on the 8746@code{stdlib} library, @file{configure.ac} could contain: 8747 8748@example 8749AC_ERLANG_SUBST_ERTS_VER 8750AC_ERLANG_CHECK_LIB([stdlib], 8751 [], 8752 [AC_MSG_ERROR([stdlib was not found!])]) 8753AC_CONFIG_FILES([example.rel]) 8754@end example 8755 8756@noindent 8757The @file{example.rel.in} file used to generate @file{example.rel} 8758should contain: 8759 8760@example 8761@{release, 8762 @{"@@PACKAGE@@", "@@VERSION@@"@}, 8763 @{erts, "@@ERLANG_ERTS_VER@@"@}, 8764 [@{stdlib, "@@ERLANG_LIB_VER_stdlib@@"@}, 8765 @{@@PACKAGE@@, "@@VERSION@@"@}]@}. 8766@end example 8767@end defmac 8768 8769In addition to the above macros, which test installed Erlang libraries, the 8770following macros determine the paths to the directories into which newly built 8771Erlang libraries are to be installed: 8772 8773@defmac AC_ERLANG_SUBST_INSTALL_LIB_DIR 8774@acindex{ERLANG_SUBST_INSTALL_LIB_DIR} 8775@ovindex ERLANG_INSTALL_LIB_DIR 8776 8777Set the @code{ERLANG_INSTALL_LIB_DIR} output variable to the directory into 8778which every built Erlang library should be installed in a separate 8779subdirectory. 8780If this variable is not set in the environment when @command{configure} runs, 8781its default value is @code{$@{libdir@}/erlang/lib}. 8782@end defmac 8783 8784@defmac AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR (@var{library}, @var{version}) 8785@acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR} 8786@ovindex ERLANG_INSTALL_LIB_DIR_@var{library} 8787 8788Set the @samp{ERLANG_INSTALL_LIB_DIR_@var{library}} output variable to the 8789directory into which the built Erlang library @var{library} version 8790@var{version} should be installed. If this variable is not set in the 8791environment when @command{configure} runs, its default value is 8792@samp{$ERLANG_INSTALL_LIB_DIR/@var{library}-@var{version}}, the value of the 8793@code{ERLANG_INSTALL_LIB_DIR} variable being set by the 8794@code{AC_ERLANG_SUBST_INSTALL_LIB_DIR} macro. 8795@end defmac 8796 8797 8798 8799 8800 8801@c ========================================================= Writing Tests 8802 8803@node Writing Tests 8804@chapter Writing Tests 8805 8806If the existing feature tests don't do something you need, you have to 8807write new ones. These macros are the building blocks. They provide 8808ways for other macros to check whether various kinds of features are 8809available and report the results. 8810 8811This chapter contains some suggestions and some of the reasons why the 8812existing tests are written the way they are. You can also learn a lot 8813about how to write Autoconf tests by looking at the existing ones. If 8814something goes wrong in one or more of the Autoconf tests, this 8815information can help you understand the assumptions behind them, which 8816might help you figure out how to best solve the problem. 8817 8818These macros check the output of the compiler system of the current 8819language (@pxref{Language Choice}). They do not cache the results of 8820their tests for future use (@pxref{Caching Results}), because they don't 8821know enough about the information they are checking for to generate a 8822cache variable name. They also do not print any messages, for the same 8823reason. The checks for particular kinds of features call these macros 8824and do cache their results and print messages about what they're 8825checking for. 8826 8827When you write a feature test that could be applicable to more than one 8828software package, the best thing to do is encapsulate it in a new macro. 8829@xref{Writing Autoconf Macros}, for how to do that. 8830 8831@menu 8832* Language Choice:: Selecting which language to use for testing 8833* Writing Test Programs:: Forging source files for compilers 8834* Running the Preprocessor:: Detecting preprocessor symbols 8835* Running the Compiler:: Detecting language or header features 8836* Running the Linker:: Detecting library features 8837* Runtime:: Testing for runtime features 8838* Systemology:: A zoology of operating systems 8839* Multiple Cases:: Tests for several possible values 8840@end menu 8841 8842@node Language Choice 8843@section Language Choice 8844@cindex Language 8845 8846Autoconf-generated @command{configure} scripts check for the C compiler and 8847its features by default. Packages that use other programming languages 8848(maybe more than one, e.g., C and C++) need to test features of the 8849compilers for the respective languages. The following macros determine 8850which programming language is used in the subsequent tests in 8851@file{configure.ac}. 8852 8853@anchor{AC_LANG} 8854@defmac AC_LANG (@var{language}) 8855@acindex{LANG} 8856Do compilation tests using the compiler, preprocessor, and file 8857extensions for the specified @var{language}. 8858 8859Supported languages are: 8860 8861@table @samp 8862@item C 8863Do compilation tests using @code{CC} and @code{CPP} and use extension 8864@file{.c} for test programs. Use compilation flags: @code{CPPFLAGS} with 8865@code{CPP}, and both @code{CPPFLAGS} and @code{CFLAGS} with @code{CC}. 8866 8867@item C++ 8868Do compilation tests using @code{CXX} and @code{CXXCPP} and use 8869extension @file{.C} for test programs. Use compilation flags: 8870@code{CPPFLAGS} with @code{CXXCPP}, and both @code{CPPFLAGS} and 8871@code{CXXFLAGS} with @code{CXX}. 8872 8873@item Fortran 77 8874Do compilation tests using @code{F77} and use extension @file{.f} for 8875test programs. Use compilation flags: @code{FFLAGS}. 8876 8877@item Fortran 8878Do compilation tests using @code{FC} and use extension @file{.f} (or 8879whatever has been set by @code{AC_FC_SRCEXT}) for test programs. Use 8880compilation flags: @code{FCFLAGS}. 8881 8882@item Erlang 8883@ovindex ERLC 8884@ovindex ERL 8885@ovindex ERLCFLAGS 8886Compile and execute tests using @code{ERLC} and @code{ERL} and use extension 8887@file{.erl} for test Erlang modules. Use compilation flags: @code{ERLCFLAGS}. 8888 8889@item Objective C 8890Do compilation tests using @code{OBJC} and @code{OBJCPP} and use 8891extension @file{.m} for test programs. Use compilation flags: 8892@code{CPPFLAGS} with @code{OBJCPP}, and both @code{CPPFLAGS} and 8893@code{OBJCFLAGS} with @code{OBJC}. 8894 8895@item Objective C++ 8896Do compilation tests using @code{OBJCXX} and @code{OBJCXXCPP} and use 8897extension @file{.mm} for test programs. Use compilation flags: 8898@code{CPPFLAGS} with @code{OBJCXXCPP}, and both @code{CPPFLAGS} and 8899@code{OBJCXXFLAGS} with @code{OBJCXX}. 8900 8901@item Go 8902Do compilation tests using @code{GOC} and use extension @file{.go} for 8903test programs. Use compilation flags @code{GOFLAGS}. 8904@end table 8905@end defmac 8906 8907@anchor{AC_LANG_PUSH} 8908@defmac AC_LANG_PUSH (@var{language}) 8909@acindex{LANG_PUSH} 8910Remember the current language (as set by @code{AC_LANG}) on a stack, and 8911then select the @var{language}. Use this macro and @code{AC_LANG_POP} 8912in macros that need to temporarily switch to a particular language. 8913@end defmac 8914 8915@defmac AC_LANG_POP (@ovar{language}) 8916@acindex{LANG_POP} 8917Select the language that is saved on the top of the stack, as set by 8918@code{AC_LANG_PUSH}, and remove it from the stack. 8919 8920If given, @var{language} specifies the language we just @emph{quit}. It 8921is a good idea to specify it when it's known (which should be the 8922case@dots{}), since Autoconf detects inconsistencies. 8923 8924@example 8925AC_LANG_PUSH([Fortran 77]) 8926# Perform some tests on Fortran 77. 8927# @dots{} 8928AC_LANG_POP([Fortran 77]) 8929@end example 8930@end defmac 8931 8932@defmac AC_LANG_ASSERT (@var{language}) 8933@acindex{LANG_ASSERT} 8934Check statically that the current language is @var{language}. 8935You should use this in your language specific macros 8936to avoid that they be called with an inappropriate language. 8937 8938This macro runs only at @command{autoconf} time, and incurs no cost at 8939@command{configure} time. Sadly enough and because Autoconf is a two 8940layer language @footnote{Because M4 is not aware of Sh code, 8941especially conditionals, some optimizations that look nice statically 8942may produce incorrect results at runtime.}, the macros 8943@code{AC_LANG_PUSH} and @code{AC_LANG_POP} cannot be ``optimizing'', 8944therefore as much as possible you ought to avoid using them to wrap 8945your code, rather, require from the user to run the macro with a 8946correct current language, and check it with @code{AC_LANG_ASSERT}. 8947And anyway, that may help the user understand she is running a Fortran 8948macro while expecting a result about her Fortran 77 compiler@enddots{} 8949@end defmac 8950 8951 8952@defmac AC_REQUIRE_CPP 8953@acindex{REQUIRE_CPP} 8954Ensure that whichever preprocessor would currently be used for tests has 8955been found. Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an 8956argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP}, 8957depending on which language is current. 8958@end defmac 8959 8960 8961@node Writing Test Programs 8962@section Writing Test Programs 8963 8964Autoconf tests follow a common scheme: feed some program with some 8965input, and most of the time, feed a compiler with some source file. 8966This section is dedicated to these source samples. 8967 8968@menu 8969* Guidelines:: General rules for writing test programs 8970* Test Functions:: Avoiding pitfalls in test programs 8971* Generating Sources:: Source program boilerplate 8972@end menu 8973 8974@node Guidelines 8975@subsection Guidelines for Test Programs 8976 8977The most important rule to follow when writing testing samples is: 8978 8979@center @emph{Look for realism.} 8980 8981This motto means that testing samples must be written with the same 8982strictness as real programs are written. In particular, you should 8983avoid ``shortcuts'' and simplifications. 8984 8985Don't just play with the preprocessor if you want to prepare a 8986compilation. For instance, using @command{cpp} to check whether a header is 8987functional might let your @command{configure} accept a header which 8988causes some @emph{compiler} error. Do not hesitate to check a header with 8989other headers included before, especially required headers. 8990 8991Make sure the symbols you use are properly defined, i.e., refrain from 8992simply declaring a function yourself instead of including the proper 8993header. 8994 8995Test programs should not write to standard output. They 8996should exit with status 0 if the test succeeds, and with status 1 8997otherwise, so that success 8998can be distinguished easily from a core dump or other failure; 8999segmentation violations and other failures produce a nonzero exit 9000status. Unless you arrange for @code{exit} to be declared, test 9001programs should @code{return}, not @code{exit}, from @code{main}, 9002because on many systems @code{exit} is not declared by default. 9003 9004Test programs can use @code{#if} or @code{#ifdef} to check the values of 9005preprocessor macros defined by tests that have already run. For 9006example, if you call @code{AC_HEADER_STDBOOL}, then later on in 9007@file{configure.ac} you can have a test program that includes 9008@file{stdbool.h} conditionally: 9009 9010@example 9011@group 9012#ifdef HAVE_STDBOOL_H 9013# include <stdbool.h> 9014#endif 9015@end group 9016@end example 9017 9018Both @code{#if HAVE_STDBOOL_H} and @code{#ifdef HAVE_STDBOOL_H} will 9019work with any standard C compiler. Some developers prefer @code{#if} 9020because it is easier to read, while others prefer @code{#ifdef} because 9021it avoids diagnostics with picky compilers like GCC with the 9022@option{-Wundef} option. 9023 9024If a test program needs to use or create a data file, give it a name 9025that starts with @file{conftest}, such as @file{conftest.data}. The 9026@command{configure} script cleans up by running @samp{rm -f -r conftest*} 9027after running test programs and if the script is interrupted. 9028 9029@node Test Functions 9030@subsection Test Functions 9031 9032These days it's safe to assume support for function prototypes 9033(introduced in C89). 9034 9035Functions that test programs declare should also be conditionalized for 9036C++, which requires @samp{extern "C"} prototypes. Make sure to not 9037include any header files containing clashing prototypes. 9038 9039@example 9040#ifdef __cplusplus 9041extern "C" 9042#endif 9043void *valloc (size_t); 9044@end example 9045 9046If a test program calls a function with invalid parameters (just to see 9047whether it exists), organize the program to ensure that it never invokes 9048that function. You can do this by calling it in another function that is 9049never invoked. You can't do it by putting it after a call to 9050@code{exit}, because GCC version 2 knows that @code{exit} 9051never returns 9052and optimizes out any code that follows it in the same block. 9053 9054If you include any header files, be sure to call the functions 9055relevant to them with the correct number of arguments, even if they are 9056just 0, to avoid compilation errors due to prototypes. GCC 9057version 2 9058has internal prototypes for several functions that it automatically 9059inlines; for example, @code{memcpy}. To avoid errors when checking for 9060them, either pass them the correct number of arguments or redeclare them 9061with a different return type (such as @code{char}). 9062 9063 9064@node Generating Sources 9065@subsection Generating Sources 9066 9067Autoconf provides a set of macros that can be used to generate test 9068source files. They are written to be language generic, i.e., they 9069actually depend on the current language (@pxref{Language Choice}) to 9070``format'' the output properly. 9071 9072 9073@defmac AC_LANG_CONFTEST (@var{source}) 9074@acindex{LANG_CONFTEST} 9075Save the @var{source} text in the current test source file: 9076@file{conftest.@var{extension}} where the @var{extension} depends on the 9077current language. As of Autoconf 2.63b, the source file also contains 9078the results of all of the @code{AC_DEFINE} performed so far. 9079 9080Note that the @var{source} is evaluated exactly once, like regular 9081Autoconf macro arguments, and therefore (i) you may pass a macro 9082invocation, (ii) if not, be sure to double quote if needed. 9083 9084This macro issues a warning during @command{autoconf} processing if 9085@var{source} does not include an expansion of the macro 9086@code{AC_LANG_DEFINES_PROVIDED} (note that both @code{AC_LANG_SOURCE} and 9087@code{AC_LANG_PROGRAM} call this macro, and thus avoid the warning). 9088 9089This macro is seldom called directly, but is used under the hood by more 9090common macros such as @code{AC_COMPILE_IFELSE} and @code{AC_RUN_IFELSE}. 9091@end defmac 9092 9093@defmac AC_LANG_DEFINES_PROVIDED 9094@acindex{LANG_DEFINES_PROVIDED} 9095This macro is called as a witness that the file 9096@file{conftest.@var{extension}} appropriate for the current language is 9097complete, including all previously determined results from 9098@code{AC_DEFINE}. This macro is seldom called directly, but exists if 9099you have a compelling reason to write a conftest file without using 9100@code{AC_LANG_SOURCE}, yet still want to avoid a syntax warning from 9101@code{AC_LANG_CONFTEST}. 9102@end defmac 9103 9104@defmac AC_LANG_SOURCE (@var{source}) 9105@acindex{LANG_SOURCE} 9106Expands into the @var{source}, with the definition of 9107all the @code{AC_DEFINE} performed so far. This macro includes an 9108expansion of @code{AC_LANG_DEFINES_PROVIDED}. 9109 9110In many cases, you may find it more convenient to use the wrapper 9111@code{AC_LANG_PROGRAM}. 9112@end defmac 9113 9114For instance, executing (observe the double quotation!): 9115 9116@example 9117@c If you change this example, adjust tests/compile.at:AC_LANG_SOURCE example. 9118AC_INIT([Hello], [1.0], [bug-hello@@example.org], [], 9119 [http://www.example.org/]) 9120AC_DEFINE([HELLO_WORLD], ["Hello, World\n"], 9121 [Greetings string.]) 9122AC_LANG([C]) 9123AC_LANG_CONFTEST( 9124 [AC_LANG_SOURCE([[const char hw[] = "Hello, World\n";]])]) 9125gcc -E -dD conftest.c 9126@end example 9127 9128@noindent 9129on a system with @command{gcc} installed, results in: 9130 9131@example 9132@c If you change this example, adjust tests/compile.at:AC_LANG_SOURCE example. 9133@dots{} 9134# 1 "conftest.c" 9135 9136#define PACKAGE_NAME "Hello" 9137#define PACKAGE_TARNAME "hello" 9138#define PACKAGE_VERSION "1.0" 9139#define PACKAGE_STRING "Hello 1.0" 9140#define PACKAGE_BUGREPORT "bug-hello@@example.org" 9141#define PACKAGE_URL "http://www.example.org/" 9142#define HELLO_WORLD "Hello, World\n" 9143 9144const char hw[] = "Hello, World\n"; 9145@end example 9146 9147When the test language is Fortran, Erlang, or Go, the @code{AC_DEFINE} 9148definitions are not automatically translated into constants in the 9149source code by this macro. 9150 9151@defmac AC_LANG_PROGRAM (@var{prologue}, @var{body}) 9152@acindex{LANG_PROGRAM} 9153Expands into a source file which consists of the @var{prologue}, and 9154then @var{body} as body of the main function (e.g., @code{main} in 9155C). Since it uses @code{AC_LANG_SOURCE}, the features of the latter are 9156available. 9157@end defmac 9158 9159For instance: 9160 9161@example 9162@c If you change this example, adjust tests/compile.at:AC_LANG_PROGRAM example. 9163AC_INIT([Hello], [1.0], [bug-hello@@example.org], [], 9164 [http://www.example.org/]) 9165AC_DEFINE([HELLO_WORLD], ["Hello, World\n"], 9166 [Greetings string.]) 9167AC_LANG_CONFTEST( 9168[AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]], 9169 [[fputs (hw, stdout);]])]) 9170gcc -E -dD conftest.c 9171@end example 9172 9173@noindent 9174on a system with @command{gcc} installed, results in: 9175 9176@example 9177@c If you change this example, adjust tests/compile.at:AC_LANG_PROGRAM example. 9178@dots{} 9179# 1 "conftest.c" 9180 9181#define PACKAGE_NAME "Hello" 9182#define PACKAGE_TARNAME "hello" 9183#define PACKAGE_VERSION "1.0" 9184#define PACKAGE_STRING "Hello 1.0" 9185#define PACKAGE_BUGREPORT "bug-hello@@example.org" 9186#define PACKAGE_URL "http://www.example.org/" 9187#define HELLO_WORLD "Hello, World\n" 9188 9189const char hw[] = "Hello, World\n"; 9190int 9191main () 9192@{ 9193fputs (hw, stdout); 9194 ; 9195 return 0; 9196@} 9197@end example 9198 9199In Erlang tests, the created source file is that of an Erlang module called 9200@code{conftest} (@file{conftest.erl}). This module defines and exports 9201at least 9202one @code{start/0} function, which is called to perform the test. The 9203@var{prologue} is optional code that is inserted between the module header and 9204the @code{start/0} function definition. @var{body} is the body of the 9205@code{start/0} function without the final period (@pxref{Runtime}, about 9206constraints on this function's behavior). 9207 9208For instance: 9209 9210@example 9211AC_INIT([Hello], [1.0], [bug-hello@@example.org]) 9212AC_LANG(Erlang) 9213AC_LANG_CONFTEST( 9214[AC_LANG_PROGRAM([[-define(HELLO_WORLD, "Hello, world!").]], 9215 [[io:format("~s~n", [?HELLO_WORLD])]])]) 9216cat conftest.erl 9217@end example 9218 9219@noindent 9220results in: 9221 9222@example 9223-module(conftest). 9224-export([start/0]). 9225-define(HELLO_WORLD, "Hello, world!"). 9226start() -> 9227io:format("~s~n", [?HELLO_WORLD]) 9228. 9229@end example 9230 9231@defmac AC_LANG_CALL (@var{prologue}, @var{function}) 9232@acindex{LANG_CALL} 9233Expands into a source file which consists of the @var{prologue}, and 9234then a call to the @var{function} as body of the main function (e.g., 9235@code{main} in C). Since it uses @code{AC_LANG_PROGRAM}, the feature 9236of the latter are available. 9237 9238This function will probably be replaced in the future by a version 9239which would enable specifying the arguments. The use of this macro is 9240not encouraged, as it violates strongly the typing system. 9241 9242This macro cannot be used for Erlang tests. 9243@end defmac 9244 9245@defmac AC_LANG_FUNC_LINK_TRY (@var{function}) 9246@acindex{LANG_FUNC_LINK_TRY} 9247Expands into a source file which uses the @var{function} in the body of 9248the main function (e.g., @code{main} in C). Since it uses 9249@code{AC_LANG_PROGRAM}, the features of the latter are available. 9250 9251As @code{AC_LANG_CALL}, this macro is documented only for completeness. 9252It is considered to be severely broken, and in the future will be 9253removed in favor of actual function calls (with properly typed 9254arguments). 9255 9256This macro cannot be used for Erlang tests. 9257@end defmac 9258 9259@node Running the Preprocessor 9260@section Running the Preprocessor 9261 9262Sometimes one might need to run the preprocessor on some source file. 9263@emph{Usually it is a bad idea}, as you typically need to @emph{compile} 9264your project, not merely run the preprocessor on it; therefore you 9265certainly want to run the compiler, not the preprocessor. Resist the 9266temptation of following the easiest path. 9267 9268Nevertheless, if you need to run the preprocessor, then use 9269@code{AC_PREPROC_IFELSE}. 9270 9271The macros described in this section cannot be used for tests in Erlang, 9272Fortran, or Go, since those languages require no preprocessor. 9273 9274@anchor{AC_PREPROC_IFELSE} 9275@defmac AC_PREPROC_IFELSE (@var{input}, @ovar{action-if-true}, @ 9276 @ovar{action-if-false}) 9277@acindex{PREPROC_IFELSE} 9278Run the preprocessor of the current language (@pxref{Language Choice}) 9279on the @var{input}, run the shell commands @var{action-if-true} on 9280success, @var{action-if-false} otherwise. The @var{input} can be made 9281by @code{AC_LANG_PROGRAM} and friends. 9282 9283This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because 9284@option{-g}, @option{-O}, etc.@: are not valid options to many C 9285preprocessors. 9286 9287It is customary to report unexpected failures with 9288@code{AC_MSG_FAILURE}. If needed, @var{action-if-true} can further access 9289the preprocessed output in the file @file{conftest.i}. 9290@end defmac 9291 9292For instance: 9293 9294@example 9295AC_INIT([Hello], [1.0], [bug-hello@@example.org]) 9296AC_DEFINE([HELLO_WORLD], ["Hello, World\n"], 9297 [Greetings string.]) 9298AC_PREPROC_IFELSE( 9299 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]], 9300 [[fputs (hw, stdout);]])], 9301 [AC_MSG_RESULT([OK])], 9302 [AC_MSG_FAILURE([unexpected preprocessor failure])]) 9303@end example 9304 9305@noindent 9306results in: 9307 9308@example 9309checking for gcc... gcc 9310checking for C compiler default output file name... a.out 9311checking whether the C compiler works... yes 9312checking whether we are cross compiling... no 9313checking for suffix of executables... 9314checking for suffix of object files... o 9315checking whether we are using the GNU C compiler... yes 9316checking whether gcc accepts -g... yes 9317checking for gcc option to accept ISO C89... none needed 9318checking how to run the C preprocessor... gcc -E 9319OK 9320@end example 9321 9322@sp 1 9323 9324The macro @code{AC_TRY_CPP} (@pxref{Obsolete Macros}) used to play the 9325role of @code{AC_PREPROC_IFELSE}, but double quotes its argument, making 9326it impossible to use it to elaborate sources. You are encouraged to 9327get rid of your old use of the macro @code{AC_TRY_CPP} in favor of 9328@code{AC_PREPROC_IFELSE}, but, in the first place, are you sure you need 9329to run the @emph{preprocessor} and not the compiler? 9330 9331@anchor{AC_EGREP_HEADER} 9332@defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @ 9333 @var{action-if-found}, @ovar{action-if-not-found}) 9334@acindex{EGREP_HEADER} 9335If the output of running the preprocessor on the system header file 9336@var{header-file} matches the extended regular expression 9337@var{pattern}, execute shell commands @var{action-if-found}, otherwise 9338execute @var{action-if-not-found}. 9339@end defmac 9340 9341@anchor{AC_EGREP_CPP} 9342@defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @ 9343 @ovar{action-if-found}, @ovar{action-if-not-found}) 9344@acindex{EGREP_CPP} 9345@var{program} is the text of a C or C++ program, on which shell 9346variable, back quote, and backslash substitutions are performed. If the 9347output of running the preprocessor on @var{program} matches the 9348extended regular expression @var{pattern}, execute shell commands 9349@var{action-if-found}, otherwise execute @var{action-if-not-found}. 9350@end defmac 9351 9352 9353 9354@node Running the Compiler 9355@section Running the Compiler 9356 9357To check for a syntax feature of the current language's (@pxref{Language 9358Choice}) compiler, such as whether it recognizes a certain keyword, or 9359simply to try some library feature, use @code{AC_COMPILE_IFELSE} to try 9360to compile a small program that uses that feature. 9361 9362@defmac AC_COMPILE_IFELSE (@var{input}, @ovar{action-if-true}, @ 9363 @ovar{action-if-false}) 9364@acindex{COMPILE_IFELSE} 9365Run the compiler and compilation flags of the current language 9366(@pxref{Language Choice}) on the @var{input}, run the shell commands 9367@var{action-if-true} on success, @var{action-if-false} otherwise. The 9368@var{input} can be made by @code{AC_LANG_PROGRAM} and friends. 9369 9370It is customary to report unexpected failures with 9371@code{AC_MSG_FAILURE}. This macro does not try to link; use 9372@code{AC_LINK_IFELSE} if you need to do that (@pxref{Running the 9373Linker}). If needed, @var{action-if-true} can further access the 9374just-compiled object file @file{conftest.$OBJEXT}. 9375 9376This macro uses @code{AC_REQUIRE} for the compiler associated with the 9377current language, which means that if the compiler has not yet been 9378determined, the compiler determination will be made prior to the body of 9379the outermost @code{AC_DEFUN} macro that triggered this macro to 9380expand (@pxref{Expanded Before Required}). 9381@end defmac 9382 9383@ovindex ERL 9384For tests in Erlang, the @var{input} must be the source code of a module named 9385@code{conftest}. @code{AC_COMPILE_IFELSE} generates a @file{conftest.beam} 9386file that can be interpreted by the Erlang virtual machine (@code{ERL}). It is 9387recommended to use @code{AC_LANG_PROGRAM} to specify the test program, 9388to ensure that the Erlang module has the right name. 9389 9390@node Running the Linker 9391@section Running the Linker 9392 9393To check for a library, a function, or a global variable, Autoconf 9394@command{configure} scripts try to compile and link a small program that 9395uses it. This is unlike Metaconfig, which by default uses @code{nm} or 9396@code{ar} on the C library to try to figure out which functions are 9397available. Trying to link with the function is usually a more reliable 9398approach because it avoids dealing with the variations in the options 9399and output formats of @code{nm} and @code{ar} and in the location of the 9400standard libraries. It also allows configuring for cross-compilation or 9401checking a function's runtime behavior if needed. On the other hand, 9402it can be slower than scanning the libraries once, but accuracy is more 9403important than speed. 9404 9405@code{AC_LINK_IFELSE} is used to compile test programs to test for 9406functions and global variables. It is also used by @code{AC_CHECK_LIB} 9407to check for libraries (@pxref{Libraries}), by adding the library being 9408checked for to @code{LIBS} temporarily and trying to link a small 9409program. 9410 9411@anchor{AC_LINK_IFELSE} 9412@defmac AC_LINK_IFELSE (@var{input}, @ovar{action-if-true}, @ 9413 @ovar{action-if-false}) 9414@acindex{LINK_IFELSE} 9415Run the compiler (and compilation flags) and the linker of the current 9416language (@pxref{Language Choice}) on the @var{input}, run the shell 9417commands @var{action-if-true} on success, @var{action-if-false} 9418otherwise. The @var{input} can be made by @code{AC_LANG_PROGRAM} and 9419friends. If needed, @var{action-if-true} can further access the 9420just-linked program file @file{conftest$EXEEXT}. 9421 9422@code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the 9423current compilation flags. 9424 9425It is customary to report unexpected failures with 9426@code{AC_MSG_FAILURE}. This macro does not try to execute the program; 9427use @code{AC_RUN_IFELSE} if you need to do that (@pxref{Runtime}). 9428@end defmac 9429 9430The @code{AC_LINK_IFELSE} macro cannot be used for Erlang tests, since Erlang 9431programs are interpreted and do not require linking. 9432 9433 9434 9435@node Runtime 9436@section Checking Runtime Behavior 9437 9438Sometimes you need to find out how a system performs at runtime, such 9439as whether a given function has a certain capability or bug. If you 9440can, make such checks when your program runs instead of when it is 9441configured. You can check for things like the machine's endianness when 9442your program initializes itself. 9443 9444If you really need to test for a runtime behavior while configuring, 9445you can write a test program to determine the result, and compile and 9446run it using @code{AC_RUN_IFELSE}. Avoid running test programs if 9447possible, because this prevents people from configuring your package for 9448cross-compiling. 9449 9450@anchor{AC_RUN_IFELSE} 9451@defmac AC_RUN_IFELSE (@var{input}, @ovar{action-if-true}, @ 9452 @ovar{action-if-false}, @dvar{action-if-cross-compiling, AC_MSG_FAILURE}) 9453@acindex{RUN_IFELSE} 9454Run the compiler (and compilation flags) and the linker of the current 9455language (@pxref{Language Choice}) on the @var{input}, then execute the 9456resulting program. If the program returns an exit 9457status of 0 when executed, run shell commands @var{action-if-true}. 9458Otherwise, run shell commands @var{action-if-false}. 9459 9460The @var{input} can be made by @code{AC_LANG_PROGRAM} and friends. 9461@code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the 9462compilation flags of the current language (@pxref{Language Choice}). 9463Additionally, @var{action-if-true} can run @command{./conftest$EXEEXT} 9464for further testing. 9465 9466In the @var{action-if-false} section, the failing exit status is 9467available in the shell variable @samp{$?}. This exit status might be 9468that of a failed compilation, or it might be that of a failed program 9469execution. 9470 9471If cross-compilation mode is enabled (this is the case if either the 9472compiler being used does not produce executables that run on the system 9473where @command{configure} is being run, or if the options @code{--build} 9474and @code{--host} were both specified and their values are different), 9475then the test program is 9476not run. If the optional shell commands @var{action-if-cross-compiling} 9477are given, those commands are run instead; typically these commands 9478provide pessimistic defaults that allow cross-compilation to work even 9479if the guess was wrong. If the fourth argument is empty or omitted, but 9480cross-compilation is detected, then @command{configure} prints an error 9481message and exits. If you want your package to be useful in a 9482cross-compilation scenario, you @emph{should} provide a non-empty 9483@var{action-if-cross-compiling} clause, as well as wrap the 9484@code{AC_RUN_IFELSE} compilation inside an @code{AC_CACHE_CHECK} 9485(@pxref{Caching Results}) which allows the user to override the 9486pessimistic default if needed. 9487 9488It is customary to report unexpected failures with 9489@code{AC_MSG_FAILURE}. 9490@end defmac 9491 9492@command{autoconf} prints a warning message when creating 9493@command{configure} each time it encounters a call to 9494@code{AC_RUN_IFELSE} with no @var{action-if-cross-compiling} argument 9495given. If you are not concerned about users configuring your package 9496for cross-compilation, you may ignore the warning. A few of the macros 9497distributed with Autoconf produce this warning message; but if this is a 9498problem for you, please report it as a bug, along with an appropriate 9499pessimistic guess to use instead. 9500 9501To configure for cross-compiling you can also choose a value for those 9502parameters based on the canonical system name (@pxref{Manual 9503Configuration}). Alternatively, set up a test results cache file with 9504the correct values for the host system (@pxref{Caching Results}). 9505 9506@ovindex cross_compiling 9507To provide a default for calls of @code{AC_RUN_IFELSE} that are embedded 9508in other macros, including a few of the ones that come with Autoconf, 9509you can test whether the shell variable @code{cross_compiling} is set to 9510@samp{yes}, and then use an alternate method to get the results instead 9511of calling the macros. 9512 9513It is also permissible to temporarily assign to @code{cross_compiling} 9514in order to force tests to behave as though they are in a 9515cross-compilation environment, particularly since this provides a way to 9516test your @var{action-if-cross-compiling} even when you are not using a 9517cross-compiler. 9518 9519@example 9520# We temporarily set cross-compile mode to force AC_COMPUTE_INT 9521# to use the slow link-only method 9522save_cross_compiling=$cross_compiling 9523cross_compiling=yes 9524AC_COMPUTE_INT([@dots{}]) 9525cross_compiling=$save_cross_compiling 9526@end example 9527 9528A C or C++ runtime test should be portable. 9529@xref{Portable C and C++}. 9530 9531Erlang tests must exit themselves the Erlang VM by calling the @code{halt/1} 9532function: the given status code is used to determine the success of the test 9533(status is @code{0}) or its failure (status is different than @code{0}), as 9534explained above. It must be noted that data output through the standard output 9535(e.g., using @code{io:format/2}) may be truncated when halting the VM. 9536Therefore, if a test must output configuration information, it is recommended 9537to create and to output data into the temporary file named @file{conftest.out}, 9538using the functions of module @code{file}. The @code{conftest.out} file is 9539automatically deleted by the @code{AC_RUN_IFELSE} macro. For instance, a 9540simplified implementation of Autoconf's @code{AC_ERLANG_SUBST_LIB_DIR} 9541macro is: 9542 9543@example 9544AC_INIT([LibdirTest], [1.0], [bug-libdirtest@@example.org]) 9545AC_ERLANG_NEED_ERL 9546AC_LANG(Erlang) 9547AC_RUN_IFELSE( 9548 [AC_LANG_PROGRAM([], [dnl 9549 file:write_file("conftest.out", code:lib_dir()), 9550 halt(0)])], 9551 [echo "code:lib_dir() returned: `cat conftest.out`"], 9552 [AC_MSG_FAILURE([test Erlang program execution failed])]) 9553@end example 9554 9555 9556@node Systemology 9557@section Systemology 9558@cindex Systemology 9559 9560This section aims at presenting some systems and pointers to 9561documentation. It may help you addressing particular problems reported 9562by users. 9563 9564@uref{http://@/www.opengroup.org/@/susv3, Posix-conforming systems} are 9565derived from the @uref{http://@/www.bell-labs.com/@/history/@/unix/, Unix 9566operating system}. 9567 9568The @uref{http://@/bhami.com/@/rosetta.html, Rosetta Stone for Unix} 9569contains a table correlating the features of various Posix-conforming 9570systems. @uref{http://@/www.levenez.com/@/unix/, Unix History} is a 9571simplified diagram of how many Unix systems were derived from each 9572other. 9573 9574@uref{http://@/heirloom.sourceforge.net/, The Heirloom Project} 9575provides some variants of traditional implementations of Unix utilities. 9576 9577@table @asis 9578@item Darwin 9579@cindex Darwin 9580Darwin is also known as Mac OS X@. Beware that the file system @emph{can} be 9581case-preserving, but case insensitive. This can cause nasty problems, 9582since for instance the installation attempt for a package having an 9583@file{INSTALL} file can result in @samp{make install} report that 9584nothing was to be done! 9585 9586That's all dependent on whether the file system is a UFS (case 9587sensitive) or HFS+ (case preserving). By default Apple wants you to 9588install the OS on HFS+. Unfortunately, there are some pieces of 9589software which really need to be built on UFS@. We may want to rebuild 9590Darwin to have both UFS and HFS+ available (and put the /local/build 9591tree on the UFS). 9592 9593@item QNX 4.25 9594@cindex QNX 4.25 9595@c FIXME: Please, if you feel like writing something more precise, 9596@c it'd be great. In particular, I can't understand the difference with 9597@c QNX Neutrino. 9598QNX is a realtime operating system running on Intel architecture 9599meant to be scalable from the small embedded systems to the hundred 9600processor super-computer. It claims to be Posix certified. More 9601information is available on the 9602@uref{http://@/www.qnx.com/, QNX home page}. 9603 9604@item Tru64 9605@cindex Tru64 9606@uref{http://@/h30097.www3.hp.com/@/docs/, 9607Documentation of several versions of Tru64} is available in different 9608formats. 9609 9610@item Unix version 7 9611@cindex Unix version 7 9612@cindex V7 9613Officially this was called the ``Seventh Edition'' of ``the UNIX 9614time-sharing system'' but we use the more-common name ``Unix version 7''. 9615Documentation is available in the 9616@uref{http://@/plan9.bell-labs.com/@/7thEdMan/, Unix Seventh Edition Manual}. 9617Previous versions of Unix are called ``Unix version 6'', etc., but 9618they were not as widely used. 9619@end table 9620 9621 9622@node Multiple Cases 9623@section Multiple Cases 9624 9625Some operations are accomplished in several possible ways, depending on 9626the OS variant. Checking for them essentially requires a ``case 9627statement''. Autoconf does not directly provide one; however, it is 9628easy to simulate by using a shell variable to keep track of whether a 9629way to perform the operation has been found yet. 9630 9631Here is an example that uses the shell variable @code{fstype} to keep 9632track of whether the remaining cases need to be checked. Note that 9633since the value of @code{fstype} is under our control, we don't have to 9634use the longer @samp{test "x$fstype" = xno}. 9635 9636@example 9637@group 9638AC_MSG_CHECKING([how to get file system type]) 9639fstype=no 9640# The order of these tests is important. 9641AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statvfs.h> 9642#include <sys/fstyp.h>]])], 9643 [AC_DEFINE([FSTYPE_STATVFS], [1], 9644 [Define if statvfs exists.]) 9645 fstype=SVR4]) 9646if test $fstype = no; then 9647 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h> 9648#include <sys/fstyp.h>]])], 9649 [AC_DEFINE([FSTYPE_USG_STATFS], [1], 9650 [Define if USG statfs.]) 9651 fstype=SVR3]) 9652fi 9653if test $fstype = no; then 9654 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h> 9655#include <sys/vmount.h>]])]), 9656 [AC_DEFINE([FSTYPE_AIX_STATFS], [1], 9657 [Define if AIX statfs.]) 9658 fstype=AIX]) 9659fi 9660# (more cases omitted here) 9661AC_MSG_RESULT([$fstype]) 9662@end group 9663@end example 9664 9665@c ====================================================== Results of Tests. 9666 9667@node Results 9668@chapter Results of Tests 9669 9670Once @command{configure} has determined whether a feature exists, what can 9671it do to record that information? There are four sorts of things it can 9672do: define a C preprocessor symbol, set a variable in the output files, 9673save the result in a cache file for future @command{configure} runs, and 9674print a message letting the user know the result of the test. 9675 9676@menu 9677* Defining Symbols:: Defining C preprocessor symbols 9678* Setting Output Variables:: Replacing variables in output files 9679* Special Chars in Variables:: Characters to beware of in variables 9680* Caching Results:: Speeding up subsequent @command{configure} runs 9681* Printing Messages:: Notifying @command{configure} users 9682@end menu 9683 9684@node Defining Symbols 9685@section Defining C Preprocessor Symbols 9686 9687A common action to take in response to a feature test is to define a C 9688preprocessor symbol indicating the results of the test. That is done by 9689calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}. 9690 9691By default, @code{AC_OUTPUT} places the symbols defined by these macros 9692into the output variable @code{DEFS}, which contains an option 9693@option{-D@var{symbol}=@var{value}} for each symbol defined. Unlike in 9694Autoconf version 1, there is no variable @code{DEFS} defined while 9695@command{configure} is running. To check whether Autoconf macros have 9696already defined a certain C preprocessor symbol, test the value of the 9697appropriate cache variable, as in this example: 9698 9699@example 9700AC_CHECK_FUNC([vprintf], [AC_DEFINE([HAVE_VPRINTF], [1], 9701 [Define if vprintf exists.])]) 9702if test "x$ac_cv_func_vprintf" != xyes; then 9703 AC_CHECK_FUNC([_doprnt], [AC_DEFINE([HAVE_DOPRNT], [1], 9704 [Define if _doprnt exists.])]) 9705fi 9706@end example 9707 9708If @code{AC_CONFIG_HEADERS} has been called, then instead of creating 9709@code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the 9710correct values into @code{#define} statements in a template file. 9711@xref{Configuration Headers}, for more information about this kind of 9712output. 9713 9714@defmac AC_DEFINE (@var{variable}, @var{value}, @ovar{description}) 9715@defmacx AC_DEFINE (@var{variable}) 9716@cvindex @var{variable} 9717@acindex{DEFINE} 9718Define @var{variable} to @var{value} (verbatim), by defining a C 9719preprocessor macro for @var{variable}. @var{variable} should be a C 9720identifier, optionally suffixed by a parenthesized argument list to 9721define a C preprocessor macro with arguments. The macro argument list, 9722if present, should be a comma-separated list of C identifiers, possibly 9723terminated by an ellipsis @samp{...} if C99 syntax is employed. 9724@var{variable} should not contain comments, white space, trigraphs, 9725backslash-newlines, universal character names, or non-ASCII 9726characters. 9727 9728@var{value} may contain backslash-escaped newlines, which will be 9729preserved if you use @code{AC_CONFIG_HEADERS} but flattened if passed 9730via @code{@@DEFS@@} (with no effect on the compilation, since the 9731preprocessor sees only one line in the first place). @var{value} should 9732not contain raw newlines. If you are not using 9733@code{AC_CONFIG_HEADERS}, @var{value} should not contain any @samp{#} 9734characters, as @command{make} tends to eat them. To use a shell 9735variable, use @code{AC_DEFINE_UNQUOTED} instead. 9736 9737@var{description} is only useful if you are using 9738@code{AC_CONFIG_HEADERS}. In this case, @var{description} is put into 9739the generated @file{config.h.in} as the comment before the macro define. 9740The following example defines the C preprocessor variable 9741@code{EQUATION} to be the string constant @samp{"$a > $b"}: 9742 9743@example 9744AC_DEFINE([EQUATION], ["$a > $b"], 9745 [Equation string.]) 9746@end example 9747 9748If neither @var{value} nor @var{description} are given, then 9749@var{value} defaults to 1 instead of to the empty string. This is for 9750backwards compatibility with older versions of Autoconf, but this usage 9751is obsolescent and may be withdrawn in future versions of Autoconf. 9752 9753If the @var{variable} is a literal string, it is passed to 9754@code{m4_pattern_allow} (@pxref{Forbidden Patterns}). 9755 9756If multiple @code{AC_DEFINE} statements are executed for the same 9757@var{variable} name (not counting any parenthesized argument list), 9758the last one wins. 9759@end defmac 9760 9761@defmac AC_DEFINE_UNQUOTED (@var{variable}, @var{value}, @ovar{description}) 9762@defmacx AC_DEFINE_UNQUOTED (@var{variable}) 9763@acindex{DEFINE_UNQUOTED} 9764@cvindex @var{variable} 9765Like @code{AC_DEFINE}, but three shell expansions are 9766performed---once---on @var{variable} and @var{value}: variable expansion 9767(@samp{$}), command substitution (@samp{`}), and backslash escaping 9768(@samp{\}), as if in an unquoted here-document. Single and double quote 9769characters in the value have no 9770special meaning. Use this macro instead of @code{AC_DEFINE} when 9771@var{variable} or @var{value} is a shell variable. Examples: 9772 9773@example 9774AC_DEFINE_UNQUOTED([config_machfile], ["$machfile"], 9775 [Configuration machine file.]) 9776AC_DEFINE_UNQUOTED([GETGROUPS_T], [$ac_cv_type_getgroups], 9777 [getgroups return type.]) 9778AC_DEFINE_UNQUOTED([$ac_tr_hdr], [1], 9779 [Translated header name.]) 9780@end example 9781@end defmac 9782 9783Due to a syntactical bizarreness of the Bourne shell, do not use 9784semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED} 9785calls from other macro calls or shell code; that can cause syntax errors 9786in the resulting @command{configure} script. Use either blanks or 9787newlines. That is, do this: 9788 9789@example 9790AC_CHECK_HEADER([elf.h], 9791 [AC_DEFINE([SVR4], [1], [System V Release 4]) LIBS="-lelf $LIBS"]) 9792@end example 9793 9794@noindent 9795or this: 9796 9797@example 9798AC_CHECK_HEADER([elf.h], 9799 [AC_DEFINE([SVR4], [1], [System V Release 4]) 9800 LIBS="-lelf $LIBS"]) 9801@end example 9802 9803@noindent 9804instead of this: 9805 9806@example 9807AC_CHECK_HEADER([elf.h], 9808 [AC_DEFINE([SVR4], [1], [System V Release 4]); LIBS="-lelf $LIBS"]) 9809@end example 9810 9811@node Setting Output Variables 9812@section Setting Output Variables 9813@cindex Output variables 9814 9815Another way to record the results of tests is to set @dfn{output 9816variables}, which are shell variables whose values are substituted into 9817files that @command{configure} outputs. The two macros below create new 9818output variables. @xref{Preset Output Variables}, for a list of output 9819variables that are always available. 9820 9821@defmac AC_SUBST (@var{variable}, @ovar{value}) 9822@acindex{SUBST} 9823Create an output variable from a shell variable. Make @code{AC_OUTPUT} 9824substitute the variable @var{variable} into output files (typically one 9825or more makefiles). This means that @code{AC_OUTPUT} 9826replaces instances of @samp{@@@var{variable}@@} in input files with the 9827value that the shell variable @var{variable} has when @code{AC_OUTPUT} 9828is called. The value can contain any non-@code{NUL} character, including 9829newline. If you are using Automake 1.11 or newer, for newlines in values 9830you might want to consider using @code{AM_SUBST_NOTMAKE} to prevent 9831@command{automake} from adding a line @code{@var{variable} = 9832@@@var{variable}@@} to the @file{Makefile.in} files (@pxref{Optional, , 9833Automake, automake, Other things Automake recognizes}). 9834 9835Variable occurrences should not overlap: e.g., an input file should 9836not contain @samp{@@@var{var1}@@@var{var2}@@} if @var{var1} and @var{var2} 9837are variable names. 9838The substituted value is not rescanned for more output variables; 9839occurrences of @samp{@@@var{variable}@@} in the value are inserted 9840literally into the output file. (The algorithm uses the special marker 9841@code{|#_!!_#|} internally, so neither the substituted value nor the 9842output file may contain @code{|#_!!_#|}.) 9843 9844If @var{value} is given, in addition assign it to @var{variable}. 9845 9846The string @var{variable} is passed to @code{m4_pattern_allow} 9847(@pxref{Forbidden Patterns}). 9848@end defmac 9849 9850@defmac AC_SUBST_FILE (@var{variable}) 9851@acindex{SUBST_FILE} 9852Another way to create an output variable from a shell variable. Make 9853@code{AC_OUTPUT} insert (without substitutions) the contents of the file 9854named by shell variable @var{variable} into output files. This means 9855that @code{AC_OUTPUT} replaces instances of 9856@samp{@@@var{variable}@@} in output files (such as @file{Makefile.in}) 9857with the contents of the file that the shell variable @var{variable} 9858names when @code{AC_OUTPUT} is called. Set the variable to 9859@file{/dev/null} for cases that do not have a file to insert. 9860This substitution occurs only when the @samp{@@@var{variable}@@} is on a 9861line by itself, optionally surrounded by spaces and tabs. The 9862substitution replaces the whole line, including the spaces, tabs, and 9863the terminating newline. 9864 9865This macro is useful for inserting makefile fragments containing 9866special dependencies or other @command{make} directives for particular host 9867or target types into makefiles. For example, @file{configure.ac} 9868could contain: 9869 9870@example 9871AC_SUBST_FILE([host_frag]) 9872host_frag=$srcdir/conf/sun4.mh 9873@end example 9874 9875@noindent 9876and then a @file{Makefile.in} could contain: 9877 9878@example 9879@@host_frag@@ 9880@end example 9881 9882The string @var{variable} is passed to @code{m4_pattern_allow} 9883(@pxref{Forbidden Patterns}). 9884@end defmac 9885 9886@cindex Precious Variable 9887@cindex Variable, Precious 9888Running @command{configure} in varying environments can be extremely 9889dangerous. If for instance the user runs @samp{CC=bizarre-cc 9890./configure}, then the cache, @file{config.h}, and many other output 9891files depend upon @command{bizarre-cc} being the C compiler. If 9892for some reason the user runs @command{./configure} again, or if it is 9893run via @samp{./config.status --recheck}, (@xref{Automatic Remaking}, 9894and @pxref{config.status Invocation}), then the configuration can be 9895inconsistent, composed of results depending upon two different 9896compilers. 9897 9898Environment variables that affect this situation, such as @samp{CC} 9899above, are called @dfn{precious variables}, and can be declared as such 9900by @code{AC_ARG_VAR}. 9901 9902@defmac AC_ARG_VAR (@var{variable}, @var{description}) 9903@acindex{ARG_VAR} 9904Declare @var{variable} is a precious variable, and include its 9905@var{description} in the variable section of @samp{./configure --help}. 9906 9907Being precious means that 9908@itemize @minus 9909@item 9910@var{variable} is substituted via @code{AC_SUBST}. 9911 9912@item 9913The value of @var{variable} when @command{configure} was launched is 9914saved in the cache, including if it was not specified on the command 9915line but via the environment. Indeed, while @command{configure} can 9916notice the definition of @code{CC} in @samp{./configure CC=bizarre-cc}, 9917it is impossible to notice it in @samp{CC=bizarre-cc ./configure}, 9918which, unfortunately, is what most users do. 9919 9920We emphasize that it is the @emph{initial} value of @var{variable} which 9921is saved, not that found during the execution of @command{configure}. 9922Indeed, specifying @samp{./configure FOO=foo} and letting 9923@samp{./configure} guess that @code{FOO} is @code{foo} can be two 9924different things. 9925 9926@item 9927@var{variable} is checked for consistency between two 9928@command{configure} runs. For instance: 9929 9930@example 9931$ @kbd{./configure --silent --config-cache} 9932$ @kbd{CC=cc ./configure --silent --config-cache} 9933configure: error: `CC' was not set in the previous run 9934configure: error: changes in the environment can compromise \ 9935the build 9936configure: error: run `make distclean' and/or \ 9937`rm config.cache' and start over 9938@end example 9939 9940@noindent 9941and similarly if the variable is unset, or if its content is changed. 9942If the content has white space changes only, then the error is degraded 9943to a warning only, but the old value is reused. 9944 9945@item 9946@var{variable} is kept during automatic reconfiguration 9947(@pxref{config.status Invocation}) as if it had been passed as a command 9948line argument, including when no cache is used: 9949 9950@example 9951$ @kbd{CC=/usr/bin/cc ./configure var=raboof --silent} 9952$ @kbd{./config.status --recheck} 9953running CONFIG_SHELL=/bin/sh /bin/sh ./configure var=raboof \ 9954 CC=/usr/bin/cc --no-create --no-recursion 9955@end example 9956@end itemize 9957@end defmac 9958 9959@node Special Chars in Variables 9960@section Special Characters in Output Variables 9961@cindex Output variables, special characters in 9962 9963Many output variables are intended to be evaluated both by 9964@command{make} and by the shell. Some characters are expanded 9965differently in these two contexts, so to avoid confusion these 9966variables' values should not contain any of the following characters: 9967 9968@example 9969" # $ & ' ( ) * ; < > ? [ \ ^ ` | 9970@end example 9971 9972Also, these variables' values should neither contain newlines, nor start 9973with @samp{~}, nor contain white space or @samp{:} immediately followed 9974by @samp{~}. The values can contain nonempty sequences of white space 9975characters like tabs and spaces, but each such sequence might 9976arbitrarily be replaced by a single space during substitution. 9977 9978These restrictions apply both to the values that @command{configure} 9979computes, and to the values set directly by the user. For example, the 9980following invocations of @command{configure} are problematic, since they 9981attempt to use special characters within @code{CPPFLAGS} and white space 9982within @code{$(srcdir)}: 9983 9984@example 9985CPPFLAGS='-DOUCH="&\"#$*?"' '../My Source/ouch-1.0/configure' 9986 9987'../My Source/ouch-1.0/configure' CPPFLAGS='-DOUCH="&\"#$*?"' 9988@end example 9989 9990@node Caching Results 9991@section Caching Results 9992@cindex Cache 9993 9994To avoid checking for the same features repeatedly in various 9995@command{configure} scripts (or in repeated runs of one script), 9996@command{configure} can optionally save the results of many checks in a 9997@dfn{cache file} (@pxref{Cache Files}). If a @command{configure} script 9998runs with caching enabled and finds a cache file, it reads the results 9999of previous runs from the cache and avoids rerunning those checks. As a 10000result, @command{configure} can then run much faster than if it had to 10001perform all of the checks every time. 10002 10003@defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it}) 10004@acindex{CACHE_VAL} 10005Ensure that the results of the check identified by @var{cache-id} are 10006available. If the results of the check were in the cache file that was 10007read, and @command{configure} was not given the @option{--quiet} or 10008@option{--silent} option, print a message saying that the result was 10009cached; otherwise, run the shell commands @var{commands-to-set-it}. If 10010the shell commands are run to determine the value, the value is 10011saved in the cache file just before @command{configure} creates its output 10012files. @xref{Cache Variable Names}, for how to choose the name of the 10013@var{cache-id} variable. 10014 10015The @var{commands-to-set-it} @emph{must have no side effects} except for 10016setting the variable @var{cache-id}, see below. 10017@end defmac 10018 10019@defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @ 10020 @var{commands-to-set-it}) 10021@acindex{CACHE_CHECK} 10022A wrapper for @code{AC_CACHE_VAL} that takes care of printing the 10023messages. This macro provides a convenient shorthand for the most 10024common way to use these macros. It calls @code{AC_MSG_CHECKING} for 10025@var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and 10026@var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}. 10027 10028The @var{commands-to-set-it} @emph{must have no side effects} except for 10029setting the variable @var{cache-id}, see below. 10030@end defmac 10031 10032It is common to find buggy macros using @code{AC_CACHE_VAL} or 10033@code{AC_CACHE_CHECK}, because people are tempted to call 10034@code{AC_DEFINE} in the @var{commands-to-set-it}. Instead, the code that 10035@emph{follows} the call to @code{AC_CACHE_VAL} should call 10036@code{AC_DEFINE}, by examining the value of the cache variable. For 10037instance, the following macro is broken: 10038 10039@example 10040@c If you change this example, adjust tests/base.at:AC_CACHE_CHECK. 10041@group 10042AC_DEFUN([AC_SHELL_TRUE], 10043[AC_CACHE_CHECK([whether true(1) works], [my_cv_shell_true_works], 10044 [my_cv_shell_true_works=no 10045 (true) 2>/dev/null && my_cv_shell_true_works=yes 10046 if test "x$my_cv_shell_true_works" = xyes; then 10047 AC_DEFINE([TRUE_WORKS], [1], 10048 [Define if `true(1)' works properly.]) 10049 fi]) 10050]) 10051@end group 10052@end example 10053 10054@noindent 10055This fails if the cache is enabled: the second time this macro is run, 10056@code{TRUE_WORKS} @emph{will not be defined}. The proper implementation 10057is: 10058 10059@example 10060@c If you change this example, adjust tests/base.at:AC_CACHE_CHECK. 10061@group 10062AC_DEFUN([AC_SHELL_TRUE], 10063[AC_CACHE_CHECK([whether true(1) works], [my_cv_shell_true_works], 10064 [my_cv_shell_true_works=no 10065 (true) 2>/dev/null && my_cv_shell_true_works=yes]) 10066 if test "x$my_cv_shell_true_works" = xyes; then 10067 AC_DEFINE([TRUE_WORKS], [1], 10068 [Define if `true(1)' works properly.]) 10069 fi 10070]) 10071@end group 10072@end example 10073 10074Also, @var{commands-to-set-it} should not print any messages, for 10075example with @code{AC_MSG_CHECKING}; do that before calling 10076@code{AC_CACHE_VAL}, so the messages are printed regardless of whether 10077the results of the check are retrieved from the cache or determined by 10078running the shell commands. 10079 10080@menu 10081* Cache Variable Names:: Shell variables used in caches 10082* Cache Files:: Files @command{configure} uses for caching 10083* Cache Checkpointing:: Loading and saving the cache file 10084@end menu 10085 10086@node Cache Variable Names 10087@subsection Cache Variable Names 10088@cindex Cache variable 10089 10090The names of cache variables should have the following format: 10091 10092@example 10093@var{package-prefix}_cv_@var{value-type}_@var{specific-value}_@ovar{additional-options} 10094@end example 10095 10096@noindent 10097for example, @samp{ac_cv_header_stat_broken} or 10098@samp{ac_cv_prog_gcc_traditional}. The parts of the variable name are: 10099 10100@table @asis 10101@item @var{package-prefix} 10102An abbreviation for your package or organization; the same prefix you 10103begin local Autoconf macros with, except lowercase by convention. 10104For cache values used by the distributed Autoconf macros, this value is 10105@samp{ac}. 10106 10107@item @code{_cv_} 10108Indicates that this shell variable is a cache value. This string 10109@emph{must} be present in the variable name, including the leading 10110underscore. 10111 10112@item @var{value-type} 10113A convention for classifying cache values, to produce a rational naming 10114system. The values used in Autoconf are listed in @ref{Macro Names}. 10115 10116@item @var{specific-value} 10117Which member of the class of cache values this test applies to. 10118For example, which function (@samp{alloca}), program (@samp{gcc}), or 10119output variable (@samp{INSTALL}). 10120 10121@item @var{additional-options} 10122Any particular behavior of the specific member that this test applies to. 10123For example, @samp{broken} or @samp{set}. This part of the name may 10124be omitted if it does not apply. 10125@end table 10126 10127The values assigned to cache variables may not contain newlines. 10128Usually, their values are Boolean (@samp{yes} or @samp{no}) or the 10129names of files or functions; so this is not an important restriction. 10130@ref{Cache Variable Index} for an index of cache variables with 10131documented semantics. 10132 10133 10134@node Cache Files 10135@subsection Cache Files 10136 10137A cache file is a shell script that caches the results of configure 10138tests run on one system so they can be shared between configure scripts 10139and configure runs. It is not useful on other systems. If its contents 10140are invalid for some reason, the user may delete or edit it, or override 10141documented cache variables on the @command{configure} command line. 10142 10143By default, @command{configure} uses no cache file, 10144to avoid problems caused by accidental 10145use of stale cache files. 10146 10147To enable caching, @command{configure} accepts @option{--config-cache} (or 10148@option{-C}) to cache results in the file @file{config.cache}. 10149Alternatively, @option{--cache-file=@var{file}} specifies that 10150@var{file} be the cache file. The cache file is created if it does not 10151exist already. When @command{configure} calls @command{configure} scripts in 10152subdirectories, it uses the @option{--cache-file} argument so that they 10153share the same cache. @xref{Subdirectories}, for information on 10154configuring subdirectories with the @code{AC_CONFIG_SUBDIRS} macro. 10155 10156@file{config.status} only pays attention to the cache file if it is 10157given the @option{--recheck} option, which makes it rerun 10158@command{configure}. 10159 10160It is wrong to try to distribute cache files for particular system types. 10161There is too much room for error in doing that, and too much 10162administrative overhead in maintaining them. For any features that 10163can't be guessed automatically, use the standard method of the canonical 10164system type and linking files (@pxref{Manual Configuration}). 10165 10166The site initialization script can specify a site-wide cache file to 10167use, instead of the usual per-program cache. In this case, the cache 10168file gradually accumulates information whenever someone runs a new 10169@command{configure} script. (Running @command{configure} merges the new cache 10170results with the existing cache file.) This may cause problems, 10171however, if the system configuration (e.g., the installed libraries or 10172compilers) changes and the stale cache file is not deleted. 10173 10174If @command{configure} is interrupted at the right time when it updates 10175a cache file outside of the build directory where the @command{configure} 10176script is run, it may leave behind a temporary file named after the 10177cache file with digits following it. You may safely delete such a file. 10178 10179 10180@node Cache Checkpointing 10181@subsection Cache Checkpointing 10182 10183If your configure script, or a macro called from @file{configure.ac}, happens 10184to abort the configure process, it may be useful to checkpoint the cache 10185a few times at key points using @code{AC_CACHE_SAVE}. Doing so 10186reduces the amount of time it takes to rerun the configure script with 10187(hopefully) the error that caused the previous abort corrected. 10188 10189@c FIXME: Do we really want to document this guy? 10190@defmac AC_CACHE_LOAD 10191@acindex{CACHE_LOAD} 10192Loads values from existing cache file, or creates a new cache file if a 10193cache file is not found. Called automatically from @code{AC_INIT}. 10194@end defmac 10195 10196@defmac AC_CACHE_SAVE 10197@acindex{CACHE_SAVE} 10198Flushes all cached values to the cache file. Called automatically from 10199@code{AC_OUTPUT}, but it can be quite useful to call 10200@code{AC_CACHE_SAVE} at key points in @file{configure.ac}. 10201@end defmac 10202 10203For instance: 10204 10205@example 10206@r{ @dots{} AC_INIT, etc. @dots{}} 10207@group 10208# Checks for programs. 10209AC_PROG_CC 10210AC_PROG_AWK 10211@r{ @dots{} more program checks @dots{}} 10212AC_CACHE_SAVE 10213@end group 10214 10215@group 10216# Checks for libraries. 10217AC_CHECK_LIB([nsl], [gethostbyname]) 10218AC_CHECK_LIB([socket], [connect]) 10219@r{ @dots{} more lib checks @dots{}} 10220AC_CACHE_SAVE 10221@end group 10222 10223@group 10224# Might abort@dots{} 10225AM_PATH_GTK([1.0.2], [], [AC_MSG_ERROR([GTK not in path])]) 10226AM_PATH_GTKMM([0.9.5], [], [AC_MSG_ERROR([GTK not in path])]) 10227@end group 10228@r{ @dots{} AC_OUTPUT, etc. @dots{}} 10229@end example 10230 10231@node Printing Messages 10232@section Printing Messages 10233@cindex Messages, from @command{configure} 10234 10235@command{configure} scripts need to give users running them several kinds 10236of information. The following macros print messages in ways appropriate 10237for each kind. The arguments to all of them get enclosed in shell 10238double quotes, so the shell performs variable and back-quote 10239substitution on them. 10240 10241These macros are all wrappers around the @command{echo} shell command. 10242They direct output to the appropriate file descriptor (@pxref{File 10243Descriptor Macros}). 10244@command{configure} scripts should rarely need to run @command{echo} directly 10245to print messages for the user. Using these macros makes it easy to 10246change how and when each kind of message is printed; such changes need 10247only be made to the macro definitions and all the callers change 10248automatically. 10249 10250To diagnose static issues, i.e., when @command{autoconf} is run, see 10251@ref{Diagnostic Macros}. 10252 10253@defmac AC_MSG_CHECKING (@var{feature-description}) 10254@acindex{MSG_CHECKING} 10255Notify the user that @command{configure} is checking for a particular 10256feature. This macro prints a message that starts with @samp{checking } 10257and ends with @samp{...} and no newline. It must be followed by a call 10258to @code{AC_MSG_RESULT} to print the result of the check and the 10259newline. The @var{feature-description} should be something like 10260@samp{whether the Fortran compiler accepts C++ comments} or @samp{for 10261c89}. 10262 10263This macro prints nothing if @command{configure} is run with the 10264@option{--quiet} or @option{--silent} option. 10265@end defmac 10266 10267@anchor{AC_MSG_RESULT} 10268@defmac AC_MSG_RESULT (@var{result-description}) 10269@acindex{MSG_RESULT} 10270Notify the user of the results of a check. @var{result-description} is 10271almost always the value of the cache variable for the check, typically 10272@samp{yes}, @samp{no}, or a file name. This macro should follow a call 10273to @code{AC_MSG_CHECKING}, and the @var{result-description} should be 10274the completion of the message printed by the call to 10275@code{AC_MSG_CHECKING}. 10276 10277This macro prints nothing if @command{configure} is run with the 10278@option{--quiet} or @option{--silent} option. 10279@end defmac 10280 10281@anchor{AC_MSG_NOTICE} 10282@defmac AC_MSG_NOTICE (@var{message}) 10283@acindex{MSG_NOTICE} 10284Deliver the @var{message} to the user. It is useful mainly to print a 10285general description of the overall purpose of a group of feature checks, 10286e.g., 10287 10288@example 10289AC_MSG_NOTICE([checking if stack overflow is detectable]) 10290@end example 10291 10292This macro prints nothing if @command{configure} is run with the 10293@option{--quiet} or @option{--silent} option. 10294@end defmac 10295 10296@anchor{AC_MSG_ERROR} 10297@defmac AC_MSG_ERROR (@var{error-description}, @dvar{exit-status, $?/1}) 10298@acindex{MSG_ERROR} 10299Notify the user of an error that prevents @command{configure} from 10300completing. This macro prints an error message to the standard error 10301output and exits @command{configure} with @var{exit-status} (@samp{$?} 10302by default, except that @samp{0} is converted to @samp{1}). 10303@var{error-description} should be something like @samp{invalid value 10304$HOME for \$HOME}. 10305 10306The @var{error-description} should start with a lower-case letter, and 10307``cannot'' is preferred to ``can't''. 10308@end defmac 10309 10310@defmac AC_MSG_FAILURE (@var{error-description}, @ovar{exit-status}) 10311@acindex{MSG_FAILURE} 10312This @code{AC_MSG_ERROR} wrapper notifies the user of an error that 10313prevents @command{configure} from completing @emph{and} that additional 10314details are provided in @file{config.log}. This is typically used when 10315abnormal results are found during a compilation. 10316@end defmac 10317 10318@anchor{AC_MSG_WARN} 10319@defmac AC_MSG_WARN (@var{problem-description}) 10320@acindex{MSG_WARN} 10321Notify the @command{configure} user of a possible problem. This macro 10322prints the message to the standard error output; @command{configure} 10323continues running afterward, so macros that call @code{AC_MSG_WARN} should 10324provide a default (back-up) behavior for the situations they warn about. 10325@var{problem-description} should be something like @samp{ln -s seems to 10326make hard links}. 10327@end defmac 10328 10329 10330 10331@c ====================================================== Programming in M4. 10332 10333@node Programming in M4 10334@chapter Programming in M4 10335@cindex M4 10336 10337Autoconf is written on top of two layers: @dfn{M4sugar}, which provides 10338convenient macros for pure M4 programming, and @dfn{M4sh}, which 10339provides macros dedicated to shell script generation. 10340 10341As of this version of Autoconf, these two layers still contain 10342experimental macros, whose interface might change in the future. As a 10343matter of fact, @emph{anything that is not documented must not be used}. 10344 10345@menu 10346* M4 Quotation:: Protecting macros from unwanted expansion 10347* Using autom4te:: The Autoconf executables backbone 10348* Programming in M4sugar:: Convenient pure M4 macros 10349* Debugging via autom4te:: Figuring out what M4 was doing 10350@end menu 10351 10352@node M4 Quotation 10353@section M4 Quotation 10354@cindex M4 quotation 10355@cindex quotation 10356 10357The most common problem with existing macros is an improper quotation. 10358This section, which users of Autoconf can skip, but which macro writers 10359@emph{must} read, first justifies the quotation scheme that was chosen 10360for Autoconf and then ends with a rule of thumb. Understanding the 10361former helps one to follow the latter. 10362 10363@menu 10364* Active Characters:: Characters that change the behavior of M4 10365* One Macro Call:: Quotation and one macro call 10366* Quoting and Parameters:: M4 vs. shell parameters 10367* Quotation and Nested Macros:: Macros calling macros 10368* Changequote is Evil:: Worse than INTERCAL: M4 + changequote 10369* Quadrigraphs:: Another way to escape special characters 10370* Balancing Parentheses:: Dealing with unbalanced parentheses 10371* Quotation Rule Of Thumb:: One parenthesis, one quote 10372@end menu 10373 10374@node Active Characters 10375@subsection Active Characters 10376 10377To fully understand where proper quotation is important, you first need 10378to know what the special characters are in Autoconf: @samp{#} introduces 10379a comment inside which no macro expansion is performed, @samp{,} 10380separates arguments, @samp{[} and @samp{]} are the quotes 10381themselves@footnote{By itself, M4 uses @samp{`} and @samp{'}; it is the 10382M4sugar layer that sets up the preferred quotes of @samp{[} and @samp{]}.}, 10383@samp{(} and @samp{)} (which M4 tries to match by pairs), and finally 10384@samp{$} inside a macro definition. 10385 10386In order to understand the delicate case of macro calls, we first have 10387to present some obvious failures. Below they are ``obvious-ified'', 10388but when you find them in real life, they are usually in disguise. 10389 10390Comments, introduced by a hash and running up to the newline, are opaque 10391tokens to the top level: active characters are turned off, and there is 10392no macro expansion: 10393 10394@example 10395# define([def], ine) 10396@result{}# define([def], ine) 10397@end example 10398 10399Each time there can be a macro expansion, there is a quotation 10400expansion, i.e., one level of quotes is stripped: 10401 10402@example 10403int tab[10]; 10404@result{}int tab10; 10405[int tab[10];] 10406@result{}int tab[10]; 10407@end example 10408 10409Without this in mind, the reader might try hopelessly to use her macro 10410@code{array}: 10411 10412@example 10413define([array], [int tab[10];]) 10414array 10415@result{}int tab10; 10416[array] 10417@result{}array 10418@end example 10419 10420@noindent 10421How can you correctly output the intended results@footnote{Using 10422@code{defn}.}? 10423 10424 10425@node One Macro Call 10426@subsection One Macro Call 10427 10428Let's proceed on the interaction between active characters and macros 10429with this small macro, which just returns its first argument: 10430 10431@example 10432define([car], [$1]) 10433@end example 10434 10435@noindent 10436The two pairs of quotes above are not part of the arguments of 10437@code{define}; rather, they are understood by the top level when it 10438tries to find the arguments of @code{define}. Therefore, assuming 10439@code{car} is not already defined, it is equivalent to write: 10440 10441@example 10442define(car, $1) 10443@end example 10444 10445@noindent 10446But, while it is acceptable for a @file{configure.ac} to avoid unnecessary 10447quotes, it is bad practice for Autoconf macros which must both be more 10448robust and also advocate perfect style. 10449 10450At the top level, there are only two possibilities: either you 10451quote or you don't: 10452 10453@example 10454car(foo, bar, baz) 10455@result{}foo 10456[car(foo, bar, baz)] 10457@result{}car(foo, bar, baz) 10458@end example 10459 10460Let's pay attention to the special characters: 10461 10462@example 10463car(#) 10464@error{}EOF in argument list 10465@end example 10466 10467The closing parenthesis is hidden in the comment; with a hypothetical 10468quoting, the top level understood it this way: 10469 10470@example 10471car([#)] 10472@end example 10473 10474@noindent 10475Proper quotation, of course, fixes the problem: 10476 10477@example 10478car([#]) 10479@result{}# 10480@end example 10481 10482Here are more examples: 10483 10484@example 10485car(foo, bar) 10486@result{}foo 10487car([foo, bar]) 10488@result{}foo, bar 10489car((foo, bar)) 10490@result{}(foo, bar) 10491car([(foo], [bar)]) 10492@result{}(foo 10493define([a], [b]) 10494@result{} 10495car(a) 10496@result{}b 10497car([a]) 10498@result{}b 10499car([[a]]) 10500@result{}a 10501car([[[a]]]) 10502@result{}[a] 10503@end example 10504 10505@node Quoting and Parameters 10506@subsection Quoting and Parameters 10507 10508When M4 encounters @samp{$} within a macro definition, followed 10509immediately by a character it recognizes (@samp{0}@dots{}@samp{9}, 10510@samp{#}, @samp{@@}, or @samp{*}), it will perform M4 parameter 10511expansion. This happens regardless of how many layers of quotes the 10512parameter expansion is nested within, or even if it occurs in text that 10513will be rescanned as a comment. 10514 10515@example 10516define([none], [$1]) 10517@result{} 10518define([one], [[$1]]) 10519@result{} 10520define([two], [[[$1]]]) 10521@result{} 10522define([comment], [# $1]) 10523@result{} 10524define([active], [ACTIVE]) 10525@result{} 10526none([active]) 10527@result{}ACTIVE 10528one([active]) 10529@result{}active 10530two([active]) 10531@result{}[active] 10532comment([active]) 10533@result{}# active 10534@end example 10535 10536On the other hand, since autoconf generates shell code, you often want 10537to output shell variable expansion, rather than performing M4 parameter 10538expansion. To do this, you must use M4 quoting to separate the @samp{$} 10539from the next character in the definition of your macro. If the macro 10540definition occurs in single-quoted text, then insert another level of 10541quoting; if the usage is already inside a double-quoted string, then 10542split it into concatenated strings. 10543 10544@example 10545define([single], [a single-quoted $[]1 definition]) 10546@result{} 10547define([double], [[a double-quoted $][1 definition]]) 10548@result{} 10549single 10550@result{}a single-quoted $1 definition 10551double 10552@result{}a double-quoted $1 definition 10553@end example 10554 10555Posix states that M4 implementations are free to provide implementation 10556extensions when @samp{$@{} is encountered in a macro definition. 10557Autoconf reserves the longer sequence @samp{$@{@{} for use with planned 10558extensions that will be available in the future GNU M4 2.0, 10559but guarantees that all other instances of @samp{$@{} will be output 10560literally. Therefore, this idiom can also be used to output shell code 10561parameter references: 10562 10563@example 10564define([first], [$@{1@}])first 10565@result{}$@{1@} 10566@end example 10567 10568Posix also states that @samp{$11} should expand to the first parameter 10569concatenated with a literal @samp{1}, although some versions of 10570GNU M4 expand the eleventh parameter instead. For 10571portability, you should only use single-digit M4 parameter expansion. 10572 10573With this in mind, we can explore the cases where macros invoke 10574macros@enddots{} 10575 10576@node Quotation and Nested Macros 10577@subsection Quotation and Nested Macros 10578 10579The examples below use the following macros: 10580 10581@example 10582define([car], [$1]) 10583define([active], [ACT, IVE]) 10584define([array], [int tab[10]]) 10585@end example 10586 10587Each additional embedded macro call introduces other possible 10588interesting quotations: 10589 10590@example 10591car(active) 10592@result{}ACT 10593car([active]) 10594@result{}ACT, IVE 10595car([[active]]) 10596@result{}active 10597@end example 10598 10599In the first case, the top level looks for the arguments of @code{car}, 10600and finds @samp{active}. Because M4 evaluates its arguments 10601before applying the macro, @samp{active} is expanded, which results in: 10602 10603@example 10604car(ACT, IVE) 10605@result{}ACT 10606@end example 10607 10608@noindent 10609In the second case, the top level gives @samp{active} as first and only 10610argument of @code{car}, which results in: 10611 10612@example 10613active 10614@result{}ACT, IVE 10615@end example 10616 10617@noindent 10618i.e., the argument is evaluated @emph{after} the macro that invokes it. 10619In the third case, @code{car} receives @samp{[active]}, which results in: 10620 10621@example 10622[active] 10623@result{}active 10624@end example 10625 10626@noindent 10627exactly as we already saw above. 10628 10629The example above, applied to a more realistic example, gives: 10630 10631@example 10632car(int tab[10];) 10633@result{}int tab10; 10634car([int tab[10];]) 10635@result{}int tab10; 10636car([[int tab[10];]]) 10637@result{}int tab[10]; 10638@end example 10639 10640@noindent 10641Huh? The first case is easily understood, but why is the second wrong, 10642and the third right? To understand that, you must know that after 10643M4 expands a macro, the resulting text is immediately subjected 10644to macro expansion and quote removal. This means that the quote removal 10645occurs twice---first before the argument is passed to the @code{car} 10646macro, and second after the @code{car} macro expands to the first 10647argument. 10648 10649As the author of the Autoconf macro @code{car}, you then consider it to 10650be incorrect that your users have to double-quote the arguments of 10651@code{car}, so you ``fix'' your macro. Let's call it @code{qar} for 10652quoted car: 10653 10654@example 10655define([qar], [[$1]]) 10656@end example 10657 10658@noindent 10659and check that @code{qar} is properly fixed: 10660 10661@example 10662qar([int tab[10];]) 10663@result{}int tab[10]; 10664@end example 10665 10666@noindent 10667Ahhh! That's much better. 10668 10669But note what you've done: now that the result of @code{qar} is always 10670a literal string, the only time a user can use nested macros is if she 10671relies on an @emph{unquoted} macro call: 10672 10673@example 10674qar(active) 10675@result{}ACT 10676qar([active]) 10677@result{}active 10678@end example 10679 10680@noindent 10681leaving no way for her to reproduce what she used to do with @code{car}: 10682 10683@example 10684car([active]) 10685@result{}ACT, IVE 10686@end example 10687 10688@noindent 10689Worse yet: she wants to use a macro that produces a set of @code{cpp} 10690macros: 10691 10692@example 10693define([my_includes], [#include <stdio.h>]) 10694car([my_includes]) 10695@result{}#include <stdio.h> 10696qar(my_includes) 10697@error{}EOF in argument list 10698@end example 10699 10700This macro, @code{qar}, because it double quotes its arguments, forces 10701its users to leave their macro calls unquoted, which is dangerous. 10702Commas and other active symbols are interpreted by M4 before 10703they are given to the macro, often not in the way the users expect. 10704Also, because @code{qar} behaves differently from the other macros, 10705it's an exception that should be avoided in Autoconf. 10706 10707@node Changequote is Evil 10708@subsection @code{changequote} is Evil 10709@cindex @code{changequote} 10710 10711The temptation is often high to bypass proper quotation, in particular 10712when it's late at night. Then, many experienced Autoconf hackers 10713finally surrender to the dark side of the force and use the ultimate 10714weapon: @code{changequote}. 10715 10716The M4 builtin @code{changequote} belongs to a set of primitives that 10717allow one to adjust the syntax of the language to adjust it to one's 10718needs. For instance, by default M4 uses @samp{`} and @samp{'} as 10719quotes, but in the context of shell programming (and actually of most 10720programming languages), that's about the worst choice one can make: 10721because of strings and back-quoted expressions in shell code (such as 10722@samp{'this'} and @samp{`that`}), and because of literal characters in usual 10723programming languages (as in @samp{'0'}), there are many unbalanced 10724@samp{`} and @samp{'}. Proper M4 quotation then becomes a nightmare, if 10725not impossible. In order to make M4 useful in such a context, its 10726designers have equipped it with @code{changequote}, which makes it 10727possible to choose another pair of quotes. M4sugar, M4sh, Autoconf, and 10728Autotest all have chosen to use @samp{[} and @samp{]}. Not especially 10729because they are unlikely characters, but @emph{because they are 10730characters unlikely to be unbalanced}. 10731 10732There are other magic primitives, such as @code{changecom} to specify 10733what syntactic forms are comments (it is common to see 10734@samp{changecom(<!--, -->)} when M4 is used to produce HTML pages), 10735@code{changeword} and @code{changesyntax} to change other syntactic 10736details (such as the character to denote the @var{n}th argument, @samp{$} by 10737default, the parentheses around arguments, etc.). 10738 10739These primitives are really meant to make M4 more useful for specific 10740domains: they should be considered like command line options: 10741@option{--quotes}, @option{--comments}, @option{--words}, and 10742@option{--syntax}. Nevertheless, they are implemented as M4 builtins, as 10743it makes M4 libraries self contained (no need for additional options). 10744 10745There lies the problem@enddots{} 10746 10747@sp 1 10748 10749The problem is that it is then tempting to use them in the middle of an 10750M4 script, as opposed to its initialization. This, if not carefully 10751thought out, can lead to disastrous effects: @emph{you are changing the 10752language in the middle of the execution}. Changing and restoring the 10753syntax is often not enough: if you happened to invoke macros in between, 10754these macros are lost, as the current syntax is probably not 10755the one they were implemented with. 10756 10757@c FIXME: I've been looking for a short, real case example, but I 10758@c lost them all :( 10759 10760 10761@node Quadrigraphs 10762@subsection Quadrigraphs 10763@cindex quadrigraphs 10764@cindex @samp{@@S|@@} 10765@cindex @samp{@@&t@@} 10766@c Info cannot handle `:' in index entries. 10767@ifnotinfo 10768@cindex @samp{@@<:@@} 10769@cindex @samp{@@:>@@} 10770@cindex @samp{@@%:@@} 10771@cindex @samp{@@@{:@@} 10772@cindex @samp{@@:@}@@} 10773@end ifnotinfo 10774 10775When writing an Autoconf macro you may occasionally need to generate 10776special characters that are difficult to express with the standard 10777Autoconf quoting rules. For example, you may need to output the regular 10778expression @samp{[^[]}, which matches any character other than @samp{[}. 10779This expression contains unbalanced brackets so it cannot be put easily 10780into an M4 macro. 10781 10782Additionally, there are a few m4sugar macros (such as @code{m4_split} 10783and @code{m4_expand}) which internally use special markers in addition 10784to the regular quoting characters. If the arguments to these macros 10785contain the literal strings @samp{-=<@{(} or @samp{)@}>=-}, the macros 10786might behave incorrectly. 10787 10788You can work around these problems by using one of the following 10789@dfn{quadrigraphs}: 10790 10791@table @samp 10792@item @@<:@@ 10793@samp{[} 10794@item @@:>@@ 10795@samp{]} 10796@item @@S|@@ 10797@samp{$} 10798@item @@%:@@ 10799@samp{#} 10800@item @@@{:@@ 10801@samp{(} 10802@item @@:@}@@ 10803@samp{)} 10804@item @@&t@@ 10805Expands to nothing. 10806@end table 10807 10808Quadrigraphs are replaced at a late stage of the translation process, 10809after @command{m4} is run, so they do not get in the way of M4 quoting. 10810For example, the string @samp{^@@<:@@}, independently of its quotation, 10811appears as @samp{^[} in the output. 10812 10813The empty quadrigraph can be used: 10814 10815@itemize @minus 10816@item to mark trailing spaces explicitly 10817 10818Trailing spaces are smashed by @command{autom4te}. This is a feature. 10819 10820@item to produce quadrigraphs and other strings reserved by m4sugar 10821 10822For instance @samp{@@<@@&t@@:@@} produces @samp{@@<:@@}. For a more 10823contrived example: 10824 10825@example 10826m4_define([a], [A])m4_define([b], [B])m4_define([c], [C])dnl 10827m4_split([a )@}>=- b -=<@{( c]) 10828@result{}[a], [], [B], [], [c] 10829m4_split([a )@}@@&t@@>=- b -=<@@&t@@@{( c]) 10830@result{}[a], [)@}>=-], [b], [-=<@{(], [c] 10831@end example 10832 10833@item to escape @emph{occurrences} of forbidden patterns 10834 10835For instance you might want to mention @code{AC_FOO} in a comment, while 10836still being sure that @command{autom4te} still catches unexpanded 10837@samp{AC_*}. Then write @samp{AC@@&t@@_FOO}. 10838@end itemize 10839 10840The name @samp{@@&t@@} was suggested by Paul Eggert: 10841 10842@quotation 10843I should give some credit to the @samp{@@&t@@} pun. The @samp{&} is my 10844own invention, but the @samp{t} came from the source code of the 10845ALGOL68C compiler, written by Steve Bourne (of Bourne shell fame), 10846and which used @samp{mt} to denote the empty string. In C, it would 10847have looked like something like: 10848 10849@example 10850char const mt[] = ""; 10851@end example 10852 10853@noindent 10854but of course the source code was written in Algol 68. 10855 10856I don't know where he got @samp{mt} from: it could have been his own 10857invention, and I suppose it could have been a common pun around the 10858Cambridge University computer lab at the time. 10859@end quotation 10860 10861 10862@node Balancing Parentheses 10863@subsection Dealing with unbalanced parentheses 10864@cindex balancing parentheses 10865@cindex parentheses, balancing 10866@cindex unbalanced parentheses, managing 10867 10868One of the pitfalls of portable shell programming is that @command{case} 10869statements require unbalanced parentheses (@pxref{case, , Limitations of 10870Shell Builtins}). With syntax highlighting 10871editors, the presence of unbalanced @samp{)} can interfere with editors 10872that perform syntax highlighting of macro contents based on finding the 10873matching @samp{(}. Another concern is how much editing must be done 10874when transferring code snippets between shell scripts and macro 10875definitions. But most importantly, the presence of unbalanced 10876parentheses can introduce expansion bugs. 10877 10878For an example, here is an underquoted attempt to use the macro 10879@code{my_case}, which happens to expand to a portable @command{case} 10880statement: 10881 10882@example 10883AC_DEFUN([my_case], 10884[case $file_name in 10885 *.c) echo "C source code";; 10886esac]) 10887AS_IF(:, my_case) 10888@end example 10889 10890@noindent 10891In the above example, the @code{AS_IF} call underquotes its arguments. 10892As a result, the unbalanced @samp{)} generated by the premature 10893expansion of @code{my_case} results in expanding @code{AS_IF} with a 10894truncated parameter, and the expansion is syntactically invalid: 10895 10896@example 10897if :; then 10898 case $file_name in 10899 *.c 10900fi echo "C source code";; 10901esac) 10902@end example 10903 10904If nothing else, this should emphasize the importance of the quoting 10905arguments to macro calls. On the other hand, there are several 10906variations for defining @code{my_case} to be more robust, even when used 10907without proper quoting, each with some benefits and some drawbacks. 10908 10909@itemize @w{} 10910@item Creative literal shell comment 10911@example 10912AC_DEFUN([my_case], 10913[case $file_name in #( 10914 *.c) echo "C source code";; 10915esac]) 10916@end example 10917@noindent 10918This version provides balanced parentheses to several editors, and can 10919be copied and pasted into a terminal as is. Unfortunately, it is still 10920unbalanced as an Autoconf argument, since @samp{#(} is an M4 comment 10921that masks the normal properties of @samp{(}. 10922 10923@item Quadrigraph shell comment 10924@example 10925AC_DEFUN([my_case], 10926[case $file_name in @@%:@@( 10927 *.c) echo "C source code";; 10928esac]) 10929@end example 10930@noindent 10931This version provides balanced parentheses to even more editors, and can 10932be used as a balanced Autoconf argument. Unfortunately, it requires 10933some editing before it can be copied and pasted into a terminal, and the 10934use of the quadrigraph @samp{@@%:@@} for @samp{#} reduces readability. 10935 10936@item Quoting just the parenthesis 10937@example 10938AC_DEFUN([my_case], 10939[case $file_name in 10940 *.c[)] echo "C source code";; 10941esac]) 10942@end example 10943@noindent 10944This version quotes the @samp{)}, so that it can be used as a balanced 10945Autoconf argument. As written, this is not balanced to an editor, but 10946it can be coupled with @samp{[#(]} to meet that need, too. However, it 10947still requires some edits before it can be copied and pasted into a 10948terminal. 10949 10950@item Double-quoting the entire statement 10951@example 10952AC_DEFUN([my_case], 10953[[case $file_name in #( 10954 *.c) echo "C source code";; 10955esac]]) 10956@end example 10957@noindent 10958Since the entire macro is double-quoted, there is no problem with using 10959this as an Autoconf argument; and since the double-quoting is over the 10960entire statement, this code can be easily copied and pasted into a 10961terminal. However, the double quoting prevents the expansion of any 10962macros inside the case statement, which may cause its own set of 10963problems. 10964 10965@item Using @code{AS_CASE} 10966@example 10967AC_DEFUN([my_case], 10968[AS_CASE([$file_name], 10969 [*.c], [echo "C source code"])]) 10970@end example 10971@noindent 10972This version avoids the balancing issue altogether, by relying on 10973@code{AS_CASE} (@pxref{Common Shell Constructs}); it also allows for the 10974expansion of @code{AC_REQUIRE} to occur prior to the entire case 10975statement, rather than within a branch of the case statement that might 10976not be taken. However, the abstraction comes with a penalty that it is 10977no longer a quick copy, paste, and edit to get back to shell code. 10978@end itemize 10979 10980 10981@node Quotation Rule Of Thumb 10982@subsection Quotation Rule Of Thumb 10983 10984To conclude, the quotation rule of thumb is: 10985 10986@center @emph{One pair of quotes per pair of parentheses.} 10987 10988Never over-quote, never under-quote, in particular in the definition of 10989macros. In the few places where the macros need to use brackets 10990(usually in C program text or regular expressions), properly quote 10991@emph{the arguments}! 10992 10993It is common to read Autoconf programs with snippets like: 10994 10995@example 10996AC_TRY_LINK( 10997changequote(<<, >>)dnl 10998<<#include <time.h> 10999#ifndef tzname /* For SGI. */ 11000extern char *tzname[]; /* RS6000 and others reject char **tzname. */ 11001#endif>>, 11002changequote([, ])dnl 11003[atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no) 11004@end example 11005 11006@noindent 11007which is incredibly useless since @code{AC_TRY_LINK} is @emph{already} 11008double quoting, so you just need: 11009 11010@example 11011AC_TRY_LINK( 11012[#include <time.h> 11013#ifndef tzname /* For SGI. */ 11014extern char *tzname[]; /* RS6000 and others reject char **tzname. */ 11015#endif], 11016 [atoi (*tzname);], 11017 [ac_cv_var_tzname=yes], 11018 [ac_cv_var_tzname=no]) 11019@end example 11020 11021@noindent 11022The M4-fluent reader might note that these two examples are rigorously 11023equivalent, since M4 swallows both the @samp{changequote(<<, >>)} 11024and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these 11025quotes are not part of the arguments! 11026 11027Simplified, the example above is just doing this: 11028 11029@example 11030changequote(<<, >>)dnl 11031<<[]>> 11032changequote([, ])dnl 11033@end example 11034 11035@noindent 11036instead of simply: 11037 11038@example 11039[[]] 11040@end example 11041 11042With macros that do not double quote their arguments (which is the 11043rule), double-quote the (risky) literals: 11044 11045@example 11046AC_LINK_IFELSE([AC_LANG_PROGRAM( 11047[[#include <time.h> 11048#ifndef tzname /* For SGI. */ 11049extern char *tzname[]; /* RS6000 and others reject char **tzname. */ 11050#endif]], 11051 [atoi (*tzname);])], 11052 [ac_cv_var_tzname=yes], 11053 [ac_cv_var_tzname=no]) 11054@end example 11055 11056Please note that the macro @code{AC_TRY_LINK} is obsolete, so you really 11057should be using @code{AC_LINK_IFELSE} instead. 11058 11059@xref{Quadrigraphs}, for what to do if you run into a hopeless case 11060where quoting does not suffice. 11061 11062When you create a @command{configure} script using newly written macros, 11063examine it carefully to check whether you need to add more quotes in 11064your macros. If one or more words have disappeared in the M4 11065output, you need more quotes. When in doubt, quote. 11066 11067However, it's also possible to put on too many layers of quotes. If 11068this happens, the resulting @command{configure} script may contain 11069unexpanded macros. The @command{autoconf} program checks for this problem 11070by looking for the string @samp{AC_} in @file{configure}. However, this 11071heuristic does not work in general: for example, it does not catch 11072overquoting in @code{AC_DEFINE} descriptions. 11073 11074 11075@c ---------------------------------------- Using autom4te 11076 11077@node Using autom4te 11078@section Using @command{autom4te} 11079 11080The Autoconf suite, including M4sugar, M4sh, and Autotest, in addition 11081to Autoconf per se, heavily rely on M4. All these different uses 11082revealed common needs factored into a layer over M4: 11083@command{autom4te}@footnote{ 11084@c 11085Yet another great name from Lars J. Aas. 11086@c 11087}. 11088 11089@command{autom4te} is a preprocessor that is like @command{m4}. 11090It supports M4 extensions designed for use in tools like Autoconf. 11091 11092@menu 11093* autom4te Invocation:: A GNU M4 wrapper 11094* Customizing autom4te:: Customizing the Autoconf package 11095@end menu 11096 11097@node autom4te Invocation 11098@subsection Invoking @command{autom4te} 11099 11100The command line arguments are modeled after M4's: 11101 11102@example 11103autom4te @var{options} @var{files} 11104@end example 11105 11106@noindent 11107@evindex M4 11108where the @var{files} are directly passed to @command{m4}. By default, 11109GNU M4 is found during configuration, but the environment 11110variable 11111@env{M4} can be set to tell @command{autom4te} where to look. In addition 11112to the regular expansion, it handles the replacement of the quadrigraphs 11113(@pxref{Quadrigraphs}), and of @samp{__oline__}, the current line in the 11114output. It supports an extended syntax for the @var{files}: 11115 11116@table @file 11117@item @var{file}.m4f 11118This file is an M4 frozen file. Note that @emph{all the previous files 11119are ignored}. See the option @option{--melt} for the rationale. 11120 11121@item @var{file}? 11122If found in the library path, the @var{file} is included for expansion, 11123otherwise it is ignored instead of triggering a failure. 11124@end table 11125 11126@sp 1 11127 11128Of course, it supports the Autoconf common subset of options: 11129 11130@table @option 11131@item --help 11132@itemx -h 11133Print a summary of the command line options and exit. 11134 11135@item --version 11136@itemx -V 11137Print the version number of Autoconf and exit. 11138 11139@item --verbose 11140@itemx -v 11141Report processing steps. 11142 11143@item --debug 11144@itemx -d 11145Don't remove the temporary files and be even more verbose. 11146 11147@item --include=@var{dir} 11148@itemx -I @var{dir} 11149Also look for input files in @var{dir}. Multiple invocations 11150accumulate. 11151 11152@item --output=@var{file} 11153@itemx -o @var{file} 11154Save output (script or trace) to @var{file}. The file @option{-} stands 11155for the standard output. 11156@end table 11157 11158@sp 1 11159 11160As an extension of @command{m4}, it includes the following options: 11161 11162@table @option 11163@item --warnings=@var{category} 11164@itemx -W @var{category} 11165@evindex WARNINGS 11166@c FIXME: Point to the M4sugar macros, not Autoconf's. 11167Report the warnings related to @var{category} (which can actually be a 11168comma separated list). @xref{Reporting Messages}, macro 11169@code{AC_DIAGNOSE}, for a comprehensive list of categories. Special 11170values include: 11171 11172@table @samp 11173@item all 11174report all the warnings 11175 11176@item none 11177report none 11178 11179@item error 11180treats warnings as errors 11181 11182@item no-@var{category} 11183disable warnings falling into @var{category} 11184@end table 11185 11186Warnings about @samp{syntax} are enabled by default, and the environment 11187variable @env{WARNINGS}, a comma separated list of categories, is 11188honored. @samp{autom4te -W @var{category}} actually 11189behaves as if you had run: 11190 11191@example 11192autom4te --warnings=syntax,$WARNINGS,@var{category} 11193@end example 11194 11195@noindent 11196For example, if you want to disable defaults and @env{WARNINGS} 11197of @command{autom4te}, but enable the warnings about obsolete 11198constructs, you would use @option{-W none,obsolete}. 11199 11200@cindex Back trace 11201@cindex Macro invocation stack 11202@command{autom4te} displays a back trace for errors, but not for 11203warnings; if you want them, just pass @option{-W error}. 11204 11205@item --melt 11206@itemx -M 11207Do not use frozen files. Any argument @code{@var{file}.m4f} is 11208replaced by @code{@var{file}.m4}. This helps tracing the macros which 11209are executed only when the files are frozen, typically 11210@code{m4_define}. For instance, running: 11211 11212@example 11213autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4 11214@end example 11215 11216@noindent 11217is roughly equivalent to running: 11218 11219@example 11220m4 1.m4 2.m4 3.m4 4.m4 input.m4 11221@end example 11222 11223@noindent 11224while 11225 11226@example 11227autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4 11228@end example 11229 11230@noindent 11231is equivalent to: 11232 11233@example 11234m4 --reload-state=4.m4f input.m4 11235@end example 11236 11237@item --freeze 11238@itemx -F 11239Produce a frozen state file. @command{autom4te} freezing is stricter 11240than M4's: it must produce no warnings, and no output other than empty 11241lines (a line with white space is @emph{not} empty) and comments 11242(starting with @samp{#}). Unlike @command{m4}'s similarly-named option, 11243this option takes no argument: 11244 11245@example 11246autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f 11247@end example 11248 11249@noindent 11250corresponds to 11251 11252@example 11253m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f 11254@end example 11255 11256@item --mode=@var{octal-mode} 11257@itemx -m @var{octal-mode} 11258Set the mode of the non-traces output to @var{octal-mode}; by default 11259@samp{0666}. 11260@end table 11261 11262@sp 1 11263 11264@cindex @file{autom4te.cache} 11265As another additional feature over @command{m4}, @command{autom4te} 11266caches its results. GNU M4 is able to produce a regular 11267output and traces at the same time. Traces are heavily used in the 11268GNU Build System: @command{autoheader} uses them to build 11269@file{config.h.in}, @command{autoreconf} to determine what 11270GNU Build System components are used, @command{automake} to 11271``parse'' @file{configure.ac} etc. To avoid recomputation, 11272traces are cached while performing regular expansion, 11273and conversely. This cache is (actually, the caches are) stored in 11274the directory @file{autom4te.cache}. @emph{It can safely be removed} 11275at any moment (especially if for some reason @command{autom4te} 11276considers it trashed). 11277 11278@table @option 11279@item --cache=@var{directory} 11280@itemx -C @var{directory} 11281Specify the name of the directory where the result should be cached. 11282Passing an empty value disables caching. Be sure to pass a relative 11283file name, as for the time being, global caches are not supported. 11284 11285@item --no-cache 11286Don't cache the results. 11287 11288@item --force 11289@itemx -f 11290If a cache is used, consider it obsolete (but update it anyway). 11291@end table 11292 11293@sp 1 11294 11295Because traces are so important to the GNU Build System, 11296@command{autom4te} provides high level tracing features as compared to 11297M4, and helps exploiting the cache: 11298 11299@table @option 11300@item --trace=@var{macro}[:@var{format}] 11301@itemx -t @var{macro}[:@var{format}] 11302Trace the invocations of @var{macro} according to the @var{format}. 11303Multiple @option{--trace} arguments can be used to list several macros. 11304Multiple @option{--trace} arguments for a single macro are not 11305cumulative; instead, you should just make @var{format} as long as 11306needed. 11307 11308The @var{format} is a regular string, with newlines if desired, and 11309several special escape codes. It defaults to @samp{$f:$l:$n:$%}. It can 11310use the following special escapes: 11311 11312@table @samp 11313@item $$ 11314@c $$ restore font-lock 11315The character @samp{$}. 11316 11317@item $f 11318The file name from which @var{macro} is called. 11319 11320@item $l 11321The line number from which @var{macro} is called. 11322 11323@item $d 11324The depth of the @var{macro} call. This is an M4 technical detail that 11325you probably don't want to know about. 11326 11327@item $n 11328The name of the @var{macro}. 11329 11330@item $@var{num} 11331The @var{num}th argument of the call to @var{macro}. 11332 11333@item $@@ 11334@itemx $@var{sep}@@ 11335@itemx $@{@var{separator}@}@@ 11336All the arguments passed to @var{macro}, separated by the character 11337@var{sep} or the string @var{separator} (@samp{,} by default). Each 11338argument is quoted, i.e., enclosed in a pair of square brackets. 11339 11340@item $* 11341@itemx $@var{sep}* 11342@itemx $@{@var{separator}@}* 11343As above, but the arguments are not quoted. 11344 11345@item $% 11346@itemx $@var{sep}% 11347@itemx $@{@var{separator}@}% 11348As above, but the arguments are not quoted, all new line characters in 11349the arguments are smashed, and the default separator is @samp{:}. 11350 11351The escape @samp{$%} produces single-line trace outputs (unless you put 11352newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do 11353not. 11354@end table 11355 11356@xref{autoconf Invocation}, for examples of trace uses. 11357 11358@item --preselect=@var{macro} 11359@itemx -p @var{macro} 11360Cache the traces of @var{macro}, but do not enable traces. This is 11361especially important to save CPU cycles in the future. For instance, 11362when invoked, @command{autoconf} preselects all the macros that 11363@command{autoheader}, @command{automake}, @command{autoreconf}, etc., 11364trace, so that running @command{m4} is not needed to trace them: the 11365cache suffices. This results in a huge speed-up. 11366@end table 11367 11368@sp 1 11369 11370@cindex Autom4te Library 11371Finally, @command{autom4te} introduces the concept of @dfn{Autom4te 11372libraries}. They consists in a powerful yet extremely simple feature: 11373sets of combined command line arguments: 11374 11375@table @option 11376@item --language=@var{language} 11377@itemx -l @var{language} 11378Use the @var{language} Autom4te library. Current languages include: 11379 11380@table @code 11381@item M4sugar 11382create M4sugar output. 11383 11384@item M4sh 11385create M4sh executable shell scripts. 11386 11387@item Autotest 11388create Autotest executable test suites. 11389 11390@item Autoconf-without-aclocal-m4 11391create Autoconf executable configure scripts without 11392reading @file{aclocal.m4}. 11393 11394@item Autoconf 11395create Autoconf executable configure scripts. This language inherits 11396all the characteristics of @code{Autoconf-without-aclocal-m4} and 11397additionally reads @file{aclocal.m4}. 11398@end table 11399 11400@item --prepend-include=@var{dir} 11401@itemx -B @var{dir} 11402Prepend directory @var{dir} to the search path. This is used to include 11403the language-specific files before any third-party macros. 11404 11405@end table 11406 11407@cindex @file{autom4te.cfg} 11408As an example, if Autoconf is installed in its default location, 11409@file{/usr/local}, the command @samp{autom4te -l m4sugar foo.m4} is 11410strictly equivalent to the command: 11411 11412@example 11413autom4te --prepend-include /usr/local/share/autoconf \ 11414 m4sugar/m4sugar.m4f --warnings syntax foo.m4 11415@end example 11416 11417@noindent 11418Recursive expansion applies here: the command @samp{autom4te -l m4sh foo.m4} 11419is the same as @samp{autom4te --language M4sugar m4sugar/m4sh.m4f 11420foo.m4}, i.e.: 11421 11422@example 11423autom4te --prepend-include /usr/local/share/autoconf \ 11424 m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4 11425@end example 11426 11427@noindent 11428The definition of the languages is stored in @file{autom4te.cfg}. 11429 11430@node Customizing autom4te 11431@subsection Customizing @command{autom4te} 11432 11433One can customize @command{autom4te} via @file{~/.autom4te.cfg} (i.e., 11434as found in the user home directory), and @file{./.autom4te.cfg} (i.e., 11435as found in the directory from which @command{autom4te} is run). The 11436order is first reading @file{autom4te.cfg}, then @file{~/.autom4te.cfg}, 11437then @file{./.autom4te.cfg}, and finally the command line arguments. 11438 11439In these text files, comments are introduced with @code{#}, and empty 11440lines are ignored. Customization is performed on a per-language basis, 11441wrapped in between a @samp{begin-language: "@var{language}"}, 11442@samp{end-language: "@var{language}"} pair. 11443 11444Customizing a language stands for appending options (@pxref{autom4te 11445Invocation}) to the current definition of the language. Options, and 11446more generally arguments, are introduced by @samp{args: 11447@var{arguments}}. You may use the traditional shell syntax to quote the 11448@var{arguments}. 11449 11450As an example, to disable Autoconf caches (@file{autom4te.cache}) 11451globally, include the following lines in @file{~/.autom4te.cfg}: 11452 11453@verbatim 11454## ------------------ ## 11455## User Preferences. ## 11456## ------------------ ## 11457 11458begin-language: "Autoconf-without-aclocal-m4" 11459args: --no-cache 11460end-language: "Autoconf-without-aclocal-m4" 11461@end verbatim 11462 11463 11464@node Programming in M4sugar 11465@section Programming in M4sugar 11466 11467@cindex M4sugar 11468M4 by itself provides only a small, but sufficient, set of all-purpose 11469macros. M4sugar introduces additional generic macros. Its name was 11470coined by Lars J. Aas: ``Readability And Greater Understanding Stands 4 11471M4sugar''. 11472 11473M4sugar reserves the macro namespace @samp{^_m4_} for internal use, and 11474the macro namespace @samp{^m4_} for M4sugar macros. You should not 11475define your own macros into these namespaces. 11476 11477@menu 11478* Redefined M4 Macros:: M4 builtins changed in M4sugar 11479* Diagnostic Macros:: Diagnostic messages from M4sugar 11480* Diversion support:: Diversions in M4sugar 11481* Conditional constructs:: Conditions in M4 11482* Looping constructs:: Iteration in M4 11483* Evaluation Macros:: More quotation and evaluation control 11484* Text processing Macros:: String manipulation in M4 11485* Number processing Macros:: Arithmetic computation in M4 11486* Set manipulation Macros:: Set manipulation in M4 11487* Forbidden Patterns:: Catching unexpanded macros 11488@end menu 11489 11490@node Redefined M4 Macros 11491@subsection Redefined M4 Macros 11492 11493@msindex{builtin} 11494@msindex{changecom} 11495@msindex{changequote} 11496@msindex{debugfile} 11497@msindex{debugmode} 11498@msindex{decr} 11499@msindex{define} 11500@msindex{divnum} 11501@msindex{errprint} 11502@msindex{esyscmd} 11503@msindex{eval} 11504@msindex{format} 11505@msindex{ifdef} 11506@msindex{incr} 11507@msindex{index} 11508@msindex{indir} 11509@msindex{len} 11510@msindex{pushdef} 11511@msindex{shift} 11512@msindex{substr} 11513@msindex{syscmd} 11514@msindex{sysval} 11515@msindex{traceoff} 11516@msindex{traceon} 11517@msindex{translit} 11518With a few exceptions, all the M4 native macros are moved in the 11519@samp{m4_} pseudo-namespace, e.g., M4sugar renames @code{define} as 11520@code{m4_define} etc. 11521 11522The list of macros unchanged from M4, except for their name, is: 11523@itemize @minus 11524@item m4_builtin 11525@item m4_changecom 11526@item m4_changequote 11527@item m4_debugfile 11528@item m4_debugmode 11529@item m4_decr 11530@item m4_define 11531@item m4_divnum 11532@item m4_errprint 11533@item m4_esyscmd 11534@item m4_eval 11535@item m4_format 11536@item m4_ifdef 11537@item m4_incr 11538@item m4_index 11539@item m4_indir 11540@item m4_len 11541@item m4_pushdef 11542@item m4_shift 11543@item m4_substr 11544@item m4_syscmd 11545@item m4_sysval 11546@item m4_traceoff 11547@item m4_traceon 11548@item m4_translit 11549@end itemize 11550 11551Some M4 macros are redefined, and are slightly incompatible with their 11552native equivalent. 11553 11554@defmac __file__ 11555@defmacx __line__ 11556@MSindex __file__ 11557@MSindex __line__ 11558All M4 macros starting with @samp{__} retain their original name: for 11559example, no @code{m4__file__} is defined. 11560@end defmac 11561 11562@defmac __oline__ 11563@MSindex __oline__ 11564This is not technically a macro, but a feature of Autom4te. The 11565sequence @code{__oline__} can be used similarly to the other m4sugar 11566location macros, but rather than expanding to the location of the input 11567file, it is translated to the line number where it appears in the output 11568file after all other M4 expansions. 11569@end defmac 11570 11571@defmac dnl 11572@MSindex dnl 11573This macro kept its original name: no @code{m4_dnl} is defined. 11574@end defmac 11575 11576@defmac m4_bpatsubst (@var{string}, @var{regexp}, @ovar{replacement}) 11577@msindex{bpatsubst} 11578This macro corresponds to @code{patsubst}. The name @code{m4_patsubst} 11579is kept for future versions of M4sugar, once GNU M4 2.0 is 11580released and supports extended regular expression syntax. 11581@end defmac 11582 11583@defmac m4_bregexp (@var{string}, @var{regexp}, @ovar{replacement}) 11584@msindex{bregexp} 11585This macro corresponds to @code{regexp}. The name @code{m4_regexp} 11586is kept for future versions of M4sugar, once GNU M4 2.0 is 11587released and supports extended regular expression syntax. 11588@end defmac 11589 11590@defmac m4_copy (@var{source}, @var{dest}) 11591@defmacx m4_copy_force (@var{source}, @var{dest}) 11592@defmacx m4_rename (@var{source}, @var{dest}) 11593@defmacx m4_rename_force (@var{source}, @var{dest}) 11594@msindex{copy} 11595@msindex{copy_force} 11596@msindex{rename} 11597@msindex{rename_force} 11598These macros aren't directly builtins, but are closely related to 11599@code{m4_pushdef} and @code{m4_defn}. @code{m4_copy} and 11600@code{m4_rename} ensure that @var{dest} is undefined, while 11601@code{m4_copy_force} and @code{m4_rename_force} overwrite any existing 11602definition. All four macros then proceed to copy the entire pushdef 11603stack of definitions of @var{source} over to @var{dest}. @code{m4_copy} 11604and @code{m4_copy_force} preserve the source (including in the special 11605case where @var{source} is undefined), while @code{m4_rename} and 11606@code{m4_rename_force} undefine the original macro name (making it an 11607error to rename an undefined @var{source}). 11608 11609Note that attempting to invoke a renamed macro might not work, since the 11610macro may have a dependence on helper macros accessed via composition of 11611@samp{$0} but that were not also renamed; likewise, other macros may 11612have a hard-coded dependence on @var{source} and could break if 11613@var{source} has been deleted. On the other hand, it is always safe to 11614rename a macro to temporarily move it out of the way, then rename it 11615back later to restore original semantics. 11616@end defmac 11617 11618@defmac m4_defn (@var{macro}@dots{}) 11619@msindex{defn} 11620This macro fails if @var{macro} is not defined, even when using older 11621versions of M4 that did not warn. See @code{m4_undefine}. 11622Unfortunately, in order to support these older versions of M4, there are 11623some situations involving unbalanced quotes where concatenating multiple 11624macros together will work in newer M4 but not in m4sugar; use 11625quadrigraphs to work around this. 11626@end defmac 11627 11628@defmac m4_divert (@var{diversion}) 11629@msindex{divert} 11630M4sugar relies heavily on diversions, so rather than behaving as a 11631primitive, @code{m4_divert} behaves like: 11632@example 11633m4_divert_pop()m4_divert_push([@var{diversion}]) 11634@end example 11635@noindent 11636@xref{Diversion support}, for more details about the use of the 11637diversion stack. In particular, this implies that @var{diversion} 11638should be a named diversion rather than a raw number. But be aware that 11639it is seldom necessary to explicitly change the diversion stack, and 11640that when done incorrectly, it can lead to syntactically invalid 11641scripts. 11642@end defmac 11643 11644@defmac m4_dumpdef (@var{name}@dots{}) 11645@defmacx m4_dumpdefs (@var{name}@dots{}) 11646@msindex{dumpdef} 11647@msindex{dumpdefs} 11648@code{m4_dumpdef} is like the M4 builtin, except that this version 11649requires at least one argument, output always goes to standard error 11650rather than the current debug file, no sorting is done on multiple 11651arguments, and an error is issued if any 11652@var{name} is undefined. @code{m4_dumpdefs} is a convenience macro that 11653calls @code{m4_dumpdef} for all of the 11654@code{m4_pushdef} stack of definitions, starting with the current, and 11655silently does nothing if @var{name} is undefined. 11656 11657Unfortunately, due to a limitation in M4 1.4.x, any macro defined as a 11658builtin is output as the empty string. This behavior is rectified by 11659using M4 1.6 or newer. However, this behavior difference means that 11660@code{m4_dumpdef} should only be used while developing m4sugar macros, 11661and never in the final published form of a macro. 11662@end defmac 11663 11664@defmac m4_esyscmd_s (@var{command}) 11665@msindex{esyscmd_s} 11666Like @code{m4_esyscmd}, this macro expands to the result of running 11667@var{command} in a shell. The difference is that any trailing newlines 11668are removed, so that the output behaves more like shell command 11669substitution. 11670@end defmac 11671 11672@defmac m4_exit (@var{exit-status}) 11673@msindex{exit} 11674This macro corresponds to @code{m4exit}. 11675@end defmac 11676 11677@defmac m4_if (@var{comment}) 11678@defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @ovar{not-equal}) 11679@defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal-1}, @ 11680 @var{string-3}, @var{string-4}, @var{equal-2}, @dots{}, @ovar{not-equal}) 11681@msindex{if} 11682This macro corresponds to @code{ifelse}. @var{string-1} and 11683@var{string-2} are compared literally, so usually one of the two 11684arguments is passed unquoted. @xref{Conditional constructs}, for more 11685conditional idioms. 11686@end defmac 11687 11688@defmac m4_include (@var{file}) 11689@defmacx m4_sinclude (@var{file}) 11690@msindex{include} 11691@msindex{sinclude} 11692Like the M4 builtins, but warn against multiple inclusions of @var{file}. 11693@end defmac 11694 11695@defmac m4_mkstemp (@var{template}) 11696@defmacx m4_maketemp (@var{template}) 11697@msindex{maketemp} 11698@msindex{mkstemp} 11699Posix requires @code{maketemp} to replace the trailing @samp{X} 11700characters in @var{template} with the process id, without regards to the 11701existence of a file by that name, but this a security hole. When this 11702was pointed out to the Posix folks, they agreed to invent a new macro 11703@code{mkstemp} that always creates a uniquely named file, but not all 11704versions of GNU M4 support the new macro. In M4sugar, 11705@code{m4_maketemp} and @code{m4_mkstemp} are synonyms for each other, 11706and both have the secure semantics regardless of which macro the 11707underlying M4 provides. 11708@end defmac 11709 11710@defmac m4_popdef (@var{macro}@dots{}) 11711@msindex{popdef} 11712This macro fails if @var{macro} is not defined, even when using older 11713versions of M4 that did not warn. See @code{m4_undefine}. 11714@end defmac 11715 11716@defmac m4_undefine (@var{macro}@dots{}) 11717@msindex{undefine} 11718This macro fails if @var{macro} is not defined, even when using older 11719versions of M4 that did not warn. Use 11720 11721@example 11722m4_ifdef([@var{macro}], [m4_undefine([@var{macro}])]) 11723@end example 11724 11725@noindent 11726if you are not sure whether @var{macro} is defined. 11727@end defmac 11728 11729@defmac m4_undivert (@var{diversion}@dots{}) 11730@msindex{undivert} 11731Unlike the M4 builtin, at least one @var{diversion} must be specified. 11732Also, since the M4sugar diversion stack prefers named 11733diversions, the use of @code{m4_undivert} to include files is risky. 11734@xref{Diversion support}, for more details about the use of the 11735diversion stack. But be aware that it is seldom necessary to explicitly 11736change the diversion stack, and that when done incorrectly, it can lead 11737to syntactically invalid scripts. 11738@end defmac 11739 11740@defmac m4_wrap (@var{text}) 11741@defmacx m4_wrap_lifo (@var{text}) 11742@msindex{wrap} 11743@msindex{wrap_lifo} 11744These macros correspond to @code{m4wrap}. Posix requires arguments of 11745multiple wrap calls to be reprocessed at EOF in the same order 11746as the original calls (first-in, first-out). GNU M4 versions 11747through 1.4.10, however, reprocess them in reverse order (last-in, 11748first-out). Both orders are useful, therefore, you can rely on 11749@code{m4_wrap} to provide FIFO semantics and @code{m4_wrap_lifo} for 11750LIFO semantics, regardless of the underlying GNU M4 version. 11751 11752Unlike the GNU M4 builtin, these macros only recognize one 11753argument, and avoid token pasting between consecutive invocations. On 11754the other hand, nested calls to @code{m4_wrap} from within wrapped text 11755work just as in the builtin. 11756@end defmac 11757 11758 11759@node Diagnostic Macros 11760@subsection Diagnostic messages from M4sugar 11761@cindex Messages, from @command{M4sugar} 11762 11763When macros statically diagnose abnormal situations, benign or fatal, 11764they should report them using these macros. For issuing dynamic issues, 11765i.e., when @command{configure} is run, see @ref{Printing Messages}. 11766 11767@defmac m4_assert (@var{expression}, @dvar{exit-status, 1}) 11768@msindex{assert} 11769Assert that the arithmetic @var{expression} evaluates to non-zero. 11770Otherwise, issue a fatal error, and exit @command{autom4te} with 11771@var{exit-status}. 11772@end defmac 11773 11774@defmac m4_errprintn (@var{message}) 11775@msindex{errprintn} 11776Similar to the builtin @code{m4_errprint}, except that a newline is 11777guaranteed after @var{message}. 11778@end defmac 11779 11780@anchor{m4_fatal} 11781@defmac m4_fatal (@var{message}) 11782@msindex{fatal} 11783Report a severe error @var{message} prefixed with the current location, 11784and have @command{autom4te} die. 11785@end defmac 11786 11787@defmac m4_location 11788@msindex{location} 11789Useful as a prefix in a message line. Short for: 11790@example 11791__file__:__line__ 11792@end example 11793@end defmac 11794 11795@anchor{m4_warn} 11796@defmac m4_warn (@var{category}, @var{message}) 11797@msindex{warn} 11798Report @var{message} as a warning (or as an error if requested by the 11799user) if warnings of the @var{category} are turned on. If the message 11800is emitted, it is prefixed with the current location, and followed by a 11801call trace of all macros defined via @code{AC_DEFUN} used to get to the 11802current expansion. You are encouraged to use standard categories, which 11803currently include: 11804 11805@table @samp 11806@item all 11807messages that don't fall into one of the following categories. Use of an 11808empty @var{category} is equivalent. 11809 11810@item cross 11811related to cross compilation issues. 11812 11813@item obsolete 11814use of an obsolete construct. 11815 11816@item syntax 11817dubious syntactic constructs, incorrectly ordered macro calls. 11818@end table 11819@end defmac 11820 11821 11822@node Diversion support 11823@subsection Diversion support 11824 11825M4sugar makes heavy use of diversions under the hood, because it is 11826often the case that 11827text that must appear early in the output is not discovered until late 11828in the input. Additionally, some of the topological sorting algorithms 11829used in resolving macro dependencies use diversions. However, most 11830macros should not need to change diversions directly, but rather rely on 11831higher-level M4sugar macros to manage diversions transparently. If you 11832change diversions improperly, you risk generating a syntactically 11833invalid script, because an incorrect diversion will violate assumptions 11834made by many macros about whether prerequisite text has been previously 11835output. In short, if you manually change the diversion, you should not 11836expect any macros provided by the Autoconf package to work until you 11837have restored the diversion stack back to its original state. 11838 11839In the rare case that it is necessary to write a macro that explicitly 11840outputs text to a different diversion, it is important to be aware of an 11841M4 limitation regarding diversions: text only goes to a diversion if it 11842is not part of argument collection. Therefore, any macro that changes 11843the current diversion cannot be used as an unquoted argument to another 11844macro, but must be expanded at the top level. The macro 11845@code{m4_expand} will diagnose any attempt to change diversions, since 11846it is generally useful only as an argument to another macro. The 11847following example shows what happens when diversion manipulation is 11848attempted within macro arguments: 11849 11850@example 11851m4_do([normal text] 11852m4_divert_push([KILL])unwanted[]m4_divert_pop([KILL]) 11853[m4_divert_push([KILL])discarded[]m4_divert_pop([KILL])])dnl 11854@result{}normal text 11855@result{}unwanted 11856@end example 11857 11858@noindent 11859Notice that the unquoted text @code{unwanted} is output, even though it 11860was processed while the current diversion was @code{KILL}, because it 11861was collected as part of the argument to @code{m4_do}. However, the 11862text @code{discarded} disappeared as desired, because the diversion 11863changes were single-quoted, and were not expanded until the top-level 11864rescan of the output of @code{m4_do}. 11865 11866To make diversion management easier, M4sugar uses the concept of named 11867diversions. Rather than using diversion numbers directly, it is nicer 11868to associate a name with each diversion. The diversion number associated 11869with a particular diversion name is an implementation detail, and a 11870syntax warning is issued if a diversion number is used instead of a 11871name. In general, you should not output text 11872to a named diversion until after calling the appropriate initialization 11873routine for your language (@code{m4_init}, @code{AS_INIT}, 11874@code{AT_INIT}, @dots{}), although there are some exceptions documented 11875below. 11876 11877M4sugar defines two named diversions. 11878@table @code 11879@item KILL 11880Text written to this diversion is discarded. This is the default 11881diversion once M4sugar is initialized. 11882@item GROW 11883This diversion is used behind the scenes by topological sorting macros, 11884such as @code{AC_REQUIRE}. 11885@end table 11886 11887M4sh adds several more named diversions. 11888@table @code 11889@item BINSH 11890This diversion is reserved for the @samp{#!} interpreter line. 11891@item HEADER-REVISION 11892This diversion holds text from @code{AC_REVISION}. 11893@item HEADER-COMMENT 11894This diversion holds comments about the purpose of a file. 11895@item HEADER-COPYRIGHT 11896This diversion is managed by @code{AC_COPYRIGHT}. 11897@item M4SH-SANITIZE 11898This diversion contains M4sh sanitization code, used to ensure M4sh is 11899executing in a reasonable shell environment. 11900@item M4SH-INIT 11901This diversion contains M4sh initialization code, initializing variables 11902that are required by other M4sh macros. 11903@item BODY 11904This diversion contains the body of the shell code, and is the default 11905diversion once M4sh is initialized. 11906@end table 11907 11908Autotest inherits diversions from M4sh, and changes the default 11909diversion from @code{BODY} back to @code{KILL}. It also adds several 11910more named diversions, with the following subset designed for developer 11911use. 11912@table @code 11913@item PREPARE_TESTS 11914This diversion contains initialization sequences which are executed 11915after @file{atconfig} and @file{atlocal}, and after all command line 11916arguments have been parsed, but prior to running any tests. It can be 11917used to set up state that is required across all tests. This diversion 11918will work even before @code{AT_INIT}. 11919@end table 11920 11921Autoconf inherits diversions from M4sh, and adds the following named 11922diversions which developers can utilize. 11923@table @code 11924@item DEFAULTS 11925This diversion contains shell variable assignments to set defaults that 11926must be in place before arguments are parsed. This diversion is placed 11927early enough in @file{configure} that it is unsafe to expand any 11928autoconf macros into this diversion. 11929@item HELP_ENABLE 11930If @code{AC_PRESERVE_HELP_ORDER} was used, then text placed in this 11931diversion will be included as part of a quoted here-doc providing all of 11932the @option{--help} output of @file{configure} related to options 11933created by @code{AC_ARG_WITH} and @code{AC_ARG_ENABLE}. 11934@item INIT_PREPARE 11935This diversion occurs after all command line options have been parsed, 11936but prior to the main body of the @file{configure} script. This 11937diversion is the last chance to insert shell code such as variable 11938assignments or shell function declarations that will used by the 11939expansion of other macros. 11940@end table 11941 11942For now, the remaining named diversions of Autoconf, Autoheader, and 11943Autotest are not documented. In other words, 11944intentionally outputting text into an undocumented diversion is subject 11945to breakage in a future release of Autoconf. 11946 11947@defmac m4_cleardivert (@var{diversion}@dots{}) 11948@msindex{cleardivert} 11949Permanently discard any text that has been diverted into 11950@var{diversion}. 11951@end defmac 11952 11953@defmac m4_divert_once (@var{diversion}, @ovar{content}) 11954@msindex{divert_once} 11955Similar to @code{m4_divert_text}, except that @var{content} is only 11956output to @var{diversion} if this is the first time that 11957@code{m4_divert_once} has been called with its particular arguments. 11958@end defmac 11959 11960@defmac m4_divert_pop (@ovar{diversion}) 11961@msindex{divert_pop} 11962If provided, check that the current diversion is indeed @var{diversion}. 11963Then change to the diversion located earlier on the stack, giving an 11964error if an attempt is made to pop beyond the initial m4sugar diversion 11965of @code{KILL}. 11966@end defmac 11967 11968@defmac m4_divert_push (@var{diversion}) 11969@msindex{divert_push} 11970Remember the former diversion on the diversion stack, and output 11971subsequent text into @var{diversion}. M4sugar maintains a diversion 11972stack, and issues an error if there is not a matching pop for every 11973push. 11974@end defmac 11975 11976@defmac m4_divert_text (@var{diversion}, @ovar{content}) 11977@msindex{divert_text} 11978Output @var{content} and a newline into @var{diversion}, without 11979affecting the current diversion. Shorthand for: 11980@example 11981m4_divert_push([@var{diversion}])@var{content} 11982m4_divert_pop([@var{diversion}])dnl 11983@end example 11984 11985One use of @code{m4_divert_text} is to develop two related macros, where 11986macro @samp{MY_A} does the work, but adjusts what work is performed 11987based on whether the optional macro @samp{MY_B} has also been expanded. 11988Of course, it is possible to use @code{AC_BEFORE} within @code{MY_A} to 11989require that @samp{MY_B} occurs first, if it occurs at all. But this 11990imposes an ordering restriction on the user; it would be nicer if macros 11991@samp{MY_A} and @samp{MY_B} can be invoked in either order. The trick 11992is to let @samp{MY_B} leave a breadcrumb in an early diversion, which 11993@samp{MY_A} can then use to determine whether @samp{MY_B} has been 11994expanded. 11995 11996@example 11997AC_DEFUN([MY_A], 11998[# various actions 11999if test -n "$b_was_used"; then 12000 # extra action 12001fi]) 12002AC_DEFUN([MY_B], 12003[AC_REQUIRE([MY_A])dnl 12004m4_divert_text([INIT_PREPARE], [b_was_used=true])]) 12005@end example 12006 12007@end defmac 12008 12009@defmac m4_init 12010@msindex{init} 12011Initialize the M4sugar environment, setting up the default named 12012diversion to be @code{KILL}. 12013@end defmac 12014 12015@node Conditional constructs 12016@subsection Conditional constructs 12017 12018The following macros provide additional conditional constructs as 12019convenience wrappers around @code{m4_if}. 12020 12021@defmac m4_bmatch (@var{string}, @var{regex-1}, @var{value-1}, @ 12022 @ovar{regex-2}, @ovar{value-2}, @dots{}, @ovar{default}) 12023@msindex{bmatch} 12024The string @var{string} is repeatedly compared against a series of 12025@var{regex} arguments; if a match is found, the expansion is the 12026corresponding @var{value}, otherwise, the macro moves on to the next 12027@var{regex}. If no @var{regex} match, then the result is the optional 12028@var{default}, or nothing. 12029@end defmac 12030 12031@defmac m4_bpatsubsts (@var{string}, @var{regex-1}, @var{subst-1}, @ 12032 @ovar{regex-2}, @ovar{subst-2}, @dots{}) 12033@msindex{bpatsubsts} 12034The string @var{string} is altered by @var{regex-1} and @var{subst-1}, 12035as if by: 12036@example 12037m4_bpatsubst([[@var{string}]], [@var{regex}], [@var{subst}]) 12038@end example 12039 12040@noindent 12041The result of the substitution is then passed through the next set of 12042@var{regex} and @var{subst}, and so forth. An empty @var{subst} implies 12043deletion of any matched portions in the current string. Note that this 12044macro over-quotes @var{string}; this behavior is intentional, so that 12045the result of each step of the recursion remains as a quoted string. 12046However, it means that anchors (@samp{^} and @samp{$} in the @var{regex} 12047will line up with the extra quotations, and not the characters of the 12048original string. The overquoting is removed after the final 12049substitution. 12050@end defmac 12051 12052@defmac m4_case (@var{string}, @var{value-1}, @var{if-value-1}, @ 12053 @ovar{value-2}, @ovar{if-value-2}, @dots{}, @ovar{default}) 12054@msindex{case} 12055Test @var{string} against multiple @var{value} possibilities, resulting 12056in the first @var{if-value} for a match, or in the optional 12057@var{default}. This is shorthand for: 12058@example 12059m4_if([@var{string}], [@var{value-1}], [@var{if-value-1}], 12060 [@var{string}], [@var{value-2}], [@var{if-value-2}], @dots{}, 12061 [@var{default}]) 12062@end example 12063@end defmac 12064 12065@defmac m4_cond (@var{test-1}, @var{value-1}, @var{if-value-1}, @ 12066 @ovar{test-2}, @ovar{value-2}, @ovar{if-value-2}, @dots{}, @ovar{default}) 12067@msindex{cond} 12068This macro was introduced in Autoconf 2.62. Similar to @code{m4_if}, 12069except that each @var{test} is expanded only when it is encountered. 12070This is useful for short-circuiting expensive tests; while @code{m4_if} 12071requires all its strings to be expanded up front before doing 12072comparisons, @code{m4_cond} only expands a @var{test} when all earlier 12073tests have failed. 12074 12075For an example, these two sequences give the same result, but in the 12076case where @samp{$1} does not contain a backslash, the @code{m4_cond} 12077version only expands @code{m4_index} once, instead of five times, for 12078faster computation if this is a common case for @samp{$1}. Notice that 12079every third argument is unquoted for @code{m4_if}, and quoted for 12080@code{m4_cond}: 12081 12082@example 12083m4_if(m4_index([$1], [\]), [-1], [$2], 12084 m4_eval(m4_index([$1], [\\]) >= 0), [1], [$2], 12085 m4_eval(m4_index([$1], [\$]) >= 0), [1], [$2], 12086 m4_eval(m4_index([$1], [\`]) >= 0), [1], [$3], 12087 m4_eval(m4_index([$1], [\"]) >= 0), [1], [$3], 12088 [$2]) 12089m4_cond([m4_index([$1], [\])], [-1], [$2], 12090 [m4_eval(m4_index([$1], [\\]) >= 0)], [1], [$2], 12091 [m4_eval(m4_index([$1], [\$]) >= 0)], [1], [$2], 12092 [m4_eval(m4_index([$1], [\`]) >= 0)], [1], [$3], 12093 [m4_eval(m4_index([$1], [\"]) >= 0)], [1], [$3], 12094 [$2]) 12095@end example 12096@end defmac 12097 12098@defmac m4_default (@var{expr-1}, @var{expr-2}) 12099@defmacx m4_default_quoted (@var{expr-1}, @var{expr-2}) 12100@defmacx m4_default_nblank (@var{expr-1}, @ovar{expr-2}) 12101@defmacx m4_default_nblank_quoted (@var{expr-1}, @ovar{expr-2}) 12102@msindex{default} 12103@msindex{default_quoted} 12104@msindex{default_nblank} 12105@msindex{default_nblank_quoted} 12106If @var{expr-1} contains text, use it. Otherwise, select @var{expr-2}. 12107@code{m4_default} expands the result, while @code{m4_default_quoted} 12108does not. Useful for providing a fixed default if the expression that 12109results in @var{expr-1} would otherwise be empty. The difference 12110between @code{m4_default} and @code{m4_default_nblank} is whether an 12111argument consisting of just blanks (space, tab, newline) is 12112significant. When using the expanding versions, note that an argument 12113may contain text but still expand to an empty string. 12114 12115@example 12116m4_define([active], [ACTIVE])dnl 12117m4_define([empty], [])dnl 12118m4_define([demo1], [m4_default([$1], [$2])])dnl 12119m4_define([demo2], [m4_default_quoted([$1], [$2])])dnl 12120m4_define([demo3], [m4_default_nblank([$1], [$2])])dnl 12121m4_define([demo4], [m4_default_nblank_quoted([$1], [$2])])dnl 12122demo1([active], [default]) 12123@result{}ACTIVE 12124demo1([], [active]) 12125@result{}ACTIVE 12126demo1([empty], [text]) 12127@result{} 12128-demo1([ ], [active])- 12129@result{}- - 12130demo2([active], [default]) 12131@result{}active 12132demo2([], [active]) 12133@result{}active 12134demo2([empty], [text]) 12135@result{}empty 12136-demo2([ ], [active])- 12137@result{}- - 12138demo3([active], [default]) 12139@result{}ACTIVE 12140demo3([], [active]) 12141@result{}ACTIVE 12142demo3([empty], [text]) 12143@result{} 12144-demo3([ ], [active])- 12145@result{}-ACTIVE- 12146demo4([active], [default]) 12147@result{}active 12148demo4([], [active]) 12149@result{}active 12150demo4([empty], [text]) 12151@result{}empty 12152-demo4([ ], [active])- 12153@result{}-active- 12154@end example 12155@end defmac 12156 12157@defmac m4_define_default (@var{macro}, @ovar{default-definition}) 12158@msindex{define_default} 12159If @var{macro} does not already have a definition, then define it to 12160@var{default-definition}. 12161@end defmac 12162 12163@defmac m4_ifblank (@var{cond}, @ovar{if-blank}, @ovar{if-text}) 12164@defmacx m4_ifnblank (@var{cond}, @ovar{if-text}, @ovar{if-blank}) 12165@msindex{ifblank} 12166@msindex{ifnblank} 12167If @var{cond} is empty or consists only of blanks (space, tab, newline), 12168then expand @var{if-blank}; otherwise, expand @var{if-text}. Two 12169variants exist, in order to make it easier to select the correct logical 12170sense when using only two parameters. Note that this is more efficient 12171than the equivalent behavior of: 12172@example 12173m4_ifval(m4_normalize([@var{cond}]), @var{if-text}, @var{if-blank}) 12174@end example 12175@end defmac 12176 12177@defmac m4_ifndef (@var{macro}, @var{if-not-defined}, @ovar{if-defined}) 12178@msindex{ifndef} 12179This is shorthand for: 12180@example 12181m4_ifdef([@var{macro}], [@var{if-defined}], [@var{if-not-defined}]) 12182@end example 12183@end defmac 12184 12185@defmac m4_ifset (@var{macro}, @ovar{if-true}, @ovar{if-false}) 12186@msindex{ifset} 12187If @var{macro} is undefined, or is defined as the empty string, expand 12188to @var{if-false}. Otherwise, expands to @var{if-true}. Similar to: 12189@example 12190m4_ifval(m4_defn([@var{macro}]), [@var{if-true}], [@var{if-false}]) 12191@end example 12192@noindent 12193except that it is not an error if @var{macro} is undefined. 12194@end defmac 12195 12196@defmac m4_ifval (@var{cond}, @ovar{if-true}, @ovar{if-false}) 12197@msindex{ifval} 12198Expands to @var{if-true} if @var{cond} is not empty, otherwise to 12199@var{if-false}. This is shorthand for: 12200@example 12201m4_if([@var{cond}], [], [@var{if-false}], [@var{if-true}]) 12202@end example 12203@end defmac 12204 12205@defmac m4_ifvaln (@var{cond}, @ovar{if-true}, @ovar{if-false}) 12206@msindex{ifvaln} 12207Similar to @code{m4_ifval}, except guarantee that a newline is present 12208after any non-empty expansion. Often followed by @code{dnl}. 12209@end defmac 12210 12211@defmac m4_n (@var{text}) 12212@msindex{n} 12213Expand to @var{text}, and add a newline if @var{text} is not empty. 12214Often followed by @code{dnl}. 12215@end defmac 12216 12217 12218@node Looping constructs 12219@subsection Looping constructs 12220 12221The following macros are useful in implementing recursive algorithms in 12222M4, including loop operations. An M4 list is formed by quoting a list 12223of quoted elements; generally the lists are comma-separated, although 12224@code{m4_foreach_w} is whitespace-separated. For example, the list 12225@samp{[[a], [b,c]]} contains two elements: @samp{[a]} and @samp{[b,c]}. 12226It is common to see lists with unquoted elements when those elements are 12227not likely to be macro names, as in @samp{[fputc_unlocked, 12228fgetc_unlocked]}. 12229 12230Although not generally recommended, it is possible for quoted lists to 12231have side effects; all side effects are expanded only once, and prior to 12232visiting any list element. On the other hand, the fact that unquoted 12233macros are expanded exactly once means that macros without side effects 12234can be used to generate lists. For example, 12235 12236@example 12237m4_foreach([i], [[1], [2], [3]m4_errprintn([hi])], [i]) 12238@error{}hi 12239@result{}123 12240m4_define([list], [[1], [2], [3]]) 12241@result{} 12242m4_foreach([i], [list], [i]) 12243@result{}123 12244@end example 12245 12246@defmac m4_argn (@var{n}, @ovar{arg}@dots{}) 12247@msindex{argn} 12248Extracts argument @var{n} (larger than 0) from the remaining arguments. 12249If there are too few arguments, the empty string is used. For any 12250@var{n} besides 1, this is more efficient than the similar 12251@samp{m4_car(m4_shiftn([@var{n}], [], [@var{arg}@dots{}]))}. 12252@end defmac 12253 12254@defmac m4_car (@var{arg}@dots{}) 12255@msindex{car} 12256Expands to the quoted first @var{arg}. Can be used with @code{m4_cdr} 12257to recursively iterate 12258through a list. Generally, when using quoted lists of quoted elements, 12259@code{m4_car} should be called without any extra quotes. 12260@end defmac 12261 12262@defmac m4_cdr (@var{arg}@dots{}) 12263@msindex{cdr} 12264Expands to a quoted list of all but the first @var{arg}, or the empty 12265string if there was only one argument. Generally, when using quoted 12266lists of quoted elements, @code{m4_cdr} should be called without any 12267extra quotes. 12268 12269For example, this is a simple implementation of @code{m4_map}; note how 12270each iteration checks for the end of recursion, then merely applies the 12271first argument to the first element of the list, then repeats with the 12272rest of the list. (The actual implementation in M4sugar is a bit more 12273involved, to gain some speed and share code with @code{m4_map_sep}, and 12274also to avoid expanding side effects in @samp{$2} twice). 12275@example 12276m4_define([m4_map], [m4_ifval([$2], 12277 [m4_apply([$1], m4_car($2))[]$0([$1], m4_cdr($2))])])dnl 12278m4_map([ m4_eval], [[[1]], [[1+1]], [[10],[16]]]) 12279@result{} 1 2 a 12280@end example 12281@end defmac 12282 12283@defmac m4_for (@var{var}, @var{first}, @var{last}, @ovar{step}, @ 12284 @var{expression}) 12285@msindex{for} 12286Loop over the numeric values between @var{first} and @var{last} 12287including bounds by increments of @var{step}. For each iteration, 12288expand @var{expression} with the numeric value assigned to @var{var}. 12289If @var{step} is omitted, it defaults to @samp{1} or @samp{-1} depending 12290on the order of the limits. If given, @var{step} has to match this 12291order. The number of iterations is determined independently from 12292definition of @var{var}; iteration cannot be short-circuited or 12293lengthened by modifying @var{var} from within @var{expression}. 12294@end defmac 12295 12296@defmac m4_foreach (@var{var}, @var{list}, @var{expression}) 12297@msindex{foreach} 12298Loop over the comma-separated M4 list @var{list}, assigning each value 12299to @var{var}, and expand @var{expression}. The following example 12300outputs two lines: 12301 12302@example 12303m4_foreach([myvar], [[foo], [bar, baz]], 12304 [echo myvar 12305])dnl 12306@result{}echo foo 12307@result{}echo bar, baz 12308@end example 12309 12310Note that for some forms of @var{expression}, it may be faster to use 12311@code{m4_map_args}. 12312@end defmac 12313 12314@anchor{m4_foreach_w} 12315@defmac m4_foreach_w (@var{var}, @var{list}, @var{expression}) 12316@msindex{foreach_w} 12317Loop over the white-space-separated list @var{list}, assigning each value 12318to @var{var}, and expand @var{expression}. If @var{var} is only 12319referenced once in @var{expression}, it is more efficient to use 12320@code{m4_map_args_w}. 12321 12322The deprecated macro @code{AC_FOREACH} is an alias of 12323@code{m4_foreach_w}. 12324@end defmac 12325 12326@defmac m4_map (@var{macro}, @var{list}) 12327@defmacx m4_mapall (@var{macro}, @var{list}) 12328@defmacx m4_map_sep (@var{macro}, @var{separator}, @var{list}) 12329@defmacx m4_mapall_sep (@var{macro}, @var{separator}, @var{list}) 12330@msindex{map} 12331@msindex{mapall} 12332@msindex{map_sep} 12333@msindex{mapall_sep} 12334Loop over the comma separated quoted list of argument descriptions in 12335@var{list}, and invoke @var{macro} with the arguments. An argument 12336description is in turn a comma-separated quoted list of quoted elements, 12337suitable for @code{m4_apply}. The macros @code{m4_map} and 12338@code{m4_map_sep} ignore empty argument descriptions, while 12339@code{m4_mapall} and @code{m4_mapall_sep} invoke @var{macro} with no 12340arguments. The macros @code{m4_map_sep} and @code{m4_mapall_sep} 12341additionally expand @var{separator} between invocations of @var{macro}. 12342 12343Note that @var{separator} is expanded, unlike in @code{m4_join}. When 12344separating output with commas, this means that the map result can be 12345used as a series of arguments, by using a single-quoted comma as 12346@var{separator}, or as a single string, by using a double-quoted comma. 12347 12348@example 12349m4_map([m4_count], []) 12350@result{} 12351m4_map([ m4_count], [[], 12352 [[1]], 12353 [[1], [2]]]) 12354@result{} 1 2 12355m4_mapall([ m4_count], [[], 12356 [[1]], 12357 [[1], [2]]]) 12358@result{} 0 1 2 12359m4_map_sep([m4_eval], [,], [[[1+2]], 12360 [[10], [16]]]) 12361@result{}3,a 12362m4_map_sep([m4_echo], [,], [[[a]], [[b]]]) 12363@result{}a,b 12364m4_count(m4_map_sep([m4_echo], [,], [[[a]], [[b]]])) 12365@result{}2 12366m4_map_sep([m4_echo], [[,]], [[[a]], [[b]]]) 12367@result{}a,b 12368m4_count(m4_map_sep([m4_echo], [[,]], [[[a]], [[b]]])) 12369@result{}1 12370@end example 12371@end defmac 12372 12373@defmac m4_map_args (@var{macro}, @var{arg}@dots{}) 12374@msindex{map_args} 12375Repeatedly invoke @var{macro} with each successive @var{arg} as its only 12376argument. In the following example, three solutions are presented with 12377the same expansion; the solution using @code{m4_map_args} is the most 12378efficient. 12379@example 12380m4_define([active], [ACTIVE])dnl 12381m4_foreach([var], [[plain], [active]], [ m4_echo(m4_defn([var]))]) 12382@result{} plain active 12383m4_map([ m4_echo], [[[plain]], [[active]]]) 12384@result{} plain active 12385m4_map_args([ m4_echo], [plain], [active]) 12386@result{} plain active 12387@end example 12388 12389In cases where it is useful to operate on additional parameters besides 12390the list elements, the macro @code{m4_curry} can be used in @var{macro} 12391to supply the argument currying necessary to generate the desired 12392argument list. In the following example, @code{list_add_n} is more 12393efficient than @code{list_add_x}. On the other hand, using 12394@code{m4_map_args_sep} can be even more efficient. 12395 12396@example 12397m4_define([list], [[1], [2], [3]])dnl 12398m4_define([add], [m4_eval(([$1]) + ([$2]))])dnl 12399dnl list_add_n(N, ARG...) 12400dnl Output a list consisting of each ARG added to N 12401m4_define([list_add_n], 12402[m4_shift(m4_map_args([,m4_curry([add], [$1])], m4_shift($@@)))])dnl 12403list_add_n([1], list) 12404@result{}2,3,4 12405list_add_n([2], list) 12406@result{}3,4,5 12407m4_define([list_add_x], 12408[m4_shift(m4_foreach([var], m4_dquote(m4_shift($@@)), 12409 [,add([$1],m4_defn([var]))]))])dnl 12410list_add_x([1], list) 12411@result{}2,3,4 12412@end example 12413@end defmac 12414 12415@defmac m4_map_args_pair (@var{macro}, @dvar{macro-end, macro}, @ 12416 @var{arg}@dots{}) 12417@msindex{map_args_pair} 12418For every pair of arguments @var{arg}, invoke @var{macro} with two 12419arguments. If there is an odd number of arguments, invoke 12420@var{macro-end}, which defaults to @var{macro}, with the remaining 12421argument. 12422 12423@example 12424m4_map_args_pair([, m4_reverse], [], [1], [2], [3]) 12425@result{}, 2, 1, 3 12426m4_map_args_pair([, m4_reverse], [, m4_dquote], [1], [2], [3]) 12427@result{}, 2, 1, [3] 12428m4_map_args_pair([, m4_reverse], [, m4_dquote], [1], [2], [3], [4]) 12429@result{}, 2, 1, 4, 3 12430@end example 12431@end defmac 12432 12433@defmac m4_map_args_sep (@ovar{pre}, @ovar{post}, @ovar{sep}, @var{arg}@dots{}) 12434@msindex{map_args_sep} 12435Expand the sequence @code{@var{pre}[@var{arg}]@var{post}} for each 12436argument, additionally expanding @var{sep} between arguments. One 12437common use of this macro is constructing a macro call, where the opening 12438and closing parentheses are split between @var{pre} and @var{post}; in 12439particular, @code{m4_map_args([@var{macro}], [@var{arg}])} is equivalent 12440to @code{m4_map_args_sep([@var{macro}(], [)], [], [@var{arg}])}. This 12441macro provides the most efficient means for iterating over an arbitrary 12442list of arguments, particularly when repeatedly constructing a macro 12443call with more arguments than @var{arg}. 12444@end defmac 12445 12446@defmac m4_map_args_w (@var{string}, @ovar{pre}, @ovar{post}, @ovar{sep}) 12447@msindex{map_args_w} 12448Expand the sequence @code{@var{pre}[word]@var{post}} for each word in 12449the whitespace-separated @var{string}, additionally expanding @var{sep} 12450between words. This macro provides the most efficient means for 12451iterating over a whitespace-separated string. In particular, 12452@code{m4_map_args_w([@var{string}], [@var{action}(], [)])} is more 12453efficient than @code{m4_foreach_w([var], [@var{string}], 12454[@var{action}(m4_defn([var]))])}. 12455@end defmac 12456 12457@defmac m4_shiftn (@var{count}, @dots{}) 12458@defmacx m4_shift2 (@dots{}) 12459@defmacx m4_shift3 (@dots{}) 12460@msindex{shift2} 12461@msindex{shift3} 12462@msindex{shiftn} 12463@code{m4_shiftn} performs @var{count} iterations of @code{m4_shift}, 12464along with validation that enough arguments were passed in to match the 12465shift count, and that the count is positive. @code{m4_shift2} and 12466@code{m4_shift3} are specializations 12467of @code{m4_shiftn}, introduced in Autoconf 2.62, and are more efficient 12468for two and three shifts, respectively. 12469@end defmac 12470 12471@defmac m4_stack_foreach (@var{macro}, @var{action}) 12472@defmacx m4_stack_foreach_lifo (@var{macro}, @var{action}) 12473@msindex{stack_foreach} 12474@msindex{stack_foreach_lifo} 12475For each of the @code{m4_pushdef} definitions of @var{macro}, expand 12476@var{action} with the single argument of a definition of @var{macro}. 12477@code{m4_stack_foreach} starts with the oldest definition, while 12478@code{m4_stack_foreach_lifo} starts with the current definition. 12479@var{action} should not push or pop definitions of @var{macro}, nor is 12480there any guarantee that the current definition of @var{macro} matches 12481the argument that was passed to @var{action}. The macro @code{m4_curry} 12482can be used if @var{action} needs more than one argument, although in 12483that case it is more efficient to use @var{m4_stack_foreach_sep}. 12484 12485Due to technical limitations, there are a few low-level m4sugar 12486functions, such as @code{m4_pushdef}, that cannot be used as the 12487@var{macro} argument. 12488 12489@example 12490m4_pushdef([a], [1])m4_pushdef([a], [2])dnl 12491m4_stack_foreach([a], [ m4_incr]) 12492@result{} 2 3 12493m4_stack_foreach_lifo([a], [ m4_curry([m4_substr], [abcd])]) 12494@result{} cd bcd 12495@end example 12496@end defmac 12497 12498@defmac m4_stack_foreach_sep (@var{macro}, @ovar{pre}, @ovar{post}, @ovar{sep}) 12499@defmacx m4_stack_foreach_sep_lifo (@var{macro}, @ovar{pre}, @ovar{post}, @ 12500 @ovar{sep}) 12501@msindex{stack_foreach_sep} 12502@msindex{stack_foreach_sep_lifo} 12503Expand the sequence @code{@var{pre}[definition]@var{post}} for each 12504@code{m4_pushdef} definition of @var{macro}, additionally expanding 12505@var{sep} between definitions. @code{m4_stack_foreach_sep} visits the 12506oldest definition first, while @code{m4_stack_foreach_sep_lifo} visits 12507the current definition first. This macro provides the most efficient 12508means for iterating over a pushdef stack. In particular, 12509@code{m4_stack_foreach([@var{macro}], [@var{action}])} is short for 12510@code{m4_stack_foreach_sep([@var{macro}], [@var{action}(], [)])}. 12511@end defmac 12512 12513@node Evaluation Macros 12514@subsection Evaluation Macros 12515 12516The following macros give some control over the order of the evaluation 12517by adding or removing levels of quotes. 12518 12519@defmac m4_apply (@var{macro}, @var{list}) 12520@msindex{apply} 12521Apply the elements of the quoted, comma-separated @var{list} as the 12522arguments to @var{macro}. If @var{list} is empty, invoke @var{macro} 12523without arguments. Note the difference between @code{m4_indir}, which 12524expects its first argument to be a macro name but can use names that are 12525otherwise invalid, and @code{m4_apply}, where @var{macro} can contain 12526other text, but must end in a valid macro name. 12527@example 12528m4_apply([m4_count], []) 12529@result{}0 12530m4_apply([m4_count], [[]]) 12531@result{}1 12532m4_apply([m4_count], [[1], [2]]) 12533@result{}2 12534m4_apply([m4_join], [[|], [1], [2]]) 12535@result{}1|2 12536@end example 12537@end defmac 12538 12539@defmac m4_count (@var{arg}, @dots{}) 12540@msindex{count} 12541This macro returns the decimal count of the number of arguments it was 12542passed. 12543@end defmac 12544 12545@defmac m4_curry (@var{macro}, @var{arg}@dots{}) 12546@msindex{curry} 12547This macro performs argument currying. The expansion of this macro is 12548another macro name that expects exactly one argument; that argument is 12549then appended to the @var{arg} list, and then @var{macro} is expanded 12550with the resulting argument list. 12551 12552@example 12553m4_curry([m4_curry], [m4_reverse], [1])([2])([3]) 12554@result{}3, 2, 1 12555@end example 12556 12557Unfortunately, due to a limitation in M4 1.4.x, it is not possible to 12558pass the definition of a builtin macro as the argument to the output of 12559@code{m4_curry}; the empty string is used instead of the builtin token. 12560This behavior is rectified by using M4 1.6 or newer. 12561@end defmac 12562 12563@defmac m4_do (@var{arg}, @dots{}) 12564@msindex{do} 12565This macro loops over its arguments and expands each @var{arg} in 12566sequence. Its main use is for readability; it allows the use of 12567indentation and fewer @code{dnl} to result in the same expansion. This 12568macro guarantees that no expansion will be concatenated with subsequent 12569text; to achieve full concatenation, use @code{m4_unquote(m4_join([], 12570@var{arg@dots{}}))}. 12571 12572@example 12573m4_define([ab],[1])m4_define([bc],[2])m4_define([abc],[3])dnl 12574m4_do([a],[b])c 12575@result{}abc 12576m4_unquote(m4_join([],[a],[b]))c 12577@result{}3 12578m4_define([a],[A])m4_define([b],[B])m4_define([c],[C])dnl 12579m4_define([AB],[4])m4_define([BC],[5])m4_define([ABC],[6])dnl 12580m4_do([a],[b])c 12581@result{}ABC 12582m4_unquote(m4_join([],[a],[b]))c 12583@result{}3 12584@end example 12585@end defmac 12586 12587@defmac m4_dquote (@var{arg}, @dots{}) 12588@msindex{dquote} 12589Return the arguments as a quoted list of quoted arguments. 12590Conveniently, if there is just one @var{arg}, this effectively adds a 12591level of quoting. 12592@end defmac 12593 12594@defmac m4_dquote_elt (@var{arg}, @dots{}) 12595@msindex{dquote_elt} 12596Return the arguments as a series of double-quoted arguments. Whereas 12597@code{m4_dquote} returns a single argument, @code{m4_dquote_elt} returns 12598as many arguments as it was passed. 12599@end defmac 12600 12601@defmac m4_echo (@var{arg}, @dots{}) 12602@msindex{echo} 12603Return the arguments, with the same level of quoting. Other than 12604discarding whitespace after unquoted commas, this macro is a no-op. 12605@end defmac 12606 12607@defmac m4_expand (@var{arg}) 12608@msindex{expand} 12609Return the expansion of @var{arg} as a quoted string. Whereas 12610@code{m4_quote} is designed to collect expanded text into a single 12611argument, @code{m4_expand} is designed to perform one level of expansion 12612on quoted text. One distinction is in the treatment of whitespace 12613following a comma in the original @var{arg}. Any time multiple 12614arguments are collected into one with @code{m4_quote}, the M4 argument 12615collection rules discard the whitespace. However, with @code{m4_expand}, 12616whitespace is preserved, even after the expansion of macros contained in 12617@var{arg}. Additionally, @code{m4_expand} is able to expand text that 12618would involve an unterminated comment, whereas expanding that same text 12619as the argument to @code{m4_quote} runs into difficulty in finding the 12620end of the argument. Since manipulating diversions during argument 12621collection is inherently unsafe, @code{m4_expand} issues an error if 12622@var{arg} attempts to change the current diversion (@pxref{Diversion 12623support}). 12624 12625@example 12626m4_define([active], [ACT, IVE])dnl 12627m4_define([active2], [[ACT, IVE]])dnl 12628m4_quote(active, active) 12629@result{}ACT,IVE,ACT,IVE 12630m4_expand([active, active]) 12631@result{}ACT, IVE, ACT, IVE 12632m4_quote(active2, active2) 12633@result{}ACT, IVE,ACT, IVE 12634m4_expand([active2, active2]) 12635@result{}ACT, IVE, ACT, IVE 12636m4_expand([# m4_echo]) 12637@result{}# m4_echo 12638m4_quote(# m4_echo) 12639) 12640@result{}# m4_echo) 12641@result{} 12642@end example 12643 12644Note that @code{m4_expand} cannot handle an @var{arg} that expands to 12645literal unbalanced quotes, but that quadrigraphs can be used when 12646unbalanced output is necessary. Likewise, unbalanced parentheses should 12647be supplied with double quoting or a quadrigraph. 12648 12649@example 12650m4_define([pattern], [[!@@<:@@]])dnl 12651m4_define([bar], [BAR])dnl 12652m4_expand([case $foo in 12653 m4_defn([pattern])@@:@}@@ bar ;; 12654 *[)] blah ;; 12655esac]) 12656@result{}case $foo in 12657@result{} [![]) BAR ;; 12658@result{} *) blah ;; 12659@result{}esac 12660@end example 12661@end defmac 12662 12663@defmac m4_ignore (@dots{}) 12664@msindex{ignore} 12665This macro was introduced in Autoconf 2.62. Expands to nothing, 12666ignoring all of its arguments. By itself, this isn't very useful. 12667However, it can be used to conditionally ignore an arbitrary number of 12668arguments, by deciding which macro name to apply to a list of arguments. 12669@example 12670dnl foo outputs a message only if [debug] is defined. 12671m4_define([foo], 12672[m4_ifdef([debug],[AC_MSG_NOTICE],[m4_ignore])([debug message])]) 12673@end example 12674 12675Note that for earlier versions of Autoconf, the macro @code{__gnu__} can 12676serve the same purpose, although it is less readable. 12677@end defmac 12678 12679@defmac m4_make_list (@var{arg}, @dots{}) 12680@msindex{make_list} 12681This macro exists to aid debugging of M4sugar algorithms. Its net 12682effect is similar to @code{m4_dquote}---it produces a quoted list of 12683quoted arguments, for each @var{arg}. The difference is that this 12684version uses a comma-newline separator instead of just comma, to improve 12685readability of the list; with the result that it is less efficient than 12686@code{m4_dquote}. 12687@example 12688m4_define([zero],[0])m4_define([one],[1])m4_define([two],[2])dnl 12689m4_dquote(zero, [one], [[two]]) 12690@result{}[0],[one],[[two]] 12691m4_make_list(zero, [one], [[two]]) 12692@result{}[0], 12693@result{}[one], 12694@result{}[[two]] 12695m4_foreach([number], m4_dquote(zero, [one], [[two]]), [ number]) 12696@result{} 0 1 two 12697m4_foreach([number], m4_make_list(zero, [one], [[two]]), [ number]) 12698@result{} 0 1 two 12699@end example 12700@end defmac 12701 12702@c m4_noquote is too dangerous to document - it invokes macros that 12703@c probably rely on @samp{[]} nested quoting for proper operation. The 12704@c user should generally prefer m4_unquote instead. 12705 12706@defmac m4_quote (@var{arg}, @dots{}) 12707@msindex{quote} 12708Return the arguments as a single entity, i.e., wrap them into a pair of 12709quotes. This effectively collapses multiple arguments into one, 12710although it loses whitespace after unquoted commas in the process. 12711@end defmac 12712 12713@defmac m4_reverse (@var{arg}, @dots{}) 12714@msindex{reverse} 12715Outputs each argument with the same level of quoting, but in reverse 12716order, and with space following each comma for readability. 12717 12718@example 12719m4_define([active], [ACT,IVE]) 12720@result{} 12721m4_reverse(active, [active]) 12722@result{}active, IVE, ACT 12723@end example 12724@end defmac 12725 12726@defmac m4_unquote (@var{arg}, @dots{}) 12727@msindex{unquote} 12728This macro was introduced in Autoconf 2.62. Expand each argument, 12729separated by commas. For a single @var{arg}, this effectively removes a 12730layer of quoting, and @code{m4_unquote([@var{arg}])} is more efficient 12731than the equivalent @code{m4_do([@var{arg}])}. For multiple arguments, 12732this results in an unquoted list of expansions. This is commonly used 12733with @code{m4_split}, in order to convert a single quoted list into a 12734series of quoted elements. 12735@end defmac 12736 12737The following example aims at emphasizing the difference between several 12738scenarios: not using these macros, using @code{m4_defn}, using 12739@code{m4_quote}, using @code{m4_dquote}, and using @code{m4_expand}. 12740 12741@example 12742$ @kbd{cat example.m4} 12743dnl Overquote, so that quotes are visible. 12744m4_define([show], [$[]1 = [$1], $[]@@ = [$@@]]) 12745m4_define([a], [A]) 12746m4_define([mkargs], [1, 2[,] 3]) 12747m4_define([arg1], [[$1]]) 12748m4_divert([0])dnl 12749show(a, b) 12750show([a, b]) 12751show(m4_quote(a, b)) 12752show(m4_dquote(a, b)) 12753show(m4_expand([a, b])) 12754 12755arg1(mkargs) 12756arg1([mkargs]) 12757arg1(m4_defn([mkargs])) 12758arg1(m4_quote(mkargs)) 12759arg1(m4_dquote(mkargs)) 12760arg1(m4_expand([mkargs])) 12761$ @kbd{autom4te -l m4sugar example.m4} 12762$1 = A, $@@ = [A],[b] 12763$1 = a, b, $@@ = [a, b] 12764$1 = A,b, $@@ = [A,b] 12765$1 = [A],[b], $@@ = [[A],[b]] 12766$1 = A, b, $@@ = [A, b] 12767 127681 12769mkargs 127701, 2[,] 3 127711,2, 3 12772[1],[2, 3] 127731, 2, 3 12774@end example 12775 12776 12777@node Text processing Macros 12778@subsection String manipulation in M4 12779 12780The following macros may be used to manipulate strings in M4. Many of 12781the macros in this section intentionally result in quoted strings as 12782output, rather than subjecting the arguments to further expansions. As 12783a result, if you are manipulating text that contains active M4 12784characters, the arguments are passed with single quoting rather than 12785double. 12786 12787@defmac m4_append (@var{macro-name}, @var{string}, @ovar{separator}) 12788@defmacx m4_append_uniq (@var{macro-name}, @var{string}, @ovar{separator} @ 12789 @ovar{if-uniq}, @ovar{if-duplicate}) 12790@msindex{append} 12791@msindex{append_uniq} 12792Redefine @var{macro-name} to its former contents with @var{separator} 12793and @var{string} added at the end. If @var{macro-name} was undefined 12794before (but not if it was defined but empty), then no @var{separator} is 12795added. As of Autoconf 2.62, neither @var{string} nor @var{separator} 12796are expanded during this macro; instead, they are expanded when 12797@var{macro-name} is invoked. 12798 12799@code{m4_append} can be used to grow strings, and @code{m4_append_uniq} 12800to grow strings without duplicating substrings. Additionally, 12801@code{m4_append_uniq} takes two optional parameters as of Autoconf 2.62; 12802@var{if-uniq} is expanded if @var{string} was appended, and 12803@var{if-duplicate} is expanded if @var{string} was already present. 12804Also, @code{m4_append_uniq} warns if @var{separator} is not empty, but 12805occurs within @var{string}, since that can lead to duplicates. 12806 12807Note that @code{m4_append} can scale linearly in the length of the final 12808string, depending on the quality of the underlying M4 implementation, 12809while @code{m4_append_uniq} has an inherent quadratic scaling factor. 12810If an algorithm can tolerate duplicates in the final string, use the 12811former for speed. If duplicates must be avoided, consider using 12812@code{m4_set_add} instead (@pxref{Set manipulation Macros}). 12813 12814@example 12815m4_define([active], [ACTIVE])dnl 12816m4_append([sentence], [This is an])dnl 12817m4_append([sentence], [ active ])dnl 12818m4_append([sentence], [symbol.])dnl 12819sentence 12820@result{}This is an ACTIVE symbol. 12821m4_undefine([active])dnl 12822@result{}This is an active symbol. 12823m4_append_uniq([list], [one], [, ], [new], [existing]) 12824@result{}new 12825m4_append_uniq([list], [one], [, ], [new], [existing]) 12826@result{}existing 12827m4_append_uniq([list], [two], [, ], [new], [existing]) 12828@result{}new 12829m4_append_uniq([list], [three], [, ], [new], [existing]) 12830@result{}new 12831m4_append_uniq([list], [two], [, ], [new], [existing]) 12832@result{}existing 12833list 12834@result{}one, two, three 12835m4_dquote(list) 12836@result{}[one],[two],[three] 12837m4_append([list2], [one], [[, ]])dnl 12838m4_append_uniq([list2], [two], [[, ]])dnl 12839m4_append([list2], [three], [[, ]])dnl 12840list2 12841@result{}one, two, three 12842m4_dquote(list2) 12843@result{}[one, two, three] 12844@end example 12845@end defmac 12846 12847@defmac m4_append_uniq_w (@var{macro-name}, @var{strings}) 12848@msindex{append_uniq_w} 12849This macro was introduced in Autoconf 2.62. It is similar to 12850@code{m4_append_uniq}, but treats @var{strings} as a whitespace 12851separated list of words to append, and only appends unique words. 12852@var{macro-name} is updated with a single space between new words. 12853@example 12854m4_append_uniq_w([numbers], [1 1 2])dnl 12855m4_append_uniq_w([numbers], [ 2 3 ])dnl 12856numbers 12857@result{}1 2 3 12858@end example 12859@end defmac 12860 12861@defmac m4_chomp (@var{string}) 12862@defmacx m4_chomp_all (@var{string}) 12863@msindex{chomp} 12864@msindex{chomp_all} 12865Output @var{string} in quotes, but without a trailing newline. The 12866macro @code{m4_chomp} is slightly faster, and removes at most one 12867newline; the macro @code{m4_chomp_all} removes all consecutive trailing 12868newlines. Unlike @code{m4_flatten}, embedded newlines are left intact, 12869and backslash does not influence the result. 12870@end defmac 12871 12872@defmac m4_combine (@ovar{separator}, @var{prefix-list}, @ovar{infix}, @ 12873 @var{suffix-1}, @ovar{suffix-2}, @dots{}) 12874@msindex{combine} 12875This macro produces a quoted string containing the pairwise combination 12876of every element of the quoted, comma-separated @var{prefix-list}, and 12877every element from the @var{suffix} arguments. Each pairwise 12878combination is joined with @var{infix} in the middle, and successive 12879pairs are joined by @var{separator}. No expansion occurs on any of the 12880arguments. No output occurs if either the @var{prefix} or @var{suffix} 12881list is empty, but the lists can contain empty elements. 12882@example 12883m4_define([a], [oops])dnl 12884m4_combine([, ], [[a], [b], [c]], [-], [1], [2], [3]) 12885@result{}a-1, a-2, a-3, b-1, b-2, b-3, c-1, c-2, c-3 12886m4_combine([, ], [[a], [b]], [-]) 12887@result{} 12888m4_combine([, ], [[a], [b]], [-], []) 12889@result{}a-, b- 12890m4_combine([, ], [], [-], [1], [2]) 12891@result{} 12892m4_combine([, ], [[]], [-], [1], [2]) 12893@result{}-1, -2 12894@end example 12895@end defmac 12896 12897@defmac m4_escape (@var{string}) 12898@msindex{escape} 12899Convert all instances of @samp{[}, @samp{]}, @samp{#}, and @samp{$} 12900within @var{string} into their respective quadrigraphs. The result is 12901still a quoted string. 12902@end defmac 12903 12904@defmac m4_flatten (@var{string}) 12905@msindex{flatten} 12906Flatten @var{string} into a single line. Delete all backslash-newline 12907pairs, and replace all remaining newlines with a space. The result is 12908still a quoted string. 12909@end defmac 12910 12911@defmac m4_join (@ovar{separator}, @var{args}@dots{}) 12912@defmacx m4_joinall (@ovar{separator}, @var{args}@dots{}) 12913@msindex{join} 12914@msindex{joinall} 12915Concatenate each @var{arg}, separated by @var{separator}. 12916@code{joinall} uses every argument, while @code{join} omits empty 12917arguments so that there are no back-to-back separators in the output. 12918The result is a quoted string. 12919@example 12920m4_define([active], [ACTIVE])dnl 12921m4_join([|], [one], [], [active], [two]) 12922@result{}one|active|two 12923m4_joinall([|], [one], [], [active], [two]) 12924@result{}one||active|two 12925@end example 12926 12927Note that if all you intend to do is join @var{args} with commas between 12928them, to form a quoted list suitable for @code{m4_foreach}, it is more 12929efficient to use @code{m4_dquote}. 12930@end defmac 12931 12932@defmac m4_newline (@ovar{text}) 12933@msindex{newline} 12934This macro was introduced in Autoconf 2.62, and expands to a newline, 12935followed by any @var{text}. 12936It is primarily useful for maintaining macro formatting, and ensuring 12937that M4 does not discard leading whitespace during argument collection. 12938@end defmac 12939 12940@defmac m4_normalize (@var{string}) 12941@msindex{normalize} 12942Remove leading and trailing spaces and tabs, sequences of 12943backslash-then-newline, and replace multiple spaces, tabs, and newlines 12944with a single space. This is a combination of @code{m4_flatten} and 12945@code{m4_strip}. To determine if @var{string} consists only of bytes 12946that would be removed by @code{m4_normalize}, you can use 12947@code{m4_ifblank}. 12948@end defmac 12949 12950@defmac m4_re_escape (@var{string}) 12951@msindex{re_escape} 12952Backslash-escape all characters in @var{string} that are active in 12953regexps. 12954@end defmac 12955 12956@c We cannot use @dvar because the macro expansion mistreats backslashes. 12957@defmac m4_split (@var{string}, @r{[}@var{regexp} = @samp{[\t ]+}@r{]}) 12958@msindex{split} 12959Split @var{string} into an M4 list of elements quoted by @samp{[} and 12960@samp{]}, while keeping white space at the beginning and at the end. 12961If @var{regexp} is given, use it instead of @samp{[\t ]+} for splitting. 12962If @var{string} is empty, the result is an empty list. 12963@end defmac 12964 12965@defmac m4_strip (@var{string}) 12966@msindex{strip} 12967Strip whitespace from @var{string}. Sequences of spaces and tabs are 12968reduced to a single space, then leading and trailing spaces are removed. 12969The result is still a quoted string. Note that this does not interfere 12970with newlines; if you want newlines stripped as well, consider 12971@code{m4_flatten}, or do it all at once with @code{m4_normalize}. To 12972quickly test if @var{string} has only whitespace, use @code{m4_ifblank}. 12973@end defmac 12974 12975@defmac m4_text_box (@var{message}, @dvar{frame, -}) 12976@msindex{text_box} 12977Add a text box around @var{message}, using @var{frame} as the border 12978character above and below the message. The @var{frame} argument must be 12979a single byte, and does not support quadrigraphs. 12980The frame correctly accounts for 12981the subsequent expansion of @var{message}. For example: 12982@example 12983m4_define([macro], [abc])dnl 12984m4_text_box([macro]) 12985@result{}## --- ## 12986@result{}## abc ## 12987@result{}## --- ## 12988@end example 12989 12990The @var{message} must contain balanced quotes and parentheses, although 12991quadrigraphs can be used to work around this. 12992@end defmac 12993 12994@defmac m4_text_wrap (@var{string}, @ovar{prefix}, @ 12995 @dvar{prefix1, @var{prefix}}, @dvar{width, 79}) 12996@msindex{text_wrap} 12997Break @var{string} into a series of whitespace-separated words, then 12998output those words separated by spaces, and wrapping lines any time the 12999output would exceed @var{width} columns. If given, @var{prefix1} begins 13000the first line, and @var{prefix} begins all wrapped lines. If 13001@var{prefix1} is longer than @var{prefix}, then the first line consists 13002of just @var{prefix1}. If @var{prefix} is longer than @var{prefix1}, 13003padding is inserted so that the first word of @var{string} begins at the 13004same indentation as all wrapped lines. Note that using literal tab 13005characters in any of the arguments will interfere with the calculation 13006of width. No expansions occur on @var{prefix}, @var{prefix1}, or the 13007words of @var{string}, although quadrigraphs are recognized. 13008 13009For some examples: 13010@example 13011m4_text_wrap([Short string */], [ ], [/* ], [20]) 13012@result{}/* Short string */ 13013m4_text_wrap([Much longer string */], [ ], [/* ], [20]) 13014@result{}/* Much longer 13015@result{} string */ 13016m4_text_wrap([Short doc.], [ ], [ --short ], [30]) 13017@result{} --short Short doc. 13018m4_text_wrap([Short doc.], [ ], [ --too-wide ], [30]) 13019@result{} --too-wide 13020@result{} Short doc. 13021m4_text_wrap([Super long documentation.], [ ], 13022 [ --too-wide ], 30) 13023@result{} --too-wide 13024@result{} Super long 13025@result{} documentation. 13026@end example 13027@end defmac 13028 13029@defmac m4_tolower (@var{string}) 13030@defmacx m4_toupper (@var{string}) 13031@msindex{tolower} 13032@msindex{toupper} 13033Return @var{string} with letters converted to upper or lower case, 13034respectively. 13035@end defmac 13036 13037@node Number processing Macros 13038@subsection Arithmetic computation in M4 13039 13040The following macros facilitate integer arithmetic operations. 13041Where a parameter is documented as taking an arithmetic expression, you 13042can use anything that can be parsed by @code{m4_eval}. 13043 13044@defmac m4_cmp (@var{expr-1}, @var{expr-2}) 13045@msindex{cmp} 13046Compare the arithmetic expressions @var{expr-1} and @var{expr-2}, and 13047expand to @samp{-1} if @var{expr-1} is smaller, @samp{0} if they are 13048equal, and @samp{1} if @var{expr-1} is larger. 13049@end defmac 13050 13051@defmac m4_list_cmp (@var{list-1}, @var{list-2}) 13052@msindex{list_cmp} 13053Compare the two M4 lists consisting of comma-separated arithmetic 13054expressions, left to right. Expand to @samp{-1} for the first element 13055pairing where the value from @var{list-1} is smaller, @samp{1} where the 13056value from @var{list-2} is smaller, or @samp{0} if both lists have the 13057same values. If one list is shorter than the other, the remaining 13058elements of the longer list are compared against zero. 13059@example 13060m4_list_cmp([1, 0], [1]) 13061@result{}0 13062m4_list_cmp([1, [1 * 0]], [1, 0]) 13063@result{}0 13064m4_list_cmp([1, 2], [1, 0]) 13065@result{}1 13066m4_list_cmp([1, [1+1], 3],[1, 2]) 13067@result{}1 13068m4_list_cmp([1, 2, -3], [1, 2]) 13069@result{}-1 13070m4_list_cmp([1, 0], [1, 2]) 13071@result{}-1 13072m4_list_cmp([1], [1, 2]) 13073@result{}-1 13074@end example 13075@end defmac 13076 13077@defmac m4_max (@var{arg}, @dots{}) 13078@msindex{max} 13079This macro was introduced in Autoconf 2.62. Expand to the decimal value 13080of the maximum arithmetic expression among all the arguments. 13081@end defmac 13082 13083@defmac m4_min (@var{arg}, @dots{}) 13084@msindex{min} 13085This macro was introduced in Autoconf 2.62. Expand to the decimal value 13086of the minimum arithmetic expression among all the arguments. 13087@end defmac 13088 13089@defmac m4_sign (@var{expr}) 13090@msindex{sign} 13091Expand to @samp{-1} if the arithmetic expression @var{expr} is negative, 13092@samp{1} if it is positive, and @samp{0} if it is zero. 13093@end defmac 13094 13095@anchor{m4_version_compare} 13096@defmac m4_version_compare (@var{version-1}, @var{version-2}) 13097@msindex{version_compare} 13098This macro was introduced in Autoconf 2.53, but had a number of 13099usability limitations that were not lifted until Autoconf 2.62. Compare 13100the version strings @var{version-1} and @var{version-2}, and expand to 13101@samp{-1} if @var{version-1} is smaller, @samp{0} if they are the same, 13102or @samp{1} @var{version-2} is smaller. Version strings must be a list 13103of elements separated by @samp{.}, @samp{,} or @samp{-}, where each 13104element is a number along with optional case-insensitive letters 13105designating beta releases. The comparison stops at the leftmost element 13106that contains a difference, although a 0 element compares equal to a 13107missing element. 13108 13109It is permissible to include commit identifiers in @var{version}, such 13110as an abbreviated SHA1 of the commit, provided there is still a 13111monotonically increasing prefix to allow for accurate version-based 13112comparisons. For example, this paragraph was written when the 13113development snapshot of autoconf claimed to be at version 13114@samp{2.61a-248-dc51}, or 248 commits after the 2.61a release, with an 13115abbreviated commit identification of @samp{dc51}. 13116 13117@example 13118m4_version_compare([1.1], [2.0]) 13119@result{}-1 13120m4_version_compare([2.0b], [2.0a]) 13121@result{}1 13122m4_version_compare([1.1.1], [1.1.1a]) 13123@result{}-1 13124m4_version_compare([1.2], [1.1.1a]) 13125@result{}1 13126m4_version_compare([1.0], [1]) 13127@result{}0 13128m4_version_compare([1.1pre], [1.1PRE]) 13129@result{}0 13130m4_version_compare([1.1a], [1,10]) 13131@result{}-1 13132m4_version_compare([2.61a], [2.61a-248-dc51]) 13133@result{}-1 13134m4_version_compare([2.61b], [2.61a-248-dc51]) 13135@result{}1 13136@end example 13137@end defmac 13138 13139@defmac m4_version_prereq (@var{version}, @ovar{if-new-enough}, @ 13140 @dvar{if-old, m4_fatal}) 13141@msindex{version_prereq} 13142Compares @var{version} against the version of Autoconf currently 13143running. If the running version is at @var{version} or newer, expand 13144@var{if-new-enough}, but if @var{version} is larger than the version 13145currently executing, expand @var{if-old}, which defaults to printing an 13146error message and exiting m4sugar with status 63. When given only one 13147argument, this behaves like @code{AC_PREREQ} (@pxref{Versioning}). 13148Remember that the autoconf philosophy favors feature checks over version 13149checks. 13150@end defmac 13151 13152@node Set manipulation Macros 13153@subsection Set manipulation in M4 13154@cindex Set manipulation 13155@cindex Data structure, set 13156@cindex Unordered set manipulation 13157 13158Sometimes, it is necessary to track a set of data, where the order does 13159not matter and where there are no duplicates in the set. The following 13160macros facilitate set manipulations. Each set is an opaque object, 13161which can only be accessed via these basic operations. The underlying 13162implementation guarantees linear scaling for set creation, which is more 13163efficient than using the quadratic @code{m4_append_uniq}. Both set 13164names and values can be arbitrary strings, except for unbalanced quotes. 13165This implementation ties up memory for removed elements until the next 13166operation that must traverse all the elements of a set; and although 13167that may slow down some operations until the memory for removed elements 13168is pruned, it still guarantees linear performance. 13169 13170@defmac m4_set_add (@var{set}, @var{value}, @ovar{if-uniq}, @ovar{if-dup}) 13171@msindex{set_add} 13172Adds the string @var{value} as a member of set @var{set}. Expand 13173@var{if-uniq} if the element was added, or @var{if-dup} if it was 13174previously in the set. Operates in amortized constant time, so that set 13175creation scales linearly. 13176@end defmac 13177 13178@defmac m4_set_add_all (@var{set}, @var{value}@dots{}) 13179@msindex{set_add_all} 13180Adds each @var{value} to the set @var{set}. This is slightly more 13181efficient than repeatedly invoking @code{m4_set_add}. 13182@end defmac 13183 13184@defmac m4_set_contains (@var{set}, @var{value}, @ovar{if-present}, @ 13185 @ovar{if-absent}) 13186@msindex{set_contains} 13187Expands @var{if-present} if the string @var{value} is a member of 13188@var{set}, otherwise @var{if-absent}. 13189 13190@example 13191m4_set_contains([a], [1], [yes], [no]) 13192@result{}no 13193m4_set_add([a], [1], [added], [dup]) 13194@result{}added 13195m4_set_add([a], [1], [added], [dup]) 13196@result{}dup 13197m4_set_contains([a], [1], [yes], [no]) 13198@result{}yes 13199m4_set_remove([a], [1], [removed], [missing]) 13200@result{}removed 13201m4_set_contains([a], [1], [yes], [no]) 13202@result{}no 13203m4_set_remove([a], [1], [removed], [missing]) 13204@result{}missing 13205@end example 13206@end defmac 13207 13208@defmac m4_set_contents (@var{set}, @ovar{sep}) 13209@defmacx m4_set_dump (@var{set}, @ovar{sep}) 13210@msindex{set_contents} 13211@msindex{set_dump} 13212Expands to a single string consisting of all the members of the set 13213@var{set}, each separated by @var{sep}, which is not expanded. 13214@code{m4_set_contents} leaves the elements in @var{set} but reclaims any 13215memory occupied by removed elements, while @code{m4_set_dump} is a 13216faster one-shot action that also deletes the set. No provision is made 13217for disambiguating members that contain a non-empty @var{sep} as a 13218substring; use @code{m4_set_empty} to distinguish between an empty set 13219and the set containing only the empty string. The order of the output 13220is unspecified; in the current implementation, part of the speed of 13221@code{m4_set_dump} results from using a different output order than 13222@code{m4_set_contents}. These macros scale linearly in the size of the 13223set before memory pruning, and @code{m4_set_contents([@var{set}], 13224[@var{sep}])} is faster than 13225@code{m4_joinall([@var{sep}]m4_set_listc([@var{set}]))}. 13226 13227@example 13228m4_set_add_all([a], [1], [2], [3]) 13229@result{} 13230m4_set_contents([a], [-]) 13231@result{}1-2-3 13232m4_joinall([-]m4_set_listc([a])) 13233@result{}1-2-3 13234m4_set_dump([a], [-]) 13235@result{}3-2-1 13236m4_set_contents([a]) 13237@result{} 13238m4_set_add([a], []) 13239@result{} 13240m4_set_contents([a], [-]) 13241@result{} 13242@end example 13243@end defmac 13244 13245@defmac m4_set_delete (@var{set}) 13246@msindex{set_delete} 13247Delete all elements and memory associated with @var{set}. This is 13248linear in the set size, and faster than removing one element at a time. 13249@end defmac 13250 13251@defmac m4_set_difference (@var{seta}, @var{setb}) 13252@defmacx m4_set_intersection (@var{seta}, @var{setb}) 13253@defmacx m4_set_union (@var{seta}, @var{setb}) 13254@msindex{set_difference} 13255@msindex{set_intersection} 13256@msindex{set_union} 13257Compute the relation between @var{seta} and @var{setb}, and output the 13258result as a list of quoted arguments without duplicates and with a 13259leading comma. Set difference selects the elements in @var{seta} but 13260not @var{setb}, intersection selects only elements in both sets, and 13261union selects elements in either set. These actions are linear in the 13262sum of the set sizes. The leading comma is necessary to distinguish 13263between no elements and the empty string as the only element. 13264 13265@example 13266m4_set_add_all([a], [1], [2], [3]) 13267@result{} 13268m4_set_add_all([b], [3], [], [4]) 13269@result{} 13270m4_set_difference([a], [b]) 13271@result{},1,2 13272m4_set_difference([b], [a]) 13273@result{},,4 13274m4_set_intersection([a], [b]) 13275@result{},3 13276m4_set_union([a], [b]) 13277@result{},1,2,3,,4 13278@end example 13279@end defmac 13280 13281@defmac m4_set_empty (@var{set}, @ovar{if-empty}, @ovar{if-elements}) 13282@msindex{set_empty} 13283Expand @var{if-empty} if the set @var{set} has no elements, otherwise 13284expand @var{if-elements}. This macro operates in constant time. Using 13285this macro can help disambiguate output from @code{m4_set_contents} or 13286@code{m4_set_list}. 13287@end defmac 13288 13289@defmac m4_set_foreach (@var{set}, @var{variable}, @var{action}) 13290@msindex{set_foreach} 13291For each element in the set @var{set}, expand @var{action} with the 13292macro @var{variable} defined as the set element. Behavior is 13293unspecified if @var{action} recursively lists the contents of @var{set} 13294(although listing other sets is acceptable), or if it modifies the set 13295in any way other than removing the element currently contained in 13296@var{variable}. This macro is faster than the corresponding 13297@code{m4_foreach([@var{variable}], 13298m4_indir([m4_dquote]m4_set_listc([@var{set}])), [@var{action}])}, 13299although @code{m4_set_map} might be faster still. 13300 13301@example 13302m4_set_add_all([a]m4_for([i], [1], [5], [], [,i])) 13303@result{} 13304m4_set_contents([a]) 13305@result{}12345 13306m4_set_foreach([a], [i], 13307 [m4_if(m4_eval(i&1), [0], [m4_set_remove([a], i, [i])])]) 13308@result{}24 13309m4_set_contents([a]) 13310@result{}135 13311@end example 13312@end defmac 13313 13314@defmac m4_set_list (@var{set}) 13315@defmacx m4_set_listc (@var{set}) 13316@msindex{set_list} 13317@msindex{set_listc} 13318Produce a list of arguments, where each argument is a quoted element 13319from the set @var{set}. The variant @code{m4_set_listc} is unambiguous, 13320by adding a leading comma if there are any set elements, whereas the 13321variant @code{m4_set_list} cannot distinguish between an empty set and a 13322set containing only the empty string. These can be directly used in 13323macros that take multiple arguments, such as @code{m4_join} or 13324@code{m4_set_add_all}, or wrapped by @code{m4_dquote} for macros that 13325take a quoted list, such as @code{m4_map} or @code{m4_foreach}. Any 13326memory occupied by removed elements is reclaimed during these macros. 13327 13328@example 13329m4_set_add_all([a], [1], [2], [3]) 13330@result{} 13331m4_set_list([a]) 13332@result{}1,2,3 13333m4_set_list([b]) 13334@result{} 13335m4_set_listc([b]) 13336@result{} 13337m4_count(m4_set_list([b])) 13338@result{}1 13339m4_set_empty([b], [0], [m4_count(m4_set_list([b]))]) 13340@result{}0 13341m4_set_add([b], []) 13342@result{} 13343m4_set_list([b]) 13344@result{} 13345m4_set_listc([b]) 13346@result{}, 13347m4_count(m4_set_list([b])) 13348@result{}1 13349m4_set_empty([b], [0], [m4_count(m4_set_list([b]))]) 13350@result{}1 13351@end example 13352@end defmac 13353 13354@defmac m4_set_map (@var{set}, @var{action}) 13355@msindex{set_map} 13356For each element in the set @var{set}, expand @var{action} with a single 13357argument of the set element. Behavior is unspecified if @var{action} 13358recursively lists the contents of @var{set} (although listing other sets 13359is acceptable), or if it modifies the set in any way other than removing 13360the element passed as an argument. This macro is faster than either 13361corresponding counterpart of 13362@code{m4_map_args([@var{action}]m4_set_listc([@var{set}]))} or 13363@code{m4_set_foreach([@var{set}], [var], 13364[@var{action}(m4_defn([var]))])}. It is possible to use @code{m4_curry} 13365if more than one argument is needed for @var{action}, although it is 13366more efficient to use @code{m4_set_map_sep} in that case. 13367@end defmac 13368 13369@defmac m4_set_map_sep (@var{set}, @ovar{pre}, @ovar{post}, @ovar{sep}) 13370@msindex{set_map_sep} 13371For each element in the set @var{set}, expand 13372@code{@var{pre}[element]@var{post}}, additionally expanding @var{sep} 13373between elements. Behavior is unspecified if the expansion recursively 13374lists the contents of @var{set} (although listing other sets 13375is acceptable), or if it modifies the set in any way other than removing 13376the element visited by the expansion. This macro provides the most 13377efficient means for non-destructively visiting the elements of a set; in 13378particular, @code{m4_set_map([@var{set}], [@var{action}])} is equivalent 13379to @code{m4_set_map_sep([@var{set}], [@var{action}(], [)])}. 13380@end defmac 13381 13382@defmac m4_set_remove (@var{set}, @var{value}, @ovar{if-present}, @ 13383 @ovar{if-absent}) 13384@msindex{set_remove} 13385If @var{value} is an element in the set @var{set}, then remove it and 13386expand @var{if-present}. Otherwise expand @var{if-absent}. This macro 13387operates in constant time so that multiple removals will scale linearly 13388rather than quadratically; but when used outside of 13389@code{m4_set_foreach} or @code{m4_set_map}, it leaves memory occupied 13390until the set is later 13391compacted by @code{m4_set_contents} or @code{m4_set_list}. Several 13392other set operations are then less efficient between the time of element 13393removal and subsequent memory compaction, but still maintain their 13394guaranteed scaling performance. 13395@end defmac 13396 13397@defmac m4_set_size (@var{set}) 13398@msindex{set_size} 13399Expand to the size of the set @var{set}. This implementation operates 13400in constant time, and is thus more efficient than 13401@code{m4_eval(m4_count(m4_set_listc([set])) - 1)}. 13402@end defmac 13403 13404 13405@node Forbidden Patterns 13406@subsection Forbidden Patterns 13407@cindex Forbidden patterns 13408@cindex Patterns, forbidden 13409 13410M4sugar provides a means to define suspicious patterns, patterns 13411describing tokens which should not be found in the output. For 13412instance, if an Autoconf @file{configure} script includes tokens such as 13413@samp{AC_DEFINE}, or @samp{dnl}, then most probably something went 13414wrong (typically a macro was not evaluated because of overquotation). 13415 13416M4sugar forbids all the tokens matching @samp{^_?m4_} and @samp{^dnl$}. 13417Additional layers, such as M4sh and Autoconf, add additional forbidden 13418patterns to the list. 13419 13420@defmac m4_pattern_forbid (@var{pattern}) 13421@msindex{pattern_forbid} 13422Declare that no token matching @var{pattern} must be found in the output. 13423Comments are not checked; this can be a problem if, for instance, you 13424have some macro left unexpanded after an @samp{#include}. No consensus 13425is currently found in the Autoconf community, as some people consider it 13426should be valid to name macros in comments (which doesn't make sense to 13427the authors of this documentation: input, such as macros, should be 13428documented by @samp{dnl} comments; reserving @samp{#}-comments to 13429document the output). 13430@end defmac 13431 13432Of course, you might encounter exceptions to these generic rules, for 13433instance you might have to refer to @samp{$m4_flags}. 13434 13435@defmac m4_pattern_allow (@var{pattern}) 13436@msindex{pattern_allow} 13437Any token matching @var{pattern} is allowed, including if it matches an 13438@code{m4_pattern_forbid} pattern. 13439@end defmac 13440 13441@node Debugging via autom4te 13442@section Debugging via autom4te 13443@cindex debugging tips 13444@cindex autom4te debugging tips 13445@cindex m4sugar debugging tips 13446At times, it is desirable to see what was happening inside m4, to see 13447why output was not matching expectations. However, post-processing done 13448by @command{autom4te} means that directly using the m4 builtin 13449@code{m4_traceon} is likely to interfere with operation. Also, frequent 13450diversion changes and the concept of forbidden tokens make it difficult 13451to use @code{m4_defn} to generate inline comments in the final output. 13452 13453There are a couple of tools to help with this. One is the use of the 13454@option{--trace} option provided by @command{autom4te} (as well as each 13455of the programs that wrap @command{autom4te}, such as 13456@command{autoconf}), in order to inspect when a macro is called and with 13457which arguments. For example, when this paragraph was written, the 13458autoconf version could be found by: 13459 13460@example 13461$ @kbd{autoconf --trace=AC_INIT} 13462configure.ac:23:AC_INIT:GNU Autoconf:2.63b.95-3963:bug-autoconf@@gnu.org 13463$ @kbd{autoconf --trace='AC_INIT:version is $2'} 13464version is 2.63b.95-3963 13465@end example 13466 13467Another trick is to print out the expansion of various m4 expressions to 13468standard error or to an independent file, with no further m4 expansion, 13469and without interfering with diversion changes or the post-processing 13470done to standard output. @code{m4_errprintn} shows a given expression 13471on standard error. For example, if you want to see the expansion of an 13472autoconf primitive or of one of your autoconf macros, you can do it like 13473this: 13474 13475@example 13476$ @kbd{cat <<\EOF > configure.ac} 13477AC_INIT 13478m4_errprintn([The definition of AC_DEFINE_UNQUOTED:]) 13479m4_errprintn(m4_defn([AC_DEFINE_UNQUOTED])) 13480AC_OUTPUT 13481EOF 13482$ @kbd{autoconf} 13483@error{}The definition of AC_DEFINE_UNQUOTED: 13484@error{}_AC_DEFINE_Q([], $@@) 13485@end example 13486 13487@node Programming in M4sh 13488@chapter Programming in M4sh 13489 13490M4sh, pronounced ``mash'', is aiming at producing portable Bourne shell 13491scripts. This name was coined by Lars J. Aas, who notes that, 13492according to the Webster's Revised Unabridged Dictionary (1913): 13493 13494@quotation 13495Mash \Mash\, n. [Akin to G. meisch, maisch, meische, maische, mash, 13496wash, and prob.@: to AS. miscian to mix. See ``Mix''.] 13497 13498@enumerate 1 13499@item 13500A mass of mixed ingredients reduced to a soft pulpy state by beating or 13501pressure@enddots{} 13502 13503@item 13504A mixture of meal or bran and water fed to animals. 13505 13506@item 13507A mess; trouble. [Obs.] --Beau.@: & Fl. 13508@end enumerate 13509@end quotation 13510 13511M4sh reserves the M4 macro namespace @samp{^_AS_} for internal use, and 13512the namespace @samp{^AS_} for M4sh macros. It also reserves the shell 13513and environment variable namespace @samp{^as_}, and the here-document 13514delimiter namespace @samp{^_AS[A-Z]} in the output file. You should not 13515define your own macros or output shell code that conflicts with these 13516namespaces. 13517 13518@menu 13519* Common Shell Constructs:: Portability layer for common shell constructs 13520* Polymorphic Variables:: Support for indirect variable names 13521* Initialization Macros:: Macros to establish a sane shell environment 13522* File Descriptor Macros:: File descriptor macros for input and output 13523@end menu 13524 13525@node Common Shell Constructs 13526@section Common Shell Constructs 13527 13528M4sh provides portable alternatives for some common shell constructs 13529that unfortunately are not portable in practice. 13530 13531@c Deprecated, to be replaced by a better API 13532@ignore 13533@defmac AS_BASENAME (@var{file-name}) 13534@asindex{BASENAME} 13535Output the non-directory portion of @var{file-name}. For example, 13536if @code{$file} is @samp{/one/two/three}, the command 13537@code{base=`AS_BASENAME(["$file"])`} sets @code{base} to @samp{three}. 13538@end defmac 13539@end ignore 13540 13541@defmac AS_BOX (@var{text}, @dvar{char, -}) 13542@asindex{BOX} 13543Expand into shell code that will output @var{text} surrounded by a box 13544with @var{char} in the top and bottom border. @var{text} should not 13545contain a newline, but may contain shell expansions valid for unquoted 13546here-documents. @var{char} defaults to @samp{-}, but can be any 13547character except @samp{/}, @samp{'}, @samp{"}, @samp{\}, 13548@samp{&}, or @samp{`}. This is useful for outputting a comment box into 13549log files to separate distinct phases of script operation. 13550@end defmac 13551 13552@defmac AS_CASE (@var{word}, @ovar{pattern1}, @ovar{if-matched1}, @ 13553 @dots{}, @ovar{default}) 13554@asindex{CASE} 13555Expand into a shell @samp{case} statement, where @var{word} is matched 13556against one or more patterns. @var{if-matched} is run if the 13557corresponding pattern matched @var{word}, else @var{default} is run. 13558Avoids several portability issues (@pxref{case, , Limitations of Shell 13559Builtins}). 13560@end defmac 13561 13562@c Deprecated, to be replaced by a better API 13563@defmac AS_DIRNAME (@var{file-name}) 13564@asindex{DIRNAME} 13565Output the directory portion of @var{file-name}. For example, 13566if @code{$file} is @samp{/one/two/three}, the command 13567@code{dir=`AS_DIRNAME(["$file"])`} sets @code{dir} to @samp{/one/two}. 13568 13569This interface may be improved in the future to avoid forks and losing 13570trailing newlines. 13571@end defmac 13572 13573@defmac AS_ECHO (@var{word}) 13574@asindex{ECHO} 13575Emits @var{word} to the standard output, followed by a newline. @var{word} 13576must be a single shell word (typically a quoted string). The bytes of 13577@var{word} are output as-is, even if it starts with "-" or contains "\". 13578Redirections can be placed outside the macro invocation. This is much 13579more portable than using @command{echo} (@pxref{echo, , Limitations of 13580Shell Builtins}). 13581@end defmac 13582 13583@defmac AS_ECHO_N (@var{word}) 13584@asindex{ECHO_N} 13585Emits @var{word} to the standard output, without a following newline. 13586@var{word} must be a single shell word (typically a quoted string) and, 13587for portability, should not include more than one newline. The bytes of 13588@var{word} are output as-is, even if it starts with "-" or contains "\". 13589Redirections can be placed outside the macro invocation. 13590@end defmac 13591 13592@c We cannot use @dvar because the macro expansion mistreats backslashes. 13593@defmac AS_ESCAPE (@var{string}, @r{[}@var{chars} = @samp{`\"$}@r{]}) 13594@asindex{ESCAPE} 13595Expands to @var{string}, with any characters in @var{chars} escaped with 13596a backslash (@samp{\}). @var{chars} should be at most four bytes long, 13597and only contain characters from the set @samp{`\"$}; however, 13598characters may be safely listed more than once in @var{chars} for the 13599sake of syntax highlighting editors. The current implementation expands 13600@var{string} after adding escapes; if @var{string} contains macro calls 13601that in turn expand to text needing shell quoting, you can use 13602@code{AS_ESCAPE(m4_dquote(m4_expand([string])))}. 13603 13604The default for @var{chars} (@samp{\"$`}) is the set of characters 13605needing escapes when @var{string} will be used literally within double 13606quotes. One common variant is the set of characters to protect when 13607@var{string} will be used literally within back-ticks or an unquoted 13608here-document (@samp{\$`}). Another common variant is @samp{""}, which can 13609be used to form a double-quoted string containing the same expansions 13610that would have occurred if @var{string} were expanded in an unquoted 13611here-document; however, when using this variant, care must be taken that 13612@var{string} does not use double quotes within complex variable 13613expansions (such as @samp{$@{foo-`echo "hi"`@}}) that would be broken 13614with improper escapes. 13615 13616This macro is often used with @code{AS_ECHO}. For an example, observe 13617the output generated by the shell code generated from this snippet: 13618 13619@example 13620foo=bar 13621AS_ECHO(["AS_ESCAPE(["$foo" = ])AS_ESCAPE(["$foo"], [""])"]) 13622@result{}"$foo" = "bar" 13623m4_define([macro], [a, [\b]]) 13624AS_ECHO(["AS_ESCAPE([[macro]])"]) 13625@result{}macro 13626AS_ECHO(["AS_ESCAPE([macro])"]) 13627@result{}a, b 13628AS_ECHO(["AS_ESCAPE(m4_dquote(m4_expand([macro])))"]) 13629@result{}a, \b 13630@end example 13631 13632@comment Should we add AS_ESCAPE_SINGLE? If we do, we can optimize in 13633@comment the case of @var{string} that does not contain '. 13634To escape a string that will be placed within single quotes, use: 13635 13636@example 13637m4_bpatsubst([[@var{string}]], ['], ['\\'']) 13638@end example 13639@end defmac 13640 13641@defmac AS_EXECUTABLE_P (@var{file}) 13642@asindex{EXECUTABLE_P} 13643Emit code to probe whether @var{file} is a regular file with executable 13644permissions (and not a directory with search permissions). The caller 13645is responsible for quoting @var{file}. 13646@end defmac 13647 13648@defmac AS_EXIT (@dvar{status, $?}) 13649@asindex{EXIT} 13650Emit code to exit the shell with @var{status}, defaulting to @samp{$?}. 13651This macro 13652works around shells that see the exit status of the command prior to 13653@code{exit} inside a @samp{trap 0} handler (@pxref{trap, , Limitations 13654of Shell Builtins}). 13655@end defmac 13656 13657@defmac AS_IF (@var{test1}, @ovar{run-if-true1}, @dots{}, @ovar{run-if-false}) 13658@asindex{IF} 13659Run shell code @var{test1}. If @var{test1} exits with a zero status then 13660run shell code @var{run-if-true1}, else examine further tests. If no test 13661exits with a zero status, run shell code @var{run-if-false}, with 13662simplifications if either @var{run-if-true1} or @var{run-if-false} 13663is empty. For example, 13664 13665@example 13666AS_IF([test "x$foo" = xyes], [HANDLE_FOO([yes])], 13667 [test "x$foo" != xno], [HANDLE_FOO([maybe])], 13668 [echo foo not specified]) 13669@end example 13670 13671@noindent 13672ensures any required macros of @code{HANDLE_FOO} 13673are expanded before the first test. 13674@end defmac 13675 13676@defmac AS_MKDIR_P (@var{file-name}) 13677@asindex{MKDIR_P} 13678Make the directory @var{file-name}, including intervening directories 13679as necessary. This is equivalent to @samp{mkdir -p -- @var{file-name}}, 13680except that it is portable to older versions of @command{mkdir} that 13681lack support for the @option{-p} option or for the @option{--} 13682delimiter (@pxref{mkdir, , Limitations of Usual Tools}). Also, 13683@code{AS_MKDIR_P} 13684succeeds if @var{file-name} is a symbolic link to an existing directory, 13685even though Posix is unclear whether @samp{mkdir -p} should 13686succeed in that case. If creation of @var{file-name} fails, exit the 13687script. 13688 13689Also see the @code{AC_PROG_MKDIR_P} macro (@pxref{Particular Programs}). 13690@end defmac 13691 13692@defmac AS_SET_STATUS (@var{status}) 13693@asindex{SET_STATUS} 13694Emit shell code to set the value of @samp{$?} to @var{status}, as 13695efficiently as possible. However, this is not guaranteed to abort a 13696shell running with @code{set -e} (@pxref{set, , Limitations of Shell 13697Builtins}). This should also be used at the end of a complex shell 13698function instead of @samp{return} (@pxref{Shell Functions}) to avoid 13699a DJGPP shell bug. 13700@end defmac 13701 13702@defmac AS_TR_CPP (@var{expression}) 13703@asindex{TR_CPP} 13704Transform @var{expression} into a valid right-hand side for a C @code{#define}. 13705For example: 13706 13707@example 13708# This outputs "#define HAVE_CHAR_P 1". 13709# Notice the m4 quoting around #, to prevent an m4 comment 13710type="char *" 13711echo "[#]define AS_TR_CPP([HAVE_$type]) 1" 13712@end example 13713@end defmac 13714 13715@defmac AS_TR_SH (@var{expression}) 13716@asindex{TR_SH} 13717Transform @var{expression} into shell code that generates a valid shell 13718variable name. The result is literal when possible at m4 time, but must 13719be used with @code{eval} if @var{expression} causes shell indirections. 13720For example: 13721 13722@example 13723# This outputs "Have it!". 13724header="sys/some file.h" 13725eval AS_TR_SH([HAVE_$header])=yes 13726if test "x$HAVE_sys_some_file_h" = xyes; then echo "Have it!"; fi 13727@end example 13728@end defmac 13729 13730@defmac AS_SET_CATFILE (@var{var}, @var{dir}, @var{file}) 13731@asindex{SET_CATFILE} 13732Set the polymorphic shell variable @var{var} to @var{dir}/@var{file}, 13733but optimizing the common cases (@var{dir} or @var{file} is @samp{.}, 13734@var{file} is absolute, etc.). 13735@end defmac 13736 13737@defmac AS_UNSET (@var{var}) 13738@asindex{UNSET} 13739Unsets the shell variable @var{var}, working around bugs in older 13740shells (@pxref{unset, , Limitations of Shell 13741Builtins}). @var{var} can be a literal or indirect variable name. 13742@end defmac 13743 13744@defmac AS_VERSION_COMPARE (@var{version-1}, @var{version-2}, @ 13745 @ovar{action-if-less}, @ovar{action-if-equal}, @ovar{action-if-greater}) 13746@asindex{VERSION_COMPARE} 13747Compare two strings @var{version-1} and @var{version-2}, possibly 13748containing shell variables, as version strings, and expand 13749@var{action-if-less}, @var{action-if-equal}, or @var{action-if-greater} 13750depending upon the result. 13751The algorithm to compare is similar to the one used by strverscmp in 13752glibc (@pxref{String/Array Comparison, , String/Array Comparison, libc, 13753The GNU C Library}). 13754@end defmac 13755 13756@node Polymorphic Variables 13757@section Support for indirect variable names 13758@cindex variable name indirection 13759@cindex polymorphic variable name 13760@cindex indirection, variable name 13761 13762Often, it is convenient to write a macro that will emit shell code 13763operating on a shell variable. The simplest case is when the variable 13764name is known. But a more powerful idiom is writing shell code that can 13765work through an indirection, where another variable or command 13766substitution produces the name of the variable to actually manipulate. 13767M4sh supports the notion of polymorphic shell variables, making it easy 13768to write a macro that can deal with either literal or indirect variable 13769names and output shell code appropriate for both use cases. Behavior is 13770undefined if expansion of an indirect variable does not result in a 13771literal variable name. 13772 13773@defmac AS_LITERAL_IF (@var{expression}, @ovar{if-literal}, @ovar{if-not}, @ 13774 @dvar{if-simple-ref, @var{if-not}}) 13775@defmacx AS_LITERAL_WORD_IF (@var{expression}, @ovar{if-literal}, @ 13776 @ovar{if-not}, @dvar{if-simple-ref, @var{if-not}}) 13777@asindex{LITERAL_IF} 13778@asindex{LITERAL_WORD_IF} 13779If the expansion of @var{expression} is definitely a shell literal, 13780expand @var{if-literal}. If the expansion of @var{expression} looks 13781like it might contain shell indirections (such as @code{$var} or 13782@code{`expr`}), then @var{if-not} is expanded. Sometimes, it is 13783possible to output optimized code if @var{expression} consists only of 13784shell variable expansions (such as @code{$@{var@}}), in which case 13785@var{if-simple-ref} can be provided; but defaulting to @var{if-not} 13786should always be safe. @code{AS_LITERAL_WORD_IF} only expands 13787@var{if-literal} if @var{expression} looks like a single shell word, 13788containing no whitespace; while @code{AS_LITERAL_IF} allows whitespace 13789in @var{expression}. 13790 13791In order to reduce the time spent recognizing whether an 13792@var{expression} qualifies as a literal or a simple indirection, the 13793implementation is somewhat conservative: @var{expression} must be a 13794single shell word (possibly after stripping whitespace), consisting only 13795of bytes that would have the same meaning whether unquoted or enclosed 13796in double quotes (for example, @samp{a.b} results in @var{if-literal}, 13797even though it is not a valid shell variable name; while both @samp{'a'} 13798and @samp{[$]} result in @var{if-not}, because they behave differently 13799than @samp{"'a'"} and @samp{"[$]"}). This macro can be used in contexts 13800for recognizing portable file names (such as in the implementation of 13801@code{AC_LIBSOURCE}), or coupled with some transliterations for forming 13802valid variable names (such as in the implementation of @code{AS_TR_SH}, 13803which uses an additional @code{m4_translit} to convert @samp{.} to 13804@samp{_}). 13805 13806This example shows how to read the contents of the shell variable 13807@code{bar}, exercising all three arguments to @code{AS_LITERAL_IF}. It 13808results in a script that will output the line @samp{hello} three times. 13809 13810@example 13811AC_DEFUN([MY_ACTION], 13812[AS_LITERAL_IF([$1], 13813 [echo "$$1"], 13814@c $$ 13815 [AS_VAR_COPY([var], [$1]) 13816 echo "$var"], 13817 [eval 'echo "$'"$1"\"])]) 13818foo=bar bar=hello 13819MY_ACTION([bar]) 13820MY_ACTION([`echo bar`]) 13821MY_ACTION([$foo]) 13822@end example 13823@end defmac 13824 13825@defmac AS_VAR_APPEND (@var{var}, @var{text}) 13826@asindex{VAR_APPEND} 13827Emit shell code to append the shell expansion of @var{text} to the end 13828of the current contents of the polymorphic shell variable @var{var}, 13829taking advantage of shells that provide the @samp{+=} extension for more 13830efficient scaling. 13831 13832For situations where the final contents of @var{var} are relatively 13833short (less than 256 bytes), it is more efficient to use the simpler 13834code sequence of @code{@var{var}=$@{@var{var}@}@var{text}} (or its 13835polymorphic equivalent of @code{AS_VAR_COPY([t], [@var{var}])} and 13836@code{AS_VAR_SET([@var{var}], ["$t"@var{text}])}). But in the case 13837when the script will be repeatedly appending text into @code{var}, 13838issues of scaling start to become apparent. A naive implementation 13839requires execution time linear to the length of the current contents of 13840@var{var} as well as the length of @var{text} for a single append, for 13841an overall quadratic scaling with multiple appends. This macro takes 13842advantage of shells which provide the extension 13843@code{@var{var}+=@var{text}}, which can provide amortized constant time 13844for a single append, for an overall linear scaling with multiple 13845appends. Note that unlike @code{AS_VAR_SET}, this macro requires that 13846@var{text} be quoted properly to avoid field splitting and file name 13847expansion. 13848@end defmac 13849 13850@defmac AS_VAR_ARITH (@var{var}, @var{expression}) 13851@asindex{VAR_ARITH} 13852Emit shell code to compute the arithmetic expansion of @var{expression}, 13853assigning the result as the contents of the polymorphic shell variable 13854@var{var}. The code takes advantage of shells that provide @samp{$(())} 13855for fewer forks, but uses @command{expr} as a fallback. Therefore, the 13856syntax for a valid @var{expression} is rather limited: all operators 13857must occur as separate shell arguments and with proper quoting, there is 13858no portable equality operator, all variables containing numeric values 13859must be expanded prior to the computation, all numeric values must be 13860provided in decimal without leading zeroes, and the first shell argument 13861should not be a negative number. In the following example, this snippet 13862will print @samp{(2+3)*4 == 20}. 13863 13864@example 13865bar=3 13866AS_VAR_ARITH([foo], [\( 2 + $bar \) \* 4]) 13867echo "(2+$bar)*4 == $foo" 13868@end example 13869@end defmac 13870 13871@defmac AS_VAR_COPY (@var{dest}, @var{source}) 13872@asindex{VAR_COPY} 13873Emit shell code to assign the contents of the polymorphic shell variable 13874@var{source} to the polymorphic shell variable @var{dest}. For example, 13875executing this M4sh snippet will output @samp{bar hi}: 13876 13877@example 13878foo=bar bar=hi 13879AS_VAR_COPY([a], [foo]) 13880AS_VAR_COPY([b], [$foo]) 13881echo "$a $b" 13882@end example 13883 13884When it is necessary to access the contents of an indirect variable 13885inside a shell double-quoted context, the recommended idiom is to first 13886copy the contents into a temporary literal shell variable. 13887 13888@smallexample 13889for header in stdint_h inttypes_h ; do 13890 AS_VAR_COPY([var], [ac_cv_header_$header]) 13891 echo "$header detected: $var" 13892done 13893@end smallexample 13894@end defmac 13895 13896@comment AS_VAR_GET is intentionally undocumented; it can't handle 13897@comment trailing newlines uniformly, and forks too much. 13898 13899@defmac AS_VAR_IF (@var{var}, @ovar{word}, @ovar{if-equal}, @ 13900 @ovar{if-not-equal}) 13901@asindex{VAR_IF} 13902Output a shell conditional statement. If the contents of the 13903polymorphic shell variable @var{var} match the string @var{word}, 13904execute @var{if-equal}; otherwise execute @var{if-not-equal}. @var{word} 13905must be a single shell word (typically a quoted string). Avoids 13906shell bugs if an interrupt signal arrives while a command substitution 13907in @var{var} is being expanded. 13908@end defmac 13909 13910@defmac AS_VAR_PUSHDEF (@var{m4-name}, @var{value}) 13911@defmacx AS_VAR_POPDEF (@var{m4-name}) 13912@asindex{VAR_PUSHDEF} 13913@asindex{VAR_POPDEF} 13914@cindex composing variable names 13915@cindex variable names, composing 13916A common M4sh idiom involves composing shell variable names from an m4 13917argument (for example, writing a macro that uses a cache variable). 13918@var{value} can be an arbitrary string, which will be transliterated 13919into a valid shell name by @code{AS_TR_SH}. In order to access the 13920composed variable name based on @var{value}, it is easier to declare a 13921temporary m4 macro @var{m4-name} with @code{AS_VAR_PUSHDEF}, then use 13922that macro as the argument to subsequent @code{AS_VAR} macros as a 13923polymorphic variable name, and finally free the temporary macro with 13924@code{AS_VAR_POPDEF}. These macros are often followed with @code{dnl}, 13925to avoid excess newlines in the output. 13926 13927Here is an involved example, that shows the power of writing macros that 13928can handle composed shell variable names: 13929 13930@example 13931m4_define([MY_CHECK_HEADER], 13932[AS_VAR_PUSHDEF([my_Header], [ac_cv_header_$1])dnl 13933AS_VAR_IF([my_Header], [yes], [echo "header $1 detected"])dnl 13934AS_VAR_POPDEF([my_Header])dnl 13935]) 13936MY_CHECK_HEADER([stdint.h]) 13937for header in inttypes.h stdlib.h ; do 13938 MY_CHECK_HEADER([$header]) 13939done 13940@end example 13941 13942@noindent 13943In the above example, @code{MY_CHECK_HEADER} can operate on polymorphic 13944variable names. In the first invocation, the m4 argument is 13945@code{stdint.h}, which transliterates into a literal @code{stdint_h}. 13946As a result, the temporary macro @code{my_Header} expands to the literal 13947shell name @samp{ac_cv_header_stdint_h}. In the second invocation, the 13948m4 argument to @code{MY_CHECK_HEADER} is @code{$header}, and the 13949temporary macro @code{my_Header} expands to the indirect shell name 13950@samp{$as_my_Header}. During the shell execution of the for loop, when 13951@samp{$header} contains @samp{inttypes.h}, then @samp{$as_my_Header} 13952contains @samp{ac_cv_header_inttypes_h}. If this script is then run on a 13953platform where all three headers have been previously detected, the 13954output of the script will include: 13955 13956@smallexample 13957header stdint.h detected 13958header inttypes.h detected 13959header stdlib.h detected 13960@end smallexample 13961@end defmac 13962 13963@defmac AS_VAR_SET (@var{var}, @ovar{value}) 13964@asindex{VAR_SET} 13965Emit shell code to assign the contents of the polymorphic shell variable 13966@var{var} to the shell expansion of @var{value}. @var{value} is not 13967subject to field splitting or file name expansion, so if command 13968substitution is used, it may be done with @samp{`""`} rather than using 13969an intermediate variable (@pxref{Shell Substitutions}). However, 13970@var{value} does undergo rescanning for additional macro names; behavior 13971is unspecified if late expansion results in any shell meta-characters. 13972@end defmac 13973 13974@defmac AS_VAR_SET_IF (@var{var}, @ovar{if-set}, @ovar{if-undef}) 13975@asindex{VAR_SET_IF} 13976Emit a shell conditional statement, which executes @var{if-set} if the 13977polymorphic shell variable @code{var} is set to any value, and 13978@var{if-undef} otherwise. 13979@end defmac 13980 13981@defmac AS_VAR_TEST_SET (@var{var}) 13982@asindex{VAR_TEST_SET} 13983Emit a shell statement that results in a successful exit status only if 13984the polymorphic shell variable @code{var} is set. 13985@end defmac 13986 13987@node Initialization Macros 13988@section Initialization Macros 13989 13990@defmac AS_BOURNE_COMPATIBLE 13991@asindex{BOURNE_COMPATIBLE} 13992Set up the shell to be more compatible with the Bourne shell as 13993standardized by Posix, if possible. This may involve setting 13994environment variables, or setting options, or similar 13995implementation-specific actions. This macro is deprecated, since 13996@code{AS_INIT} already invokes it. 13997@end defmac 13998 13999@defmac AS_INIT 14000@asindex{INIT} 14001@evindex LC_ALL 14002@evindex SHELL 14003Initialize the M4sh environment. This macro calls @code{m4_init}, then 14004outputs the @code{#! /bin/sh} line, a notice about where the output was 14005generated from, and code to sanitize the environment for the rest of the 14006script. Among other initializations, this sets @env{SHELL} to the shell 14007chosen to run the script (@pxref{CONFIG_SHELL}), and @env{LC_ALL} to 14008ensure the C locale. Finally, it changes the current diversion to 14009@code{BODY}. @code{AS_INIT} is called automatically by @code{AC_INIT} 14010and @code{AT_INIT}, so shell code in @file{configure}, 14011@file{config.status}, and @file{testsuite} all benefit from a sanitized 14012shell environment. 14013@end defmac 14014 14015@defmac AS_INIT_GENERATED (@var{file}, @ovar{comment}) 14016@asindex{INIT_GENERATED} 14017Emit shell code to start the creation of a subsidiary shell script in 14018@var{file}, including changing @var{file} to be executable. This macro 14019populates the child script with information learned from the parent 14020(thus, the emitted code is equivalent in effect, but more efficient, 14021than the code output by @code{AS_INIT}, @code{AS_BOURNE_COMPATIBLE}, and 14022@code{AS_SHELL_SANITIZE}). If present, @var{comment} is output near the 14023beginning of the child, prior to the shell initialization code, and is 14024subject to parameter expansion, command substitution, and backslash 14025quote removal. The 14026parent script should check the exit status after this macro, in case 14027@var{file} could not be properly created (for example, if the disk was 14028full). If successfully created, the parent script can then proceed to 14029append additional M4sh constructs into the child script. 14030 14031Note that the child script starts life without a log file open, so if 14032the parent script uses logging (@pxref{AS_MESSAGE_LOG_FD}), you 14033must temporarily disable any attempts to use the log file until after 14034emitting code to open a log within the child. On the other hand, if the 14035parent script has @code{AS_MESSAGE_FD} redirected somewhere besides 14036@samp{1}, then the child script already has code that copies stdout to 14037that descriptor. Currently, the suggested 14038idiom for writing a M4sh shell script from within another script is: 14039 14040@example 14041AS_INIT_GENERATED([@var{file}], [[# My child script. 14042]]) || @{ AS_ECHO(["Failed to create child script"]); AS_EXIT; @} 14043m4_pushdef([AS_MESSAGE_LOG_FD])dnl 14044cat >> "@var{file}" <<\__EOF__ 14045# Code to initialize AS_MESSAGE_LOG_FD 14046m4_popdef([AS_MESSAGE_LOG_FD])dnl 14047# Additional code 14048__EOF__ 14049@end example 14050 14051This, however, may change in the future as the M4sh interface is 14052stabilized further. 14053 14054Also, be aware that use of @env{LINENO} within the child script may 14055report line numbers relative to their location in the parent script, 14056even when using @code{AS_LINENO_PREPARE}, if the parent script was 14057unable to locate a shell with working @env{LINENO} support. 14058@end defmac 14059 14060@defmac AS_LINENO_PREPARE 14061@asindex{LINENO_PREPARE} 14062@evindex LINENO 14063Find a shell that supports the special variable @env{LINENO}, which 14064contains the number of the currently executing line. This macro is 14065automatically invoked by @code{AC_INIT} in configure scripts. 14066@end defmac 14067 14068@defmac AS_ME_PREPARE 14069@asindex{ME_PREPARE} 14070Set up variable @env{as_me} to be the basename of the currently executing 14071script. This macro is automatically invoked by @code{AC_INIT} in 14072configure scripts. 14073@end defmac 14074 14075@defmac AS_TMPDIR (@var{prefix}, @dvar{dir, $@{TMPDIR:=/tmp@}}) 14076@asindex{TMPDIR} 14077@evindex TMPDIR 14078@ovindex tmp 14079Create, as safely as possible, a temporary sub-directory within 14080@var{dir} with a name starting with @var{prefix}. @var{prefix} should 14081be 2-4 characters, to make it slightly easier to identify the owner of 14082the directory. If @var{dir} is omitted, then the value of @env{TMPDIR} 14083will be used (defaulting to @samp{/tmp}). On success, the name of the 14084newly created directory is stored in the shell variable @code{tmp}. On 14085error, the script is aborted. 14086 14087Typically, this macro is coupled with some exit traps to delete the created 14088directory and its contents on exit or interrupt. However, there is a 14089slight window between when the directory is created and when the name is 14090actually known to the shell, so an interrupt at the right moment might 14091leave the temporary directory behind. Hence it is important to use a 14092@var{prefix} that makes it easier to determine if a leftover temporary 14093directory from an interrupted script is safe to delete. 14094 14095The use of the output variable @samp{$tmp} rather than something in the 14096@samp{as_} namespace is historical; it has the unfortunate consequence 14097that reusing this otherwise common name for any other purpose inside 14098your script has the potential to break any cleanup traps designed to 14099remove the temporary directory. 14100@end defmac 14101 14102@defmac AS_SHELL_SANITIZE 14103@asindex{SHELL_SANITIZE} 14104Initialize the shell suitably for @command{configure} scripts. This has 14105the effect of @code{AS_BOURNE_COMPATIBLE}, and sets some other 14106environment variables for predictable results from configuration tests. 14107For example, it sets @env{LC_ALL} to change to the default C locale. 14108@xref{Special Shell Variables}. This macro is deprecated, since 14109@code{AS_INIT} already invokes it. 14110@end defmac 14111 14112 14113@node File Descriptor Macros 14114@section File Descriptor Macros 14115@cindex input 14116@cindex standard input 14117@cindex file descriptors 14118@cindex descriptors 14119@cindex low-level output 14120@cindex output, low-level 14121 14122The following macros define file descriptors used to output messages 14123(or input values) from @file{configure} scripts. 14124For example: 14125 14126@example 14127echo "$wombats found" >&AS_MESSAGE_LOG_FD 14128echo 'Enter desired kangaroo count:' >&AS_MESSAGE_FD 14129read kangaroos <&AS_ORIGINAL_STDIN_FD` 14130@end example 14131 14132@noindent 14133However doing so is seldom needed, because Autoconf provides higher 14134level macros as described below. 14135 14136@defmac AS_MESSAGE_FD 14137@asindex{MESSAGE_FD} 14138The file descriptor for @samp{checking for...} messages and results. 14139By default, @code{AS_INIT} sets this to @samp{1} for standalone M4sh 14140clients. However, @code{AC_INIT} shuffles things around to another file 14141descriptor, in order to allow the @option{-q} option of 14142@command{configure} to choose whether messages should go to the script's 14143standard output or be discarded. 14144 14145If you want to display some messages, consider using one of the printing 14146macros (@pxref{Printing Messages}) instead. Copies of messages output 14147via these macros are also recorded in @file{config.log}. 14148@end defmac 14149 14150@anchor{AS_MESSAGE_LOG_FD} 14151@defmac AS_MESSAGE_LOG_FD 14152@asindex{MESSAGE_LOG_FD} 14153This must either be empty, or expand to a file descriptor for log 14154messages. By default, @code{AS_INIT} sets this macro to the empty 14155string for standalone M4sh clients, thus disabling logging. However, 14156@code{AC_INIT} shuffles things around so that both @command{configure} 14157and @command{config.status} use @file{config.log} for log messages. 14158Macros that run tools, like @code{AC_COMPILE_IFELSE} (@pxref{Running the 14159Compiler}), redirect all output to this descriptor. You may want to do 14160so if you develop such a low-level macro. 14161@end defmac 14162 14163@defmac AS_ORIGINAL_STDIN_FD 14164@asindex{ORIGINAL_STDIN_FD} 14165This must expand to a file descriptor for the original standard input. 14166By default, @code{AS_INIT} sets this macro to @samp{0} for standalone 14167M4sh clients. However, @code{AC_INIT} shuffles things around for 14168safety. 14169 14170When @command{configure} runs, it may accidentally execute an 14171interactive command that has the same name as the non-interactive meant 14172to be used or checked. If the standard input was the terminal, such 14173interactive programs would cause @command{configure} to stop, pending 14174some user input. Therefore @command{configure} redirects its standard 14175input from @file{/dev/null} during its initialization. This is not 14176normally a problem, since @command{configure} normally does not need 14177user input. 14178 14179In the extreme case where your @file{configure} script really needs to 14180obtain some values from the original standard input, you can read them 14181explicitly from @code{AS_ORIGINAL_STDIN_FD}. 14182@end defmac 14183 14184 14185@c =================================================== Writing Autoconf Macros. 14186 14187@node Writing Autoconf Macros 14188@chapter Writing Autoconf Macros 14189 14190When you write a feature test that could be applicable to more than one 14191software package, the best thing to do is encapsulate it in a new macro. 14192Here are some instructions and guidelines for writing Autoconf macros. 14193 14194@menu 14195* Macro Definitions:: Basic format of an Autoconf macro 14196* Macro Names:: What to call your new macros 14197* Reporting Messages:: Notifying @command{autoconf} users 14198* Dependencies Between Macros:: What to do when macros depend on other macros 14199* Obsoleting Macros:: Warning about old ways of doing things 14200* Coding Style:: Writing Autoconf macros @`a la Autoconf 14201@end menu 14202 14203@node Macro Definitions 14204@section Macro Definitions 14205 14206@defmac AC_DEFUN (@var{name}, @ovar{body}) 14207@acindex{DEFUN} 14208Autoconf macros are defined using the @code{AC_DEFUN} macro, which is 14209similar to the M4 builtin @code{m4_define} macro; this creates a macro 14210named @var{name} and with @var{body} as its expansion. In addition to 14211defining a macro, @code{AC_DEFUN} adds to it some code that is used to 14212constrain the order in which macros are called, while avoiding redundant 14213output (@pxref{Prerequisite Macros}). 14214@end defmac 14215 14216An Autoconf macro definition looks like this: 14217 14218@example 14219AC_DEFUN(@var{macro-name}, @var{macro-body}) 14220@end example 14221 14222You can refer to any arguments passed to the macro as @samp{$1}, 14223@samp{$2}, etc. @xref{Definitions, , How to define new macros, m4.info, 14224GNU M4}, for more complete information on writing M4 macros. 14225 14226Most macros fall in one of two general categories. The first category 14227includes macros which take arguments, in order to generate output 14228parameterized by those arguments. Macros in this category are designed 14229to be directly expanded, often multiple times, and should not be used as 14230the argument to @code{AC_REQUIRE}. The other category includes macros 14231which are shorthand for a fixed block of text, and therefore do not take 14232arguments. For this category of macros, directly expanding the macro 14233multiple times results in redundant output, so it is more common to use 14234the macro as the argument to @code{AC_REQUIRE}, or to declare the macro 14235with @code{AC_DEFUN_ONCE} (@pxref{One-Shot Macros}). 14236 14237Be sure to properly quote both the @var{macro-body} @emph{and} the 14238@var{macro-name} to avoid any problems if the macro happens to have 14239been previously defined. 14240 14241Each macro should have a header comment that gives its prototype, and a 14242brief description. When arguments have default values, display them in 14243the prototype. For example: 14244 14245@example 14246# AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1]) 14247# -------------------------------------- 14248m4_define([AC_MSG_ERROR], 14249 [@{ AS_MESSAGE([error: $1], [2]) 14250 exit m4_default([$2], [1]); @}]) 14251@end example 14252 14253Comments about the macro should be left in the header comment. Most 14254other comments make their way into @file{configure}, so just keep 14255using @samp{#} to introduce comments. 14256 14257@cindex @code{dnl} 14258If you have some special comments about pure M4 code, comments 14259that make no sense in @file{configure} and in the header comment, then 14260use the builtin @code{dnl}: it causes M4 to discard the text 14261through the next newline. 14262 14263Keep in mind that @code{dnl} is rarely needed to introduce comments; 14264@code{dnl} is more useful to get rid of the newlines following macros 14265that produce no output, such as @code{AC_REQUIRE}. 14266 14267Public third-party macros need to use @code{AC_DEFUN}, and not 14268@code{m4_define}, in order to be found by @command{aclocal} 14269(@pxref{Extending aclocal,,, automake, GNU Automake}). 14270Additionally, if it is ever determined that a macro should be made 14271obsolete, it is easy to convert from @code{AC_DEFUN} to @code{AU_DEFUN} 14272in order to have @command{autoupdate} assist the user in choosing a 14273better alternative, but there is no corresponding way to make 14274@code{m4_define} issue an upgrade notice (@pxref{AU_DEFUN}). 14275 14276There is another subtle, but important, difference between using 14277@code{m4_define} and @code{AC_DEFUN}: only the former is unaffected by 14278@code{AC_REQUIRE}. When writing a file, it is always safe to replace a 14279block of text with a @code{m4_define} macro that will expand to the same 14280text. But replacing a block of text with an @code{AC_DEFUN} macro with 14281the same content does not necessarily give the same results, because it 14282changes the location where any embedded but unsatisfied 14283@code{AC_REQUIRE} invocations within the block will be expanded. For an 14284example of this, see @ref{Expanded Before Required}. 14285 14286@node Macro Names 14287@section Macro Names 14288 14289All of the public Autoconf macros have all-uppercase names in the 14290namespace @samp{^AC_} to prevent them from accidentally conflicting with 14291other text; Autoconf also reserves the namespace @samp{^_AC_} for 14292internal macros. All shell variables that they use for internal 14293purposes have mostly-lowercase names starting with @samp{ac_}. Autoconf 14294also uses here-document delimiters in the namespace @samp{^_AC[A-Z]}. During 14295@command{configure}, files produced by Autoconf make heavy use of the 14296file system namespace @samp{^conf}. 14297 14298Since Autoconf is built on top of M4sugar (@pxref{Programming in 14299M4sugar}) and M4sh (@pxref{Programming in M4sh}), you must also be aware 14300of those namespaces (@samp{^_?\(m4\|AS\)_}). And since 14301@file{configure.ac} is also designed to be scanned by Autoheader, 14302Autoscan, Autoupdate, and Automake, you should be aware of the 14303@samp{^_?A[HNUM]_} namespaces. In general, you @emph{should not use} 14304the namespace of a package that does not own the macro or shell code you 14305are writing. 14306 14307To ensure that your macros don't conflict with present or future 14308Autoconf macros, you should prefix your own macro names and any shell 14309variables they use with some other sequence. Possibilities include your 14310initials, or an abbreviation for the name of your organization or 14311software package. Historically, people have not always followed the 14312rule of using a namespace appropriate for their package, and this has 14313made it difficult for determining the origin of a macro (and where to 14314report bugs about that macro), as well as difficult for the true 14315namespace owner to add new macros without interference from pre-existing 14316uses of third-party macros. Perhaps the best example of this confusion 14317is the @code{AM_GNU_GETTEXT} macro, which belongs, not to Automake, but 14318to Gettext. 14319 14320Most of the Autoconf macros' names follow a structured naming convention 14321that indicates the kind of feature check by the name. The macro names 14322consist of several words, separated by underscores, going from most 14323general to most specific. The names of their cache variables use the 14324same convention (@pxref{Cache Variable Names}, for more information on 14325them). 14326 14327The first word of the name after the namespace initials (such as 14328@samp{AC_}) usually tells the category 14329of the feature being tested. Here are the categories used in Autoconf for 14330specific test macros, the kind of macro that you are more likely to 14331write. They are also used for cache variables, in all-lowercase. Use 14332them where applicable; where they're not, invent your own categories. 14333 14334@table @code 14335@item C 14336C language builtin features. 14337@item DECL 14338Declarations of C variables in header files. 14339@item FUNC 14340Functions in libraries. 14341@item GROUP 14342Posix group owners of files. 14343@item HEADER 14344Header files. 14345@item LIB 14346C libraries. 14347@item PROG 14348The base names of programs. 14349@item MEMBER 14350Members of aggregates. 14351@item SYS 14352Operating system features. 14353@item TYPE 14354C builtin or declared types. 14355@item VAR 14356C variables in libraries. 14357@end table 14358 14359After the category comes the name of the particular feature being 14360tested. Any further words in the macro name indicate particular aspects 14361of the feature. For example, @code{AC_PROG_CC_STDC} checks whether the 14362C compiler supports ISO Standard C. 14363 14364An internal macro should have a name that starts with an underscore; 14365Autoconf internals should therefore start with @samp{_AC_}. 14366Additionally, a macro that is an internal subroutine of another macro 14367should have a name that starts with an underscore and the name of that 14368other macro, followed by one or more words saying what the internal 14369macro does. For example, @code{AC_PATH_X} has internal macros 14370@code{_AC_PATH_X_XMKMF} and @code{_AC_PATH_X_DIRECT}. 14371 14372@node Reporting Messages 14373@section Reporting Messages 14374@cindex Messages, from @command{autoconf} 14375 14376When macros statically diagnose abnormal situations, benign or fatal, it 14377is possible to make @command{autoconf} detect the problem, and refuse to 14378create @file{configure} in the case of an error. The macros in this 14379section are considered obsolescent, and new code should use M4sugar 14380macros for this purpose, see @ref{Diagnostic Macros}. 14381 14382On the other hand, it is possible to want to detect errors when 14383@command{configure} is run, which are dependent on the environment of 14384the user rather than the maintainer. For dynamic diagnostics, see 14385@ref{Printing Messages}. 14386 14387@defmac AC_DIAGNOSE (@var{category}, @var{message}) 14388@acindex{DIAGNOSE} 14389Report @var{message} as a warning (or as an error if requested by the 14390user) if warnings of the @var{category} are turned on. This macro is 14391obsolescent; you are encouraged to use: 14392@example 14393m4_warn([@var{category}], [@var{message}]) 14394@end example 14395@noindent 14396instead. @xref{m4_warn}, for more details, including valid 14397@var{category} names. 14398@end defmac 14399 14400@defmac AC_WARNING (@var{message}) 14401@acindex{WARNING} 14402Report @var{message} as a syntax warning. This macro is obsolescent; 14403you are encouraged to use: 14404@example 14405m4_warn([syntax], [@var{message}]) 14406@end example 14407@noindent 14408instead. @xref{m4_warn}, for more details, as well as better 14409finer-grained categories of warnings (not all problems have to do with 14410syntax). 14411@end defmac 14412 14413@defmac AC_FATAL (@var{message}) 14414@acindex{FATAL} 14415Report a severe error @var{message}, and have @command{autoconf} die. 14416This macro is obsolescent; you are encouraged to use: 14417@example 14418m4_fatal([@var{message}]) 14419@end example 14420@noindent 14421instead. @xref{m4_fatal}, for more details. 14422@end defmac 14423 14424When the user runs @samp{autoconf -W error}, warnings from 14425@code{m4_warn} (including those issued through @code{AC_DIAGNOSE} and 14426@code{AC_WARNING}) are reported as errors, see @ref{autoconf Invocation}. 14427 14428@node Dependencies Between Macros 14429@section Dependencies Between Macros 14430@cindex Dependencies between macros 14431 14432Some Autoconf macros depend on other macros having been called first in 14433order to work correctly. Autoconf provides a way to ensure that certain 14434macros are called if needed and a way to warn the user if macros are 14435called in an order that might cause incorrect operation. 14436 14437@menu 14438* Prerequisite Macros:: Ensuring required information 14439* Suggested Ordering:: Warning about possible ordering problems 14440* One-Shot Macros:: Ensuring a macro is called only once 14441@end menu 14442 14443@node Prerequisite Macros 14444@subsection Prerequisite Macros 14445@cindex Prerequisite macros 14446@cindex Macros, prerequisites 14447 14448A macro that you write might need to use values that have previously 14449been computed by other macros. For example, @code{AC_DECL_YYTEXT} 14450examines the output of @code{flex} or @code{lex}, so it depends on 14451@code{AC_PROG_LEX} having been called first to set the shell variable 14452@code{LEX}. 14453 14454Rather than forcing the user of the macros to keep track of the 14455dependencies between them, you can use the @code{AC_REQUIRE} macro to do 14456it automatically. @code{AC_REQUIRE} can ensure that a macro is only 14457called if it is needed, and only called once. 14458 14459@defmac AC_REQUIRE (@var{macro-name}) 14460@acindex{REQUIRE} 14461If the M4 macro @var{macro-name} has not already been called, call it 14462(without any arguments). Make sure to quote @var{macro-name} with 14463square brackets. @var{macro-name} must have been defined using 14464@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate 14465that it has been called. 14466 14467@code{AC_REQUIRE} must be used inside a macro defined by @code{AC_DEFUN}; it 14468must not be called from the top level. Also, it does not make sense to 14469require a macro that takes parameters. 14470@end defmac 14471 14472@code{AC_REQUIRE} is often misunderstood. It really implements 14473dependencies between macros in the sense that if one macro depends upon 14474another, the latter is expanded @emph{before} the body of the 14475former. To be more precise, the required macro is expanded before 14476the outermost defined macro in the current expansion stack. 14477In particular, @samp{AC_REQUIRE([FOO])} is not replaced with the body of 14478@code{FOO}. For instance, this definition of macros: 14479 14480@example 14481@group 14482AC_DEFUN([TRAVOLTA], 14483[test "$body_temperature_in_celsius" -gt "38" && 14484 dance_floor=occupied]) 14485AC_DEFUN([NEWTON_JOHN], 14486[test "x$hair_style" = xcurly && 14487 dance_floor=occupied]) 14488@end group 14489 14490@group 14491AC_DEFUN([RESERVE_DANCE_FLOOR], 14492[if date | grep '^Sat.*pm' >/dev/null 2>&1; then 14493 AC_REQUIRE([TRAVOLTA]) 14494 AC_REQUIRE([NEWTON_JOHN]) 14495fi]) 14496@end group 14497@end example 14498 14499@noindent 14500with this @file{configure.ac} 14501 14502@example 14503AC_INIT([Dance Manager], [1.0], [bug-dance@@example.org]) 14504RESERVE_DANCE_FLOOR 14505if test "x$dance_floor" = xoccupied; then 14506 AC_MSG_ERROR([cannot pick up here, let's move]) 14507fi 14508@end example 14509 14510@noindent 14511does not leave you with a better chance to meet a kindred soul at 14512other times than Saturday night since it expands into: 14513 14514@example 14515@group 14516test "$body_temperature_in_Celsius" -gt "38" && 14517 dance_floor=occupied 14518test "x$hair_style" = xcurly && 14519 dance_floor=occupied 14520fi 14521if date | grep '^Sat.*pm' >/dev/null 2>&1; then 14522 14523 14524fi 14525@end group 14526@end example 14527 14528This behavior was chosen on purpose: (i) it prevents messages in 14529required macros from interrupting the messages in the requiring macros; 14530(ii) it avoids bad surprises when shell conditionals are used, as in: 14531 14532@example 14533@group 14534if @dots{}; then 14535 AC_REQUIRE([SOME_CHECK]) 14536fi 14537@dots{} 14538SOME_CHECK 14539@end group 14540@end example 14541 14542However, this implementation can lead to another class of problems. 14543Consider the case where an outer macro first expands, then indirectly 14544requires, an inner macro: 14545 14546@example 14547AC_DEFUN([TESTA], [[echo in A 14548if test -n "$SEEN_A" ; then echo duplicate ; fi 14549SEEN_A=:]]) 14550AC_DEFUN([TESTB], [AC_REQUIRE([TESTA])[echo in B 14551if test -z "$SEEN_A" ; then echo bug ; fi]]) 14552AC_DEFUN([TESTC], [AC_REQUIRE([TESTB])[echo in C]]) 14553AC_DEFUN([OUTER], [[echo in OUTER] 14554TESTA 14555TESTC]) 14556OUTER 14557@end example 14558 14559@noindent 14560Prior to Autoconf 2.64, the implementation of @code{AC_REQUIRE} 14561recognized that @code{TESTB} needed to be hoisted prior to the expansion 14562of @code{OUTER}, but because @code{TESTA} had already been directly 14563expanded, it failed to hoist @code{TESTA}. Therefore, the expansion of 14564@code{TESTB} occurs prior to its prerequisites, leading to the following 14565output: 14566 14567@example 14568in B 14569bug 14570in OUTER 14571in A 14572in C 14573@end example 14574 14575@noindent 14576Newer Autoconf is smart enough to recognize this situation, and hoists 14577@code{TESTA} even though it has already been expanded, but issues a 14578syntax warning in the process. This is because the hoisted expansion of 14579@code{TESTA} defeats the purpose of using @code{AC_REQUIRE} to avoid 14580redundant code, and causes its own set of problems if the hoisted macro 14581is not idempotent: 14582 14583@example 14584in A 14585in B 14586in OUTER 14587in A 14588duplicate 14589in C 14590@end example 14591 14592The bug is not in Autoconf, but in the macro definitions. If you ever 14593pass a particular macro name to @code{AC_REQUIRE}, then you are implying 14594that the macro only needs to be expanded once. But to enforce this, 14595either the macro must be declared with @code{AC_DEFUN_ONCE} (although 14596this only helps in Autoconf 2.64 or newer), or all 14597uses of that macro should be through @code{AC_REQUIRE}; directly 14598expanding the macro defeats the point of using @code{AC_REQUIRE} to 14599eliminate redundant expansion. In the example, this rule of thumb was 14600violated because @code{TESTB} requires @code{TESTA} while @code{OUTER} 14601directly expands it. One way of fixing the bug is to factor 14602@code{TESTA} into two macros, the portion designed for direct and 14603repeated use (here, named @code{TESTA}), and the portion designed for 14604one-shot output and used only inside @code{AC_REQUIRE} (here, named 14605@code{TESTA_PREREQ}). Then, by fixing all clients to use the correct 14606calling convention according to their needs: 14607 14608@example 14609AC_DEFUN([TESTA], [AC_REQUIRE([TESTA_PREREQ])[echo in A]]) 14610AC_DEFUN([TESTA_PREREQ], [[echo in A_PREREQ 14611if test -n "$SEEN_A" ; then echo duplicate ; fi 14612SEEN_A=:]]) 14613AC_DEFUN([TESTB], [AC_REQUIRE([TESTA_PREREQ])[echo in B 14614if test -z "$SEEN_A" ; then echo bug ; fi]]) 14615AC_DEFUN([TESTC], [AC_REQUIRE([TESTB])[echo in C]]) 14616AC_DEFUN([OUTER], [[echo in OUTER] 14617TESTA 14618TESTC]) 14619OUTER 14620@end example 14621 14622@noindent 14623the resulting output will then obey all dependency rules and avoid any 14624syntax warnings, whether the script is built with old or new Autoconf 14625versions: 14626 14627@example 14628in A_PREREQ 14629in B 14630in OUTER 14631in A 14632in C 14633@end example 14634 14635The helper macros @code{AS_IF} and @code{AS_CASE} may be used to 14636enforce expansion of required macros outside of shell conditional 14637constructs. You are furthermore encouraged, although not required, to 14638put all @code{AC_REQUIRE} calls 14639at the beginning of a macro. You can use @code{dnl} to avoid the empty 14640lines they leave. 14641 14642@node Suggested Ordering 14643@subsection Suggested Ordering 14644@cindex Macros, ordering 14645@cindex Ordering macros 14646 14647Some macros should be run before another macro if both are called, but 14648neither @emph{requires} that the other be called. For example, a macro 14649that changes the behavior of the C compiler should be called before any 14650macros that run the C compiler. Many of these dependencies are noted in 14651the documentation. 14652 14653Autoconf provides the @code{AC_BEFORE} macro to warn users when macros 14654with this kind of dependency appear out of order in a 14655@file{configure.ac} file. The warning occurs when creating 14656@command{configure} from @file{configure.ac}, not when running 14657@command{configure}. 14658 14659For example, @code{AC_PROG_CPP} checks whether the C compiler 14660can run the C preprocessor when given the @option{-E} option. It should 14661therefore be called after any macros that change which C compiler is 14662being used, such as @code{AC_PROG_CC}. So @code{AC_PROG_CC} contains: 14663 14664@example 14665AC_BEFORE([$0], [AC_PROG_CPP])dnl 14666@end example 14667 14668@noindent 14669This warns the user if a call to @code{AC_PROG_CPP} has already occurred 14670when @code{AC_PROG_CC} is called. 14671 14672@defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name}) 14673@acindex{BEFORE} 14674Make M4 print a warning message to the standard error output if 14675@var{called-macro-name} has already been called. @var{this-macro-name} 14676should be the name of the macro that is calling @code{AC_BEFORE}. The 14677macro @var{called-macro-name} must have been defined using 14678@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate 14679that it has been called. 14680@end defmac 14681 14682@node One-Shot Macros 14683@subsection One-Shot Macros 14684@cindex One-shot macros 14685@cindex Macros, called once 14686 14687Some macros should be called only once, either because calling them 14688multiple time is unsafe, or because it is bad style. For instance 14689Autoconf ensures that @code{AC_CANONICAL_BUILD} and cousins 14690(@pxref{Canonicalizing}) are evaluated only once, because it makes no 14691sense to run these expensive checks more than once. Such one-shot 14692macros can be defined using @code{AC_DEFUN_ONCE}. 14693 14694@defmac AC_DEFUN_ONCE (@var{macro-name}, @var{macro-body}) 14695@acindex{DEFUN_ONCE} 14696Declare macro @var{macro-name} like @code{AC_DEFUN} would (@pxref{Macro 14697Definitions}), but add additional logic that guarantees that only the 14698first use of the macro (whether by direct expansion or 14699@code{AC_REQUIRE}) causes an expansion of @var{macro-body}; the 14700expansion will occur before the start of any enclosing macro defined by 14701@code{AC_DEFUN}. Subsequent expansions are silently ignored. 14702Generally, it does not make sense for @var{macro-body} to use parameters 14703such as @code{$1}. 14704@end defmac 14705 14706Prior to Autoconf 2.64, a macro defined by @code{AC_DEFUN_ONCE} would 14707emit a warning if it was directly expanded a second time, so for 14708portability, it is better to use @code{AC_REQUIRE} than direct 14709invocation of @var{macro-name} inside a macro defined by @code{AC_DEFUN} 14710(@pxref{Prerequisite Macros}). 14711 14712@node Obsoleting Macros 14713@section Obsoleting Macros 14714@cindex Obsoleting macros 14715@cindex Macros, obsoleting 14716 14717Configuration and portability technology has evolved over the years. 14718Often better ways of solving a particular problem are developed, or 14719ad-hoc approaches are systematized. This process has occurred in many 14720parts of Autoconf. One result is that some of the macros are now 14721considered @dfn{obsolete}; they still work, but are no longer considered 14722the best thing to do, hence they should be replaced with more modern 14723macros. Ideally, @command{autoupdate} should replace the old macro calls 14724with their modern implementation. 14725 14726Autoconf provides a simple means to obsolete a macro. 14727 14728@anchor{AU_DEFUN} 14729@defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message}) 14730@auindex{DEFUN} 14731Define @var{old-macro} as @var{implementation}. The only difference 14732with @code{AC_DEFUN} is that the user is warned that 14733@var{old-macro} is now obsolete. 14734 14735If she then uses @command{autoupdate}, the call to @var{old-macro} is 14736replaced by the modern @var{implementation}. @var{message} should 14737include information on what to do after running @command{autoupdate}; 14738@command{autoupdate} prints it as a warning, and includes it 14739in the updated @file{configure.ac} file. 14740 14741The details of this macro are hairy: if @command{autoconf} encounters an 14742@code{AU_DEFUN}ed macro, all macros inside its second argument are expanded 14743as usual. However, when @command{autoupdate} is run, only M4 and M4sugar 14744macros are expanded here, while all other macros are disabled and 14745appear literally in the updated @file{configure.ac}. 14746@end defmac 14747 14748@defmac AU_ALIAS (@var{old-name}, @var{new-name}) 14749@auindex{ALIAS} 14750Used if the @var{old-name} is to be replaced by a call to @var{new-macro} 14751with the same parameters. This happens for example if the macro was renamed. 14752@end defmac 14753 14754@node Coding Style 14755@section Coding Style 14756@cindex Coding style 14757 14758The Autoconf macros follow a strict coding style. You are encouraged to 14759follow this style, especially if you intend to distribute your macro, 14760either by contributing it to Autoconf itself or the 14761@uref{http://@/www.gnu.org/@/software/@/autoconf-archive/, Autoconf Macro 14762Archive}, or by other means. 14763 14764The first requirement is to pay great attention to the quotation. For 14765more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}. 14766 14767Do not try to invent new interfaces. It is likely that there is a macro 14768in Autoconf that resembles the macro you are defining: try to stick to 14769this existing interface (order of arguments, default values, etc.). We 14770@emph{are} conscious that some of these interfaces are not perfect; 14771nevertheless, when harmless, homogeneity should be preferred over 14772creativity. 14773 14774Be careful about clashes both between M4 symbols and between shell 14775variables. 14776 14777If you stick to the suggested M4 naming scheme (@pxref{Macro Names}), 14778you are unlikely to generate conflicts. Nevertheless, when you need to 14779set a special value, @emph{avoid using a regular macro name}; rather, 14780use an ``impossible'' name. For instance, up to version 2.13, the macro 14781@code{AC_SUBST} used to remember what @var{symbol} macros were already defined 14782by setting @code{AC_SUBST_@var{symbol}}, which is a regular macro name. 14783But since there is a macro named @code{AC_SUBST_FILE}, it was just 14784impossible to @samp{AC_SUBST(FILE)}! In this case, 14785@code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should 14786have been used (yes, with the parentheses). 14787@c or better yet, high-level macros such as @code{m4_expand_once} 14788 14789No Autoconf macro should ever enter the user-variable name space; i.e., 14790except for the variables that are the actual result of running the 14791macro, all shell variables should start with @code{ac_}. In 14792addition, small macros or any macro that is likely to be embedded in 14793other macros should be careful not to use obvious names. 14794 14795@cindex @code{dnl} 14796Do not use @code{dnl} to introduce comments: most of the comments you 14797are likely to write are either header comments which are not output 14798anyway, or comments that should make their way into @file{configure}. 14799There are exceptional cases where you do want to comment special M4 14800constructs, in which case @code{dnl} is right, but keep in mind that it 14801is unlikely. 14802 14803M4 ignores the leading blanks and newlines before each argument. 14804Use this feature to 14805indent in such a way that arguments are (more or less) aligned with the 14806opening parenthesis of the macro being called. For instance, instead of 14807 14808@example 14809AC_CACHE_CHECK(for EMX OS/2 environment, 14810ac_cv_emxos2, 14811[AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])], 14812[ac_cv_emxos2=yes], [ac_cv_emxos2=no])]) 14813@end example 14814 14815@noindent 14816write 14817 14818@example 14819AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2], 14820[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])], 14821 [ac_cv_emxos2=yes], 14822 [ac_cv_emxos2=no])]) 14823@end example 14824 14825@noindent 14826or even 14827 14828@example 14829AC_CACHE_CHECK([for EMX OS/2 environment], 14830 [ac_cv_emxos2], 14831 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], 14832 [return __EMX__;])], 14833 [ac_cv_emxos2=yes], 14834 [ac_cv_emxos2=no])]) 14835@end example 14836 14837When using @code{AC_RUN_IFELSE} or any macro that cannot work when 14838cross-compiling, provide a pessimistic value (typically @samp{no}). 14839 14840Feel free to use various tricks to prevent auxiliary tools, such as 14841syntax-highlighting editors, from behaving improperly. For instance, 14842instead of: 14843 14844@example 14845m4_bpatsubst([$1], [$"]) 14846@end example 14847 14848@noindent 14849use 14850 14851@example 14852m4_bpatsubst([$1], [$""]) 14853@end example 14854 14855@noindent 14856so that Emacsen do not open an endless ``string'' at the first quote. 14857For the same reasons, avoid: 14858 14859@example 14860test $[#] != 0 14861@end example 14862 14863@noindent 14864and use: 14865 14866@example 14867test $[@@%:@@] != 0 14868@end example 14869 14870@noindent 14871Otherwise, the closing bracket would be hidden inside a @samp{#}-comment, 14872breaking the bracket-matching highlighting from Emacsen. Note the 14873preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]}, etc. Do 14874not escape when it is unnecessary. Common examples of useless quotation 14875are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}), 14876etc. If you add portability issues to the picture, you'll prefer 14877@samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something 14878better than hacking Autoconf @code{:-)}. 14879 14880When using @command{sed}, don't use @option{-e} except for indenting 14881purposes. With the @code{s} and @code{y} commands, the preferred 14882separator is @samp{/} unless @samp{/} itself might appear in the pattern 14883or replacement, in which case you should use @samp{|}, or optionally 14884@samp{,} if you know the pattern and replacement cannot contain a file 14885name. If none of these characters will do, choose a printable character 14886that cannot appear in the pattern or replacement. Characters from the 14887set @samp{"#$&'()*;<=>?`|~} are good choices if the pattern or 14888replacement might contain a file name, since they have special meaning 14889to the shell and are less likely to occur in file names. 14890 14891@xref{Macro Definitions}, for details on how to define a macro. If a 14892macro doesn't use @code{AC_REQUIRE}, is expected to never be the object 14893of an @code{AC_REQUIRE} directive, and macros required by other macros 14894inside arguments do not need to be expanded before this macro, then 14895use @code{m4_define}. In case of doubt, use @code{AC_DEFUN}. 14896Also take into account that public third-party macros need to use 14897@code{AC_DEFUN} in order to be found by @command{aclocal} 14898(@pxref{Extending aclocal,,, automake, GNU Automake}). 14899All the @code{AC_REQUIRE} statements should be at the beginning of the 14900macro, and each statement should be followed by @code{dnl}. 14901 14902You should not rely on the number of arguments: instead of checking 14903whether an argument is missing, test that it is not empty. It provides 14904both a simpler and a more predictable interface to the user, and saves 14905room for further arguments. 14906 14907Unless the macro is short, try to leave the closing @samp{])} at the 14908beginning of a line, followed by a comment that repeats the name of the 14909macro being defined. This introduces an additional newline in 14910@command{configure}; normally, that is not a problem, but if you want to 14911remove it you can use @samp{[]dnl} on the last line. You can similarly 14912use @samp{[]dnl} after a macro call to remove its newline. @samp{[]dnl} 14913is recommended instead of @samp{dnl} to ensure that M4 does not 14914interpret the @samp{dnl} as being attached to the preceding text or 14915macro output. For example, instead of: 14916 14917@example 14918AC_DEFUN([AC_PATH_X], 14919[AC_MSG_CHECKING([for X]) 14920AC_REQUIRE_CPP() 14921@r{# @dots{}omitted@dots{}} 14922 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes]) 14923fi]) 14924@end example 14925 14926@noindent 14927you would write: 14928 14929@example 14930AC_DEFUN([AC_PATH_X], 14931[AC_REQUIRE_CPP()[]dnl 14932AC_MSG_CHECKING([for X]) 14933@r{# @dots{}omitted@dots{}} 14934 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes]) 14935fi[]dnl 14936])# AC_PATH_X 14937@end example 14938 14939If the macro is long, try to split it into logical chunks. Typically, 14940macros that check for a bug in a function and prepare its 14941@code{AC_LIBOBJ} replacement should have an auxiliary macro to perform 14942this setup. Do not hesitate to introduce auxiliary macros to factor 14943your code. 14944 14945In order to highlight the recommended coding style, here is a macro 14946written the old way: 14947 14948@example 14949dnl Check for EMX on OS/2. 14950dnl _AC_EMXOS2 14951AC_DEFUN(_AC_EMXOS2, 14952[AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2, 14953[AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)], 14954ac_cv_emxos2=yes, ac_cv_emxos2=no)]) 14955test "x$ac_cv_emxos2" = xyes && EMXOS2=yes]) 14956@end example 14957 14958@noindent 14959and the new way: 14960 14961@example 14962# _AC_EMXOS2 14963# ---------- 14964# Check for EMX on OS/2. 14965m4_define([_AC_EMXOS2], 14966[AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2], 14967[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])], 14968 [ac_cv_emxos2=yes], 14969 [ac_cv_emxos2=no])]) 14970test "x$ac_cv_emxos2" = xyes && EMXOS2=yes[]dnl 14971])# _AC_EMXOS2 14972@end example 14973 14974 14975 14976 14977@c ============================================= Portable Shell Programming 14978 14979@node Portable Shell 14980@chapter Portable Shell Programming 14981@cindex Portable shell programming 14982 14983When writing your own checks, there are some shell-script programming 14984techniques you should avoid in order to make your code portable. The 14985Bourne shell and upward-compatible shells like the Korn shell and Bash 14986have evolved over the years, and many features added to the original 14987System7 shell are now supported on all interesting porting targets. 14988However, the following discussion between Russ Allbery and Robert Lipe 14989is worth reading: 14990 14991@noindent 14992Russ Allbery: 14993 14994@quotation 14995The GNU assumption that @command{/bin/sh} is the one and only shell 14996leads to a permanent deadlock. Vendors don't want to break users' 14997existing shell scripts, and there are some corner cases in the Bourne 14998shell that are not completely compatible with a Posix shell. Thus, 14999vendors who have taken this route will @emph{never} (OK@dots{}``never say 15000never'') replace the Bourne shell (as @command{/bin/sh}) with a 15001Posix shell. 15002@end quotation 15003 15004@noindent 15005Robert Lipe: 15006 15007@quotation 15008This is exactly the problem. While most (at least most System V's) do 15009have a Bourne shell that accepts shell functions most vendor 15010@command{/bin/sh} programs are not the Posix shell. 15011 15012So while most modern systems do have a shell @emph{somewhere} that meets the 15013Posix standard, the challenge is to find it. 15014@end quotation 15015 15016For this reason, part of the job of M4sh (@pxref{Programming in M4sh}) 15017is to find such a shell. But to prevent trouble, if you're not using 15018M4sh you should not take advantage of features that were added after Unix 15019version 7, circa 1977 (@pxref{Systemology}); you should not use aliases, 15020negated character classes, or even @command{unset}. @code{#} comments, 15021while not in Unix version 7, were retrofitted in the original Bourne 15022shell and can be assumed to be part of the least common denominator. 15023 15024On the other hand, if you're using M4sh you can assume that the shell 15025has the features that were added in SVR2 (circa 1984), including shell 15026functions, 15027@command{return}, @command{unset}, and I/O redirection for builtins. For 15028more information, refer to @uref{http://@/www.in-ulm.de/@/~mascheck/@/bourne/}. 15029However, some pitfalls have to be avoided for portable use of these 15030constructs; these will be documented in the rest of this chapter. 15031See in particular @ref{Shell Functions} and @ref{Limitations of 15032Builtins, , Limitations of Shell Builtins}. 15033 15034Some ancient systems have quite 15035small limits on the length of the @samp{#!} line; for instance, 32 15036bytes (not including the newline) on SunOS 4. 15037However, these ancient systems are no longer of practical concern. 15038 15039The set of external programs you should run in a @command{configure} script 15040is fairly small. @xref{Utilities in Makefiles, , Utilities in 15041Makefiles, standards, The GNU Coding Standards}, for the list. This 15042restriction allows users to start out with a fairly small set of 15043programs and build the rest, avoiding too many interdependencies between 15044packages. 15045 15046Some of these external utilities have a portable subset of features; see 15047@ref{Limitations of Usual Tools}. 15048 15049There are other sources of documentation about shells. The 15050specification for the Posix 15051@uref{http://@/www.opengroup.org/@/susv3/@/utilities/@/xcu_chap02@/.html, Shell 15052Command Language}, though more generous than the restrictive shell 15053subset described above, is fairly portable nowadays. Also please see 15054@uref{http://@/www.faqs.org/@/faqs/@/unix-faq/@/shell/, the Shell FAQs}. 15055 15056@menu 15057* Shellology:: A zoology of shells 15058* Invoking the Shell:: Invoking the shell as a command 15059* Here-Documents:: Quirks and tricks 15060* File Descriptors:: FDs and redirections 15061* Signal Handling:: Shells, signals, and headaches 15062* File System Conventions:: File names 15063* Shell Pattern Matching:: Pattern matching 15064* Shell Substitutions:: Variable and command expansions 15065* Assignments:: Varying side effects of assignments 15066* Parentheses:: Parentheses in shell scripts 15067* Slashes:: Slashes in shell scripts 15068* Special Shell Variables:: Variables you should not change 15069* Shell Functions:: What to look out for if you use them 15070* Limitations of Builtins:: Portable use of not so portable /bin/sh 15071* Limitations of Usual Tools:: Portable use of portable tools 15072@end menu 15073 15074@node Shellology 15075@section Shellology 15076@cindex Shellology 15077 15078There are several families of shells, most prominently the Bourne family 15079and the C shell family which are deeply incompatible. If you want to 15080write portable shell scripts, avoid members of the C shell family. The 15081@uref{http://@/www.faqs.org/@/faqs/@/unix-faq/@/shell/@/shell-differences/, the 15082Shell difference FAQ} includes a small history of Posix shells, and a 15083comparison between several of them. 15084 15085Below we describe some of the members of the Bourne shell family. 15086 15087@table @asis 15088@item Ash 15089@cindex Ash 15090Ash is often used on GNU/Linux and BSD 15091systems as a light-weight Bourne-compatible shell. Ash 0.2 has some 15092bugs that are fixed in the 0.3.x series, but portable shell scripts 15093should work around them, since version 0.2 is still shipped with many 15094GNU/Linux distributions. 15095 15096To be compatible with Ash 0.2: 15097 15098@itemize @minus 15099@item 15100don't use @samp{$?} after expanding empty or unset variables, 15101or at the start of an @command{eval}: 15102 15103@example 15104foo= 15105false 15106$foo 15107echo "Do not use it: $?" 15108false 15109eval 'echo "Do not use it: $?"' 15110@end example 15111 15112@item 15113don't use command substitution within variable expansion: 15114 15115@example 15116cat $@{FOO=`bar`@} 15117@end example 15118 15119@item 15120beware that single builtin substitutions are not performed by a 15121subshell, hence their effect applies to the current shell! @xref{Shell 15122Substitutions}, item ``Command Substitution''. 15123@end itemize 15124 15125@item Bash 15126@cindex Bash 15127To detect whether you are running Bash, test whether 15128@code{BASH_VERSION} is set. To require 15129Posix compatibility, run @samp{set -o posix}. @xref{Bash POSIX 15130Mode, , Bash Posix Mode, bash, The GNU Bash Reference 15131Manual}, for details. 15132 15133@item Bash 2.05 and later 15134@cindex Bash 2.05 and later 15135Versions 2.05 and later of Bash use a different format for the 15136output of the @command{set} builtin, designed to make evaluating its 15137output easier. However, this output is not compatible with earlier 15138versions of Bash (or with many other shells, probably). So if 15139you use Bash 2.05 or higher to execute @command{configure}, 15140you'll need to use Bash 2.05 for all other build tasks as well. 15141 15142@item Ksh 15143@cindex Ksh 15144@cindex Korn shell 15145@prindex @samp{ksh} 15146@prindex @samp{ksh88} 15147@prindex @samp{ksh93} 15148The Korn shell is compatible with the Bourne family and it mostly 15149conforms to Posix. It has two major variants commonly 15150called @samp{ksh88} and @samp{ksh93}, named after the years of initial 15151release. It is usually called @command{ksh}, but is called @command{sh} 15152on some hosts if you set your path appropriately. 15153 15154Solaris systems have three variants: 15155@prindex @command{/usr/bin/ksh} on Solaris 15156@command{/usr/bin/ksh} is @samp{ksh88}; it is 15157standard on Solaris 2.0 and later. 15158@prindex @command{/usr/xpg4/bin/sh} on Solaris 15159@command{/usr/xpg4/bin/sh} is a Posix-compliant variant of 15160@samp{ksh88}; it is standard on Solaris 9 and later. 15161@prindex @command{/usr/dt/bin/dtksh} on Solaris 15162@command{/usr/dt/bin/dtksh} is @samp{ksh93}. 15163Variants that are not standard may be parts of optional 15164packages. There is no extra charge for these packages, but they are 15165not part of a minimal OS install and therefore some installations may 15166not have it. 15167 15168Starting with Tru64 Version 4.0, the Korn shell @command{/usr/bin/ksh} 15169is also available as @command{/usr/bin/posix/sh}. If the environment 15170variable @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of 15171the standard shell conform to Posix. 15172 15173@item Pdksh 15174@prindex @samp{pdksh} 15175A public-domain clone of the Korn shell called @command{pdksh} is widely 15176available: it has most of the @samp{ksh88} features along with a few of 15177its own. It usually sets @code{KSH_VERSION}, except if invoked as 15178@command{/bin/sh} on OpenBSD, and similarly to Bash you can require 15179Posix compatibility by running @samp{set -o posix}. Unfortunately, with 15180@command{pdksh} 5.2.14 (the latest stable version as of January 2007) 15181Posix mode is buggy and causes @command{pdksh} to depart from Posix in 15182at least one respect, see @ref{Shell Substitutions}. 15183 15184@item Zsh 15185@cindex Zsh 15186To detect whether you are running @command{zsh}, test whether 15187@code{ZSH_VERSION} is set. By default @command{zsh} is @emph{not} 15188compatible with the Bourne shell: you must execute @samp{emulate sh}, 15189and for @command{zsh} versions before 3.1.6-dev-18 you must also 15190set @code{NULLCMD} to @samp{:}. @xref{Compatibility, , Compatibility, 15191zsh, The Z Shell Manual}, for details. 15192 15193The default Mac OS X @command{sh} was originally Zsh; it was changed to 15194Bash in Mac OS X 10.2. 15195@end table 15196 15197@node Invoking the Shell 15198@section Invoking the Shell 15199@cindex invoking the shell 15200@cindex shell invocation 15201 15202The Korn shell (up to at least version M-12/28/93d) has a bug when 15203invoked on a file whose name does not contain a slash. It first 15204searches for the file's name in @env{PATH}, and if found it executes 15205that rather than the original file. For example, assuming there is a 15206binary executable @file{/usr/bin/script} in your @env{PATH}, the last 15207command in the following example fails because the Korn shell finds 15208@file{/usr/bin/script} and refuses to execute it as a shell script: 15209 15210@example 15211$ @kbd{touch xxyzzyz script} 15212$ @kbd{ksh xxyzzyz} 15213$ @kbd{ksh ./script} 15214$ @kbd{ksh script} 15215ksh: script: cannot execute 15216@end example 15217 15218Bash 2.03 has a bug when invoked with the @option{-c} option: if the 15219option-argument ends in backslash-newline, Bash incorrectly reports a 15220syntax error. The problem does not occur if a character follows the 15221backslash: 15222 15223@example 15224$ @kbd{$ bash -c 'echo foo \} 15225> @kbd{'} 15226bash: -c: line 2: syntax error: unexpected end of file 15227$ @kbd{bash -c 'echo foo \} 15228> @kbd{ '} 15229foo 15230@end example 15231 15232@noindent 15233@xref{Backslash-Newline-Empty}, for how this can cause problems in makefiles. 15234 15235@node Here-Documents 15236@section Here-Documents 15237@cindex Here-documents 15238@cindex Shell here-documents 15239 15240Don't rely on @samp{\} being preserved just because it has no special 15241meaning together with the next symbol. In the native @command{sh} 15242on OpenBSD 2.7 @samp{\"} expands to @samp{"} in here-documents with 15243unquoted delimiter. As a general rule, if @samp{\\} expands to @samp{\} 15244use @samp{\\} to get @samp{\}. 15245 15246With OpenBSD 2.7's @command{sh} 15247 15248@example 15249@group 15250$ @kbd{cat <<EOF 15251> \" \\ 15252> EOF} 15253" \ 15254@end group 15255@end example 15256 15257@noindent 15258and with Bash: 15259 15260@example 15261@group 15262bash-2.04$ @kbd{cat <<EOF 15263> \" \\ 15264> EOF} 15265\" \ 15266@end group 15267@end example 15268 15269Using command substitutions in a here-document that is fed to a shell 15270function is not portable. For example, with Solaris 10 @command{/bin/sh}: 15271 15272@example 15273$ @kbd{kitty () @{ cat; @}} 15274$ @kbd{kitty <<EOF 15275> `echo ok` 15276> EOF} 15277/tmp/sh199886: cannot open 15278$ @kbd{echo $?} 152791 15280@end example 15281 15282Some shells mishandle large here-documents: for example, 15283Solaris 10 @command{dtksh} and the UnixWare 7.1.1 Posix shell, which are 15284derived from Korn shell version M-12/28/93d, mishandle braced variable 15285expansion that crosses a 1024- or 4096-byte buffer boundary 15286within a here-document. Only the part of the variable name after the boundary 15287is used. For example, @code{$@{variable@}} could be replaced by the expansion 15288of @code{$@{ble@}}. If the end of the variable name is aligned with the block 15289boundary, the shell reports an error, as if you used @code{$@{@}}. 15290Instead of @code{$@{variable-default@}}, the shell may expand 15291@code{$@{riable-default@}}, or even @code{$@{fault@}}. This bug can often 15292be worked around by omitting the braces: @code{$variable}. The bug was 15293fixed in 15294@samp{ksh93g} (1998-04-30) but as of 2006 many operating systems were 15295still shipping older versions with the bug. 15296 15297Empty here-documents are not portable either; with the following code, 15298@command{zsh} up to at least version 4.3.10 creates a file with a single 15299newline, whereas other shells create an empty file: 15300 15301@example 15302cat >file <<EOF 15303EOF 15304@end example 15305 15306Many shells (including the Bourne shell) implement here-documents 15307inefficiently. In particular, some shells can be extremely inefficient when 15308a single statement contains many here-documents. For instance if your 15309@file{configure.ac} includes something like: 15310 15311@example 15312@group 15313if <cross_compiling>; then 15314 assume this and that 15315else 15316 check this 15317 check that 15318 check something else 15319 @dots{} 15320 on and on forever 15321 @dots{} 15322fi 15323@end group 15324@end example 15325 15326A shell parses the whole @code{if}/@code{fi} construct, creating 15327temporary files for each here-document in it. Some shells create links 15328for such here-documents on every @code{fork}, so that the clean-up code 15329they had installed correctly removes them. It is creating the links 15330that can take the shell forever. 15331 15332Moving the tests out of the @code{if}/@code{fi}, or creating multiple 15333@code{if}/@code{fi} constructs, would improve the performance 15334significantly. Anyway, this kind of construct is not exactly the 15335typical use of Autoconf. In fact, it's even not recommended, because M4 15336macros can't look into shell conditionals, so we may fail to expand a 15337macro when it was expanded before in a conditional path, and the 15338condition turned out to be false at runtime, and we end up not 15339executing the macro at all. 15340 15341Be careful with the use of @samp{<<-} to unindent here-documents. The 15342behavior is only portable for stripping leading @key{TAB}s, and things 15343can silently break if an overzealous editor converts to using leading 15344spaces (not all shells are nice enough to warn about unterminated 15345here-documents). 15346 15347@example 15348$ @kbd{printf 'cat <<-x\n\t1\n\t 2\n\tx\n' | bash && echo done} 153491 15350 2 15351done 15352$ @kbd{printf 'cat <<-x\n 1\n 2\n x\n' | bash-3.2 && echo done} 15353 1 15354 2 15355 x 15356done 15357@end example 15358 15359@node File Descriptors 15360@section File Descriptors 15361@cindex Descriptors 15362@cindex File descriptors 15363@cindex Shell file descriptors 15364 15365Most shells, if not all (including Bash, Zsh, Ash), output traces on 15366stderr, even for subshells. This might result in undesirable content 15367if you meant to capture the standard-error output of the inner command: 15368 15369@example 15370$ @kbd{ash -x -c '(eval "echo foo >&2") 2>stderr'} 15371$ @kbd{cat stderr} 15372+ eval echo foo >&2 15373+ echo foo 15374foo 15375$ @kbd{bash -x -c '(eval "echo foo >&2") 2>stderr'} 15376$ @kbd{cat stderr} 15377+ eval 'echo foo >&2' 15378++ echo foo 15379foo 15380$ @kbd{zsh -x -c '(eval "echo foo >&2") 2>stderr'} 15381@i{# Traces on startup files deleted here.} 15382$ @kbd{cat stderr} 15383+zsh:1> eval echo foo >&2 15384+zsh:1> echo foo 15385foo 15386@end example 15387 15388@noindent 15389One workaround is to grep out uninteresting lines, hoping not to remove 15390good ones. 15391 15392If you intend to redirect both standard error and standard output, 15393redirect standard output first. This works better with HP-UX, 15394since its shell mishandles tracing if standard error is redirected 15395first: 15396 15397@example 15398$ @kbd{sh -x -c ': 2>err >out'} 15399+ : 15400+ 2> err $ @kbd{cat err} 154011> out 15402@end example 15403 15404Don't try to redirect the standard error of a command substitution. It 15405must be done @emph{inside} the command substitution. When running 15406@samp{: `cd /zorglub` 2>/dev/null} expect the error message to 15407escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly. 15408 15409On the other hand, some shells, such as Solaris or FreeBSD 15410@command{/bin/sh}, warn about missing programs before performing 15411redirections. Therefore, to silently check whether a program exists, it 15412is necessary to perform redirections on a subshell or brace group: 15413@example 15414$ @kbd{/bin/sh -c 'nosuch 2>/dev/null'} 15415nosuch: not found 15416$ @kbd{/bin/sh -c '(nosuch) 2>/dev/null'} 15417$ @kbd{/bin/sh -c '@{ nosuch; @} 2>/dev/null'} 15418$ @kbd{bash -c 'nosuch 2>/dev/null'} 15419@end example 15420 15421FreeBSD 6.2 sh may mix the trace output lines from the statements in a 15422shell pipeline. 15423 15424It is worth noting that Zsh (but not Ash nor Bash) makes it possible 15425in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}. 15426 15427Some shells, like @command{ash}, don't recognize bi-directional 15428redirection (@samp{<>}). And even on shells that recognize it, it is 15429not portable to use on fifos: Posix does not require read-write support 15430for named pipes, and Cygwin does not support it: 15431 15432@example 15433$ @kbd{mkfifo fifo} 15434$ @kbd{exec 5<>fifo} 15435$ @kbd{echo hi >&5} 15436bash: echo: write error: Communication error on send 15437@end example 15438 15439@noindent 15440Furthermore, versions of @command{dash} before 0.5.6 mistakenly truncate 15441regular files when using @samp{<>}: 15442 15443@example 15444$ @kbd{echo a > file} 15445$ @kbd{bash -c ': 1<>file'; cat file} 15446a 15447$ @kbd{dash -c ': 1<>file'; cat file} 15448$ rm a 15449@end example 15450 15451When catering to old systems, don't redirect the same file descriptor 15452several times, as you are doomed to failure under Ultrix. 15453 15454@example 15455ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995 15456UWS V4.4 (Rev. 11) 15457$ @kbd{eval 'echo matter >fullness' >void} 15458illegal io 15459$ @kbd{eval '(echo matter >fullness)' >void} 15460illegal io 15461$ @kbd{(eval '(echo matter >fullness)') >void} 15462Ambiguous output redirect. 15463@end example 15464 15465@noindent 15466In each case the expected result is of course @file{fullness} containing 15467@samp{matter} and @file{void} being empty. However, this bug is 15468probably not of practical concern to modern platforms. 15469 15470Solaris 10 @command{sh} will try to optimize away a @command{:} command 15471(even if it is redirected) in a loop after the first iteration, or in a 15472shell function after the first call: 15473 15474@example 15475$ @kbd{for i in 1 2 3 ; do : >x$i; done} 15476$ @kbd{ls x*} 15477x1 15478$ @kbd{f () @{ : >$1; @}; f y1; f y2; f y3;} 15479$ @kbd{ls y*} 15480y1 15481@end example 15482 15483@noindent 15484As a workaround, @command{echo} or @command{eval} can be used. 15485 15486Don't rely on file descriptors 0, 1, and 2 remaining closed in a 15487subsidiary program. If any of these descriptors is closed, the 15488operating system may open an unspecified file for the descriptor in the 15489new process image. Posix 2008 says this may be done only if the 15490subsidiary program is set-user-ID or set-group-ID, but HP-UX 11.23 does 15491it even for ordinary programs, and the next version of Posix will allow 15492HP-UX behavior. 15493 15494If you want a file descriptor above 2 to be inherited into a child 15495process, then you must use redirections specific to that command or a 15496containing subshell or command group, rather than relying on 15497@command{exec} in the shell. In @command{ksh} as well as HP-UX 15498@command{sh}, file descriptors above 2 which are opened using 15499@samp{exec @var{n}>file} are closed by a subsequent @samp{exec} (such as 15500that involved in the fork-and-exec which runs a program or script): 15501 15502@example 15503$ @kbd{echo 'echo hello >&5' >k} 15504$ @kbd{/bin/sh -c 'exec 5>t; ksh ./k; exec 5>&-; cat t} 15505hello 15506$ @kbd{bash -c 'exec 5>t; ksh ./k; exec 5>&-; cat t} 15507hello 15508$ @kbd{ksh -c 'exec 5>t; ksh ./k; exec 5>&-; cat t} 15509./k[1]: 5: cannot open [Bad file number] 15510$ @kbd{ksh -c '(ksh ./k) 5>t; cat t'} 15511hello 15512$ @kbd{ksh -c '@{ ksh ./k; @} 5>t; cat t'} 15513hello 15514$ @kbd{ksh -c '5>t ksh ./k; cat t} 15515hello 15516@end example 15517 15518Don't rely on duplicating a closed file descriptor to cause an 15519error. With Solaris @command{/bin/sh}, failed duplication is silently 15520ignored, which can cause unintended leaks to the original file 15521descriptor. In this example, observe the leak to standard output: 15522 15523@example 15524$ @kbd{bash -c 'echo hi >&3' 3>&-; echo $?} 15525bash: 3: Bad file descriptor 155261 15527$ @kbd{/bin/sh -c 'echo hi >&3' 3>&-; echo $?} 15528hi 155290 15530@end example 15531 15532Fortunately, an attempt to close an already closed file descriptor will 15533portably succeed. Likewise, it is safe to use either style of 15534@samp{@var{n}<&-} or @samp{@var{n}>&-} for closing a file descriptor, 15535even if it doesn't match the read/write mode that the file descriptor 15536was opened with. 15537 15538DOS variants cannot rename or remove open files, such as in 15539@samp{mv foo bar >foo} or @samp{rm foo >foo}, even though this is 15540perfectly portable among Posix hosts. 15541 15542A few ancient systems reserved some file descriptors. By convention, 15543file descriptor 3 was opened to @file{/dev/tty} when you logged into 15544Eighth Edition (1985) through Tenth Edition Unix (1989). File 15545descriptor 4 had a special use on the Stardent/Kubota Titan (circa 155461990), though we don't now remember what it was. Both these systems are 15547obsolete, so it's now safe to treat file descriptors 3 and 4 like any 15548other file descriptors. 15549 15550On the other hand, you can't portably use multi-digit file descriptors. 15551Solaris @command{ksh} doesn't understand any file descriptor larger than 15552@samp{9}: 15553 15554@example 15555$ @kbd{bash -c 'exec 10>&-'; echo $?} 155560 15557$ @kbd{ksh -c 'exec 9>&-'; echo $?} 155580 15559$ @kbd{ksh -c 'exec 10>&-'; echo $?} 15560ksh[1]: exec: 10: not found 15561127 15562@end example 15563 15564@c <http://lists.gnu.org/archive/html/bug-autoconf/2011-09/msg00004.html> 15565@node Signal Handling 15566@section Signal Handling 15567@cindex Signal handling in the shell 15568@cindex Signals, shells and 15569 15570Portable handling of signals within the shell is another major source of 15571headaches. This is worsened by the fact that various different, mutually 15572incompatible approaches are possible in this area, each with its 15573distinctive merits and demerits. A detailed description of these possible 15574approaches, as well as of their pros and cons, can be found in 15575@uref{http://www.cons.org/cracauer/sigint.html, this article}. 15576 15577Solaris 10 @command{/bin/sh} automatically traps most signals by default; 15578@c See: <http://dbaspot.com/shell/396118-bourne-shell-exit-code-term.html> 15579the shell still exits with error upon termination by one of those signals, 15580but in such a case the exit status might be somewhat unexpected (even if 15581allowed by POSIX, strictly speaking): 15582 15583@example 15584$ @kbd{bash -c 'kill -1 $$'; echo $?} # Will exit 128 + (signal number). 15585Hangup 15586129 15587$ @kbd{/bin/ksh -c 'kill -15 $$'; echo $?} # Likewise. 15588Terminated 15589143 15590$ @kbd{for sig in 1 2 3 15; do} 15591> @kbd{ echo $sig:} 15592> @kbd{ /bin/sh -c "kill -$s \$\$"; echo $?} 15593> @kbd{done} 15594signal 1: 15595Hangup 15596129 15597signal 2: 15598208 15599signal 3: 15600208 15601signal 15: 15602208 15603@end example 15604 15605This gets even worse if one is using the POSIX `wait' interface to get 15606details about the shell process terminations: it will result in the shell 15607having exited normally, rather than by receiving a signal. 15608 15609@example 15610$ @kbd{cat > foo.c <<'END'} 15611#include <stdio.h> /* for printf */ 15612#include <stdlib.h> /* for system */ 15613#include <sys/wait.h> /* for WIF* macros */ 15614int main(void) 15615@{ 15616 int status = system ("kill -15 $$"); 15617 printf ("Terminated by signal: %s\n", 15618 WIFSIGNALED (status) ? "yes" : "no"); 15619 printf ("Exited normally: %s\n", 15620 WIFEXITED (status) ? "yes" : "no"); 15621 return 0; 15622@} 15623END 15624@c $$ font-lock 15625$ @kbd{cc -o foo foo.c} 15626$ @kbd{./a.out} # On GNU/Linux 15627Terminated by signal: no 15628Exited normally: yes 15629$ @kbd{./a.out} # On Solaris 10 15630Terminated by signal: yes 15631Exited normally: no 15632@end example 15633 15634Various shells seem to handle @code{SIGQUIT} specially: they ignore it even 15635if it is not blocked, and even if the shell is not running interactively 15636(in fact, even if the shell has no attached tty); among these shells 15637are at least Bash (from version 2 onwards), Zsh 4.3.12, Solaris 10 15638@code{/bin/ksh} and @code{/usr/xpg4/bin/sh}, and AT&T @code{ksh93} (2011). 15639Still, @code{SIGQUIT} seems to be trappable quite portably within all 15640these shells. OTOH, some other shells doesn't special-case the handling 15641of @code{SIGQUIT}; among these shells are at least @code{pdksh} 5.2.14, 15642Solaris 10 and NetBSD 5.1 @code{/bin/sh}, and the Almquist Shell 0.5.5.1. 15643 15644@c See: <http://mail.opensolaris.org/pipermail/ksh93-integration-discuss/2009-February/004121.html> 15645Some shells (especially Korn shells and derivatives) might try to 15646propagate to themselves a signal that has killed a child process; this is 15647not a bug, but a conscious design choice (although its overall value might 15648be debatable). The exact details of how this is attained vary from shell 15649to shell. For example, upon running @code{perl -e 'kill 2, $$'}, after 15650the perl process has been interrupted AT&T @code{ksh93} (2011) will 15651proceed to send itself a @code{SIGINT}, while Solaris 10 @code{/bin/ksh} 15652and @code{/usr/xpg4/bin/sh} will proceed to exit with status 130 (i.e., 15653128 + 2). In any case, if there is an active trap associated with 15654@code{SIGINT}, those shells will correctly execute it. 15655 15656@c See: <http://www.austingroupbugs.net/view.php?id=51> 15657Some Korn shells, when a child process die due receiving a signal with 15658signal number @var{n}, can leave in @samp{$?} an exit status of 15659256+@var{n} instead of the more common 128+@var{n}. Observe the 15660difference between AT&T @code{ksh93} (2011) and @code{bash} 4.1.5 on 15661Debian: 15662 15663@example 15664$ @kbd{/bin/ksh -c 'sh -c "kill -1 \$\$"; echo $?'} 15665/bin/ksh: line 1: 7837: Hangup 15666257 15667$ @kbd{/bin/bash -c 'sh -c "kill -1 \$\$"; echo $?'} 15668/bin/bash: line 1: 7861 Hangup (sh -c "kill -1 \$\$") 15669129 15670@end example 15671 15672@noindent 15673This @command{ksh} behavior is allowed by POSIX, if implemented with 15674due care; see this @uref{http://www.austingroupbugs.net/view.php?id=51, 15675Austin Group discussion} for more background. However, if it is not 15676implemented with proper care, such a behavior might cause problems 15677in some corner cases. To see why, assume we have a ``wrapper'' script 15678like this: 15679 15680@example 15681#!/bin/sh 15682# Ignore some signals in the shell only, not in its child processes. 15683trap : 1 2 13 15 15684wrapped_command "$@@" 15685ret=$? 15686other_command 15687exit $ret 15688@end example 15689 15690@noindent 15691If @command{wrapped_command} is interrupted by a @code{SIGHUP} (which 15692has signal number 1), @code{ret} will be set to 257. Unless the 15693@command{exit} shell builtin is smart enough to understand that such 15694a value can only have originated from a signal, and adjust the final 15695wait status of the shell appropriately, the value 257 will just get 15696truncated to 1 by the closing @code{exit} call, so that a caller of 15697the script will have no way to determine that termination by a signal 15698was involved. Observe the different behavior of AT&T @code{ksh93} 15699(2011) and @code{bash} 4.1.5 on Debian: 15700 15701@example 15702$ @kbd{cat foo.sh} 15703#!/bin/sh 15704sh -c 'kill -1 $$' 15705ret=$? 15706echo $ret 15707exit $ret 15708$ @kbd{/bin/ksh foo.sh; echo $?} 15709foo.sh: line 2: 12479: Hangup 15710257 157111 15712$ @kbd{/bin/bash foo.sh; echo $?} 15713foo.sh: line 2: 12487 Hangup (sh -c 'kill -1 $$') 15714129 15715129 15716@end example 15717 15718@node File System Conventions 15719@section File System Conventions 15720@cindex File system conventions 15721 15722Autoconf uses shell-script processing extensively, so the file names 15723that it processes should not contain characters that are special to the 15724shell. Special characters include space, tab, newline, NUL, and 15725the following: 15726 15727@example 15728" # $ & ' ( ) * ; < = > ? [ \ ` | 15729@end example 15730 15731Also, file names should not begin with @samp{~} or @samp{-}, and should 15732contain neither @samp{-} immediately after @samp{/} nor @samp{~} 15733immediately after @samp{:}. On Posix-like platforms, directory names 15734should not contain @samp{:}, as this runs afoul of @samp{:} used as the 15735path separator. 15736 15737These restrictions apply not only to the files that you distribute, but 15738also to the absolute file names of your source, build, and destination 15739directories. 15740 15741On some Posix-like platforms, @samp{!} and @samp{^} are special too, so 15742they should be avoided. 15743 15744Posix lets implementations treat leading @file{//} specially, but 15745requires leading @file{///} and beyond to be equivalent to @file{/}. 15746Most Unix variants treat @file{//} like @file{/}. However, some treat 15747@file{//} as a ``super-root'' that can provide access to files that are 15748not otherwise reachable from @file{/}. The super-root tradition began 15749with Apollo Domain/OS, which died out long ago, but unfortunately Cygwin 15750has revived it. 15751 15752While @command{autoconf} and friends are usually run on some Posix 15753variety, they can be used on other systems, most notably DOS 15754variants. This impacts several assumptions regarding file names. 15755 15756@noindent 15757For example, the following code: 15758 15759@example 15760case $foo_dir in 15761 /*) # Absolute 15762 ;; 15763 *) 15764 foo_dir=$dots$foo_dir ;; 15765esac 15766@end example 15767 15768@noindent 15769fails to properly detect absolute file names on those systems, because 15770they can use a drivespec, and usually use a backslash as directory 15771separator. If you want to be portable to DOS variants (at the 15772price of rejecting valid but oddball Posix file names like @file{a:\b}), 15773you can check for absolute file names like this: 15774 15775@cindex absolute file names, detect 15776@example 15777case $foo_dir in 15778 [\\/]* | ?:[\\/]* ) # Absolute 15779 ;; 15780 *) 15781 foo_dir=$dots$foo_dir ;; 15782esac 15783@end example 15784 15785@noindent 15786Make sure you quote the brackets if appropriate and keep the backslash as 15787first character (@pxref{case, , Limitations of Shell Builtins}). 15788 15789Also, because the colon is used as part of a drivespec, these systems don't 15790use it as path separator. When creating or accessing paths, you can use the 15791@code{PATH_SEPARATOR} output variable instead. @command{configure} sets this 15792to the appropriate value for the build system (@samp{:} or @samp{;}) when it 15793starts up. 15794 15795File names need extra care as well. While DOS variants 15796that are Posixy enough to run @command{autoconf} (such as DJGPP) 15797are usually able to handle long file names properly, there are still 15798limitations that can seriously break packages. Several of these issues 15799can be easily detected by the 15800@uref{ftp://@/ftp.gnu.org/@/gnu/@/non-gnu/@/doschk/@/doschk-1.1.tar.gz, doschk} 15801package. 15802 15803A short overview follows; problems are marked with SFN/LFN to 15804indicate where they apply: SFN means the issues are only relevant to 15805plain DOS, not to DOS under Microsoft Windows 15806variants, while LFN identifies problems that exist even under 15807Microsoft Windows variants. 15808 15809@table @asis 15810@item No multiple dots (SFN) 15811DOS cannot handle multiple dots in file names. This is an especially 15812important thing to remember when building a portable configure script, 15813as @command{autoconf} uses a .in suffix for template files. 15814 15815This is perfectly OK on Posix variants: 15816 15817@example 15818AC_CONFIG_HEADERS([config.h]) 15819AC_CONFIG_FILES([source.c foo.bar]) 15820AC_OUTPUT 15821@end example 15822 15823@noindent 15824but it causes problems on DOS, as it requires @samp{config.h.in}, 15825@samp{source.c.in} and @samp{foo.bar.in}. To make your package more portable 15826to DOS-based environments, you should use this instead: 15827 15828@example 15829AC_CONFIG_HEADERS([config.h:config.hin]) 15830AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in]) 15831AC_OUTPUT 15832@end example 15833 15834@item No leading dot (SFN) 15835DOS cannot handle file names that start with a dot. This is usually 15836not important for @command{autoconf}. 15837 15838@item Case insensitivity (LFN) 15839DOS is case insensitive, so you cannot, for example, have both a 15840file called @samp{INSTALL} and a directory called @samp{install}. This 15841also affects @command{make}; if there's a file called @samp{INSTALL} in 15842the directory, @samp{make install} does nothing (unless the 15843@samp{install} target is marked as PHONY). 15844 15845@item The 8+3 limit (SFN) 15846Because the DOS file system only stores the first 8 characters of 15847the file name and the first 3 of the extension, those must be unique. 15848That means that @file{foobar-part1.c}, @file{foobar-part2.c} and 15849@file{foobar-prettybird.c} all resolve to the same file name 15850(@file{FOOBAR-P.C}). The same goes for @file{foo.bar} and 15851@file{foo.bartender}. 15852 15853The 8+3 limit is not usually a problem under Microsoft Windows, as it 15854uses numeric 15855tails in the short version of file names to make them unique. However, a 15856registry setting can turn this behavior off. While this makes it 15857possible to share file trees containing long file names between SFN 15858and LFN environments, it also means the above problem applies there 15859as well. 15860 15861@item Invalid characters (LFN) 15862Some characters are invalid in DOS file names, and should therefore 15863be avoided. In a LFN environment, these are @samp{/}, @samp{\}, 15864@samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}. 15865In a SFN environment, other characters are also invalid. These 15866include @samp{+}, @samp{,}, @samp{[} and @samp{]}. 15867 15868@item Invalid names (LFN) 15869Some DOS file names are reserved, and cause problems if you 15870try to use files with those names. These names include @file{CON}, 15871@file{AUX}, @file{COM1}, @file{COM2}, @file{COM3}, @file{COM4}, 15872@file{LPT1}, @file{LPT2}, @file{LPT3}, @file{NUL}, and @file{PRN}. 15873File names are case insensitive, so even names like 15874@file{aux/config.guess} are disallowed. 15875 15876@end table 15877 15878@node Shell Pattern Matching 15879@section Shell Pattern Matching 15880@cindex Shell pattern matching 15881 15882Nowadays portable patterns can use negated character classes like 15883@samp{[!-aeiou]}. The older syntax @samp{[^-aeiou]} is supported by 15884some shells but not others; hence portable scripts should never use 15885@samp{^} as the first character of a bracket pattern. 15886 15887Outside the C locale, patterns like @samp{[a-z]} are problematic since 15888they may match characters that are not lower-case letters. 15889 15890@node Shell Substitutions 15891@section Shell Substitutions 15892@cindex Shell substitutions 15893 15894Contrary to a persistent urban legend, the Bourne shell does not 15895systematically split variables and back-quoted expressions, in particular 15896on the right-hand side of assignments and in the argument of @code{case}. 15897For instance, the following code: 15898 15899@example 15900case "$given_srcdir" in 15901.) top_srcdir="`echo "$dots" | sed 's|/$||'`" ;; 15902*) top_srcdir="$dots$given_srcdir" ;; 15903esac 15904@end example 15905 15906@noindent 15907is more readable when written as: 15908 15909@example 15910case $given_srcdir in 15911.) top_srcdir=`echo "$dots" | sed 's|/$||'` ;; 15912*) top_srcdir=$dots$given_srcdir ;; 15913esac 15914@end example 15915 15916@noindent 15917and in fact it is even @emph{more} portable: in the first case of the 15918first attempt, the computation of @code{top_srcdir} is not portable, 15919since not all shells properly understand @code{"`@dots{}"@dots{}"@dots{}`"}, 15920for example Solaris 10 ksh: 15921 15922@example 15923$ @kbd{foo="`echo " bar" | sed 's, ,,'`"} 15924ksh: : cannot execute 15925ksh: bar | sed 's, ,,': cannot execute 15926@end example 15927 15928@noindent 15929Posix does not specify behavior for this sequence. On the other hand, 15930behavior for @code{"`@dots{}\"@dots{}\"@dots{}`"} is specified by Posix, 15931but in practice, not all shells understand it the same way: pdksh 5.2.14 15932prints spurious quotes when in Posix mode: 15933 15934@example 15935$ @kbd{echo "`echo \"hello\"`"} 15936hello 15937$ @kbd{set -o posix} 15938$ @kbd{echo "`echo \"hello\"`"} 15939"hello" 15940@end example 15941 15942@noindent 15943There is just no portable way to use double-quoted strings inside 15944double-quoted back-quoted expressions (pfew!). 15945 15946Bash 4.1 has a bug where quoted empty strings adjacent to unquoted 15947parameter expansions are elided during word splitting. Meanwhile, zsh 15948does not perform word splitting except when in Bourne compatibility 15949mode. In the example below, the correct behavior is to have five 15950arguments to the function, and exactly two spaces on either side of the 15951middle @samp{-}, since word splitting collapses multiple spaces in 15952@samp{$f} but leaves empty arguments intact. 15953 15954@example 15955$ @kbd{bash -c 'n() @{ echo "$#$@@"; @}; f=" - "; n - ""$f"" -'} 159563- - - 15957$ @kbd{ksh -c 'n() @{ echo "$#$@@"; @}; f=" - "; n - ""$f"" -'} 159585- - - 15959$ @kbd{zsh -c 'n() @{ echo "$#$@@"; @}; f=" - "; n - ""$f"" -'} 159603- - - 15961$ @kbd{zsh -c 'emulate sh;} 15962> @kbd{n() @{ echo "$#$@@"; @}; f=" - "; n - ""$f"" -'} 159635- - - 15964@end example 15965 15966@noindent 15967You can work around this by doing manual word splitting, such as using 15968@samp{"$str" $list} rather than @samp{"$str"$list}. 15969 15970There are also portability pitfalls with particular expansions: 15971 15972@table @code 15973@item $@@ 15974@cindex @code{"$@@"} 15975One of the most famous shell-portability issues is related to 15976@samp{"$@@"}. When there are no positional arguments, Posix says 15977that @samp{"$@@"} is supposed to be equivalent to nothing, but the 15978original Unix version 7 Bourne shell treated it as equivalent to 15979@samp{""} instead, and this behavior survives in later implementations 15980like Digital Unix 5.0. 15981 15982The traditional way to work around this portability problem is to use 15983@samp{$@{1+"$@@"@}}. Unfortunately this method does not work with 15984Zsh (3.x and 4.x), which is used on Mac OS X@. When emulating 15985the Bourne shell, Zsh performs word splitting on @samp{$@{1+"$@@"@}}: 15986 15987@example 15988zsh $ @kbd{emulate sh} 15989zsh $ @kbd{for i in "$@@"; do echo $i; done} 15990Hello World 15991! 15992zsh $ @kbd{for i in $@{1+"$@@"@}; do echo $i; done} 15993Hello 15994World 15995! 15996@end example 15997 15998@noindent 15999Zsh handles plain @samp{"$@@"} properly, but we can't use plain 16000@samp{"$@@"} because of the portability problems mentioned above. 16001One workaround relies on Zsh's ``global aliases'' to convert 16002@samp{$@{1+"$@@"@}} into @samp{"$@@"} by itself: 16003 16004@example 16005test "$@{ZSH_VERSION+set@}" = set && alias -g '$@{1+"$@@"@}'='"$@@"' 16006@end example 16007 16008Zsh only recognizes this alias when a shell word matches it exactly; 16009@samp{"foo"$@{1+"$@@"@}} remains subject to word splitting. Since this 16010case always yields at least one shell word, use plain @samp{"$@@"}. 16011 16012A more conservative workaround is to avoid @samp{"$@@"} if it is 16013possible that there may be no positional arguments. For example, 16014instead of: 16015 16016@example 16017cat conftest.c "$@@" 16018@end example 16019 16020you can use this instead: 16021 16022@example 16023case $# in 160240) cat conftest.c;; 16025*) cat conftest.c "$@@";; 16026esac 16027@end example 16028 16029Autoconf macros often use the @command{set} command to update 16030@samp{$@@}, so if you are writing shell code intended for 16031@command{configure} you should not assume that the value of @samp{$@@} 16032persists for any length of time. 16033 16034 16035@item $@{10@} 16036@cindex positional parameters 16037The 10th, 11th, @dots{} positional parameters can be accessed only after 16038a @code{shift}. The 7th Edition shell reported an error if given 16039@code{$@{10@}}, and 16040Solaris 10 @command{/bin/sh} still acts that way: 16041 16042@example 16043$ @kbd{set 1 2 3 4 5 6 7 8 9 10} 16044$ @kbd{echo $@{10@}} 16045bad substitution 16046@end example 16047 16048Conversely, not all shells obey the Posix rule that when braces are 16049omitted, multiple digits beyond a @samp{$} imply the single-digit 16050positional parameter expansion concatenated with the remaining literal 16051digits. To work around the issue, you must use braces. 16052 16053@example 16054$ @kbd{bash -c 'set a b c d e f g h i j; echo $10 $@{1@}0'} 16055a0 a0 16056$ @kbd{dash -c 'set a b c d e f g h i j; echo $10 $@{1@}0'} 16057j a0 16058@end example 16059 16060@item $@{@var{var}:-@var{value}@} 16061@c Info cannot handle `:' in index entries. 16062@ifnotinfo 16063@cindex @code{$@{@var{var}:-@var{value}@}} 16064@end ifnotinfo 16065@cindex @code{$@{@var{var}-@var{value}@}} 16066Old BSD shells, including the Ultrix @code{sh}, don't accept the 16067colon for any shell substitution, and complain and die. 16068Similarly for $@{@var{var}:=@var{value}@}, $@{@var{var}:?@var{value}@}, etc. 16069However, all shells that support functions allow the use of colon in 16070shell substitution, and since m4sh requires functions, you can portably 16071use null variable substitution patterns in configure scripts. 16072 16073@item $@{@var{var}+@var{value}@} 16074@cindex @code{$@{@var{var}+@var{value}@}} 16075When using @samp{$@{@var{var}-@var{value}@}} or 16076@samp{$@{@var{var}-@var{value}@}} for providing alternate substitutions, 16077@var{value} must either be a single shell word, quoted, or in the 16078context of an unquoted here-document. Solaris 16079@command{/bin/sh} complains otherwise. 16080 16081@example 16082$ @kbd{/bin/sh -c 'echo $@{a-b c@}'} 16083/bin/sh: bad substitution 16084$ @kbd{/bin/sh -c 'echo $@{a-'\''b c'\''@}'} 16085b c 16086$ @kbd{/bin/sh -c 'echo "$@{a-b c@}"'} 16087b c 16088$ @kbd{/bin/sh -c 'cat <<EOF 16089$@{a-b c@} 16090EOF} 16091b c 16092@end example 16093 16094According to Posix, if an expansion occurs inside double quotes, then 16095the use of unquoted double quotes within @var{value} is unspecified, and 16096any single quotes become literal characters; in that case, escaping must 16097be done with backslash. Likewise, the use of unquoted here-documents is 16098a case where double quotes have unspecified results: 16099 16100@example 16101$ @kbd{/bin/sh -c 'echo "$@{a-"b c"@}"'} 16102/bin/sh: bad substitution 16103$ @kbd{ksh -c 'echo "$@{a-"b c"@}"'} 16104b c 16105$ @kbd{bash -c 'echo "$@{a-"b c"@}"'} 16106b c 16107$ @kbd{/bin/sh -c 'a=; echo $@{a+'\''b c'\''@}'} 16108b c 16109$ @kbd{/bin/sh -c 'a=; echo "$@{a+'\''b c'\''@}"'} 16110'b c' 16111$ @kbd{/bin/sh -c 'a=; echo "$@{a+\"b c\"@}"'} 16112"b c" 16113$ @kbd{/bin/sh -c 'a=; echo "$@{a+b c@}"'} 16114b c 16115$ @kbd{/bin/sh -c 'cat <<EOF 16116$@{a-"b c"@} 16117EOF'} 16118"b c" 16119$ @kbd{/bin/sh -c 'cat <<EOF 16120$@{a-'b c'@} 16121EOF'} 16122'b c' 16123$ @kbd{bash -c 'cat <<EOF 16124$@{a-"b c"@} 16125EOF'} 16126b c 16127$ @kbd{bash -c 'cat <<EOF 16128$@{a-'b c'@} 16129EOF'} 16130'b c' 16131@end example 16132 16133Perhaps the easiest way to work around quoting issues in a manner 16134portable to all shells is to place the results in a temporary variable, 16135then use @samp{$t} as the @var{value}, rather than trying to inline 16136the expression needing quoting. 16137 16138@example 16139$ @kbd{/bin/sh -c 't="b c\"'\''@}\\"; echo "$@{a-$t@}"'} 16140b c"'@}\ 16141$ @kbd{ksh -c 't="b c\"'\''@}\\"; echo "$@{a-$t@}"'} 16142b c"'@}\ 16143$ @kbd{bash -c 't="b c\"'\''@}\\"; echo "$@{a-$t@}"'} 16144b c"'@}\ 16145@end example 16146 16147@item $@{@var{var}=@var{value}@} 16148@cindex @code{$@{@var{var}=@var{value}@}} 16149When using @samp{$@{@var{var}=@var{value}@}} to assign a default value 16150to @var{var}, remember that even though the assignment to @var{var} does 16151not undergo file name expansion, the result of the variable expansion 16152does unless the expansion occurred within double quotes. In particular, 16153when using @command{:} followed by unquoted variable expansion for the 16154side effect of setting a default value, if the final value of 16155@samp{$var} contains any globbing characters (either from @var{value} or 16156from prior contents), the shell has to spend time performing file name 16157expansion and field splitting even though those results will not be 16158used. Therefore, it is a good idea to consider double quotes when performing 16159default initialization; while remembering how this impacts any quoting 16160characters appearing in @var{value}. 16161 16162@example 16163$ @kbd{time bash -c ': "$@{a=/usr/bin/*@}"; echo "$a"'} 16164/usr/bin/* 16165 16166real 0m0.005s 16167user 0m0.002s 16168sys 0m0.003s 16169$ @kbd{time bash -c ': $@{a=/usr/bin/*@}; echo "$a"'} 16170/usr/bin/* 16171 16172real 0m0.039s 16173user 0m0.026s 16174sys 0m0.009s 16175$ @kbd{time bash -c 'a=/usr/bin/*; : $@{a=noglob@}; echo "$a"'} 16176/usr/bin/* 16177 16178real 0m0.031s 16179user 0m0.020s 16180sys 0m0.010s 16181 16182$ @kbd{time bash -c 'a=/usr/bin/*; : "$@{a=noglob@}"; echo "$a"'} 16183/usr/bin/* 16184 16185real 0m0.006s 16186user 0m0.002s 16187sys 0m0.003s 16188@end example 16189 16190As with @samp{+} and @samp{-}, you must use quotes when using @samp{=} 16191if the @var{value} contains more than one shell word; either single 16192quotes for just the @var{value}, or double quotes around the entire 16193expansion: 16194 16195@example 16196$ @kbd{: $@{var1='Some words'@}} 16197$ @kbd{: "$@{var2=like this@}"} 16198$ @kbd{echo $var1 $var2} 16199Some words like this 16200@end example 16201 16202@noindent 16203otherwise some shells, such as Solaris @command{/bin/sh} or on Digital 16204Unix V 5.0, die because of a ``bad substitution''. Meanwhile, Posix 16205requires that with @samp{=}, quote removal happens prior to the 16206assignment, and the expansion be the final contents of @var{var} without 16207quoting (and thus subject to field splitting), in contrast to the 16208behavior with @samp{-} passing the quoting through to the final 16209expansion. However, @command{bash} 4.1 does not obey this rule. 16210 16211@example 16212$ @kbd{ksh -c 'echo $@{var-a\ \ b@}'} 16213a b 16214$ @kbd{ksh -c 'echo $@{var=a\ \ b@}'} 16215a b 16216$ @kbd{bash -c 'echo $@{var=a\ \ b@}'} 16217a b 16218@end example 16219 16220Finally, Posix states that when mixing @samp{$@{a=b@}} with regular 16221commands, it is unspecified whether the assignments affect the parent 16222shell environment. It is best to perform assignments independently from 16223commands, to avoid the problems demonstrated in this example: 16224 16225@example 16226$ @kbd{bash -c 'x= y=$@{x:=b@} sh -c "echo +\$x+\$y+";echo -$x-'} 16227+b+b+ 16228-b- 16229$ @kbd{/bin/sh -c 'x= y=$@{x:=b@} sh -c "echo +\$x+\$y+";echo -$x-'} 16230++b+ 16231-- 16232$ @kbd{ksh -c 'x= y=$@{x:=b@} sh -c "echo +\$x+\$y+";echo -$x-'} 16233+b+b+ 16234-- 16235@end example 16236 16237@item $@{@var{var}=@var{value}@} 16238@cindex @code{$@{@var{var}=@var{literal}@}} 16239Solaris @command{/bin/sh} has a frightening bug in its handling of 16240literal assignments. Imagine you need set a variable to a string containing 16241@samp{@}}. This @samp{@}} character confuses Solaris @command{/bin/sh} 16242when the affected variable was already set. This bug can be exercised 16243by running: 16244 16245@example 16246$ @kbd{unset foo} 16247$ @kbd{foo=$@{foo='@}'@}} 16248$ @kbd{echo $foo} 16249@} 16250$ @kbd{foo=$@{foo='@}' # no error; this hints to what the bug is} 16251$ @kbd{echo $foo} 16252@} 16253$ @kbd{foo=$@{foo='@}'@}} 16254$ @kbd{echo $foo} 16255@}@} 16256 ^ ugh! 16257@end example 16258 16259It seems that @samp{@}} is interpreted as matching @samp{$@{}, even 16260though it is enclosed in single quotes. The problem doesn't happen 16261using double quotes, or when using a temporary variable holding the 16262problematic string. 16263 16264@item $@{@var{var}=@var{expanded-value}@} 16265@cindex @code{$@{@var{var}=@var{expanded-value}@}} 16266On Ultrix, 16267running 16268 16269@example 16270default="yu,yaa" 16271: $@{var="$default"@} 16272@end example 16273 16274@noindent 16275sets @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of 16276each char is set. You don't observe the phenomenon using a simple 16277@samp{echo $var} since apparently the shell resets the 8th bit when it 16278expands $var. Here are two means to make this shell confess its sins: 16279 16280@example 16281$ @kbd{cat -v <<EOF 16282$var 16283EOF} 16284@end example 16285 16286@noindent 16287and 16288 16289@example 16290$ @kbd{set | grep '^var=' | cat -v} 16291@end example 16292 16293One classic incarnation of this bug is: 16294 16295@example 16296default="a b c" 16297: $@{list="$default"@} 16298for c in $list; do 16299 echo $c 16300done 16301@end example 16302 16303@noindent 16304You'll get @samp{a b c} on a single line. Why? Because there are no 16305spaces in @samp{$list}: there are @samp{M- }, i.e., spaces with the 8th 16306bit set, hence no IFS splitting is performed!!! 16307 16308One piece of good news is that Ultrix works fine with @samp{: 16309$@{list=$default@}}; i.e., if you @emph{don't} quote. The bad news is 16310then that QNX 4.25 then sets @var{list} to the @emph{last} item of 16311@var{default}! 16312 16313The portable way out consists in using a double assignment, to switch 16314the 8th bit twice on Ultrix: 16315 16316@example 16317list=$@{list="$default"@} 16318@end example 16319 16320@noindent 16321@dots{}but beware of the @samp{@}} bug from Solaris (see above). For safety, 16322use: 16323 16324@example 16325test "$@{var+set@}" = set || var=@var{@{value@}} 16326@end example 16327 16328@item $@{#@var{var}@} 16329@itemx $@{@var{var}%@var{word}@} 16330@itemx $@{@var{var}%%@var{word}@} 16331@itemx $@{@var{var}#@var{word}@} 16332@itemx $@{@var{var}##@var{word}@} 16333@cindex @code{$@{#@var{var}@}} 16334@cindex @code{$@{@var{var}%@var{word}@}} 16335@cindex @code{$@{@var{var}%%@var{word}@}} 16336@cindex @code{$@{@var{var}#@var{word}@}} 16337@cindex @code{$@{@var{var}##@var{word}@}} 16338Posix requires support for these usages, but they do not work with many 16339traditional shells, e.g., Solaris 10 @command{/bin/sh}. 16340 16341Also, @command{pdksh} 5.2.14 mishandles some @var{word} forms. For 16342example if @samp{$1} is @samp{a/b} and @samp{$2} is @samp{a}, then 16343@samp{$@{1#$2@}} should yield @samp{/b}, but with @command{pdksh} it 16344yields the empty string. 16345 16346 16347@item `@var{commands}` 16348@cindex @code{`@var{commands}`} 16349@cindex Command Substitution 16350Posix requires shells to trim all trailing newlines from command 16351output before substituting it, so assignments like 16352@samp{dir=`echo "$file" | tr a A`} do not work as expected if 16353@samp{$file} ends in a newline. 16354 16355While in general it makes no sense, do not substitute a single builtin 16356with side effects, because Ash 0.2, trying to optimize, does not fork a 16357subshell to perform the command. 16358 16359For instance, if you wanted to check that @command{cd} is silent, do not 16360use @samp{test -z "`cd /`"} because the following can happen: 16361 16362@example 16363$ @kbd{pwd} 16364/tmp 16365$ @kbd{test -z "`cd /`" && pwd} 16366/ 16367@end example 16368 16369@noindent 16370The result of @samp{foo=`exit 1`} is left as an exercise to the reader. 16371 16372The MSYS shell leaves a stray byte in the expansion of a double-quoted 16373command substitution of a native program, if the end of the substitution 16374is not aligned with the end of the double quote. This may be worked 16375around by inserting another pair of quotes: 16376 16377@example 16378$ @kbd{echo "`printf 'foo\r\n'` bar" > broken} 16379$ @kbd{echo "`printf 'foo\r\n'`"" bar" | cmp - broken} 16380- broken differ: char 4, line 1 16381@end example 16382 16383Upon interrupt or SIGTERM, some shells may abort a command substitution, 16384replace it with a null string, and wrongly evaluate the enclosing 16385command before entering the trap or ending the script. This can lead to 16386spurious errors: 16387 16388@example 16389$ @kbd{sh -c 'if test `sleep 5; echo hi` = hi; then echo yes; fi'} 16390$ @kbd{^C} 16391sh: test: hi: unexpected operator/operand 16392@end example 16393 16394@noindent 16395You can avoid this by assigning the command substitution to a temporary 16396variable: 16397 16398@example 16399$ @kbd{sh -c 'res=`sleep 5; echo hi` 16400 if test "x$res" = xhi; then echo yes; fi'} 16401$ @kbd{^C} 16402@end example 16403 16404@item $(@var{commands}) 16405@cindex @code{$(@var{commands})} 16406This construct is meant to replace @samp{`@var{commands}`}, 16407and it has most of the problems listed under @code{`@var{commands}`}. 16408 16409This construct can be 16410nested while this is impossible to do portably with back quotes. 16411Unfortunately it is not yet universally supported. Most notably, even recent 16412releases of Solaris don't support it: 16413 16414@example 16415$ @kbd{showrev -c /bin/sh | grep version} 16416Command version: SunOS 5.10 Generic 121005-03 Oct 2006 16417$ @kbd{echo $(echo blah)} 16418syntax error: `(' unexpected 16419@end example 16420 16421@noindent 16422nor does IRIX 6.5's Bourne shell: 16423@example 16424$ @kbd{uname -a} 16425IRIX firebird-image 6.5 07151432 IP22 16426$ @kbd{echo $(echo blah)} 16427$(echo blah) 16428@end example 16429 16430If you do use @samp{$(@var{commands})}, make sure that the commands 16431do not start with a parenthesis, as that would cause confusion with 16432a different notation @samp{$((@var{expression}))} that in modern 16433shells is an arithmetic expression not a command. To avoid the 16434confusion, insert a space between the two opening parentheses. 16435 16436Avoid @var{commands} that contain unbalanced parentheses in 16437here-documents, comments, or case statement patterns, as many shells 16438mishandle them. For example, Bash 3.1, @samp{ksh88}, @command{pdksh} 164395.2.14, and Zsh 4.2.6 all mishandle the following valid command: 16440 16441@example 16442echo $(case x in x) echo hello;; esac) 16443@end example 16444 16445 16446@item $((@var{expression})) 16447@cindex @code{$((@var{expression}))} 16448Arithmetic expansion is not portable as some shells (most 16449notably Solaris 10 @command{/bin/sh}) don't support it. 16450 16451Among shells that do support @samp{$(( ))}, not all of them obey the 16452Posix rule that octal and hexadecimal constants must be recognized: 16453 16454@example 16455$ @kbd{bash -c 'echo $(( 010 + 0x10 ))'} 1645624 16457$ @kbd{zsh -c 'echo $(( 010 + 0x10 ))'} 1645826 16459$ @kbd{zsh -c 'emulate sh; echo $(( 010 + 0x10 ))'} 1646024 16461$ @kbd{pdksh -c 'echo $(( 010 + 0x10 ))'} 16462pdksh: 010 + 0x10 : bad number `0x10' 16463$ @kbd{pdksh -c 'echo $(( 010 ))'} 1646410 16465@end example 16466 16467When it is available, using arithmetic expansion provides a noticeable 16468speedup in script execution; but testing for support requires 16469@command{eval} to avoid syntax errors. The following construct is used 16470by @code{AS_VAR_ARITH} to provide arithmetic computation when all 16471arguments are provided in decimal and without a leading zero, and all 16472operators are properly quoted and appear as distinct arguments: 16473 16474@example 16475if ( eval 'test $(( 1 + 1 )) = 2' ) 2>/dev/null; then 16476 eval 'func_arith () 16477 @{ 16478 func_arith_result=$(( $* )) 16479 @}' 16480else 16481 func_arith () 16482 @{ 16483 func_arith_result=`expr "$@@"` 16484 @} 16485fi 16486func_arith 1 + 1 16487foo=$func_arith_result 16488@end example 16489 16490 16491@item ^ 16492@cindex @code{^} quoting 16493Always quote @samp{^}, otherwise traditional shells such as 16494@command{/bin/sh} on Solaris 10 treat this like @samp{|}. 16495 16496@end table 16497 16498 16499@node Assignments 16500@section Assignments 16501@cindex Shell assignments 16502 16503When setting several variables in a row, be aware that the order of the 16504evaluation is undefined. For instance @samp{foo=1 foo=2; echo $foo} 16505gives @samp{1} with Solaris @command{/bin/sh}, but @samp{2} with Bash. 16506You must use 16507@samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}. 16508 16509Don't rely on the following to find @file{subdir/program}: 16510 16511@example 16512PATH=subdir$PATH_SEPARATOR$PATH program 16513@end example 16514 16515@noindent 16516as this does not work with Zsh 3.0.6. Use something like this 16517instead: 16518 16519@example 16520(PATH=subdir$PATH_SEPARATOR$PATH; export PATH; exec program) 16521@end example 16522 16523Don't rely on the exit status of an assignment: Ash 0.2 does not change 16524the status and propagates that of the last statement: 16525 16526@example 16527$ @kbd{false || foo=bar; echo $?} 165281 16529$ @kbd{false || foo=`:`; echo $?} 165300 16531@end example 16532 16533@noindent 16534and to make things even worse, QNX 4.25 just sets the exit status 16535to 0 in any case: 16536 16537@example 16538$ @kbd{foo=`exit 1`; echo $?} 165390 16540@end example 16541 16542To assign default values, follow this algorithm: 16543 16544@enumerate 16545@item 16546If the default value is a literal and does not contain any closing 16547brace, use: 16548 16549@example 16550: "$@{var='my literal'@}" 16551@end example 16552 16553@item 16554If the default value contains no closing brace, has to be expanded, and 16555the variable being initialized is not intended to be IFS-split 16556(i.e., it's not a list), then use: 16557 16558@example 16559: $@{var="$default"@} 16560@end example 16561 16562@item 16563If the default value contains no closing brace, has to be expanded, and 16564the variable being initialized is intended to be IFS-split (i.e., it's a list), 16565then use: 16566 16567@example 16568var=$@{var="$default"@} 16569@end example 16570 16571@item 16572If the default value contains a closing brace, then use: 16573 16574@example 16575test "$@{var+set@}" = set || var="has a '@}'" 16576@end example 16577@end enumerate 16578 16579In most cases @samp{var=$@{var="$default"@}} is fine, but in case of 16580doubt, just use the last form. @xref{Shell Substitutions}, items 16581@samp{$@{@var{var}:-@var{value}@}} and @samp{$@{@var{var}=@var{value}@}} 16582for the rationale. 16583 16584@node Parentheses 16585@section Parentheses in Shell Scripts 16586@cindex Shell parentheses 16587 16588Beware of two opening parentheses in a row, as many shell 16589implementations treat them specially, and Posix says that a portable 16590script cannot use @samp{((} outside the @samp{$((} form used for shell 16591arithmetic. In traditional shells, @samp{((cat))} behaves like 16592@samp{(cat)}; but many shells, including 16593Bash and the Korn shell, treat @samp{((cat))} as an arithmetic 16594expression equivalent to @samp{let "cat"}, and may or may not report an 16595error when they detect that @samp{cat} is not a number. As another 16596example, @samp{pdksh} 5.2.14 does not treat the following code 16597as a traditional shell would: 16598 16599@example 16600if ((true) || false); then 16601 echo ok 16602fi 16603@end example 16604 16605@noindent 16606To work around this problem, insert a space between the two opening 16607parentheses. There is a similar problem and workaround with 16608@samp{$((}; see @ref{Shell Substitutions}. 16609 16610@node Slashes 16611@section Slashes in Shell Scripts 16612@cindex Shell slashes 16613 16614Unpatched Tru64 5.1 @command{sh} omits the last slash of command-line 16615arguments that contain two trailing slashes: 16616 16617@example 16618$ @kbd{echo / // /// //// .// //.} 16619/ / // /// ./ //. 16620$ @kbd{x=//} 16621$ @kbd{eval "echo \$x"} 16622/ 16623$ @kbd{set -x} 16624$ @kbd{echo abc | tr -t ab //} 16625+ echo abc 16626+ tr -t ab / 16627/bc 16628@end example 16629 16630Unpatched Tru64 4.0 @command{sh} adds a slash after @samp{"$var"} if the 16631variable is empty and the second double-quote is followed by a word that 16632begins and ends with slash: 16633 16634@example 16635$ @kbd{sh -xc 'p=; echo "$p"/ouch/'} 16636p= 16637+ echo //ouch/ 16638//ouch/ 16639@end example 16640 16641However, our understanding is that patches are available, so perhaps 16642it's not worth worrying about working around these horrendous bugs. 16643 16644@node Special Shell Variables 16645@section Special Shell Variables 16646@cindex Shell variables 16647@cindex Special shell variables 16648 16649Some shell variables should not be used, since they can have a deep 16650influence on the behavior of the shell. In order to recover a sane 16651behavior from the shell, some variables should be unset; M4sh takes 16652care of this and provides fallback values, whenever needed, to cater 16653for a very old @file{/bin/sh} that does not support @command{unset}. 16654(@pxref{Portable Shell, , Portable Shell Programming}). 16655 16656As a general rule, shell variable names containing a lower-case letter 16657are safe; you can define and use these variables without worrying about 16658their effect on the underlying system, and without worrying about 16659whether the shell changes them unexpectedly. (The exception is the 16660shell variable @code{status}, as described below.) 16661 16662Here is a list of names that are known to cause trouble. This list is 16663not exhaustive, but you should be safe if you avoid the name 16664@code{status} and names containing only upper-case letters and 16665underscores. 16666 16667@c Alphabetical order, case insensitive, `A' before `a'. 16668@table @code 16669@item ? 16670Not all shells correctly reset @samp{$?} after conditionals (@pxref{if, 16671, Limitations of Shell Builtins}). Not all shells manage @samp{$?} 16672correctly in shell functions (@pxref{Shell Functions}) or in traps 16673(@pxref{trap, , Limitations of Shell Builtins}). Not all shells reset 16674@samp{$?} to zero after an empty command. 16675 16676@example 16677$ @kbd{bash -c 'false; $empty; echo $?'} 166780 16679$ @kbd{zsh -c 'false; $empty; echo $?'} 166801 16681@end example 16682 16683@item _ 16684@evindex _ 16685Many shells reserve @samp{$_} for various purposes, e.g., the name of 16686the last command executed. 16687 16688@item BIN_SH 16689@evindex BIN_SH 16690In Tru64, if @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of 16691the standard shell conform to Posix. 16692 16693@item CDPATH 16694@evindex CDPATH 16695When this variable is set it specifies a list of directories to search 16696when invoking @code{cd} with a relative file name that did not start 16697with @samp{./} or @samp{../}. Posix 166981003.1-2001 says that if a nonempty directory name from @env{CDPATH} 16699is used successfully, @code{cd} prints the resulting absolute 16700file name. Unfortunately this output can break idioms like 16701@samp{abs=`cd src && pwd`} because @code{abs} receives the name twice. 16702Also, many shells do not conform to this part of Posix; for 16703example, @command{zsh} prints the result only if a directory name 16704other than @file{.} was chosen from @env{CDPATH}. 16705 16706In practice the shells that have this problem also support 16707@command{unset}, so you can work around the problem as follows: 16708 16709@example 16710(unset CDPATH) >/dev/null 2>&1 && unset CDPATH 16711@end example 16712 16713You can also avoid output by ensuring that your directory name is 16714absolute or anchored at @samp{./}, as in @samp{abs=`cd ./src && pwd`}. 16715 16716Configure scripts use M4sh, which automatically unsets @env{CDPATH} if 16717possible, so you need not worry about this problem in those scripts. 16718 16719@item CLICOLOR_FORCE 16720@evindex CLICOLOR_FORCE 16721When this variable is set, some implementations of tools like 16722@command{ls} attempt to add color to their output via terminal escape 16723sequences, even when the output is not directed to a terminal, and can 16724thus cause spurious failures in scripts. Configure scripts use M4sh, 16725which automatically unsets this variable. 16726 16727@item DUALCASE 16728@evindex DUALCASE 16729In the MKS shell, case statements and file name generation are 16730case-insensitive unless @env{DUALCASE} is nonzero. 16731Autoconf-generated scripts export this variable when they start up. 16732 16733@item ENV 16734@itemx MAIL 16735@itemx MAILPATH 16736@itemx PS1 16737@itemx PS2 16738@itemx PS4 16739@evindex ENV 16740@evindex MAIL 16741@evindex MAILPATH 16742@evindex PS1 16743@evindex PS2 16744@evindex PS4 16745These variables should not matter for shell scripts, since they are 16746supposed to affect only interactive shells. However, at least one 16747shell (the pre-3.0 UWIN Korn shell) gets confused about 16748whether it is interactive, which means that (for example) a @env{PS1} 16749with a side effect can unexpectedly modify @samp{$?}. To work around 16750this bug, M4sh scripts (including @file{configure} scripts) do something 16751like this: 16752 16753@example 16754(unset ENV) >/dev/null 2>&1 && unset ENV MAIL MAILPATH 16755PS1='$ ' 16756PS2='> ' 16757PS4='+ ' 16758@end example 16759 16760@noindent 16761(actually, there is some complication due to bugs in @command{unset}; 16762@pxref{unset, , Limitations of Shell Builtins}). 16763 16764@item FPATH 16765@evindex FPATH 16766The Korn shell uses @env{FPATH} to find shell functions, so avoid 16767@env{FPATH} in portable scripts. @env{FPATH} is consulted after 16768@env{PATH}, but you still need to be wary of tests that use @env{PATH} 16769to find whether a command exists, since they might report the wrong 16770result if @env{FPATH} is also set. 16771 16772@item GREP_OPTIONS 16773@evindex GREP_OPTIONS 16774When this variable is set, some implementations of @command{grep} honor 16775these options, even if the options include direction to enable colored 16776output via terminal escape sequences, and the result can cause spurious 16777failures when the output is not directed to a terminal. Configure 16778scripts use M4sh, which automatically unsets this variable. 16779 16780@item IFS 16781@evindex IFS 16782Long ago, shell scripts inherited @env{IFS} from the environment, 16783but this caused many problems so modern shells ignore any environment 16784settings for @env{IFS}. 16785 16786Don't set the first character of @env{IFS} to backslash. Indeed, 16787Bourne shells use the first character (backslash) when joining the 16788components in @samp{"$@@"} and some shells then reinterpret (!)@: the 16789backslash escapes, so you can end up with backspace and other strange 16790characters. 16791 16792The proper value for @env{IFS} (in regular code, not when performing 16793splits) is @samp{@key{SPC}@key{TAB}@key{RET}}. The first character is 16794especially important, as it is used to join the arguments in @samp{$*}; 16795however, note that traditional shells, but also bash-2.04, fail to adhere 16796to this and join with a space anyway. 16797 16798M4sh guarantees that @env{IFS} will have the default value at the 16799beginning of a script, and many macros within autoconf rely on this 16800setting. It is okay to use blocks of shell code that temporarily change 16801the value of @env{IFS} in order to split on another character, but 16802remember to restore it before expanding further macros. 16803 16804Unsetting @code{IFS} instead of resetting it to the default sequence 16805is not suggested, since code that tries to save and restore the 16806variable's value will incorrectly reset it to an empty value, thus 16807disabling field splitting: 16808 16809@example 16810unset IFS 16811# default separators used for field splitting 16812 16813save_IFS=$IFS 16814IFS=: 16815# ... 16816IFS=$save_IFS 16817# no field splitting performed 16818@end example 16819 16820@item LANG 16821@itemx LC_ALL 16822@itemx LC_COLLATE 16823@itemx LC_CTYPE 16824@itemx LC_MESSAGES 16825@itemx LC_MONETARY 16826@itemx LC_NUMERIC 16827@itemx LC_TIME 16828@evindex LANG 16829@evindex LC_ALL 16830@evindex LC_COLLATE 16831@evindex LC_CTYPE 16832@evindex LC_MESSAGES 16833@evindex LC_MONETARY 16834@evindex LC_NUMERIC 16835@evindex LC_TIME 16836 16837You should set all these variables to @samp{C} because so much 16838configuration code assumes the C locale and Posix requires that locale 16839environment variables be set to @samp{C} if the C locale is desired; 16840@file{configure} scripts and M4sh do that for you. 16841Export these variables after setting them. 16842 16843@c However, some older, nonstandard 16844@c systems (notably SCO) break if locale environment variables 16845@c are set to @samp{C}, so when running on these systems 16846@c Autoconf-generated scripts unset the variables instead. 16847 16848@item LANGUAGE 16849@evindex LANGUAGE 16850 16851@env{LANGUAGE} is not specified by Posix, but it is a GNU 16852extension that overrides @env{LC_ALL} in some cases, so you (or M4sh) 16853should set it too. 16854 16855@item LC_ADDRESS 16856@itemx LC_IDENTIFICATION 16857@itemx LC_MEASUREMENT 16858@itemx LC_NAME 16859@itemx LC_PAPER 16860@itemx LC_TELEPHONE 16861@evindex LC_ADDRESS 16862@evindex LC_IDENTIFICATION 16863@evindex LC_MEASUREMENT 16864@evindex LC_NAME 16865@evindex LC_PAPER 16866@evindex LC_TELEPHONE 16867 16868These locale environment variables are GNU extensions. They 16869are treated like their Posix brethren (@env{LC_COLLATE}, 16870etc.)@: as described above. 16871 16872@item LINENO 16873@evindex LINENO 16874Most modern shells provide the current line number in @code{LINENO}. 16875Its value is the line number of the beginning of the current command. 16876M4sh, and hence Autoconf, attempts to execute @command{configure} with 16877a shell that supports @code{LINENO}. If no such shell is available, it 16878attempts to implement @code{LINENO} with a Sed prepass that replaces each 16879instance of the string @code{$LINENO} (not followed by an alphanumeric 16880character) with the line's number. In M4sh scripts you should execute 16881@code{AS_LINENO_PREPARE} so that these workarounds are included in 16882your script; configure scripts do this automatically in @code{AC_INIT}. 16883 16884You should not rely on @code{LINENO} within @command{eval} or shell 16885functions, as the behavior differs in practice. The presence of a 16886quoted newline within simple commands can alter which line number is 16887used as the starting point for @code{$LINENO} substitutions within that 16888command. Also, the possibility of the Sed prepass means that you should 16889not rely on @code{$LINENO} when quoted, when in here-documents, or when 16890line continuations are used. Subshells should be OK, though. In the 16891following example, lines 1, 9, and 14 are portable, but the other 16892instances of @code{$LINENO} do not have deterministic values: 16893 16894@example 16895@group 16896$ @kbd{cat lineno} 16897echo 1. $LINENO 16898echo "2. $LINENO 168993. $LINENO" 16900cat <<EOF 169015. $LINENO 169026. $LINENO 169037. \$LINENO 16904EOF 16905( echo 9. $LINENO ) 16906eval 'echo 10. $LINENO' 16907eval 'echo 11. $LINENO 16908echo 12. $LINENO' 16909echo 13. '$LINENO' 16910echo 14. $LINENO ' 1691115.' $LINENO 16912f () @{ echo $1 $LINENO; 16913echo $1 $LINENO @} 16914f 18. 16915echo 19. \ 16916$LINENO 16917@end group 16918@group 16919$ @kbd{bash-3.2 ./lineno} 169201. 1 169212. 3 169223. 3 169235. 4 169246. 4 169257. $LINENO 169269. 9 1692710. 10 1692811. 12 1692912. 13 1693013. $LINENO 1693114. 14 1693215. 14 1693318. 16 1693418. 17 1693519. 19 16936@end group 16937@group 16938$ @kbd{zsh-4.3.4 ./lineno} 169391. 1 169402. 2 169413. 2 169425. 4 169436. 4 169447. $LINENO 169459. 9 1694610. 1 1694711. 1 1694812. 2 1694913. $LINENO 1695014. 14 1695115. 14 1695218. 0 1695318. 1 1695419. 19 16955@end group 16956@group 16957$ @kbd{pdksh-5.2.14 ./lineno} 169581. 1 169592. 2 169603. 2 169615. 4 169626. 4 169637. $LINENO 169649. 9 1696510. 0 1696611. 0 1696712. 0 1696813. $LINENO 1696914. 14 1697015. 14 1697118. 16 1697218. 17 1697319. 19 16974@end group 16975@group 16976$ @kbd{sed '=' <lineno |} 16977> @kbd{ sed '} 16978> @kbd{ N} 16979> @kbd{ s,$,-,} 16980> @kbd{ t loop} 16981> @kbd{ :loop} 16982> @kbd{ s,^\([0-9]*\)\(.*\)[$]LINENO\([^a-zA-Z0-9_]\),\1\2\1\3,} 16983> @kbd{ t loop} 16984> @kbd{ s,-$,,} 16985> @kbd{ s,^[0-9]*\n,,} 16986> @kbd{ ' |} 16987> @kbd{ sh} 169881. 1 169892. 2 169903. 3 169915. 5 169926. 6 169937. \7 169949. 9 1699510. 10 1699611. 11 1699712. 12 1699813. 13 1699914. 14 1700015. 15 1700118. 16 1700218. 17 1700319. 20 17004@end group 17005@end example 17006 17007In particular, note that @file{config.status} (and any other subsidiary 17008script created by @code{AS_INIT_GENERATED}) might report line numbers 17009relative to the parent script as a result of the potential Sed pass. 17010 17011@item NULLCMD 17012@evindex NULLCMD 17013When executing the command @samp{>foo}, @command{zsh} executes 17014@samp{$NULLCMD >foo} unless it is operating in Bourne shell 17015compatibility mode and the @command{zsh} version is newer 17016than 3.1.6-dev-18. If you are using an older @command{zsh} 17017and forget to set @env{NULLCMD}, 17018your script might be suspended waiting for data on its standard input. 17019 17020@item options 17021@evindex options 17022For @command{zsh} 4.3.10, @env{options} is treated as an associative 17023array even after @code{emulate sh}, so it should not be used. 17024 17025@item PATH_SEPARATOR 17026@evindex PATH_SEPARATOR 17027On DJGPP systems, the @env{PATH_SEPARATOR} environment 17028variable can be set to either @samp{:} or @samp{;} to control the path 17029separator Bash uses to set up certain environment variables (such as 17030@env{PATH}). You can set this variable to @samp{;} if you want 17031@command{configure} to use @samp{;} as a separator; this might be useful 17032if you plan to use non-Posix shells to execute files. @xref{File System 17033Conventions}, for more information about @code{PATH_SEPARATOR}. 17034 17035@item POSIXLY_CORRECT 17036@evindex POSIXLY_CORRECT 17037In the GNU environment, exporting @env{POSIXLY_CORRECT} with any value 17038(even empty) causes programs to try harder to conform to Posix. 17039Autoconf does not directly manipulate this variable, but @command{bash} 17040ties the shell variable @env{POSIXLY_CORRECT} to whether the script is 17041running in Posix mode. Therefore, take care when exporting or unsetting 17042this variable, so as not to change whether @command{bash} is in Posix 17043mode. 17044 17045@example 17046$ @kbd{bash --posix -c 'set -o | grep posix} 17047> @kbd{unset POSIXLY_CORRECT} 17048> @kbd{set -o | grep posix'} 17049posix on 17050posix off 17051@end example 17052 17053@item PWD 17054@evindex PWD 17055Posix 1003.1-2001 requires that @command{cd} and 17056@command{pwd} must update the @env{PWD} environment variable to point 17057to the logical name of the current directory, but traditional shells 17058do not support this. This can cause confusion if one shell instance 17059maintains @env{PWD} but a subsidiary and different shell does not know 17060about @env{PWD} and executes @command{cd}; in this case @env{PWD} 17061points to the wrong directory. Use @samp{`pwd`} rather than 17062@samp{$PWD}. 17063 17064@item RANDOM 17065@evindex RANDOM 17066Many shells provide @code{RANDOM}, a variable that returns a different 17067integer each time it is used. Most of the time, its value does not 17068change when it is not used, but on IRIX 6.5 the value changes all 17069the time. This can be observed by using @command{set}. It is common 17070practice to use @code{$RANDOM} as part of a file name, but code 17071shouldn't rely on @code{$RANDOM} expanding to a nonempty string. 17072 17073@item status 17074@evindex status 17075This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6), 17076hence read-only. Do not use it. 17077@end table 17078 17079@node Shell Functions 17080@section Shell Functions 17081@cindex Shell Functions 17082 17083Nowadays, it is difficult to find a shell that does not support 17084shell functions at all. However, some differences should be expected. 17085 17086When declaring a shell function, you must include whitespace between the 17087@samp{)} after the function name and the start of the compound 17088expression, to avoid upsetting @command{ksh}. While it is possible to 17089use any compound command, most scripts use @samp{@{@dots{}@}}. 17090 17091@example 17092$ @kbd{/bin/sh -c 'a()@{ echo hi;@}; a'} 17093hi 17094$ @kbd{ksh -c 'a()@{ echo hi;@}; a'} 17095ksh: syntax error at line 1: `@}' unexpected 17096$ @kbd{ksh -c 'a() @{ echo hi;@}; a'} 17097hi 17098@end example 17099 17100Inside a shell function, you should not rely on the error status of a 17101subshell if the last command of that subshell was @code{exit} or 17102@code{trap}, as this triggers bugs in zsh 4.x; while Autoconf tries to 17103find a shell that does not exhibit the bug, zsh might be the only shell 17104present on the user's machine. 17105 17106Likewise, the state of @samp{$?} is not reliable when entering a shell 17107function. This has the effect that using a function as the first 17108command in a @command{trap} handler can cause problems. 17109 17110@example 17111$ @kbd{bash -c 'foo() @{ echo $?; @}; trap foo 0; (exit 2); exit 2'; echo $?} 171122 171132 17114$ @kbd{ash -c 'foo() @{ echo $?; @}; trap foo 0; (exit 2); exit 2'; echo $?} 171150 171162 17117@end example 17118 17119DJGPP bash 2.04 has a bug in that @command{return} from a 17120shell function which also used a command substitution causes a 17121segmentation fault. To work around the issue, you can use 17122@command{return} from a subshell, or @samp{AS_SET_STATUS} as last command 17123in the execution flow of the function (@pxref{Common Shell Constructs}). 17124 17125Not all shells treat shell functions as simple commands impacted by 17126@samp{set -e}, for example with Solaris 10 @command{/bin/sh}: 17127 17128@example 17129$ @kbd{bash -c 'f() @{ return 1; @}; set -e; f; echo oops'} 17130$ @kbd{/bin/sh -c 'f() @{ return 1; @}; set -e; f; echo oops'} 17131oops 17132@end example 17133 17134Shell variables and functions may share the same namespace, for example 17135with Solaris 10 @command{/bin/sh}: 17136 17137@example 17138$ @kbd{f () @{ :; @}; f=; f} 17139f: not found 17140@end example 17141 17142@noindent 17143For this reason, Autoconf (actually M4sh, @pxref{Programming in M4sh}) 17144uses the prefix @samp{as_fn_} for its functions. 17145 17146Handling of positional parameters and shell options varies among shells. 17147For example, Korn shells reset and restore trace output (@samp{set -x}) 17148and other options upon function entry and exit. Inside a function, 17149IRIX sh sets @samp{$0} to the function name. 17150 17151It is not portable to pass temporary environment variables to shell 17152functions. Solaris @command{/bin/sh} does not see the variable. 17153Meanwhile, not all shells follow the Posix rule that the assignment must 17154affect the current environment in the same manner as special built-ins. 17155 17156@example 17157$ @kbd{/bin/sh -c 'func() @{ echo $a;@}; a=1 func; echo $a'} 17158@result{} 17159@result{} 17160$ @kbd{ash -c 'func() @{ echo $a;@}; a=1 func; echo $a'} 17161@result{}1 17162@result{} 17163$ @kbd{bash -c 'set -o posix; func() @{ echo $a;@}; a=1 func; echo $a'} 17164@result{}1 17165@result{}1 17166@end example 17167 17168Some ancient Bourne shell variants with function support did not reset 17169@samp{$@var{i}, @var{i} >= 0}, upon function exit, so effectively the 17170arguments of the script were lost after the first function invocation. 17171It is probably not worth worrying about these shells any more. 17172 17173With AIX sh, a @command{trap} on 0 installed in a shell function 17174triggers at function exit rather than at script exit. @xref{trap, , 17175Limitations of Shell Builtins}. 17176 17177@node Limitations of Builtins 17178@section Limitations of Shell Builtins 17179@cindex Shell builtins 17180@cindex Limitations of shell builtins 17181 17182No, no, we are serious: some shells do have limitations! :) 17183 17184You should always keep in mind that any builtin or command may support 17185options, and therefore differ in behavior with arguments 17186starting with a dash. For instance, even the innocent @samp{echo "$word"} 17187can give unexpected results when @code{word} starts with a dash. It is 17188often possible to avoid this problem using @samp{echo "x$word"}, taking 17189the @samp{x} into account later in the pipe. Many of these limitations 17190can be worked around using M4sh (@pxref{Programming in M4sh}). 17191 17192@c This table includes things like `@command{test} (files)', so we can't 17193@c use @table @command. 17194@table @asis 17195@item @command{.} 17196@c -------------- 17197@prindex @command{.} 17198Use @command{.} only with regular files (use @samp{test -f}). Bash 171992.03, for instance, chokes on @samp{. /dev/null}. Remember that 17200@command{.} uses @env{PATH} if its argument contains no slashes. Also, 17201some shells, including bash 3.2, implicitly append the current directory 17202to this @env{PATH} search, even though Posix forbids it. So if you want 17203to use @command{.} on a file @file{foo} in the current directory, you 17204must use @samp{. ./foo}. 17205 17206Not all shells gracefully handle syntax errors within a sourced file. 17207On one extreme, some non-interactive shells abort the entire script. On 17208the other, @command{zsh} 4.3.10 has a bug where it fails to react to the 17209syntax error. 17210 17211@example 17212$ @kbd{echo 'fi' > syntax} 17213$ @kbd{bash -c '. ./syntax; echo $?'} 17214./syntax: line 1: syntax error near unexpected token `fi' 17215./syntax: line 1: `fi' 172161 17217$ @kbd{ash -c '. ./syntax; echo $?'} 17218./syntax: 1: Syntax error: "fi" unexpected 17219$ @kbd{zsh -c '. ./syntax; echo $?'} 17220./syntax:1: parse error near `fi' 172210 17222@end example 17223 17224@item @command{!} 17225@c -------------- 17226@prindex @command{!} 17227The Unix version 7 shell did not support 17228negating the exit status of commands with @command{!}, and this feature 17229is still absent from some shells (e.g., Solaris @command{/bin/sh}). 17230Other shells, such as FreeBSD @command{/bin/sh} or @command{ash}, have 17231bugs when using @command{!}: 17232 17233@example 17234$ @kbd{sh -c '! : | :'; echo $?} 172351 17236$ @kbd{ash -c '! : | :'; echo $?} 172370 17238$ @kbd{sh -c '! @{ :; @}'; echo $?} 172391 17240$ @kbd{ash -c '! @{ :; @}'; echo $?} 17241@{: not found 17242Syntax error: "@}" unexpected 172432 17244@end example 17245 17246Shell code like this: 17247 17248@example 17249if ! cmp file1 file2 >/dev/null 2>&1; then 17250 echo files differ or trouble 17251fi 17252@end example 17253 17254is therefore not portable in practice. Typically it is easy to rewrite 17255such code, e.g.: 17256 17257@example 17258cmp file1 file2 >/dev/null 2>&1 || 17259 echo files differ or trouble 17260@end example 17261 17262More generally, one can always rewrite @samp{! @var{command}} as: 17263 17264@example 17265if @var{command}; then (exit 1); else :; fi 17266@end example 17267 17268 17269@item @command{@{...@}} 17270@c -------------------- 17271@prindex @command{@{...@}} 17272Bash 3.2 (and earlier versions) sometimes does not properly set 17273@samp{$?} when failing to write redirected output of a compound command. 17274This problem is most commonly observed with @samp{@{@dots{}@}}; it does 17275not occur with @samp{(@dots{})}. For example: 17276 17277@example 17278$ @kbd{bash -c '@{ echo foo; @} >/bad; echo $?'} 17279bash: line 1: /bad: Permission denied 172800 17281$ @kbd{bash -c 'while :; do echo; done >/bad; echo $?'} 17282bash: line 1: /bad: Permission denied 172830 17284@end example 17285 17286To work around the bug, prepend @samp{:;}: 17287 17288@example 17289$ @kbd{bash -c ':;@{ echo foo; @} >/bad; echo $?'} 17290bash: line 1: /bad: Permission denied 172911 17292@end example 17293 17294Posix requires a syntax error if a brace list has no contents. However, 17295not all shells obey this rule; and on shells where empty lists are 17296permitted, the effect on @samp{$?} is inconsistent. To avoid problems, 17297ensure that a brace list is never empty. 17298 17299@example 17300$ @kbd{bash -c 'false; @{ @}; echo $?' || echo $?} 17301bash: line 1: syntax error near unexpected token `@}' 17302bash: line 1: `false; @{ @}; echo $?' 173032 17304$ @kbd{zsh -c 'false; @{ @}; echo $?' || echo $?} 173051 17306$ @kbd{pdksh -c 'false; @{ @}; echo $?' || echo $?} 173070 17308@end example 17309 17310 17311@item @command{break} 17312@c ------------------ 17313@prindex @command{break} 17314The use of @samp{break 2} etc.@: is safe. 17315 17316 17317@anchor{case} 17318@item @command{case} 17319@c ----------------- 17320@prindex @command{case} 17321You don't need to quote the argument; no splitting is performed. 17322 17323You don't need the final @samp{;;}, but you should use it. 17324 17325Posix requires support for @code{case} patterns with opening 17326parentheses like this: 17327 17328@example 17329case $file_name in 17330 (*.c) echo "C source code";; 17331esac 17332@end example 17333 17334@noindent 17335but the @code{(} in this example is not portable to many Bourne 17336shell implementations, which is a pity for those of us using tools that 17337rely on balanced parentheses. For instance, with Solaris 17338@command{/bin/sh}: 17339 17340@example 17341$ @kbd{case foo in (foo) echo foo;; esac} 17342@error{}syntax error: `(' unexpected 17343@end example 17344 17345@noindent 17346The leading @samp{(} can be omitted safely. Unfortunately, there are 17347contexts where unbalanced parentheses cause other problems, such as when 17348using a syntax-highlighting editor that searches for the balancing 17349counterpart, or more importantly, when using a case statement as an 17350underquoted argument to an Autoconf macro. @xref{Balancing 17351Parentheses}, for tradeoffs involved in various styles of dealing with 17352unbalanced @samp{)}. 17353 17354Zsh handles pattern fragments derived from parameter expansions or 17355command substitutions as though quoted: 17356 17357@example 17358$ pat=\?; case aa in ?$pat) echo match;; esac 17359$ pat=\?; case a? in ?$pat) echo match;; esac 17360match 17361@end example 17362 17363@noindent 17364Because of a bug in its @code{fnmatch}, Bash fails to properly 17365handle backslashes in character classes: 17366 17367@example 17368bash-2.02$ @kbd{case /tmp in [/\\]*) echo OK;; esac} 17369bash-2.02$ 17370@end example 17371 17372@noindent 17373This is extremely unfortunate, since you are likely to use this code to 17374handle Posix or MS-DOS absolute file names. To work around this 17375bug, always put the backslash first: 17376 17377@example 17378bash-2.02$ @kbd{case '\TMP' in [\\/]*) echo OK;; esac} 17379OK 17380bash-2.02$ @kbd{case /tmp in [\\/]*) echo OK;; esac} 17381OK 17382@end example 17383 17384Many Bourne shells cannot handle closing brackets in character classes 17385correctly. 17386 17387Some shells also have problems with backslash escaping in case you do not want 17388to match the backslash: both a backslash and the escaped character match this 17389pattern. To work around this, specify the character class in a variable, so 17390that quote removal does not apply afterwards, and the special characters don't 17391have to be backslash-escaped: 17392 17393@example 17394$ @kbd{case '\' in [\<]) echo OK;; esac} 17395OK 17396$ @kbd{scanset='[<]'; case '\' in $scanset) echo OK;; esac} 17397$ 17398@end example 17399 17400Even with this, Solaris @command{ksh} matches a backslash if the set 17401contains any 17402of the characters @samp{|}, @samp{&}, @samp{(}, or @samp{)}. 17403 17404Conversely, Tru64 @command{ksh} (circa 2003) erroneously always matches 17405a closing parenthesis if not specified in a character class: 17406 17407@example 17408$ @kbd{case foo in *\)*) echo fail ;; esac} 17409fail 17410$ @kbd{case foo in *')'*) echo fail ;; esac} 17411fail 17412@end example 17413 17414Some shells, such as Ash 0.3.8, are confused by an empty 17415@code{case}/@code{esac}: 17416 17417@example 17418ash-0.3.8 $ @kbd{case foo in esac;} 17419@error{}Syntax error: ";" unexpected (expecting ")") 17420@end example 17421 17422Posix requires @command{case} to give an exit status of 0 if no cases 17423match. However, @command{/bin/sh} in Solaris 10 does not obey this 17424rule. Meanwhile, it is unclear whether a case that matches, but 17425contains no statements, must also change the exit status to 0. The M4sh 17426macro @code{AS_CASE} works around these inconsistencies. 17427 17428@example 17429$ @kbd{bash -c 'case `false` in ?) ;; esac; echo $?'} 174300 17431$ @kbd{/bin/sh -c 'case `false` in ?) ;; esac; echo $?'} 17432255 17433@end example 17434 17435 17436@item @command{cd} 17437@c --------------- 17438@prindex @command{cd} 17439Posix 1003.1-2001 requires that @command{cd} must support 17440the @option{-L} (``logical'') and @option{-P} (``physical'') options, 17441with @option{-L} being the default. However, traditional shells do 17442not support these options, and their @command{cd} command has the 17443@option{-P} behavior. 17444 17445Portable scripts should assume neither option is supported, and should 17446assume neither behavior is the default. This can be a bit tricky, 17447since the Posix default behavior means that, for example, 17448@samp{ls ..} and @samp{cd ..} may refer to different directories if 17449the current logical directory is a symbolic link. It is safe to use 17450@code{cd @var{dir}} if @var{dir} contains no @file{..} components. 17451Also, Autoconf-generated scripts check for this problem when computing 17452variables like @code{ac_top_srcdir} (@pxref{Configuration Actions}), 17453so it is safe to @command{cd} to these variables. 17454 17455Posix states that behavior is undefined if @command{cd} is given an 17456explicit empty argument. Some shells do nothing, some change to the 17457first entry in @env{CDPATH}, some change to @env{HOME}, and some exit 17458the shell rather than returning an error. Unfortunately, this means 17459that if @samp{$var} is empty, then @samp{cd "$var"} is less predictable 17460than @samp{cd $var} (at least the latter is well-behaved in all shells 17461at changing to @env{HOME}, although this is probably not what you wanted 17462in a script). You should check that a directory name was supplied 17463before trying to change locations. 17464 17465@xref{Special Shell Variables}, for portability problems involving 17466@command{cd} and the @env{CDPATH} environment variable. 17467Also please see the discussion of the @command{pwd} command. 17468 17469 17470@anchor{echo} 17471@item @command{echo} 17472@c ----------------- 17473@prindex @command{echo} 17474The simple @command{echo} is probably the most surprising source of 17475portability troubles. It is not possible to use @samp{echo} portably 17476unless both options and escape sequences are omitted. Don't expect any 17477option. 17478 17479Do not use backslashes in the arguments, as there is no consensus on 17480their handling. For @samp{echo '\n' | wc -l}, the @command{sh} of 17481Solaris outputs 2, but Bash and Zsh (in @command{sh} emulation mode) output 1. 17482The problem is truly @command{echo}: all the shells 17483understand @samp{'\n'} as the string composed of a backslash and an 17484@samp{n}. Within a command substitution, @samp{echo 'string\c'} will 17485mess up the internal state of ksh88 on AIX 6.1 so that it will print 17486the first character @samp{s} only, followed by a newline, and then 17487entirely drop the output of the next echo in a command substitution. 17488 17489Because of these problems, do not pass a string containing arbitrary 17490characters to @command{echo}. For example, @samp{echo "$foo"} is safe 17491only if you know that @var{foo}'s value cannot contain backslashes and 17492cannot start with @samp{-}. 17493 17494If this may not be true, @command{printf} is in general safer and 17495easier to use than @command{echo} and @command{echo -n}. Thus, scripts 17496where portability is not a major concern should use @command{printf 17497'%s\n'} whenever @command{echo} could fail, and similarly use 17498@command{printf %s} instead of @command{echo -n}. For portable shell 17499scripts, instead, it is suggested to use a here-document like this: 17500 17501@example 17502cat <<EOF 17503$foo 17504EOF 17505@end example 17506 17507Alternatively, M4sh provides @code{AS_ECHO} and @code{AS_ECHO_N} macros 17508which choose between various portable implementations: @samp{echo} 17509or @samp{print} where they work, @command{printf} if it is available, 17510or else other creative tricks in order to work around the above problems. 17511 17512 17513@item @command{eval} 17514@c ----------------- 17515@prindex @command{eval} 17516The @command{eval} command is useful in limited circumstances, e.g., 17517using commands like @samp{eval table_$key=\$value} and @samp{eval 17518value=table_$key} to simulate a hash table when the key is known to be 17519alphanumeric. 17520 17521You should also be wary of common bugs in @command{eval} implementations. 17522In some shell implementations (e.g., older @command{ash}, OpenBSD 3.8 17523@command{sh}, @command{pdksh} v5.2.14 99/07/13.2, and @command{zsh} 175244.2.5), the arguments of @samp{eval} are evaluated in a context where 17525@samp{$?} is 0, so they exhibit behavior like this: 17526 17527@example 17528$ @kbd{false; eval 'echo $?'} 175290 17530@end example 17531 17532The correct behavior here is to output a nonzero value, 17533but portable scripts should not rely on this. 17534 17535You should not rely on @code{LINENO} within @command{eval}. 17536@xref{Special Shell Variables}. 17537 17538Note that, even though these bugs are easily avoided, 17539@command{eval} is tricky to use on arbitrary arguments. 17540It is obviously unwise to use @samp{eval $cmd} if the string value of 17541@samp{cmd} was derived from an untrustworthy source. But even if the 17542string value is valid, @samp{eval $cmd} might not work as intended, 17543since it causes field splitting and file name expansion to occur twice, 17544once for the @command{eval} and once for the command itself. It is 17545therefore safer to use @samp{eval "$cmd"}. For example, if @var{cmd} 17546has the value @samp{cat test?.c}, @samp{eval $cmd} might expand to the 17547equivalent of @samp{cat test;.c} if there happens to be a file named 17548@file{test;.c} in the current directory; and this in turn 17549mistakenly attempts to invoke @command{cat} on the file @file{test} and 17550then execute the command @command{.c}. To avoid this problem, use 17551@samp{eval "$cmd"} rather than @samp{eval $cmd}. 17552 17553However, suppose that you want to output the text of the evaluated 17554command just before executing it. Assuming the previous example, 17555@samp{echo "Executing: $cmd"} outputs @samp{Executing: cat test?.c}, but 17556this output doesn't show the user that @samp{test;.c} is the actual name 17557of the copied file. Conversely, @samp{eval "echo Executing: $cmd"} 17558works on this example, but it fails with @samp{cmd='cat foo >bar'}, 17559since it mistakenly replaces the contents of @file{bar} by the 17560string @samp{cat foo}. No simple, general, and portable solution to 17561this problem is known. 17562 17563@item @command{exec} 17564@c ----------------- 17565@prindex @command{exec} 17566Posix describes several categories of shell built-ins. Special 17567built-ins (such as @command{exit}) must impact the environment of the 17568current shell, and need not be available through @command{exec}. All 17569other built-ins are regular, and must not propagate variable assignments 17570to the environment of the current shell. However, the group of regular 17571built-ins is further distinguished by commands that do not require a 17572@env{PATH} search (such as @command{cd}), in contrast to built-ins that 17573are offered as a more efficient version of something that must still be 17574found in a @env{PATH} search (such as @command{echo}). Posix is not 17575clear on whether @command{exec} must work with the list of 17 utilities 17576that are invoked without a @env{PATH} search, and many platforms lack an 17577executable for some of those built-ins: 17578 17579@example 17580$ @kbd{sh -c 'exec cd /tmp'} 17581sh: line 0: exec: cd: not found 17582@end example 17583 17584All other built-ins that provide utilities specified by Posix must have 17585a counterpart executable that exists on @env{PATH}, although Posix 17586allows @command{exec} to use the built-in instead of the executable. 17587For example, contrast @command{bash} 3.2 and @command{pdksh} 5.2.14: 17588 17589@example 17590$ @kbd{bash -c 'pwd --version' | head -n1} 17591bash: line 0: pwd: --: invalid option 17592pwd: usage: pwd [-LP] 17593$ @kbd{bash -c 'exec pwd --version' | head -n1} 17594pwd (GNU coreutils) 6.10 17595$ @kbd{pdksh -c 'exec pwd --version' | head -n1} 17596pdksh: pwd: --: unknown option 17597@end example 17598 17599When it is desired to avoid a regular shell built-in, the workaround is 17600to use some other forwarding command, such as @command{env} or 17601@command{nice}, that will ensure a path search: 17602 17603@example 17604$ @kbd{pdksh -c 'exec true --version' | head -n1} 17605$ @kbd{pdksh -c 'nice true --version' | head -n1} 17606true (GNU coreutils) 6.10 17607$ @kbd{pdksh -c 'env true --version' | head -n1} 17608true (GNU coreutils) 6.10 17609@end example 17610 17611@item @command{exit} 17612@c ----------------- 17613@prindex @command{exit} 17614The default value of @command{exit} is supposed to be @code{$?}; 17615unfortunately, some shells, such as the DJGPP port of Bash 2.04, just 17616perform @samp{exit 0}. 17617 17618@example 17619bash-2.04$ @kbd{foo=`exit 1` || echo fail} 17620fail 17621bash-2.04$ @kbd{foo=`(exit 1)` || echo fail} 17622fail 17623bash-2.04$ @kbd{foo=`(exit 1); exit` || echo fail} 17624bash-2.04$ 17625@end example 17626 17627Using @samp{exit $?} restores the expected behavior. 17628 17629Some shell scripts, such as those generated by @command{autoconf}, use a 17630trap to clean up before exiting. If the last shell command exited with 17631nonzero status, the trap also exits with nonzero status so that the 17632invoker can tell that an error occurred. 17633 17634Unfortunately, in some shells, such as Solaris @command{/bin/sh}, an exit 17635trap ignores the @code{exit} command's argument. In these shells, a trap 17636cannot determine whether it was invoked by plain @code{exit} or by 17637@code{exit 1}. Instead of calling @code{exit} directly, use the 17638@code{AC_MSG_ERROR} macro that has a workaround for this problem. 17639 17640 17641@anchor{export} 17642@item @command{export} 17643@c ------------------- 17644@prindex @command{export} 17645The builtin @command{export} dubs a shell variable @dfn{environment 17646variable}. Each update of exported variables corresponds to an update 17647of the environment variables. Conversely, each environment variable 17648received by the shell when it is launched should be imported as a shell 17649variable marked as exported. 17650 17651Alas, many shells, such as Solaris @command{/bin/sh}, 17652IRIX 6.3, IRIX 5.2, 17653AIX 4.1.5, and Digital Unix 4.0, forget to 17654@command{export} the environment variables they receive. As a result, 17655two variables coexist: the environment variable and the shell 17656variable. The following code demonstrates this failure: 17657 17658@example 17659#!/bin/sh 17660echo $FOO 17661FOO=bar 17662echo $FOO 17663exec /bin/sh $0 17664@end example 17665 17666@noindent 17667when run with @samp{FOO=foo} in the environment, these shells print 17668alternately @samp{foo} and @samp{bar}, although they should print only 17669@samp{foo} and then a sequence of @samp{bar}s. 17670 17671Therefore you should @command{export} again each environment variable 17672that you update; the export can occur before or after the assignment. 17673 17674Posix is not clear on whether the @command{export} of an undefined 17675variable causes the variable to be defined with the value of an empty 17676string, or merely marks any future definition of a variable by that name 17677for export. Various shells behave differently in this regard: 17678 17679@example 17680$ @kbd{sh -c 'export foo; env | grep foo'} 17681$ @kbd{ash -c 'export foo; env | grep foo'} 17682foo= 17683@end example 17684 17685Posix requires @command{export} to honor assignments made as arguments, 17686but older shells do not support this, including @command{/bin/sh} in 17687Solaris 10. Portable scripts should separate assignments and exports 17688into different statements. 17689 17690@example 17691$ @kbd{bash -c 'export foo=bar; echo $foo'} 17692bar 17693$ @kbd{/bin/sh -c 'export foo=bar; echo $foo'} 17694/bin/sh: foo=bar: is not an identifier 17695$ @kbd{/bin/sh -c 'export foo; foo=bar; echo $foo'} 17696bar 17697@end example 17698 17699@item @command{false} 17700@c ------------------ 17701@prindex @command{false} 17702Don't expect @command{false} to exit with status 1: in native 17703Solaris @file{/bin/false} exits with status 255. 17704 17705 17706@item @command{for} 17707@c ---------------- 17708@prindex @command{for} 17709To loop over positional arguments, use: 17710 17711@example 17712for arg 17713do 17714 echo "$arg" 17715done 17716@end example 17717 17718@noindent 17719You may @emph{not} leave the @code{do} on the same line as @code{for}, 17720since some shells improperly grok: 17721 17722@example 17723for arg; do 17724 echo "$arg" 17725done 17726@end example 17727 17728If you want to explicitly refer to the positional arguments, given the 17729@samp{$@@} bug (@pxref{Shell Substitutions}), use: 17730 17731@example 17732for arg in $@{1+"$@@"@}; do 17733 echo "$arg" 17734done 17735@end example 17736 17737@noindent 17738But keep in mind that Zsh, even in Bourne shell emulation mode, performs 17739word splitting on @samp{$@{1+"$@@"@}}; see @ref{Shell Substitutions}, 17740item @samp{$@@}, for more. 17741 17742In Solaris @command{/bin/sh}, when the list of arguments of a 17743@command{for} loop starts with @emph{unquoted} tokens looking like 17744variable assignments, the loop is not executed on those tokens: 17745 17746@example 17747$ @kbd{/bin/sh -c 'for v in a=b c=d x e=f; do echo $v; done'} 17748x 17749e=f 17750@end example 17751 17752@noindent 17753Thankfully, quoting the assignment-like tokens, or starting the list 17754with other tokens (including unquoted variable expansion that results in 17755an assignment-like result), avoids the problem, so it is easy to work 17756around: 17757 17758@example 17759$ @kbd{/bin/sh -c 'for v in "a=b"; do echo $v; done'} 17760a=b 17761$ @kbd{/bin/sh -c 'x=a=b; for v in $x c=d; do echo $v; done'} 17762a=b 17763c=d 17764@end example 17765 17766@anchor{if} 17767@item @command{if} 17768@c --------------- 17769@prindex @command{if} 17770Using @samp{!} is not portable. Instead of: 17771 17772@example 17773if ! cmp -s file file.new; then 17774 mv file.new file 17775fi 17776@end example 17777 17778@noindent 17779use: 17780 17781@example 17782if cmp -s file file.new; then :; else 17783 mv file.new file 17784fi 17785@end example 17786 17787@noindent 17788Or, especially if the @dfn{else} branch is short, you can use @code{||}. 17789In M4sh, the @code{AS_IF} macro provides an easy way to write these kinds 17790of conditionals: 17791 17792@example 17793AS_IF([cmp -s file file.new], [], [mv file.new file]) 17794@end example 17795 17796This is especially useful in other M4 macros, where the @dfn{then} and 17797@dfn{else} branches might be macro arguments. 17798 17799Some very old shells did not reset the exit status from an @command{if} 17800with no @command{else}: 17801 17802@example 17803$ @kbd{if (exit 42); then true; fi; echo $?} 1780442 17805@end example 17806 17807@noindent 17808whereas a proper shell should have printed @samp{0}. But this is no 17809longer a portability problem; any shell that supports functions gets it 17810correct. However, it explains why some makefiles have lengthy 17811constructs: 17812 17813@example 17814if test -f "$file"; then 17815 install "$file" "$dest" 17816else 17817 : 17818fi 17819@end example 17820 17821 17822@item @command{printf} 17823@c ------------------ 17824@prindex @command{printf} 17825A format string starting with a @samp{-} can cause problems. 17826Bash interprets it as an option and 17827gives an error. And @samp{--} to mark the end of options is not good 17828in the NetBSD Almquist shell (e.g., 0.4.6) which takes that 17829literally as the format string. Putting the @samp{-} in a @samp{%c} 17830or @samp{%s} is probably easiest: 17831 17832@example 17833printf %s -foo 17834@end example 17835 17836Bash 2.03 mishandles an escape sequence that happens to evaluate to @samp{%}: 17837 17838@example 17839$ @kbd{printf '\045'} 17840bash: printf: `%': missing format character 17841@end example 17842 17843Large outputs may cause trouble. On Solaris 2.5.1 through 10, for 17844example, @file{/usr/bin/printf} is buggy, so when using 17845@command{/bin/sh} the command @samp{printf %010000x 123} normally dumps 17846core. 17847 17848Since @command{printf} is not always a shell builtin, there is a 17849potential speed penalty for using @code{printf '%s\n'} as a replacement 17850for an @command{echo} that does not interpret @samp{\} or leading 17851@samp{-}. With Solaris @command{ksh}, it is possible to use @code{print 17852-r --} for this role instead. 17853 17854@xref{echo, , Limitations of Shell Builtins} for a discussion of 17855portable alternatives to both @command{printf} and @command{echo}. 17856 17857 17858@item @command{pwd} 17859@c ---------------- 17860@prindex @command{pwd} 17861With modern shells, plain @command{pwd} outputs a ``logical'' 17862directory name, some of whose components may be symbolic links. These 17863directory names are in contrast to ``physical'' directory names, whose 17864components are all directories. 17865 17866Posix 1003.1-2001 requires that @command{pwd} must support 17867the @option{-L} (``logical'') and @option{-P} (``physical'') options, 17868with @option{-L} being the default. However, traditional shells do 17869not support these options, and their @command{pwd} command has the 17870@option{-P} behavior. 17871 17872Portable scripts should assume neither option is supported, and should 17873assume neither behavior is the default. Also, on many hosts 17874@samp{/bin/pwd} is equivalent to @samp{pwd -P}, but Posix 17875does not require this behavior and portable scripts should not rely on 17876it. 17877 17878Typically it's best to use plain @command{pwd}. On modern hosts this 17879outputs logical directory names, which have the following advantages: 17880 17881@itemize @bullet 17882@item 17883Logical names are what the user specified. 17884@item 17885Physical names may not be portable from one installation 17886host to another due to network file system gymnastics. 17887@item 17888On modern hosts @samp{pwd -P} may fail due to lack of permissions to 17889some parent directory, but plain @command{pwd} cannot fail for this 17890reason. 17891@end itemize 17892 17893Also please see the discussion of the @command{cd} command. 17894 17895 17896@item @command{read} 17897@c ----------------- 17898@prindex @command{read} 17899No options are portable, not even support @option{-r} (Solaris 17900@command{/bin/sh} for example). Tru64/OSF 5.1 @command{sh} treats 17901@command{read} as a special built-in, so it may exit if input is 17902redirected from a non-existent or unreadable file. 17903 17904 17905@anchor{set} 17906@item @command{set} 17907@c ---------------- 17908@prindex @command{set} 17909With the FreeBSD 6.0 shell, the @command{set} command (without 17910any options) does not sort its output. 17911 17912The @command{set} builtin faces the usual problem with arguments 17913starting with a 17914dash. Modern shells such as Bash or Zsh understand @option{--} to specify 17915the end of the options (any argument after @option{--} is a parameter, 17916even @samp{-x} for instance), but many traditional shells (e.g., Solaris 1791710 @command{/bin/sh}) simply stop option 17918processing as soon as a non-option argument is found. Therefore, use 17919@samp{dummy} or simply @samp{x} to end the option processing, and use 17920@command{shift} to pop it out: 17921 17922@example 17923set x $my_list; shift 17924@end example 17925 17926Avoid @samp{set -}, e.g., @samp{set - $my_list}. Posix no 17927longer requires support for this command, and in traditional shells 17928@samp{set - $my_list} resets the @option{-v} and @option{-x} options, which 17929makes scripts harder to debug. 17930 17931Some nonstandard shells do not recognize more than one option 17932(e.g., @samp{set -e -x} assigns @samp{-x} to the command line). It is 17933better to combine them: 17934 17935@example 17936set -ex 17937@end example 17938 17939@cindex @command{set -e} 17940The option @option{-e} has historically been underspecified, with enough 17941ambiguities to cause numerous differences across various shell 17942implementations; see for example 17943@uref{http://www.in-ulm.de/@/~mascheck/@/various/@/set-e/, this overview}, 17944or @uref{http://www.austingroupbugs.net/@/view.php?id=52, this link}, 17945documenting a change to Posix 2008 to match @command{ksh88} behavior. 17946Note that mixing @code{set -e} and shell functions is asking for surprises: 17947 17948@example 17949set -e 17950doit() 17951@{ 17952 rm file 17953 echo one 17954@} 17955doit || echo two 17956@end example 17957 17958@noindent 17959According to the recommendation, @samp{one} should always be output 17960regardless of whether the @command{rm} failed, because it occurs within 17961the body of the shell function @samp{doit} invoked on the left side of 17962@samp{||}, where the effects of @samp{set -e} are not enforced. 17963Likewise, @samp{two} should never be printed, since the failure of 17964@command{rm} does not abort the function, such that the status of 17965@samp{doit} is 0. 17966 17967The BSD shell has had several problems with the @option{-e} 17968option. Older versions of the BSD 17969shell (circa 1990) mishandled @samp{&&}, @samp{||}, @samp{if}, and 17970@samp{case} when @option{-e} was in effect, causing the shell to exit 17971unexpectedly in some cases. This was particularly a problem with 17972makefiles, and led to circumlocutions like @samp{sh -c 'test -f file || 17973touch file'}, where the seemingly-unnecessary @samp{sh -c '@dots{}'} 17974wrapper works around the bug (@pxref{Failure in Make Rules}). 17975 17976Even relatively-recent versions of the BSD shell (e.g., OpenBSD 3.4) 17977wrongly exit with @option{-e} if the last command within a compound 17978statement fails and is guarded by an @samp{&&} only. For example: 17979 17980@example 17981#! /bin/sh 17982set -e 17983foo='' 17984test -n "$foo" && exit 1 17985echo one 17986if :; then 17987 test -n "$foo" && exit 1 17988 echo two 17989 test -n "$foo" && exit 1 17990fi 17991echo three 17992@end example 17993 17994@noindent 17995does not print @samp{three}. One workaround is to change the last 17996instance of @samp{test -n "$foo" && exit 1} to be @samp{if test -n 17997"$foo"; then exit 1; fi} instead. Another possibility is to warn BSD 17998users not to use @samp{sh -e}. 17999 18000When @samp{set -e} is in effect, a failed command substitution in 18001Solaris @command{/bin/sh} cannot be ignored, even with @samp{||}. 18002 18003@example 18004$ @kbd{/bin/sh -c 'set -e; foo=`false` || echo foo; echo bar'} 18005$ @kbd{bash -c 'set -e; foo=`false` || echo foo; echo bar'} 18006foo 18007bar 18008@end example 18009 18010@noindent 18011Moreover, a command substitution, successful or not, causes this shell to 18012exit from a failing outer command even in presence of an @samp{&&} list: 18013 18014@example 18015$ @kbd{bash -c 'set -e; false `true` && echo notreached; echo ok'} 18016ok 18017$ @kbd{sh -c 'set -e; false `true` && echo notreached; echo ok'} 18018$ 18019@end example 18020 18021Portable scripts should not use @samp{set -e} if @command{trap} is used 18022to install an exit handler. This is because Tru64/OSF 5.1 @command{sh} 18023sometimes enters the trap handler with the exit status of the command 18024prior to the one that triggered the errexit handler: 18025 18026@example 18027$ @kbd{sh -ec 'trap '\''echo $?'\'' 0; false'} 180280 18029$ @kbd{sh -c 'set -e; trap '\''echo $?'\'' 0; false'} 180301 18031@end example 18032 18033@noindent 18034Thus, when writing a script in M4sh, rather than trying to rely on 18035@samp{set -e}, it is better to append @samp{|| AS_EXIT} to any 18036statement where it is desirable to abort on failure. 18037 18038@cindex @command{set -b} 18039@cindex @command{set -m} 18040Job control is not provided by all shells, so the use of @samp{set -m} 18041or @samp{set -b} must be done with care. When using @command{zsh} in 18042native mode, asynchronous notification (@samp{set -b}) is enabled by 18043default, and using @samp{emulate sh} to switch to Posix mode does not 18044clear this setting (although asynchronous notification has no impact 18045unless job monitoring is also enabled). Also, @command{zsh} 4.3.10 and 18046earlier have a bug where job control can be manipulated in interactive 18047shells, but not in subshells or scripts. Furthermore, some shells, like 18048@command{pdksh}, fail to treat subshells as interactive, even though the 18049parent shell was. 18050 18051@example 18052$ @kbd{echo $ZSH_VERSION} 180534.3.10 18054$ @kbd{set -m; echo $?} 180550 18056$ @kbd{zsh -c 'set -m; echo $?'} 18057set: can't change option: -m 18058$ @kbd{(set -m); echo $?} 18059set: can't change option: -m 180601 18061$ @kbd{pdksh -ci 'echo $-; (echo $-)'} 18062cim 18063c 18064@end example 18065 18066@cindex @command{set -n} 18067Use of @command{set -n} (typically via @command{sh -n script}) to 18068validate a script is not foolproof. Modern @command{ksh93} tries to be 18069helpful by informing you about better syntax, but switching the script 18070to use the suggested syntax in order to silence the warnings would 18071render the script no longer portable to older shells: 18072 18073@example 18074$ @kbd{ksh -nc '``'} 18075ksh: warning: line 1: `...` obsolete, use $(...) 180760 18077@end example 18078 18079Furthermore, on ancient hosts, such as SunOS 4, @command{sh -n} could go 18080into an infinite loop; even with that bug fixed, Solaris 8 18081@command{/bin/sh} takes extremely long to parse large scripts. Autoconf 18082itself uses @command{sh -n} within its testsuite to check that correct 18083scripts were generated, but only after first probing for other shell 18084features (such as @code{test -n "$@{BASH_VERSION+set@}"}) that indicate 18085a reasonably fast and working implementation. 18086 18087@item @command{shift} 18088@c ------------------ 18089@prindex @command{shift} 18090Not only is @command{shift}ing a bad idea when there is nothing left to 18091shift, but in addition it is not portable: the shell of MIPS 18092RISC/OS 4.52 refuses to do it. 18093 18094Don't use @samp{shift 2} etc.; while it in the SVR1 shell (1983), 18095it is also absent in many pre-Posix shells. 18096 18097 18098@item @command{source} 18099@c ------------------- 18100@prindex @command{source} 18101This command is not portable, as Posix does not require it; use 18102@command{.} instead. 18103 18104 18105@item @command{test} 18106@c ----------------- 18107@prindex @command{test} 18108The @code{test} program is the way to perform many file and string 18109tests. It is often invoked by the alternate name @samp{[}, but using 18110that name in Autoconf code is asking for trouble since it is an M4 quote 18111character. 18112 18113The @option{-a}, @option{-o}, @samp{(}, and @samp{)} operands are not 18114present in all implementations, and have been marked obsolete by Posix 181152008. This is because there are inherent ambiguities in using them. 18116For example, @samp{test "$1" -a "$2"} looks like a binary operator to 18117check whether two strings are both non-empty, but if @samp{$1} is the 18118literal @samp{!}, then some implementations of @command{test} treat it 18119as a negation of the unary operator @option{-a}. 18120 18121Thus, portable uses of @command{test} should never have more than four 18122arguments, and scripts should use shell constructs like @samp{&&} and 18123@samp{||} instead. If you combine @samp{&&} and @samp{||} in the same 18124statement, keep in mind that they have equal precedence, so it is often 18125better to parenthesize even when this is redundant. For example: 18126 18127@smallexample 18128# Not portable: 18129test "X$a" = "X$b" -a \ 18130 '(' "X$c" != "X$d" -o "X$e" = "X$f" ')' 18131 18132# Portable: 18133test "X$a" = "X$b" && 18134 @{ test "X$c" != "X$d" || test "X$e" = "X$f"; @} 18135@end smallexample 18136 18137@command{test} does not process options like most other commands do; for 18138example, it does not recognize the @option{--} argument as marking the 18139end of options. 18140 18141It is safe to use @samp{!} as a @command{test} operator. For example, 18142@samp{if test ! -d foo; @dots{}} is portable even though @samp{if ! test 18143-d foo; @dots{}} is not. 18144 18145 18146@item @command{test} (files) 18147@c ------------------------- 18148To enable @command{configure} scripts to support cross-compilation, they 18149shouldn't do anything that tests features of the build system instead of 18150the host system. But occasionally you may find it necessary to check 18151whether some arbitrary file exists. To do so, use @samp{test -f}, 18152@samp{test -r}, or @samp{test -x}. Do not use @samp{test -e}, because 18153Solaris 10 @command{/bin/sh} 18154lacks it. To test for symbolic links on systems that have them, use 18155@samp{test -h} rather than @samp{test -L}; either form conforms to 18156Posix 1003.1-2001, but older shells like Solaris 8 18157@code{/bin/sh} support only @option{-h}. 18158 18159For historical reasons, Posix reluctantly allows implementations of 18160@samp{test -x} that will succeed for the root user, even if no execute 18161permissions are present. Furthermore, shells do not all agree on 18162whether Access Control Lists should affect @samp{test -r}, @samp{test 18163-w}, and @samp{test -x}; some shells base test results strictly on the 18164current user id compared to file owner and mode, as if by 18165@code{stat(2)}; while other shells base test results on whether the 18166current user has the given right, even if that right is only granted by 18167an ACL, as if by @code{faccessat(2)}. Furthermore, there is a classic 18168time of check to time of use race between any use of @command{test} 18169followed by operating on the just-checked file. Therefore, it is a good 18170idea to write scripts that actually attempt an operation, and are 18171prepared for the resulting failure if permission is denied, rather than 18172trying to avoid an operation based solely on whether @command{test} 18173guessed that it might not be permitted. 18174 18175@item @command{test} (strings) 18176@c --------------------------- 18177Posix says that @samp{test "@var{string}"} succeeds if @var{string} is 18178not null, but this usage is not portable to traditional platforms like 18179Solaris 10 @command{/bin/sh}, which mishandle strings like @samp{!} and 18180@samp{-n}. 18181 18182Posix also says that @samp{test ! "@var{string}"}, 18183@samp{test -n "@var{string}"} and 18184@samp{test -z "@var{string}"} work with any string, but many 18185shells (such as Solaris, AIX 3.2, UNICOS 10.0.0.6, 18186Digital Unix 4, etc.)@: get confused if 18187@var{string} looks like an operator: 18188 18189@example 18190$ @kbd{test -n =} 18191test: argument expected 18192$ @kbd{test ! -n} 18193test: argument expected 18194$ @kbd{test -z ")"; echo $?} 181950 18196@end example 18197 18198Similarly, Posix says that both @samp{test "@var{string1}" = "@var{string2"}} 18199and @samp{test "@var{string1}" != "@var{string2"}} work for any pairs of 18200strings, but in practice this is not true for troublesome strings that 18201look like operators or parentheses, or that begin with @samp{-}. 18202 18203It is best to protect such strings with a leading @samp{X}, e.g., 18204@samp{test "X@var{string}" != X} rather than @samp{test -n 18205"@var{string}"} or @samp{test ! "@var{string}"}. 18206 18207It is common to find variations of the following idiom: 18208 18209@example 18210test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" && 18211 @var{action} 18212@end example 18213 18214@noindent 18215to take an action when a token matches a given pattern. Such constructs 18216should be avoided by using: 18217 18218@example 18219case $ac_feature in 18220 *[!-a-zA-Z0-9_]*) @var{action};; 18221esac 18222@end example 18223 18224If the pattern is a complicated regular expression that cannot be 18225expressed as a shell pattern, use something like this instead: 18226 18227@example 18228expr "X$ac_feature" : 'X.*[^-a-zA-Z0-9_]' >/dev/null && 18229 @var{action} 18230@end example 18231 18232@samp{expr "X@var{foo}" : "X@var{bar}"} is more robust than @samp{echo 18233"X@var{foo}" | grep "^X@var{bar}"}, because it avoids problems when 18234@samp{@var{foo}} contains backslashes. 18235 18236 18237@anchor{trap} 18238@item @command{trap} 18239@c ----------------- 18240@prindex @command{trap} 18241It is safe to trap at least the signals 1, 2, 13, and 15. You can also 18242trap 0, i.e., have the @command{trap} run when the script ends (either via an 18243explicit @command{exit}, or the end of the script). The trap for 0 should be 18244installed outside of a shell function, or AIX 5.3 @command{/bin/sh} 18245will invoke the trap at the end of this function. 18246 18247Posix says that @samp{trap - 1 2 13 15} resets the traps for the 18248specified signals to their default values, but many common shells (e.g., 18249Solaris @command{/bin/sh}) misinterpret this and attempt to execute a 18250``command'' named @command{-} when the specified conditions arise. 18251Posix 2008 also added a requirement to support @samp{trap 1 2 13 15} to 18252reset traps, as this is supported by a larger set of shells, but there 18253are still shells like @command{dash} that mistakenly try to execute 18254@command{1} instead of resetting the traps. Therefore, there is no 18255portable workaround, except for @samp{trap - 0}, for which 18256@samp{trap '' 0} is a portable substitute. 18257 18258Although Posix is not absolutely clear on this point, it is widely 18259admitted that when entering the trap @samp{$?} should be set to the exit 18260status of the last command run before the trap. The ambiguity can be 18261summarized as: ``when the trap is launched by an @command{exit}, what is 18262the @emph{last} command run: that before @command{exit}, or 18263@command{exit} itself?'' 18264 18265Bash considers @command{exit} to be the last command, while Zsh and 18266Solaris @command{/bin/sh} consider that when the trap is run it is 18267@emph{still} in the @command{exit}, hence it is the previous exit status 18268that the trap receives: 18269 18270@example 18271$ @kbd{cat trap.sh} 18272trap 'echo $?' 0 18273(exit 42); exit 0 18274$ @kbd{zsh trap.sh} 1827542 18276$ @kbd{bash trap.sh} 182770 18278@end example 18279 18280The portable solution is then simple: when you want to @samp{exit 42}, 18281run @samp{(exit 42); exit 42}, the first @command{exit} being used to 18282set the exit status to 42 for Zsh, and the second to trigger the trap 18283and pass 42 as exit status for Bash. In M4sh, this is covered by using 18284@code{AS_EXIT}. 18285 18286The shell in FreeBSD 4.0 has the following bug: @samp{$?} is 18287reset to 0 by empty lines if the code is inside @command{trap}. 18288 18289@example 18290$ @kbd{trap 'false} 18291 18292echo $?' 0 18293$ @kbd{exit} 182940 18295@end example 18296 18297@noindent 18298Fortunately, this bug only affects @command{trap}. 18299 18300Several shells fail to execute an exit trap that is defined inside a 18301subshell, when the last command of that subshell is not a builtin. A 18302workaround is to use @samp{exit $?} as the shell builtin. 18303 18304@example 18305$ @kbd{bash -c '(trap "echo hi" 0; /bin/true)'} 18306hi 18307$ @kbd{/bin/sh -c '(trap "echo hi" 0; /bin/true)'} 18308$ @kbd{/bin/sh -c '(trap "echo hi" 0; /bin/true; exit $?)'} 18309hi 18310@end example 18311 18312@noindent 18313Likewise, older implementations of @command{bash} failed to preserve 18314@samp{$?} across an exit trap consisting of a single cleanup command. 18315 18316@example 18317$ @kbd{bash -c 'trap "/bin/true" 0; exit 2'; echo $?} 183182 18319$ @kbd{bash-2.05b -c 'trap "/bin/true" 0; exit 2'; echo $?} 183200 18321$ @kbd{bash-2.05b -c 'trap ":; /bin/true" 0; exit 2'; echo $?} 183222 18323@end example 18324 18325@item @command{true} 18326@c ----------------- 18327@prindex @command{true} 18328@c Info cannot handle `:' in index entries. 18329@c @prindex @command{:} 18330Don't worry: as far as we know @command{true} is portable. 18331Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the 18332portable shell community tends to prefer using @command{:}. This has a 18333funny side effect: when asked whether @command{false} is more portable 18334than @command{true} Alexandre Oliva answered: 18335 18336@quotation 18337In a sense, yes, because if it doesn't exist, the shell will produce an 18338exit status of failure, which is correct for @command{false}, but not 18339for @command{true}. 18340@end quotation 18341 18342Remember that even though @samp{:} ignores its arguments, it still takes 18343time to compute those arguments. It is a good idea to use double quotes 18344around any arguments to @samp{:} to avoid time spent in field splitting 18345and file name expansion. 18346 18347 18348@anchor{unset} 18349@item @command{unset} 18350@c ------------------ 18351@prindex @command{unset} 18352In some nonconforming shells (e.g., Solaris 10 @command{/bin/ksh} and 18353@command{/usr/xpg4/bin/sh}, NetBSD 5.99.43 sh, or Bash 2.05a), 18354@code{unset FOO} fails when @code{FOO} is not set. This can interfere 18355with @code{set -e} operation. You can use 18356 18357@smallexample 18358FOO=; unset FOO 18359@end smallexample 18360 18361@noindent 18362if you are not sure that @code{FOO} is set. 18363 18364A few ancient shells lack @command{unset} entirely. For some variables 18365such as @code{PS1}, you can use a neutralizing value instead: 18366 18367@smallexample 18368PS1='$ ' 18369@end smallexample 18370 18371Usually, shells that do not support @command{unset} need less effort to 18372make the environment sane, so for example is not a problem if you cannot 18373unset @command{CDPATH} on those shells. However, Bash 2.01 mishandles 18374@code{unset MAIL} and @code{unset MAILPATH} in some cases and dumps core. 18375So, you should do something like 18376 18377@smallexample 18378( (unset MAIL) || exit 1) >/dev/null 2>&1 && unset MAIL || : 18379@end smallexample 18380 18381@noindent 18382@xref{Special Shell Variables}, for some neutralizing values. Also, see 18383@ref{export, , Limitations of Builtins}, for 18384the case of environment variables. 18385 18386@item @command{wait} 18387@c ----------------- 18388@prindex @command{wait} 18389The exit status of @command{wait} is not always reliable. 18390@end table 18391 18392@node Limitations of Usual Tools 18393@section Limitations of Usual Tools 18394@cindex Limitations of usual tools 18395 18396The small set of tools you can expect to find on any machine can still 18397include some limitations you should be aware of. 18398 18399@comment Between this list and the list of builtins above, we should 18400@comment mention all the tools in GNU Coding Standards ``Utilities in 18401@comment Makefiles''. 18402 18403@c This table includes things like `@command{expr} (|)', so we can't 18404@c use @table @command. 18405@table @asis 18406@anchor{awk} 18407@item @command{awk} 18408@c ---------------- 18409@prindex @command{awk} 18410Don't leave white space before the opening parenthesis in a user function call. 18411Posix does not allow this and GNU Awk rejects it: 18412 18413@example 18414$ @kbd{gawk 'function die () @{ print "Aaaaarg!" @} 18415 BEGIN @{ die () @}'} 18416gawk: cmd. line:2: BEGIN @{ die () @} 18417gawk: cmd. line:2: ^ parse error 18418$ @kbd{gawk 'function die () @{ print "Aaaaarg!" @} 18419 BEGIN @{ die() @}'} 18420Aaaaarg! 18421@end example 18422 18423Posix says that if a program contains only @samp{BEGIN} actions, and 18424contains no instances of @code{getline}, then the program merely 18425executes the actions without reading input. However, traditional Awk 18426implementations (such as Solaris 10 @command{awk}) read and discard 18427input in this case. Portable scripts can redirect input from 18428@file{/dev/null} to work around the problem. For example: 18429 18430@example 18431awk 'BEGIN @{print "hello world"@}' </dev/null 18432@end example 18433 18434Posix says that in an @samp{END} action, @samp{$NF} (and presumably, 18435@samp{$1}) retain their value from the last record read, if no 18436intervening @samp{getline} occurred. However, some implementations 18437(such as Solaris 10 @samp{/usr/bin/awk}, @samp{nawk}, or Darwin 18438@samp{awk}) reset these variables. A workaround is to use an 18439intermediate variable prior to the @samp{END} block. For example: 18440 18441@example 18442$ @kbd{cat end.awk} 18443@{ tmp = $1 @} 18444END @{ print "a", $1, $NF, "b", tmp @} 18445$ @kbd{echo 1 | awk -f end.awk} 18446a b 1 18447$ @kbd{echo 1 | gawk -f end.awk} 18448a 1 1 b 1 18449@end example 18450 18451If you want your program to be deterministic, don't depend on @code{for} 18452on arrays: 18453 18454@example 18455$ @kbd{cat for.awk} 18456END @{ 18457 arr["foo"] = 1 18458 arr["bar"] = 1 18459 for (i in arr) 18460 print i 18461@} 18462$ @kbd{gawk -f for.awk </dev/null} 18463foo 18464bar 18465$ @kbd{nawk -f for.awk </dev/null} 18466bar 18467foo 18468@end example 18469 18470Some Awk implementations, such as HP-UX 11.0's native one, 18471mishandle anchors: 18472 18473@example 18474$ @kbd{echo xfoo | $AWK '/foo|^bar/ @{ print @}'} 18475$ @kbd{echo bar | $AWK '/foo|^bar/ @{ print @}'} 18476bar 18477$ @kbd{echo xfoo | $AWK '/^bar|foo/ @{ print @}'} 18478xfoo 18479$ @kbd{echo bar | $AWK '/^bar|foo/ @{ print @}'} 18480bar 18481@end example 18482 18483@noindent 18484Either do not depend on such patterns (i.e., use @samp{/^(.*foo|bar)/}, 18485or use a simple test to reject such implementations. 18486 18487On @samp{ia64-hp-hpux11.23}, Awk mishandles @code{printf} conversions 18488after @code{%u}: 18489 18490@example 18491$ @kbd{awk 'BEGIN @{ printf "%u %d\n", 0, -1 @}'} 184920 0 18493@end example 18494 18495AIX version 5.2 has an arbitrary limit of 399 on the 18496length of regular expressions and literal strings in an Awk program. 18497 18498Traditional Awk implementations derived from Unix version 7, such as 18499Solaris @command{/bin/awk}, have many limitations and do not 18500conform to Posix. Nowadays @code{AC_PROG_AWK} (@pxref{Particular 18501Programs}) finds you an Awk that doesn't have these problems, but if 18502for some reason you prefer not to use @code{AC_PROG_AWK} you may need to 18503address them. For more detailed descriptions, see @ref{Language 18504History, , @command{awk} language history, gawk, GNU Awk User's Guide}. 18505 18506Traditional Awk does not support multidimensional arrays or user-defined 18507functions. 18508 18509Traditional Awk does not support the @option{-v} option. You can use 18510assignments after the program instead, e.g., @code{$AWK '@{print v 18511$1@}' v=x}; however, don't forget that such assignments are not 18512evaluated until they are encountered (e.g., after any @code{BEGIN} 18513action). 18514 18515Traditional Awk does not support the keywords @code{delete} or @code{do}. 18516 18517Traditional Awk does not support the expressions 18518@code{@var{a}?@var{b}:@var{c}}, @code{!@var{a}}, @code{@var{a}^@var{b}}, 18519or @code{@var{a}^=@var{b}}. 18520 18521Traditional Awk does not support the predefined @code{CONVFMT} or 18522@code{ENVIRON} variables. 18523 18524Traditional Awk supports only the predefined functions @code{exp}, @code{index}, 18525@code{int}, @code{length}, @code{log}, @code{split}, @code{sprintf}, 18526@code{sqrt}, and @code{substr}. 18527 18528Traditional Awk @code{getline} is not at all compatible with Posix; 18529avoid it. 18530 18531Traditional Awk has @code{for (i in a) @dots{}} but no other uses of the 18532@code{in} keyword. For example, it lacks @code{if (i in a) @dots{}}. 18533 18534In code portable to both traditional and modern Awk, @code{FS} must be a 18535string containing just one ordinary character, and similarly for the 18536field-separator argument to @code{split}. 18537 18538Traditional Awk has a limit of 99 fields in a record. Since some Awk 18539implementations, like Tru64's, split the input even if you don't refer 18540to any field in the script, to circumvent this problem, set @samp{FS} 18541to an unusual character and use @code{split}. 18542 18543Traditional Awk has a limit of at most 99 bytes in a number formatted by 18544@code{OFMT}; for example, @code{OFMT="%.300e"; print 0.1;} typically 18545dumps core. 18546 18547The original version of Awk had a limit of at most 99 bytes per 18548@code{split} field, 99 bytes per @code{substr} substring, and 99 bytes 18549per run of non-special characters in a @code{printf} format, but these 18550bugs have been fixed on all practical hosts that we know of. 18551 18552HP-UX 11.00 and IRIX 6.5 Awk require that input files have a line length 18553of at most 3070 bytes. 18554 18555@item @command{basename} 18556@c --------------------- 18557@prindex @command{basename} 18558Not all hosts have a working @command{basename}. 18559You can use @command{expr} instead. 18560 18561@c AS_BASENAME is to be replaced by a better API. 18562@ignore 18563Not all hosts have a working @command{basename}, and you should instead 18564use @code{AS_BASENAME} (@pxref{Programming in M4sh}), followed by 18565@command{expr} if you need to strip a suffix. For example: 18566 18567@example 18568a=`basename "$aname"` # This is not portable. 18569a=`AS_BASENAME(["$aname"])` # This is more portable. 18570 18571# This is not portable. 18572c=`basename "$cname" .c` 18573 18574# This is more portable. 18575c=`AS_BASENAME(["$cname"])` 18576case $c in 18577?*.c) c=`expr "X$c" : 'X\(.*\)\.c'`;; 18578esac 18579@end example 18580@end ignore 18581 18582 18583@item @command{cat} 18584@c ---------------- 18585@prindex @command{cat} 18586Don't rely on any option. 18587 18588 18589@item @command{cc} 18590@c --------------- 18591@prindex @command{cc} 18592The command @samp{cc -c foo.c} traditionally produces an object file 18593named @file{foo.o}. Most compilers allow @option{-c} to be combined 18594with @option{-o} to specify a different object file name, but 18595Posix does not require this combination and a few compilers 18596lack support for it. @xref{C Compiler}, for how GNU Make 18597tests for this feature with @code{AC_PROG_CC_C_O}. 18598 18599When a compilation such as @samp{cc -o foo foo.c} fails, some compilers 18600(such as CDS on Reliant Unix) leave a @file{foo.o}. 18601 18602HP-UX @command{cc} doesn't accept @file{.S} files to preprocess and 18603assemble. @samp{cc -c foo.S} appears to succeed, but in fact does 18604nothing. 18605 18606The default executable, produced by @samp{cc foo.c}, can be 18607 18608@itemize 18609@item @file{a.out} --- usual Posix convention. 18610@item @file{b.out} --- i960 compilers (including @command{gcc}). 18611@item @file{a.exe} --- DJGPP port of @command{gcc}. 18612@item @file{a_out.exe} --- GNV @command{cc} wrapper for DEC C on OpenVMS. 18613@item @file{foo.exe} --- various MS-DOS compilers. 18614@end itemize 18615 18616The C compiler's traditional name is @command{cc}, but other names like 18617@command{gcc} are common. Posix 1003.1-2001 specifies the 18618name @command{c99}, but older Posix editions specified 18619@command{c89} and anyway these standard names are rarely used in 18620practice. Typically the C compiler is invoked from makefiles that use 18621@samp{$(CC)}, so the value of the @samp{CC} make variable selects the 18622compiler name. 18623 18624@item @command{chgrp} 18625@itemx @command{chown} 18626@c ------------------- 18627@prindex @command{chgrp} 18628@prindex @command{chown} 18629It is not portable to change a file's group to a group that the owner 18630does not belong to. 18631 18632@item @command{chmod} 18633@c ------------------ 18634@prindex @command{chmod} 18635Avoid usages like @samp{chmod -w file}; use @samp{chmod a-w file} 18636instead, for two reasons. First, plain @option{-w} does not necessarily 18637make the file unwritable, since it does not affect mode bits that 18638correspond to bits in the file mode creation mask. Second, 18639Posix says that the @option{-w} might be interpreted as an 18640implementation-specific option, not as a mode; Posix suggests 18641using @samp{chmod -- -w file} to avoid this confusion, but unfortunately 18642@samp{--} does not work on some older hosts. 18643 18644 18645@item @command{cmp} 18646@c ---------------- 18647@prindex @command{cmp} 18648@command{cmp} performs a raw data comparison of two files, while 18649@command{diff} compares two text files. Therefore, if you might compare 18650DOS files, even if only checking whether two files are different, use 18651@command{diff} to avoid spurious differences due to differences of 18652newline encoding. 18653 18654 18655@item @command{cp} 18656@c --------------- 18657@prindex @command{cp} 18658Avoid the @option{-r} option, since Posix 1003.1-2004 marks it as 18659obsolescent and its behavior on special files is implementation-defined. 18660Use @option{-R} instead. On GNU hosts the two options 18661are equivalent, but on Solaris hosts (for example) @code{cp -r} 18662reads from pipes instead of replicating them. AIX 5.3 @code{cp -R} may 18663corrupt its own memory with some directory hierarchies and error out or 18664dump core: 18665 18666@example 18667@kbd{mkdir -p 12345678/12345678/12345678/12345678} 18668@kbd{touch 12345678/12345678/x} 18669@kbd{cp -R 12345678 t} 18670cp: 0653-440 12345678/12345678/: name too long. 18671@end example 18672 18673Some @command{cp} implementations (e.g., BSD/OS 4.2) do not allow 18674trailing slashes at the end of nonexistent destination directories. To 18675avoid this problem, omit the trailing slashes. For example, use 18676@samp{cp -R source /tmp/newdir} rather than @samp{cp -R source 18677/tmp/newdir/} if @file{/tmp/newdir} does not exist. 18678 18679@c This is thanks to Ian. 18680The ancient SunOS 4 @command{cp} does not support @option{-f}, although 18681its @command{mv} does. 18682 18683@cindex timestamp resolution 18684Traditionally, file timestamps had 1-second resolution, and @samp{cp 18685-p} copied the timestamps exactly. However, many modern file systems 18686have timestamps with 1-nanosecond resolution. Unfortunately, some older 18687@samp{cp -p} implementations truncate timestamps when copying files, 18688which can cause the destination file to appear to be older than the 18689source. The exact amount of truncation depends on the resolution of 18690the system calls that @command{cp} uses. Traditionally this was 18691@code{utime}, which has 1-second resolution. Less-ancient @command{cp} 18692implementations such as GNU Core Utilities 5.0.91 (2003) use 18693@code{utimes}, which has 1-microsecond resolution. Modern 18694implementations such as GNU Core Utilities 6.12 (2008) can set timestamps to 18695the full nanosecond resolution, using the modern system calls 18696@code{futimens} and @code{utimensat} when they are available. As of 186972011, though, many platforms do not yet fully support these new system 18698calls. 18699 18700Bob Proulx notes that @samp{cp -p} always @emph{tries} to copy 18701ownerships. But whether it actually does copy ownerships or not is a 18702system dependent policy decision implemented by the kernel. If the 18703kernel allows it then it happens. If the kernel does not allow it then 18704it does not happen. It is not something @command{cp} itself has control 18705over. 18706 18707In Unix System V any user can chown files to any other user, and System 18708V also has a non-sticky @file{/tmp}. That probably derives from the 18709heritage of System V in a business environment without hostile users. 18710BSD changed this 18711to be a more secure model where only root can @command{chown} files and 18712a sticky @file{/tmp} is used. That undoubtedly derives from the heritage 18713of BSD in a campus environment. 18714 18715GNU/Linux and Solaris by default follow BSD, but 18716can be configured to allow a System V style @command{chown}. On the 18717other hand, HP-UX follows System V, but can 18718be configured to use the modern security model and disallow 18719@command{chown}. Since it is an administrator-configurable parameter 18720you can't use the name of the kernel as an indicator of the behavior. 18721 18722 18723 18724@item @command{date} 18725@c ----------------- 18726@prindex @command{date} 18727Some versions of @command{date} do not recognize special @samp{%} directives, 18728and unfortunately, instead of complaining, they just pass them through, 18729and exit with success: 18730 18731@example 18732$ @kbd{uname -a} 18733OSF1 medusa.sis.pasteur.fr V5.1 732 alpha 18734$ @kbd{date "+%s"} 18735%s 18736@end example 18737 18738 18739@item @command{diff} 18740@c ----------------- 18741@prindex @command{diff} 18742Option @option{-u} is nonportable. 18743 18744Some implementations, such as Tru64's, fail when comparing to 18745@file{/dev/null}. Use an empty file instead. 18746 18747 18748@item @command{dirname} 18749@c -------------------- 18750@prindex @command{dirname} 18751Not all hosts have a working @command{dirname}, and you should instead 18752use @code{AS_DIRNAME} (@pxref{Programming in M4sh}). For example: 18753 18754@example 18755dir=`dirname "$file"` # This is not portable. 18756dir=`AS_DIRNAME(["$file"])` # This is more portable. 18757@end example 18758 18759 18760@item @command{egrep} 18761@c ------------------ 18762@prindex @command{egrep} 18763Posix 1003.1-2001 no longer requires @command{egrep}, 18764but many hosts do not yet support the Posix 18765replacement @code{grep -E}. Also, some traditional implementations do 18766not work on long input lines. To work around these problems, invoke 18767@code{AC_PROG_EGREP} and then use @code{$EGREP}. 18768 18769Portable extended regular expressions should use @samp{\} only to escape 18770characters in the string @samp{$()*+.?[\^@{|}. For example, @samp{\@}} 18771is not portable, even though it typically matches @samp{@}}. 18772 18773The empty alternative is not portable. Use @samp{?} instead. For 18774instance with Digital Unix v5.0: 18775 18776@example 18777> printf "foo\n|foo\n" | $EGREP '^(|foo|bar)$' 18778|foo 18779> printf "bar\nbar|\n" | $EGREP '^(foo|bar|)$' 18780bar| 18781> printf "foo\nfoo|\n|bar\nbar\n" | $EGREP '^(foo||bar)$' 18782foo 18783|bar 18784@end example 18785 18786@command{$EGREP} also suffers the limitations of @command{grep} 18787(@pxref{grep, , Limitations of Usual Tools}). 18788 18789@item @command{expr} 18790@c ----------------- 18791@prindex @command{expr} 18792Not all implementations obey the Posix rule that @samp{--} separates 18793options from arguments; likewise, not all implementations provide the 18794extension to Posix that the first argument can be treated as part of a 18795valid expression rather than an invalid option if it begins with 18796@samp{-}. When performing arithmetic, use @samp{expr 0 + $var} if 18797@samp{$var} might be a negative number, to keep @command{expr} from 18798interpreting it as an option. 18799 18800No @command{expr} keyword starts with @samp{X}, so use @samp{expr 18801X"@var{word}" : 'X@var{regex}'} to keep @command{expr} from 18802misinterpreting @var{word}. 18803 18804Don't use @code{length}, @code{substr}, @code{match} and @code{index}. 18805 18806@item @command{expr} (@samp{|}) 18807@prindex @command{expr} (@samp{|}) 18808You can use @samp{|}. Although Posix does require that @samp{expr 18809''} return the empty string, it does not specify the result when you 18810@samp{|} together the empty string (or zero) with the empty string. For 18811example: 18812 18813@example 18814expr '' \| '' 18815@end example 18816 18817Posix 1003.2-1992 returns the empty string 18818for this case, but traditional Unix returns @samp{0} (Solaris is 18819one such example). In Posix 1003.1-2001, the specification was 18820changed to match traditional Unix's behavior (which is 18821bizarre, but it's too late to fix this). Please note that the same 18822problem does arise when the empty string results from a computation, 18823as in: 18824 18825@example 18826expr bar : foo \| foo : bar 18827@end example 18828 18829@noindent 18830Avoid this portability problem by avoiding the empty string. 18831 18832 18833@item @command{expr} (@samp{:}) 18834@c ---------------------------- 18835@prindex @command{expr} 18836Portable @command{expr} regular expressions should use @samp{\} to 18837escape only characters in the string @samp{$()*.0123456789[\^n@{@}}. 18838For example, alternation, @samp{\|}, is common but Posix does not 18839require its support, so it should be avoided in portable scripts. 18840Similarly, @samp{\+} and @samp{\?} should be avoided. 18841 18842Portable @command{expr} regular expressions should not begin with 18843@samp{^}. Patterns are automatically anchored so leading @samp{^} is 18844not needed anyway. 18845 18846On the other hand, the behavior of the @samp{$} anchor is not portable 18847on multi-line strings. Posix is ambiguous whether the anchor applies to 18848each line, as was done in older versions of the GNU Core Utilities, or 18849whether it applies only to the end of the overall string, as in 18850Coreutils 6.0 and most other implementations. 18851 18852@example 18853$ @kbd{baz='foo} 18854> @kbd{bar'} 18855$ @kbd{expr "X$baz" : 'X\(foo\)$'} 18856 18857$ @kbd{expr-5.97 "X$baz" : 'X\(foo\)$'} 18858foo 18859@end example 18860 18861The Posix standard is ambiguous as to whether 18862@samp{expr 'a' : '\(b\)'} outputs @samp{0} or the empty string. 18863In practice, it outputs the empty string on most platforms, but portable 18864scripts should not assume this. For instance, the QNX 4.25 native 18865@command{expr} returns @samp{0}. 18866 18867One might think that a way to get a uniform behavior would be to use 18868the empty string as a default value: 18869 18870@example 18871expr a : '\(b\)' \| '' 18872@end example 18873 18874@noindent 18875Unfortunately this behaves exactly as the original expression; see the 18876@command{expr} (@samp{|}) entry for more information. 18877 18878Some ancient @command{expr} implementations (e.g., SunOS 4 @command{expr} and 18879Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes 18880@command{expr} to fail if the matched substring is longer than 120 18881bytes. In this case, you might want to fall back on @samp{echo|sed} if 18882@command{expr} fails. Nowadays this is of practical importance only for 18883the rare installer who mistakenly puts @file{/usr/ucb} before 18884@file{/usr/bin} in @env{PATH}. 18885 18886On Mac OS X 10.4, @command{expr} mishandles the pattern @samp{[^-]} in 18887some cases. For example, the command 18888@example 18889expr Xpowerpc-apple-darwin8.1.0 : 'X[^-]*-[^-]*-\(.*\)' 18890@end example 18891 18892@noindent 18893outputs @samp{apple-darwin8.1.0} rather than the correct @samp{darwin8.1.0}. 18894This particular case can be worked around by substituting @samp{[^--]} 18895for @samp{[^-]}. 18896 18897Don't leave, there is some more! 18898 18899The QNX 4.25 @command{expr}, in addition of preferring @samp{0} to 18900the empty string, has a funny behavior in its exit status: it's always 1 18901when parentheses are used! 18902 18903@example 18904$ @kbd{val=`expr 'a' : 'a'`; echo "$?: $val"} 189050: 1 18906$ @kbd{val=`expr 'a' : 'b'`; echo "$?: $val"} 189071: 0 18908 18909$ @kbd{val=`expr 'a' : '\(a\)'`; echo "?: $val"} 189101: a 18911$ @kbd{val=`expr 'a' : '\(b\)'`; echo "?: $val"} 189121: 0 18913@end example 18914 18915@noindent 18916In practice this can be a big problem if you are ready to catch failures 18917of @command{expr} programs with some other method (such as using 18918@command{sed}), since you may get twice the result. For instance 18919 18920@example 18921$ @kbd{expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'} 18922@end example 18923 18924@noindent 18925outputs @samp{a} on most hosts, but @samp{aa} on QNX 4.25. A 18926simple workaround consists of testing @command{expr} and using a variable 18927set to @command{expr} or to @command{false} according to the result. 18928 18929Tru64 @command{expr} incorrectly treats the result as a number, if it 18930can be interpreted that way: 18931 18932@example 18933$ @kbd{expr 00001 : '.*\(...\)'} 189341 18935@end example 18936 18937On HP-UX 11, @command{expr} only supports a single 18938sub-expression. 18939 18940@example 18941$ @kbd{expr 'Xfoo' : 'X\(f\(oo\)*\)$'} 18942expr: More than one '\(' was used. 18943@end example 18944 18945 18946@item @command{fgrep} 18947@c ------------------ 18948@prindex @command{fgrep} 18949Posix 1003.1-2001 no longer requires @command{fgrep}, 18950but many hosts do not yet support the Posix 18951replacement @code{grep -F}. Also, some traditional implementations do 18952not work on long input lines. To work around these problems, invoke 18953@code{AC_PROG_FGREP} and then use @code{$FGREP}. 18954 18955Tru64/OSF 5.1 @command{fgrep} does not match an empty pattern. 18956 18957 18958@item @command{find} 18959@c ----------------- 18960@prindex @command{find} 18961The option @option{-maxdepth} seems to be GNU specific. 18962Tru64 v5.1, NetBSD 1.5 and Solaris @command{find} 18963commands do not understand it. 18964 18965The replacement of @samp{@{@}} is guaranteed only if the argument is 18966exactly @emph{@{@}}, not if it's only a part of an argument. For 18967instance on DU, and HP-UX 10.20 and HP-UX 11: 18968 18969@example 18970$ @kbd{touch foo} 18971$ @kbd{find . -name foo -exec echo "@{@}-@{@}" \;} 18972@{@}-@{@} 18973@end example 18974 18975@noindent 18976while GNU @command{find} reports @samp{./foo-./foo}. 18977 18978 18979@anchor{grep} 18980@item @command{grep} 18981@c ----------------- 18982@prindex @command{grep} 18983Portable scripts can rely on the @command{grep} options @option{-c}, 18984@option{-l}, @option{-n}, and @option{-v}, but should avoid other 18985options. For example, don't use @option{-w}, as Posix does not require 18986it and Irix 6.5.16m's @command{grep} does not support it. Also, 18987portable scripts should not combine @option{-c} with @option{-l}, 18988as Posix does not allow this. 18989 18990Some of the options required by Posix are not portable in practice. 18991Don't use @samp{grep -q} to suppress output, because many @command{grep} 18992implementations (e.g., Solaris) do not support @option{-q}. 18993Don't use @samp{grep -s} to suppress output either, because Posix 18994says @option{-s} does not suppress output, only some error messages; 18995also, the @option{-s} option of traditional @command{grep} behaved 18996like @option{-q} does in most modern implementations. Instead, 18997redirect the standard output and standard error (in case the file 18998doesn't exist) of @code{grep} to @file{/dev/null}. Check the exit 18999status of @code{grep} to determine whether it found a match. 19000 19001The QNX4 implementation fails to count lines with @code{grep -c '$'}, 19002but works with @code{grep -c '^'}. Other alternatives for counting 19003lines are to use @code{sed -n '$='} or @code{wc -l}. 19004 19005Some traditional @command{grep} implementations do not work on long 19006input lines. On AIX the default @code{grep} silently truncates long 19007lines on the input before matching. 19008 19009Also, many implementations do not support multiple regexps 19010with @option{-e}: they either reject @option{-e} entirely (e.g., Solaris) 19011or honor only the last pattern (e.g., IRIX 6.5 and NeXT). To 19012work around these problems, invoke @code{AC_PROG_GREP} and then use 19013@code{$GREP}. 19014 19015Another possible workaround for the multiple @option{-e} problem is to 19016separate the patterns by newlines, for example: 19017 19018@example 19019grep 'foo 19020bar' in.txt 19021@end example 19022 19023@noindent 19024except that this fails with traditional @command{grep} 19025implementations and with OpenBSD 3.8 @command{grep}. 19026 19027Traditional @command{grep} implementations (e.g., Solaris) do not 19028support the @option{-E} or @option{-F} options. To work around these 19029problems, invoke @code{AC_PROG_EGREP} and then use @code{$EGREP}, and 19030similarly for @code{AC_PROG_FGREP} and @code{$FGREP}. Even if you are 19031willing to require support for Posix @command{grep}, your script should 19032not use both @option{-E} and @option{-F}, since Posix does not allow 19033this combination. 19034 19035Portable @command{grep} regular expressions should use @samp{\} only to 19036escape characters in the string @samp{$()*.0123456789[\^@{@}}. For example, 19037alternation, @samp{\|}, is common but Posix does not require its 19038support in basic regular expressions, so it should be avoided in 19039portable scripts. Solaris and HP-UX @command{grep} do not support it. 19040Similarly, the following escape sequences should also be avoided: 19041@samp{\<}, @samp{\>}, @samp{\+}, @samp{\?}, @samp{\`}, @samp{\'}, 19042@samp{\B}, @samp{\b}, @samp{\S}, @samp{\s}, @samp{\W}, and @samp{\w}. 19043 19044Posix does not specify the behavior of @command{grep} on binary files. 19045An example where this matters is using BSD @command{grep} to 19046search text that includes embedded ANSI escape sequences for 19047colored output to terminals (@samp{\033[m} is the sequence to restore 19048normal output); the behavior depends on whether input is seekable: 19049 19050@example 19051$ @kbd{printf 'esc\033[mape\n' > sample} 19052$ @kbd{grep . sample} 19053Binary file sample matches 19054$ @kbd{cat sample | grep .} 19055escape 19056@end example 19057 19058 19059@item @command{join} 19060@c ----------------- 19061@prindex @command{join} 19062Solaris 8 @command{join} has bugs when the second operand is standard 19063input, and when standard input is a pipe. For example, the following 19064shell script causes Solaris 8 @command{join} to loop forever: 19065 19066@example 19067cat >file <<'EOF' 190681 x 190692 y 19070EOF 19071cat file | join file - 19072@end example 19073 19074Use @samp{join - file} instead. 19075 19076On NetBSD, @command{join -a 1 file1 file2} mistakenly behaves like 19077@command{join -a 1 -a 2 1 file1 file2}, resulting in a usage warning; 19078the workaround is to use @command{join -a1 file1 file2} instead. 19079 19080@item @command{ln} 19081@c --------------- 19082@prindex @command{ln} 19083@cindex Symbolic links 19084Don't rely on @command{ln} having a @option{-f} option. Symbolic links 19085are not available on old systems; use @samp{$(LN_S)} as a portable substitute. 19086 19087For versions of the DJGPP before 2.04, 19088@command{ln} emulates symbolic links 19089to executables by generating a stub that in turn calls the real 19090program. This feature also works with nonexistent files like in the 19091Posix spec. So @samp{ln -s file link} generates @file{link.exe}, 19092which attempts to call @file{file.exe} if run. But this feature only 19093works for executables, so @samp{cp -p} is used instead for these 19094systems. DJGPP versions 2.04 and later have full support 19095for symbolic links. 19096 19097 19098@item @command{ls} 19099@c --------------- 19100@prindex @command{ls} 19101@cindex Listing directories 19102The portable options are @option{-acdilrtu}. Current practice is for 19103@option{-l} to output both owner and group, even though ancient versions 19104of @command{ls} omitted the group. 19105 19106On ancient hosts, @samp{ls foo} sent the diagnostic @samp{foo not found} 19107to standard output if @file{foo} did not exist. Hence a shell command 19108like @samp{sources=`ls *.c 2>/dev/null`} did not always work, since it 19109was equivalent to @samp{sources='*.c not found'} in the absence of 19110@samp{.c} files. This is no longer a practical problem, since current 19111@command{ls} implementations send diagnostics to standard error. 19112 19113The behavior of @command{ls} on a directory that is being concurrently 19114modified is not always predictable, because of a data race where cached 19115information returned by @code{readdir} does not match the current 19116directory state. In fact, MacOS 10.5 has an intermittent bug where 19117@code{readdir}, and thus @command{ls}, sometimes lists a file more than 19118once if other files were added or removed from the directory immediately 19119prior to the @command{ls} call. Since @command{ls} already sorts its 19120output, the duplicate entries can be avoided by piping the results 19121through @code{uniq}. 19122 19123@anchor{mkdir} 19124@item @command{mkdir} 19125@c ------------------ 19126@prindex @command{mkdir} 19127@cindex Making directories 19128No @command{mkdir} option is portable to older systems. Instead of 19129@samp{mkdir -p @var{file-name}}, you should use 19130@code{AS_MKDIR_P(@var{file-name})} (@pxref{Programming in M4sh}) 19131or @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs}). 19132 19133Combining the @option{-m} and @option{-p} options, as in @samp{mkdir -m 19134go-w -p @var{dir}}, often leads to trouble. FreeBSD 19135@command{mkdir} incorrectly attempts to change the permissions of 19136@var{dir} even if it already exists. HP-UX 11.23 and 19137IRIX 6.5 @command{mkdir} often assign the wrong permissions to 19138any newly-created parents of @var{dir}. 19139 19140Posix does not clearly specify whether @samp{mkdir -p foo} 19141should succeed when @file{foo} is a symbolic link to an already-existing 19142directory. The GNU Core Utilities 5.1.0 @command{mkdir} 19143succeeds, but Solaris @command{mkdir} fails. 19144 19145Traditional @code{mkdir -p} implementations suffer from race conditions. 19146For example, if you invoke @code{mkdir -p a/b} and @code{mkdir -p a/c} 19147at the same time, both processes might detect that @file{a} is missing, 19148one might create @file{a}, then the other might try to create @file{a} 19149and fail with a @code{File exists} diagnostic. The GNU Core 19150Utilities (@samp{fileutils} version 4.1), FreeBSD 5.0, 19151NetBSD 2.0.2, and OpenBSD 2.4 are known to be 19152race-free when two processes invoke @code{mkdir -p} simultaneously, but 19153earlier versions are vulnerable. Solaris @command{mkdir} is still 19154vulnerable as of Solaris 10, and other traditional Unix systems are 19155probably vulnerable too. This possible race is harmful in parallel 19156builds when several Make rules call @code{mkdir -p} to 19157construct directories. You may use 19158@code{install-sh -d} as a safe replacement, provided this script is 19159recent enough; the copy shipped with Autoconf 2.60 and Automake 1.10 is 19160OK, but copies from older versions are vulnerable. 19161 19162 19163@item @command{mkfifo} 19164@itemx @command{mknod} 19165@c ------------------- 19166@prindex @command{mkfifo} 19167@prindex @command{mknod} 19168The GNU Coding Standards state that @command{mknod} is safe to use on 19169platforms where it has been tested to exist; but it is generally portable 19170only for creating named FIFOs, since device numbers are 19171platform-specific. Autotest uses @command{mkfifo} to implement parallel 19172testsuites. Posix states that behavior is unspecified when opening a 19173named FIFO for both reading and writing; on at least Cygwin, this 19174results in failure on any attempt to read or write to that file 19175descriptor. 19176 19177@item @command{mktemp} 19178@c ------------------- 19179@prindex @command{mktemp} 19180@cindex Creating temporary files 19181Shell scripts can use temporary files safely with @command{mktemp}, but 19182it does not exist on all systems. A portable way to create a safe 19183temporary file name is to create a temporary directory with mode 700 and 19184use a file inside this directory. Both methods prevent attackers from 19185gaining control, though @command{mktemp} is far less likely to fail 19186gratuitously under attack. 19187 19188Here is sample code to create a new temporary directory @samp{$dir} safely: 19189 19190@example 19191# Create a temporary directory $dir in $TMPDIR (default /tmp). 19192# Use mktemp if possible; otherwise fall back on mkdir, 19193# with $RANDOM to make collisions less likely. 19194: "$@{TMPDIR:=/tmp@}" 19195@{ 19196 dir=` 19197 (umask 077 && mktemp -d "$TMPDIR/fooXXXXXX") 2>/dev/null 19198 ` && 19199 test -d "$dir" 19200@} || @{ 19201 dir=$TMPDIR/foo$$-$RANDOM 19202@c $$ restore font-lock 19203 (umask 077 && mkdir "$dir") 19204@} || exit $? 19205@end example 19206 19207 19208@item @command{mv} 19209@c --------------- 19210@prindex @command{mv} 19211@cindex Moving open files 19212The only portable options are @option{-f} and @option{-i}. 19213 19214Moving individual files between file systems is portable (it was in Unix 19215version 6), 19216but it is not always atomic: when doing @samp{mv new existing}, there's 19217a critical section where neither the old nor the new version of 19218@file{existing} actually exists. 19219 19220On some systems moving files from @file{/tmp} can sometimes cause 19221undesirable (but perfectly valid) warnings, even if you created these 19222files. This is because @file{/tmp} belongs to a group that ordinary 19223users are not members of, and files created in @file{/tmp} inherit 19224the group of @file{/tmp}. When the file is copied, @command{mv} issues 19225a diagnostic without failing: 19226 19227@smallexample 19228$ @kbd{touch /tmp/foo} 19229$ @kbd{mv /tmp/foo .} 19230@error{}mv: ./foo: set owner/group (was: 100/0): Operation not permitted 19231$ @kbd{echo $?} 192320 19233$ @kbd{ls foo} 19234foo 19235@end smallexample 19236 19237@noindent 19238This annoying behavior conforms to Posix, unfortunately. 19239 19240Moving directories across mount points is not portable, use @command{cp} 19241and @command{rm}. 19242 19243DOS variants cannot rename or remove open files, and do not 19244support commands like @samp{mv foo bar >foo}, even though this is 19245perfectly portable among Posix hosts. 19246 19247 19248@item @command{od} 19249@c --------------- 19250@prindex @command{od} 19251 19252In Mac OS X 10.3, @command{od} does not support the 19253standard Posix options @option{-A}, @option{-j}, @option{-N}, or 19254@option{-t}, or the XSI option @option{-s}. The only 19255supported Posix option is @option{-v}, and the only supported 19256XSI options are those in @option{-bcdox}. The BSD 19257@command{hexdump} program can be used instead. 19258 19259This problem no longer exists in Mac OS X 10.4.3. 19260 19261 19262@item @command{rm} 19263@c --------------- 19264@prindex @command{rm} 19265The @option{-f} and @option{-r} options are portable. 19266 19267It is not portable to invoke @command{rm} without options or operands. 19268On the other hand, Posix now requires @command{rm -f} to silently 19269succeed when there are no operands (useful for constructs like 19270@command{rm -rf $filelist} without first checking if @samp{$filelist} 19271was empty). But this was not always portable; at least NetBSD 19272@command{rm} built before 2008 would fail with a diagnostic. 19273 19274A file might not be removed even if its parent directory is writable 19275and searchable. Many Posix hosts cannot remove a mount point, a named 19276stream, a working directory, or a last link to a file that is being 19277executed. 19278 19279DOS variants cannot rename or remove open files, and do not 19280support commands like @samp{rm foo >foo}, even though this is 19281perfectly portable among Posix hosts. 19282 19283@item @command{rmdir} 19284@c ------------------ 19285@prindex @command{rmdir} 19286Just as with @command{rm}, some platforms refuse to remove a working 19287directory. 19288 19289@anchor{sed} 19290@item @command{sed} 19291@c ---------------- 19292@prindex @command{sed} 19293Patterns should not include the separator (unless escaped), even as part 19294of a character class. In conformance with Posix, the Cray 19295@command{sed} rejects @samp{s/[^/]*$//}: use @samp{s%[^/]*$%%}. 19296Even when escaped, patterns should not include separators that are also 19297used as @command{sed} metacharacters. For example, GNU sed 4.0.9 rejects 19298@samp{s,x\@{1\,\@},,}, while sed 4.1 strips the backslash before the comma 19299before evaluating the basic regular expression. 19300 19301Avoid empty patterns within parentheses (i.e., @samp{\(\)}). Posix does 19302not require support for empty patterns, and Unicos 9 @command{sed} rejects 19303them. 19304 19305Unicos 9 @command{sed} loops endlessly on patterns like @samp{.*\n.*}. 19306 19307Sed scripts should not use branch labels longer than 7 characters and 19308should not contain comments; AIX 5.3 @command{sed} rejects indented comments. 19309HP-UX sed has a limit of 99 commands (not counting @samp{:} commands) and 1931048 labels, which cannot be circumvented by using more than one script 19311file. It can execute up to 19 reads with the @samp{r} command per cycle. 19312Solaris @command{/usr/ucb/sed} rejects usages that exceed a limit of 19313about 6000 bytes for the internal representation of commands. 19314 19315Avoid redundant @samp{;}, as some @command{sed} implementations, such as 19316NetBSD 1.4.2's, incorrectly try to interpret the second 19317@samp{;} as a command: 19318 19319@example 19320$ @kbd{echo a | sed 's/x/x/;;s/x/x/'} 19321sed: 1: "s/x/x/;;s/x/x/": invalid command code ; 19322@end example 19323 19324Some @command{sed} implementations have a buffer limited to 4000 bytes, 19325and this limits the size of input lines, output lines, and internal 19326buffers that can be processed portably. Likewise, 19327not all @command{sed} implementations can handle embedded @code{NUL} or 19328a missing trailing newline. 19329 19330Remember that ranges within a bracket expression of a regular expression 19331are only well-defined in the @samp{C} (or @samp{POSIX}) locale. 19332Meanwhile, support for character classes like @samp{[[:upper:]]} is not 19333yet universal, so if you cannot guarantee the setting of @env{LC_ALL}, 19334it is better to spell out a range @samp{[ABCDEFGHIJKLMNOPQRSTUVWXYZ]} 19335than to rely on @samp{[A-Z]}. 19336 19337Additionally, Posix states that regular expressions are only 19338well-defined on characters. Unfortunately, there exist platforms such 19339as MacOS X 10.5 where not all 8-bit byte values are valid characters, 19340even though that platform has a single-byte @samp{C} locale. And Posix 19341allows the existence of a multi-byte @samp{C} locale, although that does 19342not yet appear to be a common implementation. At any rate, it means 19343that not all bytes will be matched by the regular expression @samp{.}: 19344 19345@example 19346$ @kbd{printf '\200\n' | LC_ALL=C sed -n /./p | wc -l} 193470 19348$ @kbd{printf '\200\n' | LC_ALL=en_US.ISO8859-1 sed -n /./p | wc -l} 193491 19350@end example 19351 19352Portable @command{sed} regular expressions should use @samp{\} only to escape 19353characters in the string @samp{$()*.0123456789[\^n@{@}}. For example, 19354alternation, @samp{\|}, is common but Posix does not require its 19355support, so it should be avoided in portable scripts. Solaris 19356@command{sed} does not support alternation; e.g., @samp{sed '/a\|b/d'} 19357deletes only lines that contain the literal string @samp{a|b}. 19358Similarly, @samp{\+} and @samp{\?} should be avoided. 19359 19360Anchors (@samp{^} and @samp{$}) inside groups are not portable. 19361 19362Nested parentheses in patterns (e.g., @samp{\(\(a*\)b*)\)}) are 19363quite portable to current hosts, but was not supported by some ancient 19364@command{sed} implementations like SVR3. 19365 19366Some @command{sed} implementations, e.g., Solaris, restrict the special 19367role of the asterisk @samp{*} to one-character regular expressions and 19368back-references, and the special role of interval expressions 19369@samp{\@{@var{m}\@}}, @samp{\@{@var{m},\@}}, or @samp{\@{@var{m},@var{n}\@}} 19370to one-character regular expressions. This may lead to unexpected behavior: 19371 19372@example 19373$ @kbd{echo '1*23*4' | /usr/bin/sed 's/\(.\)*/x/g'} 19374x2x4 19375$ @kbd{echo '1*23*4' | /usr/xpg4/bin/sed 's/\(.\)*/x/g'} 19376x 19377@end example 19378 19379The @option{-e} option is mostly portable. 19380However, its argument 19381cannot start with @samp{a}, @samp{c}, or @samp{i}, 19382as this runs afoul of a Tru64 5.1 bug. 19383Also, its argument cannot be empty, as this fails on AIX 5.3. 19384Some people prefer to use @samp{-e}: 19385 19386@example 19387sed -e '@var{command-1}' \ 19388 -e '@var{command-2}' 19389@end example 19390 19391@noindent 19392as opposed to the equivalent: 19393 19394@example 19395sed ' 19396 @var{command-1} 19397 @var{command-2} 19398' 19399@end example 19400 19401@noindent 19402The following usage is sometimes equivalent: 19403 19404@example 19405sed '@var{command-1};@var{command-2}' 19406@end example 19407 19408but Posix says that this use of a semicolon has undefined effect if 19409@var{command-1}'s verb is @samp{@{}, @samp{a}, @samp{b}, @samp{c}, 19410@samp{i}, @samp{r}, @samp{t}, @samp{w}, @samp{:}, or @samp{#}, so you 19411should use semicolon only with simple scripts that do not use these 19412verbs. 19413 19414Posix up to the 2008 revision requires the argument of the @option{-e} 19415option to be a syntactically complete script. GNU @command{sed} allows 19416to pass multiple script fragments, each as argument of a separate 19417@option{-e} option, that are then combined, with newlines between the 19418fragments, and a future Posix revision may allow this as well. This 19419approach is not portable with script fragments ending in backslash; for 19420example, the @command{sed} programs on Solaris 10, HP-UX 11, and AIX 19421don't allow splitting in this case: 19422 19423@example 19424$ @kbd{echo a | sed -n -e 'i\} 19425@kbd{0'} 194260 19427$ @kbd{echo a | sed -n -e 'i\' -e 0} 19428Unrecognized command: 0 19429@end example 19430 19431@noindent 19432In practice, however, this technique of joining fragments 19433through @option{-e} works for multiple @command{sed} functions within 19434@samp{@{} and @samp{@}}, even if that is not specified by Posix: 19435 19436@example 19437@c The quote around the closing brace silences interactive zsh. 19438$ @kbd{echo a | sed -n -e '/a/@{' -e s/a/b/ -e p -e '@}'} 19439b 19440@end example 19441 19442Commands inside @{ @} brackets are further restricted. Posix 2008 says that 19443they cannot be preceded by addresses, @samp{!}, or @samp{;}, and that 19444each command must be followed immediately by a newline, without any 19445intervening blanks or semicolons. The closing bracket must be alone on 19446a line, other than white space preceding or following it. However, a 19447future version of Posix may standardize the use of addresses within brackets. 19448 19449Contrary to yet another urban legend, you may portably use @samp{&} in 19450the replacement part of the @code{s} command to mean ``what was 19451matched''. All descendants of Unix version 7 @command{sed} 19452(at least; we 19453don't have first hand experience with older @command{sed} implementations) have 19454supported it. 19455 19456Posix requires that you must not have any white space between 19457@samp{!} and the following command. It is OK to have blanks between 19458the address and the @samp{!}. For instance, on Solaris: 19459 19460@example 19461$ @kbd{echo "foo" | sed -n '/bar/ ! p'} 19462@error{}Unrecognized command: /bar/ ! p 19463$ @kbd{echo "foo" | sed -n '/bar/! p'} 19464@error{}Unrecognized command: /bar/! p 19465$ @kbd{echo "foo" | sed -n '/bar/ !p'} 19466foo 19467@end example 19468 19469Posix also says that you should not combine @samp{!} and @samp{;}. If 19470you use @samp{!}, it is best to put it on a command that is delimited by 19471newlines rather than @samp{;}. 19472 19473Also note that Posix requires that the @samp{b}, @samp{t}, @samp{r}, and 19474@samp{w} commands be followed by exactly one space before their argument. 19475On the other hand, no white space is allowed between @samp{:} and the 19476subsequent label name. 19477 19478If a sed script is specified on the command line and ends in an 19479@samp{a}, @samp{c}, or @samp{i} command, the last line of inserted text 19480should be followed by a newline. Otherwise some @command{sed} 19481implementations (e.g., OpenBSD 3.9) do not append a newline to the 19482inserted text. 19483 19484Many @command{sed} implementations (e.g., MacOS X 10.4, 19485OpenBSD 3.9, Solaris 10 19486@command{/usr/ucb/sed}) strip leading white space from the text of 19487@samp{a}, @samp{c}, and @samp{i} commands. Prepend a backslash to 19488work around this incompatibility with Posix: 19489 19490@example 19491$ @kbd{echo flushleft | sed 'a\} 19492> @kbd{ indented} 19493> @kbd{'} 19494flushleft 19495indented 19496$ @kbd{echo foo | sed 'a\} 19497> @kbd{\ indented} 19498> @kbd{'} 19499flushleft 19500 indented 19501@end example 19502 19503Posix requires that with an empty regular expression, the last non-empty 19504regular expression from either an address specification or substitution 19505command is applied. However, busybox 1.6.1 complains when using a 19506substitution command with a replacement containing a back-reference to 19507an empty regular expression; the workaround is repeating the regular 19508expression. 19509 19510@example 19511$ @kbd{echo abc | busybox sed '/a\(b\)c/ s//\1/'} 19512sed: No previous regexp. 19513$ @kbd{echo abc | busybox sed '/a\(b\)c/ s/a\(b\)c/\1/'} 19514b 19515@end example 19516 19517 19518@item @command{sed} (@samp{t}) 19519@c --------------------------- 19520@prindex @command{sed} (@samp{t}) 19521Some old systems have @command{sed} that ``forget'' to reset their 19522@samp{t} flag when starting a new cycle. For instance on MIPS 19523RISC/OS, and on IRIX 5.3, if you run the following @command{sed} 19524script (the line numbers are not actual part of the texts): 19525 19526@example 19527s/keep me/kept/g # a 19528t end # b 19529s/.*/deleted/g # c 19530:end # d 19531@end example 19532 19533@noindent 19534on 19535 19536@example 19537delete me # 1 19538delete me # 2 19539keep me # 3 19540delete me # 4 19541@end example 19542 19543@noindent 19544you get 19545 19546@example 19547deleted 19548delete me 19549kept 19550deleted 19551@end example 19552 19553@noindent 19554instead of 19555 19556@example 19557deleted 19558deleted 19559kept 19560deleted 19561@end example 19562 19563Why? When processing line 1, (c) matches, therefore sets the @samp{t} 19564flag, and the output is produced. When processing 19565line 2, the @samp{t} flag is still set (this is the bug). Command (a) 19566fails to match, but @command{sed} is not supposed to clear the @samp{t} 19567flag when a substitution fails. Command (b) sees that the flag is set, 19568therefore it clears it, and jumps to (d), hence you get @samp{delete me} 19569instead of @samp{deleted}. When processing line (3), @samp{t} is clear, 19570(a) matches, so the flag is set, hence (b) clears the flags and jumps. 19571Finally, since the flag is clear, line 4 is processed properly. 19572 19573There are two things one should remember about @samp{t} in @command{sed}. 19574Firstly, always remember that @samp{t} jumps if @emph{some} substitution 19575succeeded, not only the immediately preceding substitution. Therefore, 19576always use a fake @samp{t clear} followed by a @samp{:clear} on the next 19577line, to reset the @samp{t} flag where needed. 19578 19579Secondly, you cannot rely on @command{sed} to clear the flag at each new 19580cycle. 19581 19582One portable implementation of the script above is: 19583 19584@example 19585t clear 19586:clear 19587s/keep me/kept/g 19588t end 19589s/.*/deleted/g 19590:end 19591@end example 19592 19593@item @command{sleep} 19594@c ------------------ 19595@prindex @command{sleep} 19596Using @command{sleep} is generally portable. However, remember that 19597adding a @command{sleep} to work around timestamp issues, with a minimum 19598granularity of one second, doesn't scale well for parallel builds on 19599modern machines with sub-second process completion. 19600 19601@item @command{sort} 19602@c ----------------- 19603@prindex @command{sort} 19604Remember that sort order is influenced by the current locale. Inside 19605@file{configure}, the C locale is in effect, but in Makefile snippets, 19606you may need to specify @code{LC_ALL=C sort}. 19607 19608@item @command{tar} 19609@c ---------------- 19610@prindex @command{tar} 19611There are multiple file formats for @command{tar}; if you use Automake, 19612the macro @code{AM_INIT_AUTOMAKE} has some options controlling which 19613level of portability to use. 19614 19615@anchor{touch} 19616@item @command{touch} 19617@c ------------------ 19618@prindex @command{touch} 19619@cindex timestamp resolution 19620If you specify the desired timestamp (e.g., with the @option{-r} 19621option), older @command{touch} implementations use the @code{utime} or 19622@code{utimes} system call, which can result in the same kind of 19623timestamp truncation problems that @samp{cp -p} has. 19624 19625On ancient BSD systems, @command{touch} or any command that 19626results in an empty file does not update the timestamps, so use a 19627command like @command{echo} as a workaround. 19628Also, 19629GNU @command{touch} 3.16r (and presumably all before that) 19630fails to work on SunOS 4.1.3 when the empty file is on an 19631NFS-mounted 4.2 volume. 19632However, these problems are no longer of practical concern. 19633 19634@item @command{tr} 19635@c --------------- 19636@prindex @command{tr} 19637@cindex carriage return, deleting 19638@cindex newline, deleting 19639@cindex deleting carriage return 19640Not all versions of @command{tr} handle all backslash character escapes. 19641For example, Solaris 10 @command{/usr/ucb/tr} falls over, even though 19642Solaris contains more modern @command{tr} in other locations. 19643Using octal escapes is more portable for carriage returns, since 19644@samp{\015} is the same for both ASCII and EBCDIC, and since use of 19645literal carriage returns in scripts causes a number of other problems. 19646But for other characters, like newline, using octal escapes ties the 19647operation to ASCII, so it is better to use literal characters. 19648 19649@example 19650$ @kbd{@{ echo moon; echo light; @} | /usr/ucb/tr -d '\n' ; echo} 19651moo 19652light 19653$ @kbd{@{ echo moon; echo light; @} | /usr/bin/tr -d '\n' ; echo} 19654moonlight 19655$ @kbd{@{ echo moon; echo light; @} | /usr/ucb/tr -d '\012' ; echo} 19656moonlight 19657$ @kbd{nl='} 19658@kbd{'; @{ echo moon; echo light; @} | /usr/ucb/tr -d "$nl" ; echo} 19659moonlight 19660@end example 19661 19662Not all versions of @command{tr} recognize direct ranges of characters: at 19663least Solaris @command{/usr/bin/tr} still fails to do so. But you can 19664use @command{/usr/xpg4/bin/tr} instead, or add brackets (which in Posix 19665transliterate to themselves). 19666 19667@example 19668$ @kbd{echo "Hazy Fantazy" | LC_ALL=C /usr/bin/tr a-z A-Z} 19669HAZy FAntAZy 19670$ @kbd{echo "Hazy Fantazy" | LC_ALL=C /usr/bin/tr '[a-z]' '[A-Z]'} 19671HAZY FANTAZY 19672$ @kbd{echo "Hazy Fantazy" | LC_ALL=C /usr/xpg4/bin/tr a-z A-Z} 19673HAZY FANTAZY 19674@end example 19675 19676When providing two arguments, be sure the second string is at least as 19677long as the first. 19678 19679@example 19680$ @kbd{echo abc | /usr/xpg4/bin/tr bc d} 19681adc 19682$ @kbd{echo abc | coreutils/tr bc d} 19683add 19684@end example 19685 19686Posix requires @command{tr} to operate on binary files. But at least 19687Solaris @command{/usr/ucb/tr} and @command{/usr/bin/tr} silently discard 19688@code{NUL} in the input prior to doing any translation. When using 19689@command{tr} to process a binary file that may contain @code{NUL} bytes, 19690it is necessary to use @command{/usr/xpg4/bin/tr} instead, or 19691@command{/usr/xpg6/bin/tr} if that is available. 19692 19693@example 19694$ @kbd{printf 'a\0b' | /usr/ucb/tr x x | od -An -tx1} 19695 61 62 19696$ @kbd{printf 'a\0b' | /usr/bin/tr x x | od -An -tx1} 19697 61 62 19698$ @kbd{printf 'a\0b' | /usr/xpg4/bin/tr x x | od -An -tx1} 19699 61 00 62 19700@end example 19701 19702Solaris @command{/usr/ucb/tr} additionally fails to handle @samp{\0} as the 19703octal escape for @code{NUL}. 19704 19705@example 19706$ @kbd{printf 'abc' | /usr/ucb/tr 'bc' '\0d' | od -An -tx1} 19707 61 62 63 19708$ @kbd{printf 'abc' | /usr/bin/tr 'bc' '\0d' | od -An -tx1} 19709 61 00 64 19710$ @kbd{printf 'abc' | /usr/xpg4/bin/tr 'bc' '\0d' | od -An -tx1} 19711 61 00 64 19712@end example 19713 19714@end table 19715 19716 19717@node Portable Make 19718@chapter Portable Make Programming 19719@prindex @command{make} 19720@cindex Limitations of @command{make} 19721 19722Writing portable makefiles is an art. Since a makefile's commands are 19723executed by the shell, you must consider the shell portability issues 19724already mentioned. However, other issues are specific to @command{make} 19725itself. 19726 19727@menu 19728* $< in Ordinary Make Rules:: $< in ordinary rules 19729* Failure in Make Rules:: Failing portably in rules 19730* Special Chars in Names:: Special Characters in Macro Names 19731* Backslash-Newline-Empty:: Empty lines after backslash-newline 19732* Backslash-Newline Comments:: Spanning comments across line boundaries 19733* Long Lines in Makefiles:: Line length limitations 19734* Macros and Submakes:: @code{make macro=value} and submakes 19735* The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues 19736* The Make Macro SHELL:: @code{$(SHELL)} portability issues 19737* Parallel Make:: Parallel @command{make} quirks 19738* Comments in Make Rules:: Other problems with Make comments 19739* Newlines in Make Rules:: Using literal newlines in rules 19740* Comments in Make Macros:: Other problems with Make comments in macros 19741* Trailing whitespace in Make Macros:: Macro substitution problems 19742* Command-line Macros and whitespace:: Whitespace trimming of values 19743* obj/ and Make:: Don't name a subdirectory @file{obj} 19744* make -k Status:: Exit status of @samp{make -k} 19745* VPATH and Make:: @code{VPATH} woes 19746* Single Suffix Rules:: Single suffix rules and separated dependencies 19747* Timestamps and Make:: Subsecond timestamp resolution 19748@end menu 19749 19750@node $< in Ordinary Make Rules 19751@section @code{$<} in Ordinary Make Rules 19752 19753Posix says that the @samp{$<} construct in makefiles can be 19754used only in inference rules and in the @samp{.DEFAULT} rule; its 19755meaning in ordinary rules is unspecified. Solaris @command{make} 19756for instance replaces it with the empty string. OpenBSD (3.0 and 19757later) @command{make} diagnoses these uses and errors out. 19758 19759@node Failure in Make Rules 19760@section Failure in Make Rules 19761 19762Posix 2008 requires that @command{make} must invoke each command with 19763the equivalent of a @samp{sh -e -c} subshell, which causes the 19764subshell to exit immediately if a subsidiary simple-command fails, 19765although not all @command{make} implementations have historically 19766followed this rule. For 19767example, the command @samp{touch T; rm -f U} may attempt to 19768remove @file{U} even if the @command{touch} fails, although this is not 19769permitted with Posix make. One way to work around failures in simple 19770commands is to reword them so that they always succeed, e.g., @samp{touch 19771T || :; rm -f U}. 19772However, even this approach can run into common bugs in BSD 19773implementations of the @option{-e} option of @command{sh} and 19774@command{set} (@pxref{set, , Limitations of Shell Builtins}), so if you 19775are worried 19776about porting to buggy BSD shells it may be simpler to migrate 19777complicated @command{make} actions into separate scripts. 19778 19779@node Special Chars in Names 19780@section Special Characters in Make Macro Names 19781 19782Posix limits macro names to nonempty strings containing only 19783ASCII letters and digits, @samp{.}, and @samp{_}. Many 19784@command{make} implementations allow a wider variety of characters, but 19785portable makefiles should avoid them. It is portable to start a name 19786with a special character, e.g., @samp{$(.FOO)}. 19787 19788Some ancient @command{make} implementations don't support leading 19789underscores in macro names. An example is NEWS-OS 4.2R. 19790 19791@example 19792$ @kbd{cat Makefile} 19793_am_include = # 19794_am_quote = 19795all:; @@echo this is test 19796$ @kbd{make} 19797Make: Must be a separator on rules line 2. Stop. 19798$ @kbd{cat Makefile2} 19799am_include = # 19800am_quote = 19801all:; @@echo this is test 19802$ @kbd{make -f Makefile2} 19803this is test 19804@end example 19805 19806@noindent 19807However, this problem is no longer of practical concern. 19808 19809@node Backslash-Newline-Empty 19810@section Backslash-Newline Before Empty Lines 19811 19812A bug in Bash 2.03 can cause problems if a Make rule contains a 19813backslash-newline followed by line that expands to nothing. 19814For example, on Solaris 8: 19815 19816@example 19817SHELL = /bin/bash 19818EMPTY = 19819foo: 19820 touch foo \ 19821 $(EMPTY) 19822@end example 19823 19824@noindent 19825executes 19826 19827@example 19828/bin/bash -c 'touch foo \ 19829' 19830@end example 19831 19832@noindent 19833which fails with a syntax error, due to the Bash bug. To avoid this 19834problem, avoid nullable macros in the last line of a multiline command. 19835 19836@c This has been seen on ia64 hpux 11.20, and on one hppa hpux 10.20, 19837@c but another hppa hpux 10.20 didn't have it. Bob Proulx 19838@c <bob@proulx.com> thinks it was in hpux 8.0 too. 19839On some versions of HP-UX, @command{make} reads multiple newlines 19840following a backslash, continuing to the next non-empty line. For 19841example, 19842 19843@example 19844FOO = one \ 19845 19846BAR = two 19847 19848test: 19849 : FOO is "$(FOO)" 19850 : BAR is "$(BAR)" 19851@end example 19852 19853@noindent 19854shows @code{FOO} equal to @code{one BAR = two}. Other implementations 19855sensibly let a backslash continue only to the immediately following 19856line. 19857 19858@node Backslash-Newline Comments 19859@section Backslash-Newline in Make Comments 19860 19861According to Posix, Make comments start with @code{#} 19862and continue until an unescaped newline is reached. 19863 19864@example 19865$ @kbd{cat Makefile} 19866# A = foo \ 19867 bar \ 19868 baz 19869 19870all: 19871 @@echo ok 19872$ @kbd{make} # GNU make 19873ok 19874@end example 19875 19876@noindent 19877However this is not always the case. Some implementations 19878discard everything from @code{#} through the end of the line, ignoring any 19879trailing backslash. 19880 19881@example 19882$ @kbd{pmake} # BSD make 19883"Makefile", line 3: Need an operator 19884Fatal errors encountered -- cannot continue 19885@end example 19886 19887@noindent 19888Therefore, if you want to comment out a multi-line definition, prefix each 19889line with @code{#}, not only the first. 19890 19891@example 19892# A = foo \ 19893# bar \ 19894# baz 19895@end example 19896 19897@node Long Lines in Makefiles 19898@section Long Lines in Makefiles 19899 19900Tru64 5.1's @command{make} has been reported to crash when given a 19901makefile with lines longer than around 20 kB. Earlier versions are 19902reported to exit with @code{Line too long} diagnostics. 19903 19904@node Macros and Submakes 19905@section @code{make macro=value} and Submakes 19906 19907A command-line variable definition such as @code{foo=bar} overrides any 19908definition of @code{foo} in a makefile. Some @command{make} 19909implementations (such as GNU @command{make}) propagate this 19910override to subsidiary invocations of @command{make}. Some other 19911implementations do not pass the substitution along to submakes. 19912 19913@example 19914$ @kbd{cat Makefile} 19915foo = foo 19916one: 19917 @@echo $(foo) 19918 $(MAKE) two 19919two: 19920 @@echo $(foo) 19921$ @kbd{make foo=bar} # GNU make 3.79.1 19922bar 19923make two 19924make[1]: Entering directory `/home/adl' 19925bar 19926make[1]: Leaving directory `/home/adl' 19927$ @kbd{pmake foo=bar} # BSD make 19928bar 19929pmake two 19930foo 19931@end example 19932 19933You have a few possibilities if you do want the @code{foo=bar} override 19934to propagate to submakes. One is to use the @option{-e} 19935option, which causes all environment variables to have precedence over 19936the makefile macro definitions, and declare foo as an environment 19937variable: 19938 19939@example 19940$ @kbd{env foo=bar make -e} 19941@end example 19942 19943The @option{-e} option is propagated to submakes automatically, 19944and since the environment is inherited between @command{make} 19945invocations, the @code{foo} macro is overridden in 19946submakes as expected. 19947 19948This syntax (@code{foo=bar make -e}) is portable only when used 19949outside of a makefile, for instance from a script or from the 19950command line. When run inside a @command{make} rule, GNU 19951@command{make} 3.80 and prior versions forget to propagate the 19952@option{-e} option to submakes. 19953 19954Moreover, using @option{-e} could have unexpected side effects if your 19955environment contains some other macros usually defined by the 19956makefile. (See also the note about @code{make -e} and @code{SHELL} 19957below.) 19958 19959If you can foresee all macros that a user might want to override, then 19960you can propagate them to submakes manually, from your makefile: 19961 19962@example 19963foo = foo 19964one: 19965 @@echo $(foo) 19966 $(MAKE) foo=$(foo) two 19967two: 19968 @@echo $(foo) 19969@end example 19970 19971Another way to propagate a variable to submakes in a portable way is to 19972expand an extra variable in every invocation of @samp{$(MAKE)} within 19973your makefile: 19974 19975@example 19976foo = foo 19977one: 19978 @@echo $(foo) 19979 $(MAKE) $(SUBMAKEFLAGS) two 19980two: 19981 @@echo $(foo) 19982@end example 19983 19984Users must be aware that this technique is in use to take advantage of 19985it, e.g.@: with @code{make foo=bar SUBMAKEFLAGS='foo=bar'}, but it 19986allows any macro to be overridden. Makefiles generated by 19987@command{automake} use this technique, expanding @code{$(AM_MAKEFLAGS)} 19988on the command lines of submakes (@pxref{Subdirectories, , Automake, 19989automake, GNU Automake}). 19990 19991@node The Make Macro MAKEFLAGS 19992@section The Make Macro MAKEFLAGS 19993@cindex @code{MAKEFLAGS} and @command{make} 19994@cindex @command{make} and @code{MAKEFLAGS} 19995 19996Posix requires @command{make} to use @code{MAKEFLAGS} to affect the 19997current and recursive invocations of make, but allows implementations 19998several formats for the variable. It is tricky to parse 19999@code{$MAKEFLAGS} to determine whether @option{-s} for silent execution 20000or @option{-k} for continued execution are in effect. For example, you 20001cannot assume that the first space-separated word in @code{$MAKEFLAGS} 20002contains single-letter options, since in the Cygwin version of 20003GNU @command{make} it is either @option{--unix} or 20004@option{--win32} with the second word containing single-letter options. 20005 20006@example 20007$ @kbd{cat Makefile} 20008all: 20009 @@echo MAKEFLAGS = $(MAKEFLAGS) 20010$ @kbd{make} 20011MAKEFLAGS = --unix 20012$ @kbd{make -k} 20013MAKEFLAGS = --unix -k 20014@end example 20015 20016@node The Make Macro SHELL 20017@section The Make Macro @code{SHELL} 20018@cindex @code{SHELL} and @command{make} 20019@cindex @command{make} and @code{SHELL} 20020 20021Posix-compliant @command{make} internally uses the @code{$(SHELL)} 20022macro to spawn shell processes and execute Make rules. This 20023is a builtin macro supplied by @command{make}, but it can be modified 20024by a makefile or by a command-line argument. 20025 20026Not all @command{make} implementations define this @code{SHELL} macro. 20027Tru64 20028@command{make} is an example; this implementation always uses 20029@code{/bin/sh}. So it's a good idea to always define @code{SHELL} in 20030your makefiles. If you use Autoconf, do 20031 20032@example 20033SHELL = @@SHELL@@ 20034@end example 20035 20036@noindent 20037If you use Automake, this is done for you. 20038 20039Do not force @code{SHELL = /bin/sh} because that is not correct 20040everywhere. Remember, @file{/bin/sh} is not Posix compliant on many 20041systems, such as FreeBSD 4, NetBSD 3, AIX 3, Solaris 10, or Tru64. 20042Additionally, DJGPP lacks @code{/bin/sh}, and when its 20043GNU @command{make} port sees such a setting it enters a 20044special emulation mode where features like pipes and redirections are 20045emulated on top of DOS's @command{command.com}. Unfortunately this 20046emulation is incomplete; for instance it does not handle command 20047substitutions. Using @code{@@SHELL@@} means that your makefile will 20048benefit from the same improved shell, such as @command{bash} or 20049@command{ksh}, that was discovered during @command{configure}, so that 20050you aren't fighting two different sets of shell bugs between the two 20051contexts. 20052 20053Posix-compliant @command{make} should never acquire the value of 20054$(SHELL) from the environment, even when @code{make -e} is used 20055(otherwise, think about what would happen to your rules if 20056@code{SHELL=/bin/tcsh}). 20057 20058However not all @command{make} implementations have this exception. 20059For instance it's not surprising that Tru64 @command{make} doesn't 20060protect @code{SHELL}, since it doesn't use it. 20061 20062@example 20063$ @kbd{cat Makefile} 20064SHELL = /bin/sh 20065FOO = foo 20066all: 20067 @@echo $(SHELL) 20068 @@echo $(FOO) 20069$ @kbd{env SHELL=/bin/tcsh FOO=bar make -e} # Tru64 Make 20070/bin/tcsh 20071bar 20072$ @kbd{env SHELL=/bin/tcsh FOO=bar gmake -e} # GNU make 20073/bin/sh 20074bar 20075@end example 20076 20077Conversely, @command{make} is not supposed to export any changes to the 20078macro @code{SHELL} to child processes. Again, many implementations 20079break this rule: 20080 20081@example 20082$ @kbd{cat Makefile} 20083all: 20084 @@echo $(SHELL) 20085 @@printenv SHELL 20086$ @kbd{env SHELL=sh make -e SHELL=/bin/ksh} # BSD Make, GNU make 3.80 20087/bin/ksh 20088/bin/ksh 20089$ @kbd{env SHELL=sh gmake -e SHELL=/bin/ksh} # GNU make 3.81 20090/bin/ksh 20091sh 20092@end example 20093 20094@node Parallel Make 20095@section Parallel Make 20096@cindex Parallel @command{make} 20097 20098Support for parallel execution in @command{make} implementation varies. 20099Generally, using GNU make is your best bet. 20100 20101When NetBSD or FreeBSD @command{make} are run in parallel mode, they will 20102reuse the same shell for multiple commands within one recipe. This can 20103have various unexpected consequences. For example, changes of directories 20104or variables persist between recipes, so that: 20105 20106@example 20107all: 20108 @@var=value; cd /; pwd; echo $$var; echo $$$$ 20109 @@pwd; echo $$var; echo $$$$ 20110@end example 20111 20112@noindent 20113may output the following with @code{make -j1}, at least on NetBSD up to 201145.1 and FreeBSD up to 8.2: 20115 20116@example 20117/ 20118value 2011932235 20120/ 20121value 2012232235 20123@end example 20124 20125@noindent 20126while without @option{-j1}, or with @option{-B}, the output looks less 20127surprising: 20128 20129@example 20130/ 20131value 2013232238 20133/tmp 20134 2013532239 20136@end example 20137 20138@noindent 20139Another consequence is that, if one command in a recipe uses @code{exit 0} 20140to indicate a successful exit, the shell will be gone and the remaining 20141commands of this recipe will not be executed. 20142 20143The BSD @command{make} implementations, when run in parallel mode, 20144will also pass the @command{Makefile} recipes to the shell through 20145its standard input, thus making it unusable from the recipes: 20146 20147@example 20148$ @kbd{cat Makefile} 20149read: 20150 @@read line; echo LINE: $$line 20151@c $$ @c restore font-lock 20152$ @kbd{echo foo | make read} 20153LINE: foo 20154$ @kbd{echo foo | make -j1 read} # NetBSD 5.1 and FreeBSD 8.2 20155LINE: 20156@end example 20157 20158@noindent 20159Moreover, when FreeBSD @command{make} (up at least to 8.2) is run in 20160parallel mode, it implements the @code{@@} and @code{-} ``recipe 20161modifiers'' by dynamically modifying the active shell flags. This 20162behavior has the effects of potentially clobbering the exit status 20163of recipes silenced with the @code{@@} modifier if they also unset 20164the @option{errexit} shell flag, and of mangling the output in 20165unexpected ways: 20166 20167@example 20168$ @kbd{cat Makefile} 20169a: 20170 @@echo $$-; set +e; false 20171b: 20172 -echo $$-; false; echo set - 20173$ @kbd{make a; echo status: $?} 20174ehBc 20175*** Error code 1 20176status: 1 20177$ @kbd{make -j1 a; echo status: $?} 20178ehB 20179status: 0 20180$ @kbd{make b} 20181echo $-; echo set - 20182hBc 20183set - 20184$ @kbd{make -j1 b} 20185echo $-; echo hvB 20186@end example 20187 20188@noindent 20189You can avoid all these issues by using the @option{-B} option to enable 20190compatibility semantics. However, that will effectively also disable 20191all parallelism as that will cause prerequisites to be updated in the 20192order they are listed in a rule. 20193 20194Some make implementations (among them, FreeBSD @command{make}, NetBSD 20195@command{make}, and Solaris @command{dmake}), when invoked with a 20196@option{-j@var{N}} option, connect the standard output and standard 20197error of all their child processes to pipes or temporary regular 20198files. This can lead to subtly different semantics in the behavior 20199of the spawned processes. For example, even if the @command{make} 20200standard output is connected to a tty, the recipe command will not be: 20201 20202@example 20203$ @kbd{cat Makefile} 20204all: 20205 @@test -t 1 && echo "Is a tty" || echo "Is not a tty" 20206$ @kbd{make -j 2} # FreeBSD 8.2 make 20207Is not a tty 20208$ @kbd{make -j 2} # NetBSD 5.1 make 20209--- all --- 20210Is not a tty 20211$ @kbd{dmake -j 2} # Solaris 10 dmake 20212@var{hostname} --> 1 job 20213@var{hostname} --> Job output 20214Is not a tty 20215@end example 20216 20217@noindent 20218On the other hand: 20219 20220@example 20221$ @kbd{make -j 2} # GNU make, Heirloom make 20222Is a tty 20223@end example 20224 20225@noindent 20226The above examples also show additional status output produced in parallel 20227mode for targets being updated by Solaris @command{dmake} and NetBSD 20228@command{make} (but @emph{not} by FreeBSD @command{make}). 20229 20230Furthermore, parallel runs of those @command{make} implementations will 20231route standard error from commands that they spawn into their own 20232standard output, and may remove leading whitespace from output lines. 20233 20234 20235@node Comments in Make Rules 20236@section Comments in Make Rules 20237@cindex Comments in @file{Makefile} rules 20238@cindex @file{Makefile} rules and comments 20239 20240Never put comments in a rule. 20241 20242Some @command{make} treat anything starting with a tab as a command for 20243the current rule, even if the tab is immediately followed by a @code{#}. 20244The @command{make} from Tru64 Unix V5.1 is one of them. The following 20245makefile runs @code{# foo} through the shell. 20246 20247@example 20248all: 20249 # foo 20250@end example 20251 20252As a workaround, you can use the @command{:} no-op command with a string 20253argument that gets ignored: 20254 20255@example 20256all: 20257 : "foo" 20258@end example 20259 20260Conversely, if you want to use the @samp{#} character in some command, 20261you can only do so by expanding it inside a rule (@pxref{Comments in 20262Make Macros}). So for example, if @samp{COMMENT_CHAR} is substituted by 20263@command{config.status} as @samp{#}, then the following substitutes 20264@samp{@@COMMENT_CHAR@@} in a generated header: 20265 20266@example 20267foo.h: foo.h.in 20268 sed -e 's|@@''COMMENT_CHAR''@@|@@COMMENT_CHAR@@|g' \ 20269 $(srcdir)/foo.h.in > $@@ 20270@end example 20271 20272The funny shell quoting avoids a substitution at @command{config.status} 20273run time of the left-hand side of the @command{sed} @samp{s} command. 20274 20275@node Newlines in Make Rules 20276@section Newlines in Make Rules 20277@cindex Newlines in @file{Makefile} rules 20278@cindex @file{Makefile} rules and newlines 20279 20280In shell scripts, newlines can be used inside string literals. But in 20281the shell statements of @file{Makefile} rules, this is not possible: 20282A newline not preceded by a backslash is a separator between shell 20283statements. Whereas a newline that is preceded by a backslash becomes 20284part of the shell statement according to POSIX, but gets replaced, 20285together with the backslash that precedes it, by a space in GNU 20286@command{make} 3.80 and older. So, how can a newline be used in a string 20287literal? 20288 20289The trick is to set up a shell variable that contains a newline: 20290 20291@example 20292nlinit=`echo 'nl="'; echo '"'`; eval "$$nlinit" 20293@end example 20294 20295For example, in order to create a multiline @samp{sed} expression that 20296inserts a blank line after every line of a file, this code can be used: 20297 20298@example 20299nlinit=`echo 'nl="'; echo '"'`; eval "$$nlinit"; \ 20300sed -e "s/\$$/\\$$@{nl@}/" < input > output 20301@end example 20302 20303@node Comments in Make Macros 20304@section Comments in Make Macros 20305@cindex Comments in @file{Makefile} macros 20306@cindex @file{Makefile} macros and comments 20307 20308Avoid putting comments in macro values as far as possible. Posix 20309specifies that the text starting from the @samp{#} sign until the end of 20310the line is to be ignored, which has the unfortunate effect of 20311disallowing them even within quotes. Thus, the following might lead to 20312a syntax error at compile time: 20313 20314@example 20315CPPFLAGS = "-DCOMMENT_CHAR='#'" 20316@end example 20317 20318@noindent 20319as @samp{CPPFLAGS} may be expanded to @samp{"-DCOMMENT_CHAR='}. 20320 20321Most @command{make} implementations disregard this and treat single and 20322double quotes specially here. Also, GNU @command{make} lets you put 20323@samp{#} into a macro value by escaping it with a backslash, i.e., 20324@samp{\#}. However, neither of these usages are portable. 20325@xref{Comments in Make Rules}, for a portable alternative. 20326 20327Even without quoting involved, comments can have surprising effects, 20328because the whitespace before them is part of the variable value: 20329 20330@example 20331foo = bar # trailing comment 20332print: ; @@echo "$(foo)." 20333@end example 20334 20335@noindent 20336prints @samp{bar .}, which is usually not intended, and can expose 20337@command{make} bugs as described below. 20338 20339@node Trailing whitespace in Make Macros 20340@section Trailing whitespace in Make Macros 20341@cindex whitespace in @file{Makefile} macros 20342@cindex @file{Makefile} macros and whitespace 20343 20344GNU @command{make} 3.80 mistreats trailing whitespace in macro 20345substitutions and appends another spurious suffix: 20346 20347@example 20348empty = 20349foo = bar $(empty) 20350print: ; @@echo $(foo:=.test) 20351@end example 20352 20353@noindent 20354prints @samp{bar.test .test}. 20355 20356BSD and Solaris @command{make} implementations do not honor trailing 20357whitespace in macro definitions as Posix requires: 20358 20359@example 20360foo = bar # Note the space after "bar". 20361print: ; @@echo $(foo)t 20362@end example 20363 20364@noindent 20365prints @samp{bart} instead of @samp{bar t}. To work around this, you 20366can use a helper macro as in the previous example. 20367 20368 20369@node Command-line Macros and whitespace 20370@section Command-line Macros and whitespace 20371@cindex whitespace in command-line macros 20372@cindex command-line, macros set on 20373@cindex environment, macros set from 20374 20375Some @command{make} implementations may strip trailing whitespace off 20376of macros set on the command line in addition to leading whitespace. 20377Further, some may strip leading whitespace off of macros set from 20378environment variables: 20379 20380@example 20381$ @kbd{echo 'print: ; @@echo "x$(foo)x$(bar)x"' | 20382 foo=' f f ' make -f - bar=' b b '} 20383x f f xb b x # AIX, BSD, GNU make 20384xf f xb b x # HP-UX, IRIX, Tru64/OSF make 20385x f f xb bx # Solaris make 20386@end example 20387 20388 20389@node obj/ and Make 20390@section The @file{obj/} Subdirectory and Make 20391@cindex @file{obj/}, subdirectory 20392@cindex BSD @command{make} and @file{obj/} 20393 20394Never name one of your subdirectories @file{obj/} if you don't like 20395surprises. 20396 20397If an @file{obj/} directory exists, BSD @command{make} enters it 20398before reading the makefile. Hence the makefile in the 20399current directory is not read. 20400 20401@example 20402$ @kbd{cat Makefile} 20403all: 20404 echo Hello 20405$ @kbd{cat obj/Makefile} 20406all: 20407 echo World 20408$ @kbd{make} # GNU make 20409echo Hello 20410Hello 20411$ @kbd{pmake} # BSD make 20412echo World 20413World 20414@end example 20415 20416@node make -k Status 20417@section Exit Status of @code{make -k} 20418@cindex @code{make -k} 20419 20420Do not rely on the exit status of @code{make -k}. Some implementations 20421reflect whether they encountered an error in their exit status; other 20422implementations always succeed. 20423 20424@example 20425$ @kbd{cat Makefile} 20426all: 20427 false 20428$ @kbd{make -k; echo exit status: $?} # GNU make 20429false 20430make: *** [all] Error 1 20431exit status: 2 20432$ @kbd{pmake -k; echo exit status: $?} # BSD make 20433false 20434*** Error code 1 (continuing) 20435exit status: 0 20436@end example 20437 20438@node VPATH and Make 20439@section @code{VPATH} and Make 20440@cindex @code{VPATH} 20441 20442Posix does not specify the semantics of @code{VPATH}. Typically, 20443@command{make} supports @code{VPATH}, but its implementation is not 20444consistent. 20445 20446Autoconf and Automake support makefiles whose usages of @code{VPATH} are 20447portable to recent-enough popular implementations of @command{make}, but 20448to keep the resulting makefiles portable, a package's makefile 20449prototypes must take the following issues into account. These issues 20450are complicated and are often poorly understood, and installers who use 20451@code{VPATH} should expect to find many bugs in this area. If you use 20452@code{VPATH}, the simplest way to avoid these portability bugs is to 20453stick with GNU @command{make}, since it is the most 20454commonly-used @command{make} among Autoconf users. 20455 20456Here are some known issues with some @code{VPATH} 20457implementations. 20458 20459@menu 20460* Variables listed in VPATH:: @code{VPATH} must be literal on ancient hosts 20461* VPATH and Double-colon:: Problems with @samp{::} on ancient hosts 20462* $< in Explicit Rules:: @code{$<} does not work in ordinary rules 20463* Automatic Rule Rewriting:: @code{VPATH} goes wild on Solaris 20464* Tru64 Directory Magic:: @command{mkdir} goes wild on Tru64 20465* Make Target Lookup:: More details about @code{VPATH} lookup 20466@end menu 20467 20468@node Variables listed in VPATH 20469@subsection Variables listed in @code{VPATH} 20470@cindex @code{VPATH} and variables 20471@cindex variables and @code{VPATH} 20472 20473Do not set @code{VPATH} to the value of another variable, for example 20474@samp{VPATH = $(srcdir)}, because some ancient versions of 20475@command{make} do not do variable substitutions on the value of 20476@code{VPATH}. For example, use this 20477 20478@example 20479srcdir = @@srcdir@@ 20480VPATH = @@srcdir@@ 20481@end example 20482 20483@noindent 20484rather than @samp{VPATH = $(srcdir)}. Note that with GNU 20485Automake, there is no need to set this yourself. 20486 20487@node VPATH and Double-colon 20488@subsection @code{VPATH} and Double-colon Rules 20489@cindex @code{VPATH} and double-colon rules 20490@cindex double-colon rules and @code{VPATH} 20491 20492With ancient versions of Sun @command{make}, 20493any assignment to @code{VPATH} causes @command{make} to execute only 20494the first set of double-colon rules. 20495However, this problem is no longer of practical concern. 20496 20497@node $< in Explicit Rules 20498@subsection @code{$<} Not Supported in Explicit Rules 20499@cindex explicit rules, @code{$<}, and @code{VPATH} 20500@cindex @code{$<}, explicit rules, and @code{VPATH} 20501@cindex @code{VPATH}, explicit rules, and @code{$<} 20502 20503Using @code{$<} in explicit rules is not portable. 20504The prerequisite file must be named explicitly in the rule. If you want 20505to find the prerequisite via a @code{VPATH} search, you have to code the 20506whole thing manually. @xref{Build Directories}. 20507 20508@node Automatic Rule Rewriting 20509@subsection Automatic Rule Rewriting 20510@cindex @code{VPATH} and automatic rule rewriting 20511@cindex automatic rule rewriting and @code{VPATH} 20512 20513Some @command{make} implementations, such as Solaris and Tru64, 20514search for prerequisites in @code{VPATH} and 20515then rewrite each occurrence as a plain word in the rule. 20516For instance: 20517 20518@example 20519# This isn't portable to GNU make. 20520VPATH = ../pkg/src 20521f.c: if.c 20522 cp if.c f.c 20523@end example 20524 20525@noindent 20526executes @code{cp ../pkg/src/if.c f.c} if @file{if.c} is 20527found in @file{../pkg/src}. 20528 20529However, this rule leads to real problems in practice. For example, if 20530the source directory contains an ordinary file named @file{test} that is 20531used in a dependency, Solaris @command{make} rewrites commands like 20532@samp{if test -r foo; @dots{}} to @samp{if ../pkg/src/test -r foo; 20533@dots{}}, which is typically undesirable. In fact, @command{make} is 20534completely unaware of shell syntax used in the rules, so the VPATH 20535rewrite can potentially apply to @emph{any} whitespace-separated word 20536in a rule, including shell variables, functions, and keywords. 20537 20538@example 20539$ @kbd{mkdir build} 20540$ @kbd{cd build} 20541$ @kbd{cat > Makefile <<'END'} 20542VPATH = .. 20543all: arg func for echo 20544 func () @{ for arg in "$$@@"; do echo $$arg; done; @}; \ 20545 func "hello world" 20546END 20547$ @kbd{touch ../arg ../func ../for ../echo} 20548$ @kbd{make} 20549../func () @{ ../for ../arg in "$@@"; do ../echo $arg; done; @}; \ 20550../func "hello world" 20551sh: syntax error at line 1: `do' unexpected 20552*** Error code 2 20553@end example 20554 20555@noindent 20556To avoid this problem, portable makefiles should never mention a source 20557file or dependency whose name is that of a shell keyword like @file{for} 20558or @file{until}, a shell command like @command{cat} or @command{gcc} or 20559@command{test}, or a shell function or variable used in the corresponding 20560@command{Makefile} recipe. 20561 20562Because of these problems GNU @command{make} and many other @command{make} 20563implementations do not rewrite commands, so portable makefiles should 20564search @code{VPATH} manually. It is tempting to write this: 20565 20566@smallexample 20567# This isn't portable to Solaris make. 20568VPATH = ../pkg/src 20569f.c: if.c 20570 cp `test -f if.c || echo $(VPATH)/`if.c f.c 20571@end smallexample 20572 20573@noindent 20574However, the ``prerequisite rewriting'' still applies here. So if 20575@file{if.c} is in @file{../pkg/src}, Solaris and Tru64 @command{make} 20576execute 20577 20578@smallexample 20579cp `test -f ../pkg/src/if.c || echo ../pkg/src/`if.c f.c 20580@end smallexample 20581 20582@noindent 20583which reduces to 20584 20585@example 20586cp if.c f.c 20587@end example 20588 20589@noindent 20590and thus fails. Oops. 20591 20592A simple workaround, and good practice anyway, is to use @samp{$?} and 20593@samp{$@@} when possible: 20594 20595@smallexample 20596VPATH = ../pkg/src 20597f.c: if.c 20598 cp $? $@@ 20599@end smallexample 20600 20601@noindent 20602but this does not generalize well to commands with multiple 20603prerequisites. A more general workaround is to rewrite the rule so that 20604the prerequisite @file{if.c} never appears as a plain word. For 20605example, these three rules would be safe, assuming @file{if.c} is in 20606@file{../pkg/src} and the other files are in the working directory: 20607 20608@smallexample 20609VPATH = ../pkg/src 20610f.c: if.c f1.c 20611 cat `test -f ./if.c || echo $(VPATH)/`if.c f1.c >$@@ 20612g.c: if.c g1.c 20613 cat `test -f 'if.c' || echo $(VPATH)/`if.c g1.c >$@@ 20614h.c: if.c h1.c 20615 cat `test -f "if.c" || echo $(VPATH)/`if.c h1.c >$@@ 20616@end smallexample 20617 20618Things get worse when your prerequisites are in a macro. 20619 20620@example 20621VPATH = ../pkg/src 20622HEADERS = f.h g.h h.h 20623install-HEADERS: $(HEADERS) 20624 for i in $(HEADERS); do \ 20625 $(INSTALL) -m 644 \ 20626 `test -f $$i || echo $(VPATH)/`$$i \ 20627 $(DESTDIR)$(includedir)/$$i; \ 20628@c $$ restore font-lock 20629 done 20630@end example 20631 20632The above @code{install-HEADERS} rule is not Solaris-proof because @code{for 20633i in $(HEADERS);} is expanded to @code{for i in f.h g.h h.h;} 20634where @code{f.h} and @code{g.h} are plain words and are hence 20635subject to @code{VPATH} adjustments. 20636 20637If the three files are in @file{../pkg/src}, the rule is run as: 20638 20639@example 20640for i in ../pkg/src/f.h ../pkg/src/g.h h.h; do \ 20641 install -m 644 \ 20642 `test -f $i || echo ../pkg/src/`$i \ 20643 /usr/local/include/$i; \ 20644done 20645@end example 20646 20647where the two first @command{install} calls fail. For instance, 20648consider the @code{f.h} installation: 20649 20650@example 20651install -m 644 \ 20652 `test -f ../pkg/src/f.h || \ 20653 echo ../pkg/src/ \ 20654 `../pkg/src/f.h \ 20655 /usr/local/include/../pkg/src/f.h; 20656@end example 20657 20658@noindent 20659It reduces to: 20660 20661@example 20662install -m 644 \ 20663 ../pkg/src/f.h \ 20664 /usr/local/include/../pkg/src/f.h; 20665@end example 20666 20667Note that the manual @code{VPATH} search did not cause any problems here; 20668however this command installs @file{f.h} in an incorrect directory. 20669 20670Trying to quote @code{$(HEADERS)} in some way, as we did for 20671@code{foo.c} a few makefiles ago, does not help: 20672 20673@example 20674install-HEADERS: $(HEADERS) 20675 headers='$(HEADERS)'; \ 20676 for i in $$headers; do \ 20677 $(INSTALL) -m 644 \ 20678 `test -f $$i || echo $(VPATH)/`$$i \ 20679 $(DESTDIR)$(includedir)/$$i; \ 20680 done 20681@end example 20682 20683Now, @code{headers='$(HEADERS)'} macro-expands to: 20684 20685@example 20686headers='f.h g.h h.h' 20687@end example 20688 20689@noindent 20690but @code{g.h} is still a plain word. (As an aside, the idiom 20691@code{headers='$(HEADERS)'; for i in $$headers;} is a good 20692idea if @code{$(HEADERS)} can be empty, because some shells diagnose a 20693syntax error on @code{for i in;}.) 20694 20695One workaround is to strip this unwanted @file{../pkg/src/} prefix manually: 20696 20697@example 20698VPATH = ../pkg/src 20699HEADERS = f.h g.h h.h 20700install-HEADERS: $(HEADERS) 20701 headers='$(HEADERS)'; \ 20702 for i in $$headers; do \ 20703 i=`expr "$$i" : '$(VPATH)/\(.*\)'`; 20704 $(INSTALL) -m 644 \ 20705 `test -f $$i || echo $(VPATH)/`$$i \ 20706 $(DESTDIR)$(includedir)/$$i; \ 20707@c $$ restore font-lock 20708 done 20709@end example 20710 20711Automake does something similar. However the above hack works only if 20712the files listed in @code{HEADERS} are in the current directory or a 20713subdirectory; they should not be in an enclosing directory. If we had 20714@code{HEADERS = ../f.h}, the above fragment would fail in a VPATH 20715build with Tru64 @command{make}. The reason is that not only does 20716Tru64 @command{make} rewrite dependencies, but it also simplifies 20717them. Hence @code{../f.h} becomes @code{../pkg/f.h} instead of 20718@code{../pkg/src/../f.h}. This obviously defeats any attempt to strip 20719a leading @file{../pkg/src/} component. 20720 20721The following example makes the behavior of Tru64 @command{make} 20722more apparent. 20723 20724@example 20725$ @kbd{cat Makefile} 20726VPATH = sub 20727all: ../foo 20728 echo ../foo 20729$ @kbd{ls} 20730Makefile foo 20731$ @kbd{make} 20732echo foo 20733foo 20734@end example 20735 20736@noindent 20737Dependency @file{../foo} was found in @file{sub/../foo}, but Tru64 20738@command{make} simplified it as @file{foo}. (Note that the @file{sub/} 20739directory does not even exist, this just means that the simplification 20740occurred before the file was checked for.) 20741 20742For the record here is how SunOS 4 @command{make} behaves on this 20743example. 20744 20745@smallexample 20746$ @kbd{make} 20747make: Fatal error: Don't know how to make target `../foo' 20748$ @kbd{mkdir sub} 20749$ @kbd{make} 20750echo sub/../foo 20751sub/../foo 20752@end smallexample 20753 20754 20755@node Tru64 Directory Magic 20756@subsection Tru64 @command{make} Creates Prerequisite Directories Magically 20757@cindex @code{VPATH} and prerequisite directories 20758@cindex prerequisite directories and @code{VPATH} 20759 20760When a prerequisite is a subdirectory of @code{VPATH}, Tru64 20761@command{make} creates it in the current directory. 20762 20763@example 20764$ @kbd{mkdir -p foo/bar build} 20765$ @kbd{cd build} 20766$ @kbd{cat >Makefile <<END 20767VPATH = .. 20768all: foo/bar 20769END} 20770$ @kbd{make} 20771mkdir foo 20772mkdir foo/bar 20773@end example 20774 20775This can yield unexpected results if a rule uses a manual @code{VPATH} 20776search as presented before. 20777 20778@example 20779VPATH = .. 20780all : foo/bar 20781 command `test -d foo/bar || echo ../`foo/bar 20782@end example 20783 20784The above @command{command} is run on the empty @file{foo/bar} 20785directory that was created in the current directory. 20786 20787@node Make Target Lookup 20788@subsection Make Target Lookup 20789@cindex @code{VPATH}, resolving target pathnames 20790 20791GNU @command{make} uses a complex algorithm to decide when it 20792should use files found via a @code{VPATH} search. @xref{Search 20793Algorithm, , How Directory Searches are Performed, make, The GNU Make 20794Manual}. 20795 20796If a target needs to be rebuilt, GNU @command{make} discards the 20797file name found during the @code{VPATH} search for this target, and 20798builds the file locally using the file name given in the makefile. 20799If a target does not need to be rebuilt, GNU @command{make} uses the 20800file name found during the @code{VPATH} search. 20801 20802Other @command{make} implementations, like NetBSD @command{make}, are 20803easier to describe: the file name found during the @code{VPATH} search 20804is used whether the target needs to be rebuilt or not. Therefore 20805new files are created locally, but existing files are updated at their 20806@code{VPATH} location. 20807 20808OpenBSD and FreeBSD @command{make}, however, 20809never perform a 20810@code{VPATH} search for a dependency that has an explicit rule. 20811This is extremely annoying. 20812 20813When attempting a @code{VPATH} build for an autoconfiscated package 20814(e.g., @code{mkdir build && cd build && ../configure}), this means 20815GNU 20816@command{make} builds everything locally in the @file{build} 20817directory, while BSD @command{make} builds new files locally and 20818updates existing files in the source directory. 20819 20820@example 20821$ @kbd{cat Makefile} 20822VPATH = .. 20823all: foo.x bar.x 20824foo.x bar.x: newer.x 20825 @@echo Building $@@ 20826$ @kbd{touch ../bar.x} 20827$ @kbd{touch ../newer.x} 20828$ @kbd{make} # GNU make 20829Building foo.x 20830Building bar.x 20831$ @kbd{pmake} # NetBSD make 20832Building foo.x 20833Building ../bar.x 20834$ @kbd{fmake} # FreeBSD make, OpenBSD make 20835Building foo.x 20836Building bar.x 20837$ @kbd{tmake} # Tru64 make 20838Building foo.x 20839Building bar.x 20840$ @kbd{touch ../bar.x} 20841$ @kbd{make} # GNU make 20842Building foo.x 20843$ @kbd{pmake} # NetBSD make 20844Building foo.x 20845$ @kbd{fmake} # FreeBSD make, OpenBSD make 20846Building foo.x 20847Building bar.x 20848$ @kbd{tmake} # Tru64 make 20849Building foo.x 20850Building bar.x 20851@end example 20852 20853Note how NetBSD @command{make} updates @file{../bar.x} in its 20854VPATH location, and how FreeBSD, OpenBSD, and Tru64 20855@command{make} always 20856update @file{bar.x}, even when @file{../bar.x} is up to date. 20857 20858Another point worth mentioning is that once GNU @command{make} has 20859decided to ignore a @code{VPATH} file name (e.g., it ignored 20860@file{../bar.x} in the above example) it continues to ignore it when 20861the target occurs as a prerequisite of another rule. 20862 20863The following example shows that GNU @command{make} does not look up 20864@file{bar.x} in @code{VPATH} before performing the @code{.x.y} rule, 20865because it ignored the @code{VPATH} result of @file{bar.x} while running 20866the @code{bar.x: newer.x} rule. 20867 20868@example 20869$ @kbd{cat Makefile} 20870VPATH = .. 20871all: bar.y 20872bar.x: newer.x 20873 @@echo Building $@@ 20874.SUFFIXES: .x .y 20875.x.y: 20876 cp $< $@@ 20877$ @kbd{touch ../bar.x} 20878$ @kbd{touch ../newer.x} 20879$ @kbd{make} # GNU make 20880Building bar.x 20881cp bar.x bar.y 20882cp: cannot stat `bar.x': No such file or directory 20883make: *** [bar.y] Error 1 20884$ @kbd{pmake} # NetBSD make 20885Building ../bar.x 20886cp ../bar.x bar.y 20887$ @kbd{rm bar.y} 20888$ @kbd{fmake} # FreeBSD make, OpenBSD make 20889echo Building bar.x 20890cp bar.x bar.y 20891cp: cannot stat `bar.x': No such file or directory 20892*** Error code 1 20893$ @kbd{tmake} # Tru64 make 20894Building bar.x 20895cp: bar.x: No such file or directory 20896*** Exit 1 20897@end example 20898 20899Note that if you drop away the command from the @code{bar.x: newer.x} 20900rule, GNU @command{make} magically starts to work: it 20901knows that @code{bar.x} hasn't been updated, therefore it doesn't 20902discard the result from @code{VPATH} (@file{../bar.x}) in succeeding 20903uses. Tru64 also works, but FreeBSD and OpenBSD 20904still don't. 20905 20906@example 20907$ @kbd{cat Makefile} 20908VPATH = .. 20909all: bar.y 20910bar.x: newer.x 20911.SUFFIXES: .x .y 20912.x.y: 20913 cp $< $@@ 20914$ @kbd{touch ../bar.x} 20915$ @kbd{touch ../newer.x} 20916$ @kbd{make} # GNU make 20917cp ../bar.x bar.y 20918$ @kbd{rm bar.y} 20919$ @kbd{pmake} # NetBSD make 20920cp ../bar.x bar.y 20921$ @kbd{rm bar.y} 20922$ @kbd{fmake} # FreeBSD make, OpenBSD make 20923cp bar.x bar.y 20924cp: cannot stat `bar.x': No such file or directory 20925*** Error code 1 20926$ @kbd{tmake} # Tru64 make 20927cp ../bar.x bar.y 20928@end example 20929 20930It seems the sole solution that would please every @command{make} 20931implementation is to never rely on @code{VPATH} searches for targets. 20932In other words, @code{VPATH} should be reserved to unbuilt sources. 20933 20934 20935@node Single Suffix Rules 20936@section Single Suffix Rules and Separated Dependencies 20937@cindex Single Suffix Inference Rule 20938@cindex Rule, Single Suffix Inference 20939A @dfn{Single Suffix Rule} is basically a usual suffix (inference) rule 20940(@samp{.from.to:}), but which @emph{destination} suffix is empty 20941(@samp{.from:}). 20942 20943@cindex Separated Dependencies 20944@dfn{Separated dependencies} simply refers to listing the prerequisite 20945of a target, without defining a rule. Usually one can list on the one 20946hand side, the rules, and on the other hand side, the dependencies. 20947 20948Solaris @command{make} does not support separated dependencies for 20949targets defined by single suffix rules: 20950 20951@example 20952$ @kbd{cat Makefile} 20953.SUFFIXES: .in 20954foo: foo.in 20955.in: 20956 cp $< $@@ 20957$ @kbd{touch foo.in} 20958$ @kbd{make} 20959$ @kbd{ls} 20960Makefile foo.in 20961@end example 20962 20963@noindent 20964while GNU Make does: 20965 20966@example 20967$ @kbd{gmake} 20968cp foo.in foo 20969$ @kbd{ls} 20970Makefile foo foo.in 20971@end example 20972 20973Note it works without the @samp{foo: foo.in} dependency. 20974 20975@example 20976$ @kbd{cat Makefile} 20977.SUFFIXES: .in 20978.in: 20979 cp $< $@@ 20980$ @kbd{make foo} 20981cp foo.in foo 20982@end example 20983 20984@noindent 20985and it works with double suffix inference rules: 20986 20987@example 20988$ @kbd{cat Makefile} 20989foo.out: foo.in 20990.SUFFIXES: .in .out 20991.in.out: 20992 cp $< $@@ 20993$ @kbd{make} 20994cp foo.in foo.out 20995@end example 20996 20997As a result, in such a case, you have to write target rules. 20998 20999@node Timestamps and Make 21000@section Timestamp Resolution and Make 21001@cindex timestamp resolution 21002Traditionally, file timestamps had 1-second resolution, and 21003@command{make} used those timestamps to determine whether one file was 21004newer than the other. However, many modern file systems have 21005timestamps with 1-nanosecond resolution. Some @command{make} 21006implementations look at the entire timestamp; others ignore the 21007fractional part, which can lead to incorrect results. Normally this 21008is not a problem, but in some extreme cases you may need to use tricks 21009like @samp{sleep 1} to work around timestamp truncation bugs. 21010 21011Commands like @samp{cp -p} and @samp{touch -r} typically do not copy 21012file timestamps to their full resolutions (@pxref{touch, , Limitations of Usual 21013Tools}). Hence you should be wary of rules like this: 21014 21015@example 21016dest: src 21017 cp -p src dest 21018@end example 21019 21020as @file{dest} often appears to be older than @file{src} after the 21021timestamp is truncated, and this can cause @command{make} to do 21022needless rework the next time it is invoked. To work around this 21023problem, you can use a timestamp file, e.g.: 21024 21025@example 21026dest-stamp: src 21027 cp -p src dest 21028 date >dest-stamp 21029@end example 21030 21031Apart from timestamp resolution, there are also differences in handling 21032equal timestamps. HP-UX @command{make} updates targets if it has the 21033same time stamp as one of its prerequisites, in violation of Posix rules. 21034 21035This can cause spurious rebuilds for repeated runs of @command{make}. 21036This in turn can cause @command{make} to fail if it tries to rebuild 21037generated files in a possibly read-only source tree with tools not 21038present on the end-user machine. Use GNU @command{make} instead. 21039 21040 21041 21042@c ======================================== Portable C and C++ Programming 21043 21044@node Portable C and C++ 21045@chapter Portable C and C++ Programming 21046@cindex Portable C and C++ programming 21047 21048C and C++ programs often use low-level features of the underlying 21049system, and therefore are often more difficult to make portable to other 21050platforms. 21051 21052Several standards have been developed to help make your programs more 21053portable. If you write programs with these standards in mind, you can 21054have greater confidence that your programs work on a wide variety 21055of systems. 21056@ifhtml 21057@uref{http://@/gcc.gnu.org/@/onlinedocs/@/gcc/@/Standards.html, Language 21058Standards Supported by GCC} 21059@end ifhtml 21060@ifnothtml 21061@xref{Standards, , Language Standards Supported by 21062GCC, gcc, Using the GNU Compiler Collection 21063(GCC)}, 21064@end ifnothtml 21065for a list of C-related standards. Many programs also assume the 21066@uref{http://@/www.opengroup.org/@/susv3, Posix standard}. 21067 21068Some old code is written to be portable to K&R C, which predates any C 21069standard. K&R C compilers are no longer of practical interest, though, 21070and the rest of section assumes at least C89, the first C standard. 21071 21072Program portability is a huge topic, and this section can only briefly 21073introduce common pitfalls. @xref{System Portability, , Portability 21074between System Types, standards, The GNU Coding Standards}, for 21075more information. 21076 21077@menu 21078* Varieties of Unportability:: How to make your programs unportable 21079* Integer Overflow:: When integers get too large 21080* Preprocessor Arithmetic:: @code{#if} expression problems 21081* Null Pointers:: Properties of null pointers 21082* Buffer Overruns:: Subscript errors and the like 21083* Volatile Objects:: @code{volatile} and signals 21084* Floating Point Portability:: Portable floating-point arithmetic 21085* Exiting Portably:: Exiting and the exit status 21086@end menu 21087 21088@node Varieties of Unportability 21089@section Varieties of Unportability 21090@cindex portability 21091 21092Autoconf tests and ordinary programs often need to test what is allowed 21093on a system, and therefore they may need to deliberately exceed the 21094boundaries of what the standards allow, if only to see whether an 21095optional feature is present. When you write such a program, you should 21096keep in mind the difference between constraints, unspecified behavior, 21097and undefined behavior. 21098 21099In C, a @dfn{constraint} is a rule that the compiler must enforce. An 21100example constraint is that C programs must not declare a bit-field with 21101negative width. Tests can therefore reliably assume that programs with 21102negative-width bit-fields are rejected by a compiler that conforms 21103to the standard. 21104 21105@dfn{Unspecified behavior} is valid behavior, where the standard allows 21106multiple possibilities. For example, the order of evaluation of 21107function arguments is unspecified. Some unspecified behavior is 21108@dfn{implementation-defined}, i.e., documented by the implementation, 21109but since Autoconf tests cannot read the documentation they cannot 21110distinguish between implementation-defined and other unspecified 21111behavior. It is common for Autoconf tests to probe implementations to 21112determine otherwise-unspecified behavior. 21113 21114@dfn{Undefined behavior} is invalid behavior, where the standard allows 21115the implementation to do anything it pleases. For example, 21116dereferencing a null pointer leads to undefined behavior. If possible, 21117test programs should avoid undefined behavior, since a program with 21118undefined behavior might succeed on a test that should fail. 21119 21120The above rules apply to programs that are intended to conform to the 21121standard. However, strictly-conforming programs are quite rare, since 21122the standards are so limiting. A major goal of Autoconf is to support 21123programs that use implementation features not described by the standard, 21124and it is fairly common for test programs to violate the above rules, if 21125the programs work well enough in practice. 21126 21127@node Integer Overflow 21128@section Integer Overflow 21129@cindex integer overflow 21130@cindex overflow, signed integer 21131@cindex signed integer overflow 21132@cindex wraparound arithmetic 21133 21134In practice many portable C programs assume that signed integer overflow wraps 21135around reliably using two's complement arithmetic. Yet the C standard 21136says that program behavior is undefined on overflow, and in a few cases 21137C programs do not work on some modern implementations because their 21138overflows do not wrap around as their authors expected. Conversely, in 21139signed integer remainder, the C standard requires overflow 21140behavior that is commonly not implemented. 21141 21142@menu 21143* Integer Overflow Basics:: Why integer overflow is a problem 21144* Signed Overflow Examples:: Examples of code assuming wraparound 21145* Optimization and Wraparound:: Optimizations that break uses of wraparound 21146* Signed Overflow Advice:: Practical advice for signed overflow issues 21147* Signed Integer Division:: @code{INT_MIN / -1} and @code{INT_MIN % -1} 21148@end menu 21149 21150@node Integer Overflow Basics 21151@subsection Basics of Integer Overflow 21152@cindex integer overflow 21153@cindex overflow, signed integer 21154@cindex signed integer overflow 21155@cindex wraparound arithmetic 21156 21157In languages like C, unsigned integer overflow reliably wraps around; 21158e.g., @code{UINT_MAX + 1} yields zero. 21159This is guaranteed by the C standard and is 21160portable in practice, unless you specify aggressive, 21161nonstandard optimization options 21162suitable only for special applications. 21163 21164In contrast, the C standard says that signed integer overflow leads to 21165undefined behavior where a program can do anything, including dumping 21166core or overrunning a buffer. The misbehavior can even precede the 21167overflow. Such an overflow can occur during addition, subtraction, 21168multiplication, division, and left shift. 21169 21170Despite this requirement of the standard, many C programs and Autoconf 21171tests assume that signed integer overflow silently wraps around modulo a 21172power of two, using two's complement arithmetic, so long as you cast the 21173resulting value to a signed integer type or store it into a signed 21174integer variable. If you use conservative optimization flags, such 21175programs are generally portable to the vast majority of modern 21176platforms, with a few exceptions discussed later. 21177 21178For historical reasons the C standard also allows implementations with 21179ones' complement or signed magnitude arithmetic, but it is safe to 21180assume two's complement nowadays. 21181 21182Also, overflow can occur when converting an out-of-range value to a 21183signed integer type. Here a standard implementation must define what 21184happens, but this might include raising an exception. In practice all 21185known implementations support silent wraparound in this case, so you need 21186not worry about other possibilities. 21187 21188@node Signed Overflow Examples 21189@subsection Examples of Code Assuming Wraparound Overflow 21190@cindex integer overflow 21191@cindex overflow, signed integer 21192@cindex signed integer overflow 21193@cindex wraparound arithmetic 21194 21195There has long been a tension between what the C standard requires for 21196signed integer overflow, and what C programs commonly assume. The 21197standard allows aggressive optimizations based on assumptions that 21198overflow never occurs, but many practical C programs rely on overflow 21199wrapping around. These programs do not conform to the standard, but 21200they commonly work in practice because compiler writers are 21201understandably reluctant to implement optimizations that would break 21202many programs, unless perhaps a user specifies aggressive optimization. 21203 21204The C Standard says that if a program has signed integer overflow its 21205behavior is undefined, and the undefined behavior can even precede the 21206overflow. To take an extreme example: 21207 21208@c Inspired by Robert Dewar's example in 21209@c <http://gcc.gnu.org/ml/gcc/2007-01/msg00038.html> (2007-01-01). 21210@example 21211if (password == expected_password) 21212 allow_superuser_privileges (); 21213else if (counter++ == INT_MAX) 21214 abort (); 21215else 21216 printf ("%d password mismatches\n", counter); 21217@end example 21218 21219@noindent 21220If the @code{int} variable @code{counter} equals @code{INT_MAX}, 21221@code{counter++} must overflow and the behavior is undefined, so the C 21222standard allows the compiler to optimize away the test against 21223@code{INT_MAX} and the @code{abort} call. 21224Worse, if an earlier bug in the program lets the compiler deduce that 21225@code{counter == INT_MAX} or that @code{counter} previously overflowed, 21226the C standard allows the compiler to optimize away the password test 21227and generate code that allows superuser privileges unconditionally. 21228 21229Despite this requirement by the standard, it has long been common for C 21230code to assume wraparound arithmetic after signed overflow, and all 21231known practical C implementations support some C idioms that assume 21232wraparound signed arithmetic, even if the idioms do not conform 21233strictly to the standard. If your code looks like the following 21234examples it will almost surely work with real-world compilers. 21235 21236Here is an example derived from the 7th Edition Unix implementation of 21237@code{atoi} (1979-01-10): 21238 21239@example 21240char *p; 21241int f, n; 21242@dots{} 21243while (*p >= '0' && *p <= '9') 21244 n = n * 10 + *p++ - '0'; 21245return (f ? -n : n); 21246@end example 21247 21248@noindent 21249Even if the input string is in range, on most modern machines this has 21250signed overflow when computing the most negative integer (the @code{-n} 21251overflows) or a value near an extreme integer (the first @code{+} 21252overflows). 21253 21254Here is another example, derived from the 7th Edition implementation of 21255@code{rand} (1979-01-10). Here the programmer expects both 21256multiplication and addition to wrap on overflow: 21257 21258@example 21259static long int randx = 1; 21260@dots{} 21261randx = randx * 1103515245 + 12345; 21262return (randx >> 16) & 077777; 21263@end example 21264 21265In the following example, derived from the GNU C Library 2.5 21266implementation of @code{mktime} (2006-09-09), the code assumes 21267wraparound arithmetic in @code{+} to detect signed overflow: 21268 21269@example 21270time_t t, t1, t2; 21271int sec_requested, sec_adjustment; 21272@dots{} 21273t1 = t + sec_requested; 21274t2 = t1 + sec_adjustment; 21275if (((t1 < t) != (sec_requested < 0)) 21276 | ((t2 < t1) != (sec_adjustment < 0))) 21277 return -1; 21278@end example 21279 21280If your code looks like these examples, it is probably safe even though 21281it does not strictly conform to the C standard. This might lead one to 21282believe that one can generally assume wraparound on overflow, but that 21283is not always true, as can be seen in the next section. 21284 21285@node Optimization and Wraparound 21286@subsection Optimizations That Break Wraparound Arithmetic 21287@cindex loop induction 21288 21289Compilers sometimes generate code that is incompatible with wraparound 21290integer arithmetic. A simple example is an algebraic simplification: a 21291compiler might translate @code{(i * 2000) / 1000} to @code{i * 2} 21292because it assumes that @code{i * 2000} does not overflow. The 21293translation is not equivalent to the original when overflow occurs: 21294e.g., in the typical case of 32-bit signed two's complement wraparound 21295@code{int}, if @code{i} has type @code{int} and value @code{1073742}, 21296the original expression returns @minus{}2147483 but the optimized 21297version returns the mathematically correct value 2147484. 21298 21299More subtly, loop induction optimizations often exploit the undefined 21300behavior of signed overflow. Consider the following contrived function 21301@code{sumc}: 21302 21303@example 21304int 21305sumc (int lo, int hi) 21306@{ 21307 int sum = 0; 21308 int i; 21309 for (i = lo; i <= hi; i++) 21310 sum ^= i * 53; 21311 return sum; 21312@} 21313@end example 21314 21315@noindent 21316To avoid multiplying by 53 each time through the loop, an optimizing 21317compiler might internally transform @code{sumc} to the equivalent of the 21318following: 21319 21320@example 21321int 21322transformed_sumc (int lo, int hi) 21323@{ 21324 int sum = 0; 21325 int hic = hi * 53; 21326 int ic; 21327 for (ic = lo * 53; ic <= hic; ic += 53) 21328 sum ^= ic; 21329 return sum; 21330@} 21331@end example 21332 21333@noindent 21334This transformation is allowed by the C standard, but it is invalid for 21335wraparound arithmetic when @code{INT_MAX / 53 < hi}, because then the 21336overflow in computing expressions like @code{hi * 53} can cause the 21337expression @code{i <= hi} to yield a different value from the 21338transformed expression @code{ic <= hic}. 21339 21340For this reason, compilers that use loop induction and similar 21341techniques often do not support reliable wraparound arithmetic when a 21342loop induction variable like @code{ic} is involved. Since loop 21343induction variables are generated by the compiler, and are not visible 21344in the source code, it is not always trivial to say whether the problem 21345affects your code. 21346 21347Hardly any code actually depends on wraparound arithmetic in cases like 21348these, so in practice these loop induction optimizations are almost 21349always useful. However, edge cases in this area can cause problems. 21350For example: 21351 21352@example 21353int j; 21354for (j = 1; 0 < j; j *= 2) 21355 test (j); 21356@end example 21357 21358@noindent 21359Here, the loop attempts to iterate through all powers of 2 that 21360@code{int} can represent, but the C standard allows a compiler to 21361optimize away the comparison and generate an infinite loop, 21362under the argument that behavior is undefined on overflow. As of this 21363writing this optimization is not done by any production version of 21364GCC with @option{-O2}, but it might be performed by other 21365compilers, or by more aggressive GCC optimization options, 21366and the GCC developers have not decided whether it will 21367continue to work with GCC and @option{-O2}. 21368 21369@node Signed Overflow Advice 21370@subsection Practical Advice for Signed Overflow Issues 21371@cindex integer overflow 21372@cindex overflow, signed integer 21373@cindex signed integer overflow 21374@cindex wraparound arithmetic 21375 21376Ideally the safest approach is to avoid signed integer overflow 21377entirely. For example, instead of multiplying two signed integers, you 21378can convert them to unsigned integers, multiply the unsigned values, 21379then test whether the result is in signed range. 21380 21381Rewriting code in this way will be inconvenient, though, particularly if 21382the signed values might be negative. Also, it may hurt 21383performance. Using unsigned arithmetic to check for overflow is 21384particularly painful to do portably and efficiently when dealing with an 21385integer type like @code{uid_t} whose width and signedness vary from 21386platform to platform. 21387 21388Furthermore, many C applications pervasively assume wraparound behavior 21389and typically it is not easy to find and remove all these assumptions. 21390Hence it is often useful to maintain nonstandard code that assumes 21391wraparound on overflow, instead of rewriting the code. The rest of this 21392section attempts to give practical advice for this situation. 21393 21394If your code wants to detect signed integer overflow in @code{sum = a + 21395b}, it is generally safe to use an expression like @code{(sum < a) != (b 21396< 0)}. 21397 21398If your code uses a signed loop index, make sure that the index cannot 21399overflow, along with all signed expressions derived from the index. 21400Here is a contrived example of problematic code with two instances of 21401overflow. 21402 21403@example 21404for (i = INT_MAX - 10; i <= INT_MAX; i++) 21405 if (i + 1 < 0) 21406 @{ 21407 report_overflow (); 21408 break; 21409 @} 21410@end example 21411 21412@noindent 21413Because of the two overflows, a compiler might optimize away or 21414transform the two comparisons in a way that is incompatible with the 21415wraparound assumption. 21416 21417If your code uses an expression like @code{(i * 2000) / 1000} and you 21418actually want the multiplication to wrap around on overflow, use 21419unsigned arithmetic 21420to do it, e.g., @code{((int) (i * 2000u)) / 1000}. 21421 21422If your code assumes wraparound behavior and you want to insulate it 21423against any GCC optimizations that would fail to support that 21424behavior, you should use GCC's @option{-fwrapv} option, which 21425causes signed overflow to wrap around reliably (except for division and 21426remainder, as discussed in the next section). 21427 21428If you need to port to platforms where signed integer overflow does not 21429reliably wrap around (e.g., due to hardware overflow checking, or to 21430highly aggressive optimizations), you should consider debugging with 21431GCC's @option{-ftrapv} option, which causes signed overflow to 21432raise an exception. 21433 21434@node Signed Integer Division 21435@subsection Signed Integer Division and Integer Overflow 21436@cindex division, integer 21437 21438Overflow in signed 21439integer division is not always harmless: for example, on CPUs of the 21440i386 family, dividing @code{INT_MIN} by @code{-1} yields a SIGFPE signal 21441which by default terminates the program. Worse, taking the remainder 21442of these two values typically yields the same signal on these CPUs, 21443even though the C standard requires @code{INT_MIN % -1} to yield zero 21444because the expression does not overflow. 21445 21446@node Preprocessor Arithmetic 21447@section Preprocessor Arithmetic 21448@cindex preprocessor arithmetic 21449 21450In C99, preprocessor arithmetic, used for @code{#if} expressions, must 21451be evaluated as if all signed values are of type @code{intmax_t} and all 21452unsigned values of type @code{uintmax_t}. Many compilers are buggy in 21453this area, though. For example, as of 2007, Sun C mishandles @code{#if 21454LLONG_MIN < 0} on a platform with 32-bit @code{long int} and 64-bit 21455@code{long long int}. Also, some older preprocessors mishandle 21456constants ending in @code{LL}. To work around these problems, you can 21457compute the value of expressions like @code{LONG_MAX < LLONG_MAX} at 21458@code{configure}-time rather than at @code{#if}-time. 21459 21460@node Null Pointers 21461@section Properties of Null Pointers 21462@cindex null pointers 21463 21464Most modern hosts reliably fail when you attempt to dereference a null 21465pointer. 21466 21467On almost all modern hosts, null pointers use an all-bits-zero internal 21468representation, so you can reliably use @code{memset} with 0 to set all 21469the pointers in an array to null values. 21470 21471If @code{p} is a null pointer to an object type, the C expression 21472@code{p + 0} always evaluates to @code{p} on modern hosts, even though 21473the standard says that it has undefined behavior. 21474 21475@node Buffer Overruns 21476@section Buffer Overruns and Subscript Errors 21477@cindex buffer overruns 21478 21479Buffer overruns and subscript errors are the most common dangerous 21480errors in C programs. They result in undefined behavior because storing 21481outside an array typically modifies storage that is used by some other 21482object, and most modern systems lack runtime checks to catch these 21483errors. Programs should not rely on buffer overruns being caught. 21484 21485There is one exception to the usual rule that a portable program cannot 21486address outside an array. In C, it is valid to compute the address just 21487past an object, e.g., @code{&a[N]} where @code{a} has @code{N} elements, 21488so long as you do not dereference the resulting pointer. But it is not 21489valid to compute the address just before an object, e.g., @code{&a[-1]}; 21490nor is it valid to compute two past the end, e.g., @code{&a[N+1]}. On 21491most platforms @code{&a[-1] < &a[0] && &a[N] < &a[N+1]}, but this is not 21492reliable in general, and it is usually easy enough to avoid the 21493potential portability problem, e.g., by allocating an extra unused array 21494element at the start or end. 21495 21496@uref{http://@/valgrind.org/, Valgrind} can catch many overruns. 21497GCC 21498users might also consider using the @option{-fmudflap} option to catch 21499overruns. 21500 21501Buffer overruns are usually caused by off-by-one errors, but there are 21502more subtle ways to get them. 21503 21504Using @code{int} values to index into an array or compute array sizes 21505causes problems on typical 64-bit hosts where an array index might 21506be @math{2^{31}} or larger. Index values of type @code{size_t} avoid this 21507problem, but cannot be negative. Index values of type @code{ptrdiff_t} 21508are signed, and are wide enough in practice. 21509 21510If you add or multiply two numbers to calculate an array size, e.g., 21511@code{malloc (x * sizeof y + z)}, havoc ensues if the addition or 21512multiplication overflows. 21513 21514Many implementations of the @code{alloca} function silently misbehave 21515and can generate buffer overflows if given sizes that are too large. 21516The size limits are implementation dependent, but are at least 4000 21517bytes on all platforms that we know about. 21518 21519The standard functions @code{asctime}, @code{asctime_r}, @code{ctime}, 21520@code{ctime_r}, and @code{gets} are prone to buffer overflows, and 21521portable code should not use them unless the inputs are known to be 21522within certain limits. The time-related functions can overflow their 21523buffers if given timestamps out of range (e.g., a year less than -999 21524or greater than 9999). Time-related buffer overflows cannot happen with 21525recent-enough versions of the GNU C library, but are possible 21526with other 21527implementations. The @code{gets} function is the worst, since it almost 21528invariably overflows its buffer when presented with an input line larger 21529than the buffer. 21530 21531@node Volatile Objects 21532@section Volatile Objects 21533@cindex volatile objects 21534 21535The keyword @code{volatile} is often misunderstood in portable code. 21536Its use inhibits some memory-access optimizations, but programmers often 21537wish that it had a different meaning than it actually does. 21538 21539@code{volatile} was designed for code that accesses special objects like 21540memory-mapped device registers whose contents spontaneously change. 21541Such code is inherently low-level, and it is difficult to specify 21542portably what @code{volatile} means in these cases. The C standard 21543says, ``What constitutes an access to an object that has 21544volatile-qualified type is implementation-defined,'' so in theory each 21545implementation is supposed to fill in the gap by documenting what 21546@code{volatile} means for that implementation. In practice, though, 21547this documentation is usually absent or incomplete. 21548 21549One area of confusion is the distinction between objects defined with 21550volatile types, and volatile lvalues. From the C standard's point of 21551view, an object defined with a volatile type has externally visible 21552behavior. You can think of such objects as having little oscilloscope 21553probes attached to them, so that the user can observe some properties of 21554accesses to them, just as the user can observe data written to output 21555files. However, the standard does not make it clear whether users can 21556observe accesses by volatile lvalues to ordinary objects. For example: 21557 21558@example 21559/* Declare and access a volatile object. 21560 Accesses to X are "visible" to users. */ 21561static int volatile x; 21562x = 1; 21563 21564/* Access two ordinary objects via a volatile lvalue. 21565 It's not clear whether accesses to *P are "visible". */ 21566int y; 21567int *z = malloc (sizeof (int)); 21568int volatile *p; 21569p = &y; 21570*p = 1; 21571p = z; 21572*p = 1; 21573@end example 21574 21575Programmers often wish that @code{volatile} meant ``Perform the memory 21576access here and now, without merging several memory accesses, without 21577changing the memory word size, and without reordering.'' But the C 21578standard does not require this. For objects defined with a volatile 21579type, accesses must be done before the next sequence point; but 21580otherwise merging, reordering, and word-size change is allowed. Worse, 21581it is not clear from the standard whether volatile lvalues provide more 21582guarantees in general than nonvolatile lvalues, if the underlying 21583objects are ordinary. 21584 21585Even when accessing objects defined with a volatile type, 21586the C standard allows only 21587extremely limited signal handlers: the behavior is undefined if a signal 21588handler reads any nonlocal object, or writes to any nonlocal object 21589whose type is not @code{sig_atomic_t volatile}, or calls any standard 21590library function other than @code{abort}, @code{signal}, and (if C99) 21591@code{_Exit}. Hence C compilers need not worry about a signal handler 21592disturbing ordinary computation, unless the computation accesses a 21593@code{sig_atomic_t volatile} lvalue that is not a local variable. 21594(There is an obscure exception for accesses via a pointer to a volatile 21595character, since it may point into part of a @code{sig_atomic_t 21596volatile} object.) Posix 21597adds to the list of library functions callable from a portable signal 21598handler, but otherwise is like the C standard in this area. 21599 21600Some C implementations allow memory-access optimizations within each 21601translation unit, such that actual behavior agrees with the behavior 21602required by the standard only when calling a function in some other 21603translation unit, and a signal handler acts like it was called from a 21604different translation unit. The C standard hints that in these 21605implementations, objects referred to by signal handlers ``would require 21606explicit specification of @code{volatile} storage, as well as other 21607implementation-defined restrictions.'' But unfortunately even for this 21608special case these other restrictions are often not documented well. 21609@xref{Volatiles, , When is a Volatile Object Accessed?, gcc, Using the 21610GNU Compiler Collection (GCC)}, for some 21611restrictions imposed by GCC. @xref{Defining Handlers, , 21612Defining Signal Handlers, libc, The GNU C Library}, for some 21613restrictions imposed by the GNU C library. Restrictions 21614differ on other platforms. 21615 21616If possible, it is best to use a signal handler that fits within the 21617limits imposed by the C and Posix standards. 21618 21619If this is not practical, you can try the following rules of thumb. A 21620signal handler should access only volatile lvalues, preferably lvalues 21621that refer to objects defined with a volatile type, and should not 21622assume that the accessed objects have an internally consistent state 21623if they are larger than a machine word. Furthermore, installers 21624should employ compilers and compiler options that are commonly used 21625for building operating system kernels, because kernels often need more 21626from @code{volatile} than the C Standard requires, and installers who 21627compile an application in a similar environment can sometimes benefit 21628from the extra constraints imposed by kernels on compilers. 21629Admittedly we are handwaving somewhat here, as there are few 21630guarantees in this area; the rules of thumb may help to fix some bugs 21631but there is a good chance that they will not fix them all. 21632 21633For @code{volatile}, C++ has the same problems that C does. 21634Multithreaded applications have even more problems with @code{volatile}, 21635but they are beyond the scope of this section. 21636 21637The bottom line is that using @code{volatile} typically hurts 21638performance but should not hurt correctness. In some cases its use 21639does help correctness, but these cases are often so poorly understood 21640that all too often adding @code{volatile} to a data structure merely 21641alleviates some symptoms of a bug while not fixing the bug in general. 21642 21643@node Floating Point Portability 21644@section Floating Point Portability 21645@cindex floating point 21646 21647Almost all modern systems use IEEE-754 floating point, and it is safe to 21648assume IEEE-754 in most portable code these days. For more information, 21649please see David Goldberg's classic paper 21650@uref{http://@/www.validlab.com/@/goldberg/@/paper.pdf, What Every Computer 21651Scientist Should Know About Floating-Point Arithmetic}. 21652 21653@node Exiting Portably 21654@section Exiting Portably 21655@cindex exiting portably 21656 21657A C or C++ program can exit with status @var{N} by returning 21658@var{N} from the @code{main} function. Portable programs are supposed 21659to exit either with status 0 or @code{EXIT_SUCCESS} to succeed, or with 21660status @code{EXIT_FAILURE} to fail, but in practice it is portable to 21661fail by exiting with status 1, and test programs that assume Posix can 21662fail by exiting with status values from 1 through 255. Programs on 21663SunOS 2.0 (1985) through 3.5.2 (1988) incorrectly exited with zero 21664status when @code{main} returned nonzero, but ancient systems like these 21665are no longer of practical concern. 21666 21667A program can also exit with status @var{N} by passing @var{N} to the 21668@code{exit} function, and a program can fail by calling the @code{abort} 21669function. If a program is specialized to just some platforms, it can fail 21670by calling functions specific to those platforms, e.g., @code{_exit} 21671(Posix) and @code{_Exit} (C99). However, like other functions, an exit 21672function should be declared, typically by including a header. For 21673example, if a C program calls @code{exit}, it should include @file{stdlib.h} 21674either directly or via the default includes (@pxref{Default Includes}). 21675 21676A program can fail due to undefined behavior such as dereferencing a null 21677pointer, but this is not recommended as undefined behavior allows an 21678implementation to do whatever it pleases and this includes exiting 21679successfully. 21680 21681 21682@c ================================================== Manual Configuration 21683 21684@node Manual Configuration 21685@chapter Manual Configuration 21686 21687A few kinds of features can't be guessed automatically by running test 21688programs. For example, the details of the object-file format, or 21689special options that need to be passed to the compiler or linker. You 21690can check for such features using ad-hoc means, such as having 21691@command{configure} check the output of the @code{uname} program, or 21692looking for libraries that are unique to particular systems. However, 21693Autoconf provides a uniform method for handling unguessable features. 21694 21695@menu 21696* Specifying Target Triplets:: Specifying target triplets 21697* Canonicalizing:: Getting the canonical system type 21698* Using System Type:: What to do with the system type 21699@end menu 21700 21701@node Specifying Target Triplets 21702@section Specifying target triplets 21703@cindex System type 21704@cindex Target triplet 21705@c This node used to be named Specifying Names. The @anchor allows old 21706@c links to still work. 21707@anchor{Specifying Names} 21708 21709Autoconf-generated 21710@command{configure} scripts can make decisions based on a canonical name 21711for the system type, or @dfn{target triplet}, which has the form: 21712@samp{@var{cpu}-@var{vendor}-@var{os}}, where @var{os} can be 21713@samp{@var{system}} or @samp{@var{kernel}-@var{system}} 21714 21715@command{configure} can usually guess the canonical name for the type of 21716system it's running on. To do so it runs a script called 21717@command{config.guess}, which infers the name using the @code{uname} 21718command or symbols predefined by the C preprocessor. 21719 21720Alternately, the user can specify the system type with command line 21721arguments to @command{configure} (@pxref{System Type}. Doing so is 21722necessary when 21723cross-compiling. In the most complex case of cross-compiling, three 21724system types are involved. The options to specify them are: 21725 21726@table @option 21727@item --build=@var{build-type} 21728the type of system on which the package is being configured and 21729compiled. It defaults to the result of running @command{config.guess}. 21730Specifying a @var{build-type} that differs from @var{host-type} enables 21731cross-compilation mode. 21732 21733@item --host=@var{host-type} 21734the type of system on which the package runs. By default it is the 21735same as the build machine. Specifying a @var{host-type} that differs 21736from @var{build-type}, when @var{build-type} was also explicitly 21737specified, enables cross-compilation mode. 21738 21739@item --target=@var{target-type} 21740the type of system for which any compiler tools in the package 21741produce code (rarely needed). By default, it is the same as host. 21742@end table 21743 21744If you mean to override the result of @command{config.guess}, use 21745@option{--build}, not @option{--host}, since the latter enables 21746cross-compilation. For historical reasons, 21747whenever you specify @option{--host}, 21748be sure to specify @option{--build} too; this will be fixed in the 21749future. So, to enter cross-compilation mode, use a command like this 21750 21751@example 21752./configure --build=i686-pc-linux-gnu --host=m68k-coff 21753@end example 21754 21755@noindent 21756Note that if you do not specify @option{--host}, @command{configure} 21757fails if it can't run the code generated by the specified compiler. For 21758example, configuring as follows fails: 21759 21760@example 21761./configure CC=m68k-coff-gcc 21762@end example 21763 21764When cross-compiling, @command{configure} will warn about any tools 21765(compilers, linkers, assemblers) whose name is not prefixed with the 21766host type. This is an aid to users performing cross-compilation. 21767Continuing the example above, if a cross-compiler named @command{cc} is 21768used with a native @command{pkg-config}, then libraries found by 21769@command{pkg-config} will likely cause subtle build failures; but using 21770the names @command{m68k-coff-cc} and @command{m68k-coff-pkg-config} 21771avoids any confusion. Avoiding the warning is as simple as creating the 21772correct symlinks naming the cross tools. 21773 21774@cindex @command{config.sub} 21775@command{configure} recognizes short aliases for many system types; for 21776example, @samp{decstation} can be used instead of 21777@samp{mips-dec-ultrix4.2}. @command{configure} runs a script called 21778@command{config.sub} to canonicalize system type aliases. 21779 21780This section deliberately omits the description of the obsolete 21781interface; see @ref{Hosts and Cross-Compilation}. 21782 21783 21784@node Canonicalizing 21785@section Getting the Canonical System Type 21786@cindex System type 21787@cindex Canonical system type 21788 21789The following macros make the system type available to @command{configure} 21790scripts. 21791 21792@ovindex build_alias 21793@ovindex host_alias 21794@ovindex target_alias 21795 21796The variables @samp{build_alias}, @samp{host_alias}, and 21797@samp{target_alias} are always exactly the arguments of @option{--build}, 21798@option{--host}, and @option{--target}; in particular, they are left empty 21799if the user did not use them, even if the corresponding 21800@code{AC_CANONICAL} macro was run. Any configure script may use these 21801variables anywhere. These are the variables that should be used when in 21802interaction with the user. 21803 21804If you need to recognize some special environments based on their system 21805type, run the following macros to get canonical system names. These 21806variables are not set before the macro call. 21807 21808If you use these macros, you must distribute @command{config.guess} and 21809@command{config.sub} along with your source code. @xref{Output}, for 21810information about the @code{AC_CONFIG_AUX_DIR} macro which you can use 21811to control in which directory @command{configure} looks for those scripts. 21812 21813 21814@defmac AC_CANONICAL_BUILD 21815@acindex{CANONICAL_BUILD} 21816@ovindex build 21817@ovindex build_cpu 21818@ovindex build_vendor 21819@ovindex build_os 21820Compute the canonical build-system type variable, @code{build}, and its 21821three individual parts @code{build_cpu}, @code{build_vendor}, and 21822@code{build_os}. 21823 21824If @option{--build} was specified, then @code{build} is the 21825canonicalization of @code{build_alias} by @command{config.sub}, 21826otherwise it is determined by the shell script @command{config.guess}. 21827@end defmac 21828 21829@defmac AC_CANONICAL_HOST 21830@acindex{CANONICAL_HOST} 21831@ovindex host 21832@ovindex host_cpu 21833@ovindex host_vendor 21834@ovindex host_os 21835Compute the canonical host-system type variable, @code{host}, and its 21836three individual parts @code{host_cpu}, @code{host_vendor}, and 21837@code{host_os}. 21838 21839If @option{--host} was specified, then @code{host} is the 21840canonicalization of @code{host_alias} by @command{config.sub}, 21841otherwise it defaults to @code{build}. 21842@end defmac 21843 21844@defmac AC_CANONICAL_TARGET 21845@acindex{CANONICAL_TARGET} 21846@ovindex target 21847@ovindex target_cpu 21848@ovindex target_vendor 21849@ovindex target_os 21850Compute the canonical target-system type variable, @code{target}, and its 21851three individual parts @code{target_cpu}, @code{target_vendor}, and 21852@code{target_os}. 21853 21854If @option{--target} was specified, then @code{target} is the 21855canonicalization of @code{target_alias} by @command{config.sub}, 21856otherwise it defaults to @code{host}. 21857@end defmac 21858 21859Note that there can be artifacts due to the backward compatibility 21860code. @xref{Hosts and Cross-Compilation}, for more. 21861 21862@node Using System Type 21863@section Using the System Type 21864 21865In @file{configure.ac} the system type is generally used by one or more 21866@code{case} statements to select system-specifics. Shell wildcards can 21867be used to match a group of system types. 21868 21869For example, an extra assembler code object file could be chosen, giving 21870access to a CPU cycle counter register. @code{$(CYCLE_OBJ)} in the 21871following would be used in a makefile to add the object to a 21872program or library. 21873 21874@example 21875AS_CASE([$host], 21876 [alpha*-*-*], [CYCLE_OBJ=rpcc.o], 21877 [i?86-*-*], [CYCLE_OBJ=rdtsc.o], 21878 [CYCLE_OBJ=""] 21879) 21880AC_SUBST([CYCLE_OBJ]) 21881@end example 21882 21883@code{AC_CONFIG_LINKS} (@pxref{Configuration Links}) is another good way 21884to select variant source files, for example optimized code for some 21885CPUs. The configured CPU type doesn't always indicate exact CPU types, 21886so some runtime capability checks may be necessary too. 21887 21888@example 21889case $host in 21890 alpha*-*-*) AC_CONFIG_LINKS([dither.c:alpha/dither.c]) ;; 21891 powerpc*-*-*) AC_CONFIG_LINKS([dither.c:powerpc/dither.c]) ;; 21892 *-*-*) AC_CONFIG_LINKS([dither.c:generic/dither.c]) ;; 21893esac 21894@end example 21895 21896The host system type can also be used to find cross-compilation tools 21897with @code{AC_CHECK_TOOL} (@pxref{Generic Programs}). 21898 21899The above examples all show @samp{$host}, since this is where the code 21900is going to run. Only rarely is it necessary to test @samp{$build} 21901(which is where the build is being done). 21902 21903Whenever you're tempted to use @samp{$host} it's worth considering 21904whether some sort of probe would be better. New system types come along 21905periodically or previously missing features are added. Well-written 21906probes can adapt themselves to such things, but hard-coded lists of 21907names can't. Here are some guidelines, 21908 21909@itemize @bullet 21910@item 21911Availability of libraries and library functions should always be checked 21912by probing. 21913@item 21914Variant behavior of system calls is best identified with runtime tests 21915if possible, but bug workarounds or obscure difficulties might have to 21916be driven from @samp{$host}. 21917@item 21918Assembler code is inevitably highly CPU-specific and is best selected 21919according to @samp{$host_cpu}. 21920@item 21921Assembler variations like underscore prefix on globals or ELF versus 21922COFF type directives are however best determined by probing, perhaps 21923even examining the compiler output. 21924@end itemize 21925 21926@samp{$target} is for use by a package creating a compiler or similar. 21927For ordinary packages it's meaningless and should not be used. It 21928indicates what the created compiler should generate code for, if it can 21929cross-compile. @samp{$target} generally selects various hard-coded CPU 21930and system conventions, since usually the compiler or tools under 21931construction themselves determine how the target works. 21932 21933 21934@c ===================================================== Site Configuration. 21935 21936@node Site Configuration 21937@chapter Site Configuration 21938 21939@command{configure} scripts support several kinds of local configuration 21940decisions. There are ways for users to specify where external software 21941packages are, include or exclude optional features, install programs 21942under modified names, and set default values for @command{configure} 21943options. 21944 21945@menu 21946* Help Formatting:: Customizing @samp{configure --help} 21947* External Software:: Working with other optional software 21948* Package Options:: Selecting optional features 21949* Pretty Help Strings:: Formatting help string 21950* Option Checking:: Controlling checking of @command{configure} options 21951* Site Details:: Configuring site details 21952* Transforming Names:: Changing program names when installing 21953* Site Defaults:: Giving @command{configure} local defaults 21954@end menu 21955 21956@node Help Formatting 21957@section Controlling Help Output 21958 21959Users consult @samp{configure --help} to learn of configuration 21960decisions specific to your package. By default, @command{configure} 21961breaks this output into sections for each type of option; within each 21962section, help strings appear in the order @file{configure.ac} defines 21963them: 21964 21965@example 21966Optional Features: 21967 @dots{} 21968 --enable-bar include bar 21969 21970Optional Packages: 21971 @dots{} 21972 --with-foo use foo 21973@end example 21974 21975@defmac AC_PRESERVE_HELP_ORDER 21976@acindex{PRESERVE_HELP_ORDER} 21977 21978Request an alternate @option{--help} format, in which options of all 21979types appear together, in the order defined. Call this macro before any 21980@code{AC_ARG_ENABLE} or @code{AC_ARG_WITH}. 21981 21982@example 21983Optional Features and Packages: 21984 @dots{} 21985 --enable-bar include bar 21986 --with-foo use foo 21987@end example 21988 21989@end defmac 21990 21991@node External Software 21992@section Working With External Software 21993@cindex External software 21994 21995Some packages require, or can optionally use, other software packages 21996that are already installed. The user can give @command{configure} 21997command line options to specify which such external software to use. 21998The options have one of these forms: 21999 22000@c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something 22001@c awful. 22002@example 22003--with-@var{package}@r{[}=@var{arg}@r{]} 22004--without-@var{package} 22005@end example 22006 22007For example, @option{--with-gnu-ld} means work with the GNU linker 22008instead of some other linker. @option{--with-x} means work with The X 22009Window System. 22010 22011The user can give an argument by following the package name with 22012@samp{=} and the argument. Giving an argument of @samp{no} is for 22013packages that are used by default; it says to @emph{not} use the 22014package. An argument that is neither @samp{yes} nor @samp{no} could 22015include a name or number of a version of the other package, to specify 22016more precisely which other package this program is supposed to work 22017with. If no argument is given, it defaults to @samp{yes}. 22018@option{--without-@var{package}} is equivalent to 22019@option{--with-@var{package}=no}. 22020 22021Normally @command{configure} scripts complain about 22022@option{--with-@var{package}} options that they do not support. 22023@xref{Option Checking}, for details, and for how to override the 22024defaults. 22025 22026For each external software package that may be used, @file{configure.ac} 22027should call @code{AC_ARG_WITH} to detect whether the @command{configure} 22028user asked to use it. Whether each package is used or not by default, 22029and which arguments are valid, is up to you. 22030 22031@anchor{AC_ARG_WITH} 22032@defmac AC_ARG_WITH (@var{package}, @var{help-string}, @ 22033 @ovar{action-if-given}, @ovar{action-if-not-given}) 22034@acindex{ARG_WITH} 22035If the user gave @command{configure} the option @option{--with-@var{package}} 22036or @option{--without-@var{package}}, run shell commands 22037@var{action-if-given}. If neither option was given, run shell commands 22038@var{action-if-not-given}. The name @var{package} indicates another 22039software package that this program should work with. It should consist 22040only of alphanumeric characters, dashes, plus signs, and dots. 22041 22042The option's argument is available to the shell commands 22043@var{action-if-given} in the shell variable @code{withval}, which is 22044actually just the value of the shell variable named 22045@code{with_@var{package}}, with any non-alphanumeric characters in 22046@var{package} changed into @samp{_}. You may use that variable instead, 22047if you wish. 22048 22049The argument @var{help-string} is a description of the option that 22050looks like this: 22051@example 22052 --with-readline support fancy command line editing 22053@end example 22054 22055@noindent 22056@var{help-string} may be more than one line long, if more detail is 22057needed. Just make sure the columns line up in @samp{configure 22058--help}. Avoid tabs in the help string. The easiest way to provide the 22059proper leading whitespace is to format your @var{help-string} with the macro 22060@code{AS_HELP_STRING} (@pxref{Pretty Help Strings}). 22061 22062The following example shows how to use the @code{AC_ARG_WITH} macro in 22063a common situation. You want to let the user decide whether to enable 22064support for an external library (e.g., the readline library); if the user 22065specified neither @option{--with-readline} nor @option{--without-readline}, 22066you want to enable support for readline only if the library is available 22067on the system. 22068 22069@c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved. 22070@example 22071AC_ARG_WITH([readline], 22072 [AS_HELP_STRING([--with-readline], 22073 [support fancy command line editing @@<:@@default=check@@:>@@])], 22074 [], 22075 [with_readline=check]) 22076 22077LIBREADLINE= 22078AS_IF([test "x$with_readline" != xno], 22079 [AC_CHECK_LIB([readline], [main], 22080 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"]) 22081 AC_DEFINE([HAVE_LIBREADLINE], [1], 22082 [Define if you have libreadline]) 22083 ], 22084 [if test "x$with_readline" != xcheck; then 22085 AC_MSG_FAILURE( 22086 [--with-readline was given, but test for readline failed]) 22087 fi 22088 ], -lncurses)]) 22089@end example 22090 22091The next example shows how to use @code{AC_ARG_WITH} to give the user the 22092possibility to enable support for the readline library, in case it is still 22093experimental and not well tested, and is therefore disabled by default. 22094 22095@c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved. 22096@example 22097AC_ARG_WITH([readline], 22098 [AS_HELP_STRING([--with-readline], 22099 [enable experimental support for readline])], 22100 [], 22101 [with_readline=no]) 22102 22103LIBREADLINE= 22104AS_IF([test "x$with_readline" != xno], 22105 [AC_CHECK_LIB([readline], [main], 22106 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"]) 22107 AC_DEFINE([HAVE_LIBREADLINE], [1], 22108 [Define if you have libreadline]) 22109 ], 22110 [AC_MSG_FAILURE( 22111 [--with-readline was given, but test for readline failed])], 22112 [-lncurses])]) 22113@end example 22114 22115The last example shows how to use @code{AC_ARG_WITH} to give the user the 22116possibility to disable support for the readline library, given that it is 22117an important feature and that it should be enabled by default. 22118 22119@c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved. 22120@example 22121AC_ARG_WITH([readline], 22122 [AS_HELP_STRING([--without-readline], 22123 [disable support for readline])], 22124 [], 22125 [with_readline=yes]) 22126 22127LIBREADLINE= 22128AS_IF([test "x$with_readline" != xno], 22129 [AC_CHECK_LIB([readline], [main], 22130 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"]) 22131 AC_DEFINE([HAVE_LIBREADLINE], [1], 22132 [Define if you have libreadline]) 22133 ], 22134 [AC_MSG_FAILURE( 22135 [readline test failed (--without-readline to disable)])], 22136 [-lncurses])]) 22137@end example 22138 22139These three examples can be easily adapted to the case where 22140@code{AC_ARG_ENABLE} should be preferred to @code{AC_ARG_WITH} (see 22141@ref{Package Options}). 22142@end defmac 22143 22144@node Package Options 22145@section Choosing Package Options 22146@cindex Package options 22147@cindex Options, package 22148 22149If a software package has optional compile-time features, the user can 22150give @command{configure} command line options to specify whether to 22151compile them. The options have one of these forms: 22152 22153@c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something 22154@c awful. 22155@example 22156--enable-@var{feature}@r{[}=@var{arg}@r{]} 22157--disable-@var{feature} 22158@end example 22159 22160These options allow users to choose which optional features to build and 22161install. @option{--enable-@var{feature}} options should never make a 22162feature behave differently or cause one feature to replace another. 22163They should only cause parts of the program to be built rather than left 22164out. 22165 22166The user can give an argument by following the feature name with 22167@samp{=} and the argument. Giving an argument of @samp{no} requests 22168that the feature @emph{not} be made available. A feature with an 22169argument looks like @option{--enable-debug=stabs}. If no argument is 22170given, it defaults to @samp{yes}. @option{--disable-@var{feature}} is 22171equivalent to @option{--enable-@var{feature}=no}. 22172 22173Normally @command{configure} scripts complain about 22174@option{--enable-@var{package}} options that they do not support. 22175@xref{Option Checking}, for details, and for how to override the 22176defaults. 22177 22178For each optional feature, @file{configure.ac} should call 22179@code{AC_ARG_ENABLE} to detect whether the @command{configure} user asked 22180to include it. Whether each feature is included or not by default, and 22181which arguments are valid, is up to you. 22182 22183@anchor{AC_ARG_ENABLE} 22184@defmac AC_ARG_ENABLE (@var{feature}, @var{help-string}, @ 22185 @ovar{action-if-given}, @ovar{action-if-not-given}) 22186@acindex{ARG_ENABLE} 22187If the user gave @command{configure} the option 22188@option{--enable-@var{feature}} or @option{--disable-@var{feature}}, run 22189shell commands @var{action-if-given}. If neither option was given, run 22190shell commands @var{action-if-not-given}. The name @var{feature} 22191indicates an optional user-level facility. It should consist only of 22192alphanumeric characters, dashes, plus signs, and dots. 22193 22194The option's argument is available to the shell commands 22195@var{action-if-given} in the shell variable @code{enableval}, which is 22196actually just the value of the shell variable named 22197@code{enable_@var{feature}}, with any non-alphanumeric characters in 22198@var{feature} changed into @samp{_}. You may use that variable instead, 22199if you wish. The @var{help-string} argument is like that of 22200@code{AC_ARG_WITH} (@pxref{External Software}). 22201 22202You should format your @var{help-string} with the macro 22203@code{AS_HELP_STRING} (@pxref{Pretty Help Strings}). 22204 22205See the examples suggested with the definition of @code{AC_ARG_WITH} 22206(@pxref{External Software}) to get an idea of possible applications of 22207@code{AC_ARG_ENABLE}. 22208@end defmac 22209 22210@node Pretty Help Strings 22211@section Making Your Help Strings Look Pretty 22212@cindex Help strings 22213 22214Properly formatting the @samp{help strings} which are used in 22215@code{AC_ARG_WITH} (@pxref{External Software}) and @code{AC_ARG_ENABLE} 22216(@pxref{Package Options}) can be challenging. Specifically, you want 22217your own @samp{help strings} to line up in the appropriate columns of 22218@samp{configure --help} just like the standard Autoconf @samp{help 22219strings} do. This is the purpose of the @code{AS_HELP_STRING} macro. 22220 22221@anchor{AS_HELP_STRING} 22222@defmac AS_HELP_STRING (@var{left-hand-side}, @var{right-hand-side} @ 22223 @dvar{indent-column, 26}, @dvar{wrap-column, 79}) 22224@asindex{HELP_STRING} 22225 22226Expands into a help string that looks pretty when the user executes 22227@samp{configure --help}. It is typically used in @code{AC_ARG_WITH} 22228(@pxref{External Software}) or @code{AC_ARG_ENABLE} (@pxref{Package 22229Options}). The following example makes this clearer. 22230 22231@example 22232AC_ARG_WITH([foo], 22233 [AS_HELP_STRING([--with-foo], 22234 [use foo (default is no)])], 22235 [use_foo=$withval], 22236 [use_foo=no]) 22237@end example 22238 22239Then the last few lines of @samp{configure --help} appear like 22240this: 22241 22242@example 22243--enable and --with options recognized: 22244 --with-foo use foo (default is no) 22245@end example 22246 22247Macro expansion is performed on the first argument. However, the second 22248argument of @code{AS_HELP_STRING} is treated as a whitespace separated 22249list of text to be reformatted, and is not subject to macro expansion. 22250Since it is not expanded, it should not be double quoted. 22251@xref{Autoconf Language}, for a more detailed explanation. 22252 22253The @code{AS_HELP_STRING} macro is particularly helpful when the 22254@var{left-hand-side} and/or @var{right-hand-side} are composed of macro 22255arguments, as shown in the following example. Be aware that 22256@var{left-hand-side} may not expand to unbalanced quotes, 22257although quadrigraphs can be used. 22258 22259@example 22260AC_DEFUN([MY_ARG_WITH], 22261 [AC_ARG_WITH(m4_translit([[$1]], [_], [-]), 22262 [AS_HELP_STRING([--with-m4_translit([$1], [_], [-])], 22263 [use $1 (default is $2)])], 22264 [use_[]$1=$withval], 22265 [use_[]$1=$2])]) 22266MY_ARG_WITH([a_b], [no]) 22267@end example 22268@noindent 22269Here, the last few lines of @samp{configure --help} will include: 22270 22271@example 22272--enable and --with options recognized: 22273 --with-a-b use a_b (default is no) 22274@end example 22275 22276The parameters @var{indent-column} and @var{wrap-column} were introduced 22277in Autoconf 2.62. Generally, they should not be specified; they exist 22278for fine-tuning of the wrapping. 22279@example 22280AS_HELP_STRING([--option], [description of option]) 22281@result{} --option description of option 22282AS_HELP_STRING([--option], [description of option], [15], [30]) 22283@result{} --option description of 22284@result{} option 22285@end example 22286@end defmac 22287 22288 22289@node Option Checking 22290@section Controlling Checking of @command{configure} Options 22291@cindex Options, Package 22292 22293The @command{configure} script checks its command-line options against a 22294list of known options, like @option{--help} or @option{--config-cache}. 22295An unknown option ordinarily indicates a mistake by the user and 22296@command{configure} halts with an error. However, by default unknown 22297@option{--with-@var{package}} and @option{--enable-@var{feature}} 22298options elicit only a warning, to support configuring entire source 22299trees. 22300 22301Source trees often contain multiple packages with a top-level 22302@command{configure} script that uses the @code{AC_CONFIG_SUBDIRS} macro 22303(@pxref{Subdirectories}). Because the packages generally support 22304different @option{--with-@var{package}} and 22305@option{--enable-@var{feature}} options, the GNU Coding 22306Standards say they must accept unrecognized options without halting. 22307Even a warning message is undesirable here, so @code{AC_CONFIG_SUBDIRS} 22308automatically disables the warnings. 22309 22310This default behavior may be modified in two ways. First, the installer 22311can invoke @code{configure --disable-option-checking} to disable 22312these warnings, or invoke @code{configure --enable-option-checking=fatal} 22313options to turn them into fatal errors, respectively. Second, the 22314maintainer can use @code{AC_DISABLE_OPTION_CHECKING}. 22315 22316@defmac AC_DISABLE_OPTION_CHECKING 22317@acindex{DISABLE_OPTION_CHECKING} 22318 22319By default, disable warnings related to any unrecognized 22320@option{--with-@var{package}} or @option{--enable-@var{feature}} 22321options. This is implied by @code{AC_CONFIG_SUBDIRS}. 22322 22323The installer can override this behavior by passing 22324@option{--enable-option-checking} (enable warnings) or 22325@option{--enable-option-checking=fatal} (enable errors) to 22326@command{configure}. 22327@end defmac 22328 22329 22330@node Site Details 22331@section Configuring Site Details 22332@cindex Site details 22333 22334Some software packages require complex site-specific information. Some 22335examples are host names to use for certain services, company names, and 22336email addresses to contact. Since some configuration scripts generated 22337by Metaconfig ask for such information interactively, people sometimes 22338wonder how to get that information in Autoconf-generated configuration 22339scripts, which aren't interactive. 22340 22341Such site configuration information should be put in a file that is 22342edited @emph{only by users}, not by programs. The location of the file 22343can either be based on the @code{prefix} variable, or be a standard 22344location such as the user's home directory. It could even be specified 22345by an environment variable. The programs should examine that file at 22346runtime, rather than at compile time. Runtime configuration is more 22347convenient for users and makes the configuration process simpler than 22348getting the information while configuring. @xref{Directory Variables, , 22349Variables for Installation Directories, standards, The GNU Coding 22350Standards}, for more information on where to put data files. 22351 22352@node Transforming Names 22353@section Transforming Program Names When Installing 22354@cindex Transforming program names 22355@cindex Program names, transforming 22356 22357Autoconf supports changing the names of programs when installing them. 22358In order to use these transformations, @file{configure.ac} must call the 22359macro @code{AC_ARG_PROGRAM}. 22360 22361@defmac AC_ARG_PROGRAM 22362@acindex{ARG_PROGRAM} 22363@ovindex program_transform_name 22364Place in output variable @code{program_transform_name} a sequence of 22365@code{sed} commands for changing the names of installed programs. 22366 22367If any of the options described below are given to @command{configure}, 22368program names are transformed accordingly. Otherwise, if 22369@code{AC_CANONICAL_TARGET} has been called and a @option{--target} value 22370is given, the target type followed by a dash is used as a prefix. 22371Otherwise, no program name transformation is done. 22372@end defmac 22373 22374@menu 22375* Transformation Options:: @command{configure} options to transform names 22376* Transformation Examples:: Sample uses of transforming names 22377* Transformation Rules:: Makefile uses of transforming names 22378@end menu 22379 22380@node Transformation Options 22381@subsection Transformation Options 22382 22383You can specify name transformations by giving @command{configure} these 22384command line options: 22385 22386@table @option 22387@item --program-prefix=@var{prefix} 22388prepend @var{prefix} to the names; 22389 22390@item --program-suffix=@var{suffix} 22391append @var{suffix} to the names; 22392 22393@item --program-transform-name=@var{expression} 22394perform @code{sed} substitution @var{expression} on the names. 22395@end table 22396 22397@node Transformation Examples 22398@subsection Transformation Examples 22399 22400These transformations are useful with programs that can be part of a 22401cross-compilation development environment. For example, a 22402cross-assembler running on a Sun 4 configured with 22403@option{--target=i960-vxworks} is normally installed as 22404@file{i960-vxworks-as}, rather than @file{as}, which could be confused 22405with a native Sun 4 assembler. 22406 22407You can force a program name to begin with @file{g}, if you don't want 22408GNU programs installed on your system to shadow other programs with 22409the same name. For example, if you configure GNU @code{diff} with 22410@option{--program-prefix=g}, then when you run @samp{make install} it is 22411installed as @file{/usr/local/bin/gdiff}. 22412 22413As a more sophisticated example, you could use 22414 22415@example 22416--program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/' 22417@end example 22418@noindent 22419 22420to prepend @samp{g} to most of the program names in a source tree, 22421excepting those like @code{gdb} that already have one and those like 22422@code{less} and @code{lesskey} that aren't GNU programs. (That is 22423assuming that you have a source tree containing those programs that is 22424set up to use this feature.) 22425 22426One way to install multiple versions of some programs simultaneously is 22427to append a version number to the name of one or both. For example, if 22428you want to keep Autoconf version 1 around for awhile, you can configure 22429Autoconf version 2 using @option{--program-suffix=2} to install the 22430programs as @file{/usr/local/bin/autoconf2}, 22431@file{/usr/local/bin/autoheader2}, etc. Nevertheless, pay attention 22432that only the binaries are renamed, therefore you'd have problems with 22433the library files which might overlap. 22434 22435@node Transformation Rules 22436@subsection Transformation Rules 22437 22438Here is how to use the variable @code{program_transform_name} in a 22439@file{Makefile.in}: 22440 22441@example 22442PROGRAMS = cp ls rm 22443transform = @@program_transform_name@@ 22444install: 22445 for p in $(PROGRAMS); do \ 22446 $(INSTALL_PROGRAM) $$p $(DESTDIR)$(bindir)/`echo $$p | \ 22447 sed '$(transform)'`; \ 22448 done 22449 22450uninstall: 22451 for p in $(PROGRAMS); do \ 22452 rm -f $(DESTDIR)$(bindir)/`echo $$p | sed '$(transform)'`; \ 22453@c $$ restore font-lock 22454 done 22455@end example 22456 22457It is guaranteed that @code{program_transform_name} is never empty, and 22458that there are no useless separators. Therefore you may safely embed 22459@code{program_transform_name} within a sed program using @samp{;}: 22460 22461@example 22462transform = @@program_transform_name@@ 22463transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/ 22464@end example 22465 22466Whether to do the transformations on documentation files (Texinfo or 22467@code{man}) is a tricky question; there seems to be no perfect answer, 22468due to the several reasons for name transforming. Documentation is not 22469usually particular to a specific architecture, and Texinfo files do not 22470conflict with system documentation. But they might conflict with 22471earlier versions of the same files, and @code{man} pages sometimes do 22472conflict with system documentation. As a compromise, it is probably 22473best to do name transformations on @code{man} pages but not on Texinfo 22474manuals. 22475 22476@node Site Defaults 22477@section Setting Site Defaults 22478@cindex Site defaults 22479@cindex config.site 22480 22481Autoconf-generated @command{configure} scripts allow your site to provide 22482default values for some configuration values. You do this by creating 22483site- and system-wide initialization files. 22484 22485@evindex CONFIG_SITE 22486If the environment variable @code{CONFIG_SITE} is set, @command{configure} 22487uses its value as the name of a shell script to read; it is recommended 22488that this be an absolute file name. Otherwise, it 22489reads the shell script @file{@var{prefix}/share/config.site} if it exists, 22490then @file{@var{prefix}/etc/config.site} if it exists. Thus, 22491settings in machine-specific files override those in machine-independent 22492ones in case of conflict. 22493 22494Site files can be arbitrary shell scripts, but only certain kinds of 22495code are really appropriate to be in them. Because @command{configure} 22496reads any cache file after it has read any site files, a site file can 22497define a default cache file to be shared between all Autoconf-generated 22498@command{configure} scripts run on that system (@pxref{Cache Files}). If 22499you set a default cache file in a site file, it is a good idea to also 22500set the output variable @code{CC} in that site file, because the cache 22501file is only valid for a particular compiler, but many systems have 22502several available. 22503 22504You can examine or override the value set by a command line option to 22505@command{configure} in a site file; options set shell variables that have 22506the same names as the options, with any dashes turned into underscores. 22507The exceptions are that @option{--without-} and @option{--disable-} options 22508are like giving the corresponding @option{--with-} or @option{--enable-} 22509option and the value @samp{no}. Thus, @option{--cache-file=localcache} 22510sets the variable @code{cache_file} to the value @samp{localcache}; 22511@option{--enable-warnings=no} or @option{--disable-warnings} sets the variable 22512@code{enable_warnings} to the value @samp{no}; @option{--prefix=/usr} sets the 22513variable @code{prefix} to the value @samp{/usr}; etc. 22514 22515Site files are also good places to set default values for other output 22516variables, such as @code{CFLAGS}, if you need to give them non-default 22517values: anything you would normally do, repetitively, on the command 22518line. If you use non-default values for @var{prefix} or 22519@var{exec_prefix} (wherever you locate the site file), you can set them 22520in the site file if you specify it with the @code{CONFIG_SITE} 22521environment variable. 22522 22523You can set some cache values in the site file itself. Doing this is 22524useful if you are cross-compiling, where it is impossible to check features 22525that require running a test program. You could ``prime the cache'' by 22526setting those values correctly for that system in 22527@file{@var{prefix}/etc/config.site}. To find out the names of the cache 22528variables you need to set, see the documentation of the respective 22529Autoconf macro. If the variables or their semantics are undocumented, 22530you may need to look for shell variables with @samp{_cv_} in their names 22531in the affected @command{configure} scripts, or in the Autoconf M4 22532source code for those macros; but in that case, their name or semantics 22533may change in a future Autoconf version. 22534 22535The cache file is careful to not override any variables set in the site 22536files. Similarly, you should not override command-line options in the 22537site files. Your code should check that variables such as @code{prefix} 22538and @code{cache_file} have their default values (as set near the top of 22539@command{configure}) before changing them. 22540 22541Here is a sample file @file{/usr/share/local/@/gnu/share/@/config.site}. The 22542command @samp{configure --prefix=/usr/share/local/gnu} would read this 22543file (if @code{CONFIG_SITE} is not set to a different file). 22544 22545@example 22546# /usr/share/local/gnu/share/config.site for configure 22547# 22548# Change some defaults. 22549test "$prefix" = NONE && prefix=/usr/share/local/gnu 22550test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu 22551test "$sharedstatedir" = '$@{prefix@}/com' && sharedstatedir=/var 22552test "$localstatedir" = '$@{prefix@}/var' && localstatedir=/var 22553 22554# Give Autoconf 2.x generated configure scripts a shared default 22555# cache file for feature test results, architecture-specific. 22556if test "$cache_file" = /dev/null; then 22557 cache_file="$prefix/var/config.cache" 22558 # A cache file is only valid for one C compiler. 22559 CC=gcc 22560fi 22561@end example 22562 22563@c Leave this use of ``File system'' rendered as one word, but 22564@c slightly obfuscated so as not to trigger the syntax-check prohibition. 22565@cindex File@/system Hierarchy Standard 22566@cindex FHS 22567 22568Another use of @file{config.site} is for priming the directory variables 22569@c ``File system'', but slightly obfuscated, as above. 22570in a manner consistent with the File@/system Hierarchy Standard 22571(FHS). Once the following file is installed at 22572@file{/usr/share/config.site}, a user can execute simply 22573@code{./configure --prefix=/usr} to get all the directories chosen in 22574the locations recommended by FHS. 22575 22576@example 22577# /usr/share/config.site for FHS defaults when installing below /usr, 22578# and the respective settings were not changed on the command line. 22579if test "$prefix" = /usr; then 22580 test "$sysconfdir" = '$@{prefix@}/etc' && sysconfdir=/etc 22581 test "$sharedstatedir" = '$@{prefix@}/com' && sharedstatedir=/var 22582 test "$localstatedir" = '$@{prefix@}/var' && localstatedir=/var 22583fi 22584@end example 22585 22586@cindex @file{lib64} 22587@cindex 64-bit libraries 22588Likewise, on platforms where 64-bit libraries are built by default, then 22589installed in @file{/usr/local/@/lib64} instead of @file{/usr/local/@/lib}, 22590it is appropriate to install @file{/usr/local/@/share/config.site}: 22591 22592@example 22593# /usr/local/share/config.site for platforms that prefer 22594# the directory /usr/local/lib64 over /usr/local/lib. 22595test "$libdir" = '$@{exec_prefix@}/lib' && libdir='$@{exec_prefix@}/lib64' 22596@end example 22597 22598 22599@c ============================================== Running configure Scripts. 22600 22601@node Running configure Scripts 22602@chapter Running @command{configure} Scripts 22603@cindex @command{configure} 22604 22605Below are instructions on how to configure a package that uses a 22606@command{configure} script, suitable for inclusion as an @file{INSTALL} 22607file in the package. A plain-text version of @file{INSTALL} which you 22608may use comes with Autoconf. 22609 22610@menu 22611* Basic Installation:: Instructions for typical cases 22612* Compilers and Options:: Selecting compilers and optimization 22613* Multiple Architectures:: Compiling for multiple architectures at once 22614* Installation Names:: Installing in different directories 22615* Optional Features:: Selecting optional features 22616* Particular Systems:: Particular systems 22617* System Type:: Specifying the system type 22618* Sharing Defaults:: Setting site-wide defaults for @command{configure} 22619* Defining Variables:: Specifying the compiler etc. 22620* configure Invocation:: Changing how @command{configure} runs 22621@end menu 22622 22623@set autoconf 22624@include install.texi 22625 22626 22627@c ============================================== config.status Invocation 22628 22629@node config.status Invocation 22630@chapter config.status Invocation 22631@cindex @command{config.status} 22632 22633The @command{configure} script creates a file named @file{config.status}, 22634which actually configures, @dfn{instantiates}, the template files. It 22635also records the configuration options that were specified when the 22636package was last configured in case reconfiguring is needed. 22637 22638Synopsis: 22639@example 22640./config.status @ovar{option}@dots{} @ovar{tag}@dots{} 22641@end example 22642 22643It configures each @var{tag}; if none are specified, all the templates 22644are instantiated. A @var{tag} refers to a file or other tag associated 22645with a configuration action, as specified by an @code{AC_CONFIG_@var{ITEMS}} 22646macro (@pxref{Configuration Actions}). The files must be specified 22647without their dependencies, as in 22648 22649@example 22650./config.status foobar 22651@end example 22652 22653@noindent 22654not 22655 22656@example 22657./config.status foobar:foo.in:bar.in 22658@end example 22659 22660The supported options are: 22661 22662@table @option 22663@item --help 22664@itemx -h 22665Print a summary of the command line options, the list of the template 22666files, and exit. 22667 22668@item --version 22669@itemx -V 22670Print the version number of Autoconf and the configuration settings, 22671and exit. 22672 22673@item --config 22674Print the configuration settings in reusable way, quoted for the shell, 22675and exit. For example, for a debugging build that otherwise reuses the 22676configuration from a different build directory @var{build-dir} of a 22677package in @var{src-dir}, you could use the following: 22678 22679@example 22680args=`@var{build-dir}/config.status --config` 22681eval @var{src-dir}/configure "$args" CFLAGS=-g --srcdir=@var{src-dir} 22682@end example 22683 22684@noindent 22685Note that it may be necessary to override a @option{--srcdir} setting 22686that was saved in the configuration, if the arguments are used in a 22687different build directory. 22688 22689@item --silent 22690@itemx --quiet 22691@itemx -q 22692Do not print progress messages. 22693 22694@item --debug 22695@itemx -d 22696Don't remove the temporary files. 22697 22698@item --file=@var{file}[:@var{template}] 22699Require that @var{file} be instantiated as if 22700@samp{AC_CONFIG_FILES(@var{file}:@var{template})} was used. Both 22701@var{file} and @var{template} may be @samp{-} in which case the standard 22702output and/or standard input, respectively, is used. If a 22703@var{template} file name is relative, it is first looked for in the build 22704tree, and then in the source tree. @xref{Configuration Actions}, for 22705more details. 22706 22707This option and the following ones provide one way for separately 22708distributed packages to share the values computed by @command{configure}. 22709Doing so can be useful if some of the packages need a superset of the 22710features that one of them, perhaps a common library, does. These 22711options allow a @file{config.status} file to create files other than the 22712ones that its @file{configure.ac} specifies, so it can be used for a 22713different package, or for extracting a subset of values. For example, 22714 22715@example 22716echo '@@CC@@' | ./config.status --file=- 22717@end example 22718 22719@noindent 22720provides the value of @code{@@CC@@} on standard output. 22721 22722@item --header=@var{file}[:@var{template}] 22723Same as @option{--file} above, but with @samp{AC_CONFIG_HEADERS}. 22724 22725@item --recheck 22726Ask @file{config.status} to update itself and exit (no instantiation). 22727This option is useful if you change @command{configure}, so that the 22728results of some tests might be different from the previous run. The 22729@option{--recheck} option reruns @command{configure} with the same arguments 22730you used before, plus the @option{--no-create} option, which prevents 22731@command{configure} from running @file{config.status} and creating 22732@file{Makefile} and other files, and the @option{--no-recursion} option, 22733which prevents @command{configure} from running other @command{configure} 22734scripts in subdirectories. (This is so other Make rules can 22735run @file{config.status} when it changes; @pxref{Automatic Remaking}, 22736for an example). 22737@end table 22738 22739@file{config.status} checks several optional environment variables that 22740can alter its behavior: 22741 22742@anchor{CONFIG_SHELL} 22743@defvar CONFIG_SHELL 22744@evindex CONFIG_SHELL 22745The shell with which to run @command{configure}. It must be 22746Bourne-compatible, and the absolute name of the shell should be passed. 22747The default is a shell that supports @code{LINENO} if available, and 22748@file{/bin/sh} otherwise. 22749@end defvar 22750 22751@defvar CONFIG_STATUS 22752@evindex CONFIG_STATUS 22753The file name to use for the shell script that records the 22754configuration. The default is @file{./config.status}. This variable is 22755useful when one package uses parts of another and the @command{configure} 22756scripts shouldn't be merged because they are maintained separately. 22757@end defvar 22758 22759You can use @file{./config.status} in your makefiles. For example, in 22760the dependencies given above (@pxref{Automatic Remaking}), 22761@file{config.status} is run twice when @file{configure.ac} has changed. 22762If that bothers you, you can make each run only regenerate the files for 22763that rule: 22764@example 22765@group 22766config.h: stamp-h 22767stamp-h: config.h.in config.status 22768 ./config.status config.h 22769 echo > stamp-h 22770 22771Makefile: Makefile.in config.status 22772 ./config.status Makefile 22773@end group 22774@end example 22775 22776The calling convention of @file{config.status} has changed; see 22777@ref{Obsolete config.status Use}, for details. 22778 22779 22780@c =================================================== Obsolete Constructs 22781 22782@node Obsolete Constructs 22783@chapter Obsolete Constructs 22784@cindex Obsolete constructs 22785 22786Autoconf changes, and throughout the years some constructs have been 22787obsoleted. Most of the changes involve the macros, but in some cases 22788the tools themselves, or even some concepts, are now considered 22789obsolete. 22790 22791You may completely skip this chapter if you are new to Autoconf. Its 22792intention is mainly to help maintainers updating their packages by 22793understanding how to move to more modern constructs. 22794 22795@menu 22796* Obsolete config.status Use:: Obsolete convention for @command{config.status} 22797* acconfig Header:: Additional entries in @file{config.h.in} 22798* autoupdate Invocation:: Automatic update of @file{configure.ac} 22799* Obsolete Macros:: Backward compatibility macros 22800* Autoconf 1:: Tips for upgrading your files 22801* Autoconf 2.13:: Some fresher tips 22802@end menu 22803 22804@node Obsolete config.status Use 22805@section Obsolete @file{config.status} Invocation 22806 22807@file{config.status} now supports arguments to specify the files to 22808instantiate; see @ref{config.status Invocation}, for more details. 22809Before, environment variables had to be used. 22810 22811@defvar CONFIG_COMMANDS 22812@evindex CONFIG_COMMANDS 22813The tags of the commands to execute. The default is the arguments given 22814to @code{AC_OUTPUT} and @code{AC_CONFIG_COMMANDS} in 22815@file{configure.ac}. 22816@end defvar 22817 22818@defvar CONFIG_FILES 22819@evindex CONFIG_FILES 22820The files in which to perform @samp{@@@var{variable}@@} substitutions. 22821The default is the arguments given to @code{AC_OUTPUT} and 22822@code{AC_CONFIG_FILES} in @file{configure.ac}. 22823@end defvar 22824 22825@defvar CONFIG_HEADERS 22826@evindex CONFIG_HEADERS 22827The files in which to substitute C @code{#define} statements. The 22828default is the arguments given to @code{AC_CONFIG_HEADERS}; if that 22829macro was not called, @file{config.status} ignores this variable. 22830@end defvar 22831 22832@defvar CONFIG_LINKS 22833@evindex CONFIG_LINKS 22834The symbolic links to establish. The default is the arguments given to 22835@code{AC_CONFIG_LINKS}; if that macro was not called, 22836@file{config.status} ignores this variable. 22837@end defvar 22838 22839In @ref{config.status Invocation}, using this old interface, the example 22840would be: 22841 22842@example 22843@group 22844config.h: stamp-h 22845stamp-h: config.h.in config.status 22846 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \ 22847 CONFIG_HEADERS=config.h ./config.status 22848 echo > stamp-h 22849 22850Makefile: Makefile.in config.status 22851 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \ 22852 CONFIG_FILES=Makefile ./config.status 22853@end group 22854@end example 22855 22856@noindent 22857(If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is 22858no need to set @code{CONFIG_HEADERS} in the @command{make} rules. Equally 22859for @code{CONFIG_COMMANDS}, etc.) 22860 22861 22862@node acconfig Header 22863@section @file{acconfig.h} 22864 22865@cindex @file{acconfig.h} 22866@cindex @file{config.h.top} 22867@cindex @file{config.h.bot} 22868 22869In order to produce @file{config.h.in}, @command{autoheader} needs to 22870build or to find templates for each symbol. Modern releases of Autoconf 22871use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader 22872Macros}), but in older releases a file, @file{acconfig.h}, contained the 22873list of needed templates. @command{autoheader} copied comments and 22874@code{#define} and @code{#undef} statements from @file{acconfig.h} in 22875the current directory, if present. This file used to be mandatory if 22876you @code{AC_DEFINE} any additional symbols. 22877 22878Modern releases of Autoconf also provide @code{AH_TOP} and 22879@code{AH_BOTTOM} if you need to prepend/append some information to 22880@file{config.h.in}. Ancient versions of Autoconf had a similar feature: 22881if @file{./acconfig.h} contains the string @samp{@@TOP@@}, 22882@command{autoheader} copies the lines before the line containing 22883@samp{@@TOP@@} into the top of the file that it generates. Similarly, 22884if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@}, 22885@command{autoheader} copies the lines after that line to the end of the 22886file it generates. Either or both of those strings may be omitted. An 22887even older alternate way to produce the same effect in ancient versions 22888of Autoconf is to create the files @file{@var{file}.top} (typically 22889@file{config.h.top}) and/or @file{@var{file}.bot} in the current 22890directory. If they exist, @command{autoheader} copies them to the 22891beginning and end, respectively, of its output. 22892 22893In former versions of Autoconf, the files used in preparing a software 22894package for distribution were: 22895@example 22896@group 22897configure.ac --. .------> autoconf* -----> configure 22898 +---+ 22899[aclocal.m4] --+ `---. 22900[acsite.m4] ---' | 22901 +--> [autoheader*] -> [config.h.in] 22902[acconfig.h] ----. | 22903 +-----' 22904[config.h.top] --+ 22905[config.h.bot] --' 22906@end group 22907@end example 22908 22909Using only the @code{AH_} macros, @file{configure.ac} should be 22910self-contained, and should not depend upon @file{acconfig.h} etc. 22911 22912 22913@node autoupdate Invocation 22914@section Using @command{autoupdate} to Modernize @file{configure.ac} 22915@cindex @command{autoupdate} 22916 22917The @command{autoupdate} program updates a @file{configure.ac} file that 22918calls Autoconf macros by their old names to use the current macro names. 22919In version 2 of Autoconf, most of the macros were renamed to use a more 22920uniform and descriptive naming scheme. @xref{Macro Names}, for a 22921description of the new scheme. Although the old names still work 22922(@pxref{Obsolete Macros}, for a list of the old macros and the corresponding 22923new names), you can make your @file{configure.ac} files more readable 22924and make it easier to use the current Autoconf documentation if you 22925update them to use the new macro names. 22926 22927@evindex SIMPLE_BACKUP_SUFFIX 22928If given no arguments, @command{autoupdate} updates @file{configure.ac}, 22929backing up the original version with the suffix @file{~} (or the value 22930of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is 22931set). If you give @command{autoupdate} an argument, it reads that file 22932instead of @file{configure.ac} and writes the updated file to the 22933standard output. 22934 22935@noindent 22936@command{autoupdate} accepts the following options: 22937 22938@table @option 22939@item --help 22940@itemx -h 22941Print a summary of the command line options and exit. 22942 22943@item --version 22944@itemx -V 22945Print the version number of Autoconf and exit. 22946 22947@item --verbose 22948@itemx -v 22949Report processing steps. 22950 22951@item --debug 22952@itemx -d 22953Don't remove the temporary files. 22954 22955@item --force 22956@itemx -f 22957Force the update even if the file has not changed. Disregard the cache. 22958 22959@item --include=@var{dir} 22960@itemx -I @var{dir} 22961Also look for input files in @var{dir}. Multiple invocations accumulate. 22962Directories are browsed from last to first. 22963 22964@item --prepend-include=@var{dir} 22965@itemx -B @var{dir} 22966Prepend directory @var{dir} to the search path. This is used to include 22967the language-specific files before any third-party macros. 22968@end table 22969 22970@node Obsolete Macros 22971@section Obsolete Macros 22972 22973Several macros are obsoleted in Autoconf, for various reasons (typically 22974they failed to quote properly, couldn't be extended for more recent 22975issues, etc.). They are still supported, but deprecated: their use 22976should be avoided. 22977 22978During the jump from Autoconf version 1 to version 2, most of the 22979macros were renamed to use a more uniform and descriptive naming scheme, 22980but their signature did not change. @xref{Macro Names}, for a 22981description of the new naming scheme. Below, if there is just the mapping 22982from old names to new names for these macros, the reader is invited to 22983refer to the definition of the new macro for the signature and the 22984description. 22985 22986@defmac AC_AIX 22987@acindex{AIX} 22988@cvindex _ALL_SOURCE 22989This macro is a platform-specific subset of 22990@code{AC_USE_SYSTEM_EXTENSIONS} (@pxref{AC_USE_SYSTEM_EXTENSIONS}). 22991@end defmac 22992 22993@defmac AC_ALLOCA 22994@acindex{ALLOCA} 22995Replaced by @code{AC_FUNC_ALLOCA} (@pxref{AC_FUNC_ALLOCA}). 22996@end defmac 22997 22998@defmac AC_ARG_ARRAY 22999@acindex{ARG_ARRAY} 23000Removed because of limited usefulness. 23001@end defmac 23002 23003@defmac AC_C_CROSS 23004@acindex{C_CROSS} 23005This macro is obsolete; it does nothing. 23006@end defmac 23007 23008@defmac AC_C_LONG_DOUBLE 23009@acindex{C_LONG_DOUBLE} 23010@cvindex HAVE_LONG_DOUBLE 23011If the C compiler supports a working @code{long double} type with more 23012range or precision than the @code{double} type, define 23013@code{HAVE_LONG_DOUBLE}. 23014 23015You should use @code{AC_TYPE_LONG_DOUBLE} or 23016@code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}. 23017@end defmac 23018 23019@defmac AC_CANONICAL_SYSTEM 23020@acindex{CANONICAL_SYSTEM} 23021Determine the system type and set output variables to the names of the 23022canonical system types. @xref{Canonicalizing}, for details about the 23023variables this macro sets. 23024 23025The user is encouraged to use either @code{AC_CANONICAL_BUILD}, or 23026@code{AC_CANONICAL_HOST}, or @code{AC_CANONICAL_TARGET}, depending on 23027the needs. Using @code{AC_CANONICAL_TARGET} is enough to run the two 23028other macros (@pxref{Canonicalizing}). 23029@end defmac 23030 23031@defmac AC_CHAR_UNSIGNED 23032@acindex{CHAR_UNSIGNED} 23033Replaced by @code{AC_C_CHAR_UNSIGNED} (@pxref{AC_C_CHAR_UNSIGNED}). 23034@end defmac 23035 23036@defmac AC_CHECK_TYPE (@var{type}, @var{default}) 23037@acindex{CHECK_TYPE} 23038Autoconf, up to 2.13, used to provide this version of 23039@code{AC_CHECK_TYPE}, deprecated because of its flaws. First, although 23040it is a member of the @code{CHECK} clan, it does 23041more than just checking. Secondly, missing types are defined 23042using @code{#define}, not @code{typedef}, and this can lead to 23043problems in the case of pointer types. 23044 23045This use of @code{AC_CHECK_TYPE} is obsolete and discouraged; see 23046@ref{Generic Types}, for the description of the current macro. 23047 23048If the type @var{type} is not defined, define it to be the C (or C++) 23049builtin type @var{default}, e.g., @samp{short int} or @samp{unsigned int}. 23050 23051This macro is equivalent to: 23052 23053@example 23054AC_CHECK_TYPE([@var{type}], [], 23055 [AC_DEFINE_UNQUOTED([@var{type}], [@var{default}], 23056 [Define to `@var{default}' 23057 if <sys/types.h> does not define.])]) 23058@end example 23059 23060In order to keep backward compatibility, the two versions of 23061@code{AC_CHECK_TYPE} are implemented, selected using these heuristics: 23062 23063@enumerate 23064@item 23065If there are three or four arguments, the modern version is used. 23066 23067@item 23068If the second argument appears to be a C or C++ type, then the 23069obsolete version is used. This happens if the argument is a C or C++ 23070@emph{builtin} type or a C identifier ending in @samp{_t}, optionally 23071followed by one of @samp{[(* } and then by a string of zero or more 23072characters taken from the set @samp{[]()* _a-zA-Z0-9}. 23073 23074@item 23075If the second argument is spelled with the alphabet of valid C and C++ 23076types, the user is warned and the modern version is used. 23077 23078@item 23079Otherwise, the modern version is used. 23080@end enumerate 23081 23082@noindent 23083You are encouraged either to use a valid builtin type, or to use the 23084equivalent modern code (see above), or better yet, to use 23085@code{AC_CHECK_TYPES} together with 23086 23087@example 23088#ifndef HAVE_LOFF_T 23089typedef loff_t off_t; 23090#endif 23091@end example 23092@end defmac 23093@c end of AC_CHECK_TYPE 23094 23095@defmac AC_CHECKING (@var{feature-description}) 23096@acindex{CHECKING} 23097Same as 23098 23099@example 23100AC_MSG_NOTICE([checking @var{feature-description}@dots{}] 23101@end example 23102 23103@noindent 23104@xref{AC_MSG_NOTICE}. 23105@end defmac 23106 23107@defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @ 23108 @var{function-body}, @var{action-if-true}, @ovar{action-if-false}) 23109@acindex{COMPILE_CHECK} 23110This is an obsolete version of @code{AC_TRY_COMPILE} itself replaced by 23111@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}), with the 23112addition that it prints @samp{checking for @var{echo-text}} to the 23113standard output first, if @var{echo-text} is non-empty. Use 23114@code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT} instead to print 23115messages (@pxref{Printing Messages}). 23116@end defmac 23117 23118@defmac AC_CONST 23119@acindex{CONST} 23120Replaced by @code{AC_C_CONST} (@pxref{AC_C_CONST}). 23121@end defmac 23122 23123@defmac AC_CROSS_CHECK 23124@acindex{CROSS_CHECK} 23125Same as @code{AC_C_CROSS}, which is obsolete too, and does nothing 23126@code{:-)}. 23127@end defmac 23128 23129@defmac AC_CYGWIN 23130@acindex{CYGWIN} 23131@evindex CYGWIN 23132Check for the Cygwin environment in which case the shell variable 23133@code{CYGWIN} is set to @samp{yes}. Don't use this macro, the dignified 23134means to check the nature of the host is using @code{AC_CANONICAL_HOST} 23135(@pxref{Canonicalizing}). As a matter of fact this macro is defined as: 23136 23137@example 23138AC_REQUIRE([AC_CANONICAL_HOST])[]dnl 23139case $host_os in 23140 *cygwin* ) CYGWIN=yes;; 23141 * ) CYGWIN=no;; 23142esac 23143@end example 23144 23145Beware that the variable @env{CYGWIN} has a special meaning when 23146running Cygwin, and should not be changed. That's yet another reason 23147not to use this macro. 23148@end defmac 23149 23150@defmac AC_DECL_SYS_SIGLIST 23151@acindex{DECL_SYS_SIGLIST} 23152@cvindex SYS_SIGLIST_DECLARED 23153Same as: 23154 23155@example 23156AC_CHECK_DECLS([sys_siglist], [], [], 23157[#include <signal.h> 23158/* NetBSD declares sys_siglist in unistd.h. */ 23159#ifdef HAVE_UNISTD_H 23160# include <unistd.h> 23161#endif 23162]) 23163@end example 23164 23165@noindent 23166@xref{AC_CHECK_DECLS}. 23167@end defmac 23168 23169@defmac AC_DECL_YYTEXT 23170@acindex{DECL_YYTEXT} 23171Does nothing, now integrated in @code{AC_PROG_LEX} (@pxref{AC_PROG_LEX}). 23172@end defmac 23173 23174@defmac AC_DIR_HEADER 23175@acindex{DIR_HEADER} 23176@cvindex DIRENT 23177@cvindex SYSNDIR 23178@cvindex SYSDIR 23179@cvindex NDIR 23180Like calling @code{AC_FUNC_CLOSEDIR_VOID} 23181(@pxref{AC_FUNC_CLOSEDIR_VOID}) and @code{AC_HEADER_DIRENT} 23182(@pxref{AC_HEADER_DIRENT}), 23183but defines a different set of C preprocessor macros to indicate which 23184header file is found: 23185 23186@multitable {@file{sys/ndir.h}} {Old Symbol} {@code{HAVE_SYS_NDIR_H}} 23187@item Header @tab Old Symbol @tab New Symbol 23188@item @file{dirent.h} @tab @code{DIRENT} @tab @code{HAVE_DIRENT_H} 23189@item @file{sys/ndir.h} @tab @code{SYSNDIR} @tab @code{HAVE_SYS_NDIR_H} 23190@item @file{sys/dir.h} @tab @code{SYSDIR} @tab @code{HAVE_SYS_DIR_H} 23191@item @file{ndir.h} @tab @code{NDIR} @tab @code{HAVE_NDIR_H} 23192@end multitable 23193@end defmac 23194 23195@defmac AC_DYNIX_SEQ 23196@acindex{DYNIX_SEQ} 23197If on DYNIX/ptx, add @option{-lseq} to output variable 23198@code{LIBS}. This macro used to be defined as 23199 23200@example 23201AC_CHECK_LIB([seq], [getmntent], [LIBS="-lseq $LIBS"]) 23202@end example 23203 23204@noindent 23205now it is just @code{AC_FUNC_GETMNTENT} (@pxref{AC_FUNC_GETMNTENT}). 23206@end defmac 23207 23208@defmac AC_EXEEXT 23209@acindex{EXEEXT} 23210@ovindex EXEEXT 23211Defined the output variable @code{EXEEXT} based on the output of the 23212compiler, which is now done automatically. Typically set to empty 23213string if Posix and @samp{.exe} if a DOS variant. 23214@end defmac 23215 23216@defmac AC_EMXOS2 23217@acindex{EMXOS2} 23218Similar to @code{AC_CYGWIN} but checks for the EMX environment on OS/2 23219and sets @code{EMXOS2}. Don't use this macro, the dignified means to 23220check the nature of the host is using @code{AC_CANONICAL_HOST} 23221(@pxref{Canonicalizing}). 23222@end defmac 23223 23224@defmac AC_ENABLE (@var{feature}, @var{action-if-given}, @ 23225 @ovar{action-if-not-given}) 23226@acindex{ENABLE} 23227This is an obsolete version of @code{AC_ARG_ENABLE} that does not 23228support providing a help string (@pxref{AC_ARG_ENABLE}). 23229@end defmac 23230 23231@defmac AC_ERROR 23232@acindex{ERROR} 23233Replaced by @code{AC_MSG_ERROR} (@pxref{AC_MSG_ERROR}). 23234@end defmac 23235 23236@defmac AC_FIND_X 23237@acindex{FIND_X} 23238Replaced by @code{AC_PATH_X} (@pxref{AC_PATH_X}). 23239@end defmac 23240 23241@defmac AC_FIND_XTRA 23242@acindex{FIND_XTRA} 23243Replaced by @code{AC_PATH_XTRA} (@pxref{AC_PATH_XTRA}). 23244@end defmac 23245 23246@defmac AC_FOREACH 23247@acindex{FOREACH} 23248Replaced by @code{m4_foreach_w} (@pxref{m4_foreach_w}). 23249@end defmac 23250 23251@defmac AC_FUNC_CHECK 23252@acindex{FUNC_CHECK} 23253Replaced by @code{AC_CHECK_FUNC} (@pxref{AC_CHECK_FUNC}). 23254@end defmac 23255 23256@anchor{AC_FUNC_SETVBUF_REVERSED} 23257@defmac AC_FUNC_SETVBUF_REVERSED 23258@acindex{FUNC_SETVBUF_REVERSED} 23259@cvindex SETVBUF_REVERSED 23260@c @fuindex setvbuf 23261@prindex @code{setvbuf} 23262Do nothing. Formerly, this macro checked whether @code{setvbuf} takes 23263the buffering type as its second argument and the buffer pointer as the 23264third, instead of the other way around, and defined 23265@code{SETVBUF_REVERSED}. However, the last systems to have the problem 23266were those based on SVR2, which became obsolete in 1987, and the macro 23267is no longer needed. 23268@end defmac 23269 23270@defmac AC_FUNC_WAIT3 23271@acindex{FUNC_WAIT3} 23272@cvindex HAVE_WAIT3 23273@c @fuindex wait3 23274@prindex @code{wait3} 23275If @code{wait3} is found and fills in the contents of its third argument 23276(a @samp{struct rusage *}), which HP-UX does not do, define 23277@code{HAVE_WAIT3}. 23278 23279These days portable programs should use @code{waitpid}, not 23280@code{wait3}, as @code{wait3} has been removed from Posix. 23281@end defmac 23282 23283@defmac AC_GCC_TRADITIONAL 23284@acindex{GCC_TRADITIONAL} 23285Replaced by @code{AC_PROG_GCC_TRADITIONAL} (@pxref{AC_PROG_GCC_TRADITIONAL}). 23286@end defmac 23287 23288@defmac AC_GETGROUPS_T 23289@acindex{GETGROUPS_T} 23290Replaced by @code{AC_TYPE_GETGROUPS} (@pxref{AC_TYPE_GETGROUPS}). 23291@end defmac 23292 23293@defmac AC_GETLOADAVG 23294@acindex{GETLOADAVG} 23295Replaced by @code{AC_FUNC_GETLOADAVG} (@pxref{AC_FUNC_GETLOADAVG}). 23296@end defmac 23297 23298@defmac AC_GNU_SOURCE 23299@acindex{GNU_SOURCE} 23300@cvindex _GNU_SOURCE 23301This macro is a platform-specific subset of 23302@code{AC_USE_SYSTEM_EXTENSIONS} (@pxref{AC_USE_SYSTEM_EXTENSIONS}). 23303@end defmac 23304 23305@defmac AC_HAVE_FUNCS 23306@acindex{HAVE_FUNCS} 23307Replaced by @code{AC_CHECK_FUNCS} (@pxref{AC_CHECK_FUNCS}). 23308@end defmac 23309 23310@defmac AC_HAVE_HEADERS 23311@acindex{HAVE_HEADERS} 23312Replaced by @code{AC_CHECK_HEADERS} (@pxref{AC_CHECK_HEADERS}). 23313@end defmac 23314 23315@defmac AC_HAVE_LIBRARY (@var{library}, @ovar{action-if-found}, @ 23316 @ovar{action-if-not-found}, @ovar{other-libraries}) 23317@acindex{HAVE_LIBRARY} 23318This macro is equivalent to calling @code{AC_CHECK_LIB} with a 23319@var{function} argument of @code{main}. In addition, @var{library} can 23320be written as any of @samp{foo}, @option{-lfoo}, or @samp{libfoo.a}. In 23321all of those cases, the compiler is passed @option{-lfoo}. However, 23322@var{library} cannot be a shell variable; it must be a literal name. 23323@xref{AC_CHECK_LIB}. 23324@end defmac 23325 23326@defmac AC_HAVE_POUNDBANG 23327@acindex{HAVE_POUNDBANG} 23328Replaced by @code{AC_SYS_INTERPRETER} (@pxref{AC_SYS_INTERPRETER}). 23329@end defmac 23330 23331@defmac AC_HEADER_CHECK 23332@acindex{HEADER_CHECK} 23333Replaced by @code{AC_CHECK_HEADER} (@pxref{AC_CHECK_HEADER}). 23334@end defmac 23335 23336@defmac AC_HEADER_EGREP 23337@acindex{HEADER_EGREP} 23338Replaced by @code{AC_EGREP_HEADER} (@pxref{AC_EGREP_HEADER}). 23339@end defmac 23340 23341@defmac AC_HELP_STRING 23342@acindex{HELP_STRING} 23343Replaced by @code{AS_HELP_STRING} (@pxref{AS_HELP_STRING}). 23344@end defmac 23345 23346@defmac AC_INIT (@var{unique-file-in-source-dir}) 23347@acindex{INIT} 23348Formerly @code{AC_INIT} used to have a single argument, and was 23349equivalent to: 23350 23351@example 23352AC_INIT 23353AC_CONFIG_SRCDIR(@var{unique-file-in-source-dir}) 23354@end example 23355See @ref{AC_INIT} and @ref{AC_CONFIG_SRCDIR}. 23356@end defmac 23357 23358@defmac AC_INLINE 23359@acindex{INLINE} 23360Replaced by @code{AC_C_INLINE} (@pxref{AC_C_INLINE}). 23361@end defmac 23362 23363@defmac AC_INT_16_BITS 23364@acindex{INT_16_BITS} 23365@cvindex INT_16_BITS 23366If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}. 23367Use @samp{AC_CHECK_SIZEOF(int)} instead (@pxref{AC_CHECK_SIZEOF}). 23368@end defmac 23369 23370@defmac AC_IRIX_SUN 23371@acindex{IRIX_SUN} 23372If on IRIX (Silicon Graphics Unix), add @option{-lsun} to output 23373@code{LIBS}. If you were using it to get @code{getmntent}, use 23374@code{AC_FUNC_GETMNTENT} instead. If you used it for the NIS versions 23375of the password and group functions, use @samp{AC_CHECK_LIB(sun, 23376getpwnam)}. Up to Autoconf 2.13, it used to be 23377 23378@example 23379AC_CHECK_LIB([sun], [getmntent], [LIBS="-lsun $LIBS"]) 23380@end example 23381 23382@noindent 23383now it is defined as 23384 23385@example 23386AC_FUNC_GETMNTENT 23387AC_CHECK_LIB([sun], [getpwnam]) 23388@end example 23389 23390@noindent 23391See @ref{AC_FUNC_GETMNTENT} and @ref{AC_CHECK_LIB}. 23392@end defmac 23393 23394@defmac AC_ISC_POSIX 23395@acindex{ISC_POSIX} 23396@ovindex LIBS 23397This macro adds @option{-lcposix} to output variable @code{LIBS} if 23398necessary for Posix facilities. Sun dropped support for the obsolete 23399INTERACTIVE Systems Corporation Unix on 2006-07-23. New programs 23400need not use this macro. It is implemented as 23401@code{AC_SEARCH_LIBS([strerror], [cposix])} (@pxref{AC_SEARCH_LIBS}). 23402@end defmac 23403 23404@defmac AC_LANG_C 23405@acindex{LANG_C} 23406Same as @samp{AC_LANG([C])} (@pxref{AC_LANG}). 23407@end defmac 23408 23409@defmac AC_LANG_CPLUSPLUS 23410@acindex{LANG_CPLUSPLUS} 23411Same as @samp{AC_LANG([C++])} (@pxref{AC_LANG}). 23412@end defmac 23413 23414@defmac AC_LANG_FORTRAN77 23415@acindex{LANG_FORTRAN77} 23416Same as @samp{AC_LANG([Fortran 77])} (@pxref{AC_LANG}). 23417@end defmac 23418 23419@defmac AC_LANG_RESTORE 23420@acindex{LANG_RESTORE} 23421Select the @var{language} that is saved on the top of the stack, as set 23422by @code{AC_LANG_SAVE}, remove it from the stack, and call 23423@code{AC_LANG(@var{language})}. @xref{Language Choice}, for the 23424preferred way to change languages. 23425@end defmac 23426 23427@defmac AC_LANG_SAVE 23428@acindex{LANG_SAVE} 23429Remember the current language (as set by @code{AC_LANG}) on a stack. 23430The current language does not change. @code{AC_LANG_PUSH} is preferred 23431(@pxref{AC_LANG_PUSH}). 23432@end defmac 23433 23434@defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{}) 23435@acindex{LINK_FILES} 23436This is an obsolete version of @code{AC_CONFIG_LINKS} 23437(@pxref{AC_CONFIG_LINKS}. An updated version of: 23438 23439@example 23440AC_LINK_FILES(config/$machine.h config/$obj_format.h, 23441 host.h object.h) 23442@end example 23443 23444@noindent 23445is: 23446 23447@example 23448AC_CONFIG_LINKS([host.h:config/$machine.h 23449 object.h:config/$obj_format.h]) 23450@end example 23451@end defmac 23452 23453@defmac AC_LN_S 23454@acindex{LN_S} 23455Replaced by @code{AC_PROG_LN_S} (@pxref{AC_PROG_LN_S}). 23456@end defmac 23457 23458@defmac AC_LONG_64_BITS 23459@acindex{LONG_64_BITS} 23460@cvindex LONG_64_BITS 23461Define @code{LONG_64_BITS} if the C type @code{long int} is 64 bits wide. 23462Use the generic macro @samp{AC_CHECK_SIZEOF([long int])} instead 23463(@pxref{AC_CHECK_SIZEOF}). 23464@end defmac 23465 23466@defmac AC_LONG_DOUBLE 23467@acindex{LONG_DOUBLE} 23468If the C compiler supports a working @code{long double} type with more 23469range or precision than the @code{double} type, define 23470@code{HAVE_LONG_DOUBLE}. 23471 23472You should use @code{AC_TYPE_LONG_DOUBLE} or 23473@code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}. 23474@end defmac 23475 23476@defmac AC_LONG_FILE_NAMES 23477@acindex{LONG_FILE_NAMES} 23478Replaced by 23479@example 23480AC_SYS_LONG_FILE_NAMES 23481@end example 23482@noindent 23483@xref{AC_SYS_LONG_FILE_NAMES}. 23484@end defmac 23485 23486@defmac AC_MAJOR_HEADER 23487@acindex{MAJOR_HEADER} 23488Replaced by @code{AC_HEADER_MAJOR} (@pxref{AC_HEADER_MAJOR}). 23489@end defmac 23490 23491@defmac AC_MEMORY_H 23492@acindex{MEMORY_H} 23493@cvindex NEED_MEMORY_H 23494Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were 23495defined in @file{memory.h}. Today it is equivalent to 23496@samp{AC_CHECK_HEADERS([memory.h])} (@pxref{AC_CHECK_HEADERS}). Adjust 23497your code to depend upon 23498@code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}; see @ref{Standard 23499Symbols}. 23500@end defmac 23501 23502@defmac AC_MINGW32 23503@acindex{MINGW32} 23504Similar to @code{AC_CYGWIN} but checks for the MinGW compiler 23505environment and sets @code{MINGW32}. Don't use this macro, the 23506dignified means to check the nature of the host is using 23507@code{AC_CANONICAL_HOST} (@pxref{Canonicalizing}). 23508@end defmac 23509 23510@defmac AC_MINIX 23511@acindex{MINIX} 23512@cvindex _MINIX 23513@cvindex _POSIX_SOURCE 23514@cvindex _POSIX_1_SOURCE 23515This macro is a platform-specific subset of 23516@code{AC_USE_SYSTEM_EXTENSIONS} (@pxref{AC_USE_SYSTEM_EXTENSIONS}). 23517@end defmac 23518 23519@defmac AC_MINUS_C_MINUS_O 23520@acindex{MINUS_C_MINUS_O} 23521Replaced by @code{AC_PROG_CC_C_O} (@pxref{AC_PROG_CC_C_O}). 23522@end defmac 23523 23524@defmac AC_MMAP 23525@acindex{MMAP} 23526Replaced by @code{AC_FUNC_MMAP} (@pxref{AC_FUNC_MMAP}). 23527@end defmac 23528 23529@defmac AC_MODE_T 23530@acindex{MODE_T} 23531Replaced by @code{AC_TYPE_MODE_T} (@pxref{AC_TYPE_MODE_T}). 23532@end defmac 23533 23534@defmac AC_OBJEXT 23535@acindex{OBJEXT} 23536@ovindex OBJEXT 23537Defined the output variable @code{OBJEXT} based on the output of the 23538compiler, after .c files have been excluded. Typically set to @samp{o} 23539if Posix, @samp{obj} if a DOS variant. 23540Now the compiler checking macros handle 23541this automatically. 23542@end defmac 23543 23544@defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion}) 23545@acindex{OBSOLETE} 23546Make M4 print a message to the standard error output warning that 23547@var{this-macro-name} is obsolete, and giving the file and line number 23548where it was called. @var{this-macro-name} should be the name of the 23549macro that is calling @code{AC_OBSOLETE}. If @var{suggestion} is given, 23550it is printed at the end of the warning message; for example, it can be 23551a suggestion for what to use instead of @var{this-macro-name}. 23552 23553For instance 23554 23555@example 23556AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl 23557@end example 23558 23559@noindent 23560You are encouraged to use @code{AU_DEFUN} instead, since it gives better 23561services to the user (@pxref{AU_DEFUN}). 23562@end defmac 23563 23564@defmac AC_OFF_T 23565@acindex{OFF_T} 23566Replaced by @code{AC_TYPE_OFF_T} (@pxref{AC_TYPE_OFF_T}). 23567@end defmac 23568 23569@defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds}) 23570@acindex{OUTPUT} 23571The use of @code{AC_OUTPUT} with arguments is deprecated. This obsoleted 23572interface is equivalent to: 23573 23574@example 23575@group 23576AC_CONFIG_FILES(@var{file}@dots{}) 23577AC_CONFIG_COMMANDS([default], 23578 @var{extra-cmds}, @var{init-cmds}) 23579AC_OUTPUT 23580@end group 23581@end example 23582 23583@noindent 23584See @ref{AC_CONFIG_FILES}, @ref{AC_CONFIG_COMMANDS}, and @ref{AC_OUTPUT}. 23585@end defmac 23586 23587@defmac AC_OUTPUT_COMMANDS (@var{extra-cmds}, @ovar{init-cmds}) 23588@acindex{OUTPUT_COMMANDS} 23589Specify additional shell commands to run at the end of 23590@file{config.status}, and shell commands to initialize any variables 23591from @command{configure}. This macro may be called multiple times. It is 23592obsolete, replaced by @code{AC_CONFIG_COMMANDS} (@pxref{AC_CONFIG_COMMANDS}). 23593 23594Here is an unrealistic example: 23595 23596@example 23597fubar=27 23598AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.], 23599 [fubar=$fubar]) 23600AC_OUTPUT_COMMANDS([echo this is another, extra, bit], 23601 [echo init bit]) 23602@end example 23603 23604Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an 23605additional key, an important difference is that 23606@code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, unlike 23607@code{AC_CONFIG_COMMANDS}. This means that @code{AC_CONFIG_COMMANDS} 23608can safely be given macro calls as arguments: 23609 23610@example 23611AC_CONFIG_COMMANDS(foo, [my_FOO()]) 23612@end example 23613 23614@noindent 23615Conversely, where one level of quoting was enough for literal strings 23616with @code{AC_OUTPUT_COMMANDS}, you need two with 23617@code{AC_CONFIG_COMMANDS}. The following lines are equivalent: 23618 23619@example 23620@group 23621AC_OUTPUT_COMMANDS([echo "Square brackets: []"]) 23622AC_CONFIG_COMMANDS([default], [[echo "Square brackets: []"]]) 23623@end group 23624@end example 23625@end defmac 23626 23627@defmac AC_PID_T 23628@acindex{PID_T} 23629Replaced by @code{AC_TYPE_PID_T} (@pxref{AC_TYPE_PID_T}). 23630@end defmac 23631 23632@defmac AC_PREFIX 23633@acindex{PREFIX} 23634Replaced by @code{AC_PREFIX_PROGRAM} (@pxref{AC_PREFIX_PROGRAM}). 23635@end defmac 23636 23637@defmac AC_PROGRAMS_CHECK 23638@acindex{PROGRAMS_CHECK} 23639Replaced by @code{AC_CHECK_PROGS} (@pxref{AC_CHECK_PROGS}). 23640@end defmac 23641 23642@defmac AC_PROGRAMS_PATH 23643@acindex{PROGRAMS_PATH} 23644Replaced by @code{AC_PATH_PROGS} (@pxref{AC_PATH_PROGS}). 23645@end defmac 23646 23647@defmac AC_PROGRAM_CHECK 23648@acindex{PROGRAM_CHECK} 23649Replaced by @code{AC_CHECK_PROG} (@pxref{AC_CHECK_PROG}). 23650@end defmac 23651 23652@defmac AC_PROGRAM_EGREP 23653@acindex{PROGRAM_EGREP} 23654Replaced by @code{AC_EGREP_CPP} (@pxref{AC_EGREP_CPP}). 23655@end defmac 23656 23657@defmac AC_PROGRAM_PATH 23658@acindex{PROGRAM_PATH} 23659Replaced by @code{AC_PATH_PROG} (@pxref{AC_PATH_PROG}). 23660@end defmac 23661 23662@defmac AC_REMOTE_TAPE 23663@acindex{REMOTE_TAPE} 23664Removed because of limited usefulness. 23665@end defmac 23666 23667@defmac AC_RESTARTABLE_SYSCALLS 23668@acindex{RESTARTABLE_SYSCALLS} 23669This macro was renamed @code{AC_SYS_RESTARTABLE_SYSCALLS}. However, 23670these days portable programs should use @code{sigaction} with 23671@code{SA_RESTART} if they want restartable system calls. They should 23672not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a 23673system call is restartable is a dynamic issue, not a configuration-time 23674issue. 23675@end defmac 23676 23677@defmac AC_RETSIGTYPE 23678@acindex{RETSIGTYPE} 23679Replaced by @code{AC_TYPE_SIGNAL} (@pxref{AC_TYPE_SIGNAL}), which itself 23680is obsolete when assuming C89 or better. 23681@end defmac 23682 23683@defmac AC_RSH 23684@acindex{RSH} 23685Removed because of limited usefulness. 23686@end defmac 23687 23688@defmac AC_SCO_INTL 23689@acindex{SCO_INTL} 23690@ovindex LIBS 23691If on SCO Unix, add @option{-lintl} to output variable @code{LIBS}. This 23692macro used to do this: 23693 23694@example 23695AC_CHECK_LIB([intl], [strftime], [LIBS="-lintl $LIBS"]) 23696@end example 23697 23698@noindent 23699Now it just calls @code{AC_FUNC_STRFTIME} instead (@pxref{AC_FUNC_STRFTIME}). 23700@end defmac 23701 23702@defmac AC_SETVBUF_REVERSED 23703@acindex{SETVBUF_REVERSED} 23704Replaced by 23705@example 23706AC_FUNC_SETVBUF_REVERSED 23707@end example 23708@noindent 23709@xref{AC_FUNC_SETVBUF_REVERSED}. 23710@end defmac 23711 23712@defmac AC_SET_MAKE 23713@acindex{SET_MAKE} 23714Replaced by @code{AC_PROG_MAKE_SET} (@pxref{AC_PROG_MAKE_SET}). 23715@end defmac 23716 23717@defmac AC_SIZEOF_TYPE 23718@acindex{SIZEOF_TYPE} 23719Replaced by @code{AC_CHECK_SIZEOF} (@pxref{AC_CHECK_SIZEOF}). 23720@end defmac 23721 23722@defmac AC_SIZE_T 23723@acindex{SIZE_T} 23724Replaced by @code{AC_TYPE_SIZE_T} (@pxref{AC_TYPE_SIZE_T}). 23725@end defmac 23726 23727@defmac AC_STAT_MACROS_BROKEN 23728@acindex{STAT_MACROS_BROKEN} 23729Replaced by @code{AC_HEADER_STAT} (@pxref{AC_HEADER_STAT}). 23730@end defmac 23731 23732@defmac AC_STDC_HEADERS 23733@acindex{STDC_HEADERS} 23734Replaced by @code{AC_HEADER_STDC} (@pxref{AC_HEADER_STDC}). 23735@end defmac 23736 23737@defmac AC_STRCOLL 23738@acindex{STRCOLL} 23739Replaced by @code{AC_FUNC_STRCOLL} (@pxref{AC_FUNC_STRCOLL}). 23740@end defmac 23741 23742@defmac AC_STRUCT_ST_BLKSIZE 23743@acindex{STRUCT_ST_BLKSIZE} 23744@cvindex HAVE_STRUCT_STAT_ST_BLKSIZE 23745@cvindex HAVE_ST_BLKSIZE 23746If @code{struct stat} contains an @code{st_blksize} member, define 23747@code{HAVE_STRUCT_STAT_ST_BLKSIZE}. The former name, 23748@code{HAVE_ST_BLKSIZE} is to be avoided, as its support will cease in 23749the future. This macro is obsoleted, and should be replaced by 23750 23751@example 23752AC_CHECK_MEMBERS([struct stat.st_blksize]) 23753@end example 23754@noindent 23755@xref{AC_CHECK_MEMBERS}. 23756@end defmac 23757 23758@defmac AC_STRUCT_ST_RDEV 23759@acindex{STRUCT_ST_RDEV} 23760@cvindex HAVE_ST_RDEV 23761@cvindex HAVE_STRUCT_STAT_ST_RDEV 23762If @code{struct stat} contains an @code{st_rdev} member, define 23763@code{HAVE_STRUCT_STAT_ST_RDEV}. The former name for this macro, 23764@code{HAVE_ST_RDEV}, is to be avoided as it will cease to be supported 23765in the future. Actually, even the new macro is obsolete and should be 23766replaced by: 23767@example 23768AC_CHECK_MEMBERS([struct stat.st_rdev]) 23769@end example 23770@noindent 23771@xref{AC_CHECK_MEMBERS}. 23772@end defmac 23773 23774@defmac AC_ST_BLKSIZE 23775@acindex{ST_BLKSIZE} 23776Replaced by @code{AC_CHECK_MEMBERS} (@pxref{AC_CHECK_MEMBERS}). 23777@end defmac 23778 23779@defmac AC_ST_BLOCKS 23780@acindex{ST_BLOCKS} 23781Replaced by @code{AC_STRUCT_ST_BLOCKS} (@pxref{AC_STRUCT_ST_BLOCKS}). 23782@end defmac 23783 23784@defmac AC_ST_RDEV 23785@acindex{ST_RDEV} 23786Replaced by @code{AC_CHECK_MEMBERS} (@pxref{AC_CHECK_MEMBERS}). 23787@end defmac 23788 23789@defmac AC_SYS_RESTARTABLE_SYSCALLS 23790@acindex{SYS_RESTARTABLE_SYSCALLS} 23791@cvindex HAVE_RESTARTABLE_SYSCALLS 23792If the system automatically restarts a system call that is interrupted 23793by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}. This macro does 23794not check whether system calls are restarted in general---it checks whether a 23795signal handler installed with @code{signal} (but not @code{sigaction}) 23796causes system calls to be restarted. It does not check whether system calls 23797can be restarted when interrupted by signals that have no handler. 23798 23799These days portable programs should use @code{sigaction} with 23800@code{SA_RESTART} if they want restartable system calls. They should 23801not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a 23802system call is restartable is a dynamic issue, not a configuration-time 23803issue. 23804@end defmac 23805 23806@defmac AC_SYS_SIGLIST_DECLARED 23807@acindex{SYS_SIGLIST_DECLARED} 23808This macro was renamed @code{AC_DECL_SYS_SIGLIST}. However, even that 23809name is obsolete, as the same functionality is now achieved via 23810@code{AC_CHECK_DECLS} (@pxref{AC_CHECK_DECLS}). 23811@end defmac 23812 23813@defmac AC_TEST_CPP 23814@acindex{TEST_CPP} 23815This macro was renamed @code{AC_TRY_CPP}, which in turn was replaced by 23816@code{AC_PREPROC_IFELSE} (@pxref{AC_PREPROC_IFELSE}). 23817@end defmac 23818 23819@defmac AC_TEST_PROGRAM 23820@acindex{TEST_PROGRAM} 23821This macro was renamed @code{AC_TRY_RUN}, which in turn was replaced by 23822@code{AC_RUN_IFELSE} (@pxref{AC_RUN_IFELSE}). 23823@end defmac 23824 23825@defmac AC_TIMEZONE 23826@acindex{TIMEZONE} 23827Replaced by @code{AC_STRUCT_TIMEZONE} (@pxref{AC_STRUCT_TIMEZONE}). 23828@end defmac 23829 23830@defmac AC_TIME_WITH_SYS_TIME 23831@acindex{TIME_WITH_SYS_TIME} 23832Replaced by @code{AC_HEADER_TIME} (@pxref{AC_HEADER_TIME}). 23833@end defmac 23834 23835@defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @ 23836 @ovar{action-if-true}, @ovar{action-if-false}) 23837@acindex{TRY_COMPILE} 23838Same as: 23839 23840@example 23841AC_COMPILE_IFELSE( 23842 [AC_LANG_PROGRAM([[@var{includes}]], 23843 [[@var{function-body}]])], 23844 [@var{action-if-true}], 23845 [@var{action-if-false}]) 23846@end example 23847 23848@noindent 23849@xref{Running the Compiler}. 23850 23851This macro double quotes both @var{includes} and @var{function-body}. 23852 23853For C and C++, @var{includes} is any @code{#include} statements needed 23854by the code in @var{function-body} (@var{includes} is ignored if 23855the currently selected language is Fortran or Fortran 77). The compiler 23856and compilation flags are determined by the current language 23857(@pxref{Language Choice}). 23858@end defmac 23859 23860@defmac AC_TRY_CPP (@var{input}, @ovar{action-if-true}, @ovar{action-if-false}) 23861@acindex{TRY_CPP} 23862Same as: 23863 23864@example 23865AC_PREPROC_IFELSE( 23866 [AC_LANG_SOURCE([[@var{input}]])], 23867 [@var{action-if-true}], 23868 [@var{action-if-false}]) 23869@end example 23870 23871@noindent 23872@xref{Running the Preprocessor}. 23873 23874This macro double quotes the @var{input}. 23875@end defmac 23876 23877@defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @ 23878 @ovar{action-if-true}, @ovar{action-if-false}) 23879@acindex{TRY_LINK} 23880Same as: 23881 23882@example 23883AC_LINK_IFELSE( 23884 [AC_LANG_PROGRAM([[@var{includes}]], 23885 [[@var{function-body}]])], 23886 [@var{action-if-true}], 23887 [@var{action-if-false}]) 23888@end example 23889 23890@noindent 23891@xref{Running the Compiler}. 23892 23893This macro double quotes both @var{includes} and @var{function-body}. 23894 23895Depending on the current language (@pxref{Language Choice}), create a 23896test program to see whether a function whose body consists of 23897@var{function-body} can be compiled and linked. If the file compiles 23898and links successfully, run shell commands @var{action-if-found}, 23899otherwise run @var{action-if-not-found}. 23900 23901This macro double quotes both @var{includes} and @var{function-body}. 23902 23903For C and C++, @var{includes} is any @code{#include} statements needed 23904by the code in @var{function-body} (@var{includes} is ignored if 23905the currently selected language is Fortran or Fortran 77). The compiler 23906and compilation flags are determined by the current language 23907(@pxref{Language Choice}), and in addition @code{LDFLAGS} and 23908@code{LIBS} are used for linking. 23909@end defmac 23910 23911@defmac AC_TRY_LINK_FUNC (@var{function}, @ovar{action-if-found}, @ 23912 @ovar{action-if-not-found}) 23913@acindex{TRY_LINK_FUNC} 23914This macro is equivalent to 23915@example 23916AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])], 23917 [@var{action-if-found}], [@var{action-if-not-found}]) 23918@end example 23919@noindent 23920@xref{AC_LINK_IFELSE}. 23921@end defmac 23922 23923@defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @ 23924 @ovar{action-if-false}, @dvar{action-if-cross-compiling, AC_MSG_FAILURE}) 23925@acindex{TRY_RUN} 23926Same as: 23927 23928@example 23929AC_RUN_IFELSE( 23930 [AC_LANG_SOURCE([[@var{program}]])], 23931 [@var{action-if-true}], 23932 [@var{action-if-false}], 23933 [@var{action-if-cross-compiling}]) 23934@end example 23935 23936@noindent 23937@xref{Runtime}. 23938@end defmac 23939 23940@anchor{AC_TYPE_SIGNAL} 23941@defmac AC_TYPE_SIGNAL 23942@acindex{TYPE_SIGNAL} 23943@cvindex RETSIGTYPE 23944@hdrindex{signal.h} 23945If @file{signal.h} declares @code{signal} as returning a pointer to a 23946function returning @code{void}, define @code{RETSIGTYPE} to be 23947@code{void}; otherwise, define it to be @code{int}. These days, it is 23948portable to assume C89, and that signal handlers return @code{void}, 23949without needing to use this macro or @code{RETSIGTYPE}. 23950 23951When targeting older K&R C, it is possible to define signal handlers as 23952returning type @code{RETSIGTYPE}, and omit a return statement: 23953 23954@example 23955@group 23956RETSIGTYPE 23957hup_handler () 23958@{ 23959@dots{} 23960@} 23961@end group 23962@end example 23963@end defmac 23964 23965@defmac AC_UID_T 23966@acindex{UID_T} 23967Replaced by @code{AC_TYPE_UID_T} (@pxref{AC_TYPE_UID_T}). 23968@end defmac 23969 23970@defmac AC_UNISTD_H 23971@acindex{UNISTD_H} 23972Same as @samp{AC_CHECK_HEADERS([unistd.h])} (@pxref{AC_CHECK_HEADERS}). 23973@end defmac 23974 23975@defmac AC_USG 23976@acindex{USG} 23977@cvindex USG 23978Define @code{USG} if the BSD string functions are defined in 23979@file{strings.h}. You should no longer depend upon @code{USG}, but on 23980@code{HAVE_STRING_H}; see @ref{Standard Symbols}. 23981@end defmac 23982 23983@defmac AC_UTIME_NULL 23984@acindex{UTIME_NULL} 23985Replaced by @code{AC_FUNC_UTIME_NULL} (@pxref{AC_FUNC_UTIME_NULL}). 23986@end defmac 23987 23988@defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@ovar{cmd}) 23989@acindex{VALIDATE_CACHED_SYSTEM_TUPLE} 23990If the cache file is inconsistent with the current host, target and 23991build system types, it used to execute @var{cmd} or print a default 23992error message. This is now handled by default. 23993@end defmac 23994 23995@defmac AC_VERBOSE (@var{result-description}) 23996@acindex{VERBOSE} 23997Replaced by @code{AC_MSG_RESULT} (@pxref{AC_MSG_RESULT}). 23998@end defmac 23999 24000@defmac AC_VFORK 24001@acindex{VFORK} 24002Replaced by @code{AC_FUNC_FORK} (@pxref{AC_FUNC_FORK}). 24003@end defmac 24004 24005@defmac AC_VPRINTF 24006@acindex{VPRINTF} 24007Replaced by @code{AC_FUNC_VPRINTF} (@pxref{AC_FUNC_VPRINTF}). 24008@end defmac 24009 24010@defmac AC_WAIT3 24011@acindex{WAIT3} 24012This macro was renamed @code{AC_FUNC_WAIT3}. However, these days 24013portable programs should use @code{waitpid}, not @code{wait3}, as 24014@code{wait3} has been removed from Posix. 24015@end defmac 24016 24017@defmac AC_WARN 24018@acindex{WARN} 24019Replaced by @code{AC_MSG_WARN} (@pxref{AC_MSG_WARN}). 24020@end defmac 24021 24022@defmac AC_WITH (@var{package}, @var{action-if-given}, @ 24023 @ovar{action-if-not-given}) 24024@acindex{WITH} 24025This is an obsolete version of @code{AC_ARG_WITH} that does not 24026support providing a help string (@pxref{AC_ARG_WITH}). 24027@end defmac 24028 24029@defmac AC_WORDS_BIGENDIAN 24030@acindex{WORDS_BIGENDIAN} 24031Replaced by @code{AC_C_BIGENDIAN} (@pxref{AC_C_BIGENDIAN}). 24032@end defmac 24033 24034@defmac AC_XENIX_DIR 24035@acindex{XENIX_DIR} 24036@ovindex LIBS 24037This macro used to add @option{-lx} to output variable @code{LIBS} if on 24038Xenix. Also, if @file{dirent.h} is being checked for, added 24039@option{-ldir} to @code{LIBS}. Now it is merely an alias of 24040@code{AC_HEADER_DIRENT} instead, plus some code to detect whether 24041running XENIX on which you should not depend: 24042 24043@example 24044AC_MSG_CHECKING([for Xenix]) 24045AC_EGREP_CPP([yes], 24046[#if defined M_XENIX && !defined M_UNIX 24047 yes 24048#endif], 24049 [AC_MSG_RESULT([yes]); XENIX=yes], 24050 [AC_MSG_RESULT([no]); XENIX=]) 24051@end example 24052@noindent 24053Don't use this macro, the dignified means to check the nature of the 24054host is using @code{AC_CANONICAL_HOST} (@pxref{Canonicalizing}). 24055@end defmac 24056 24057@defmac AC_YYTEXT_POINTER 24058@acindex{YYTEXT_POINTER} 24059This macro was renamed @code{AC_DECL_YYTEXT}, which in turn was 24060integrated into @code{AC_PROG_LEX} (@pxref{AC_PROG_LEX}). 24061@end defmac 24062 24063@node Autoconf 1 24064@section Upgrading From Version 1 24065@cindex Upgrading autoconf 24066@cindex Autoconf upgrading 24067 24068Autoconf version 2 is mostly backward compatible with version 1. 24069However, it introduces better ways to do some things, and doesn't 24070support some of the ugly things in version 1. So, depending on how 24071sophisticated your @file{configure.ac} files are, you might have to do 24072some manual work in order to upgrade to version 2. This chapter points 24073out some problems to watch for when upgrading. Also, perhaps your 24074@command{configure} scripts could benefit from some of the new features in 24075version 2; the changes are summarized in the file @file{NEWS} in the 24076Autoconf distribution. 24077 24078@menu 24079* Changed File Names:: Files you might rename 24080* Changed Makefiles:: New things to put in @file{Makefile.in} 24081* Changed Macros:: Macro calls you might replace 24082* Changed Results:: Changes in how to check test results 24083* Changed Macro Writing:: Better ways to write your own macros 24084@end menu 24085 24086@node Changed File Names 24087@subsection Changed File Names 24088 24089If you have an @file{aclocal.m4} installed with Autoconf (as opposed to 24090in a particular package's source directory), you must rename it to 24091@file{acsite.m4}. @xref{autoconf Invocation}. 24092 24093If you distribute @file{install.sh} with your package, rename it to 24094@file{install-sh} so @command{make} builtin rules don't inadvertently 24095create a file called @file{install} from it. @code{AC_PROG_INSTALL} 24096looks for the script under both names, but it is best to use the new name. 24097 24098If you were using @file{config.h.top}, @file{config.h.bot}, or 24099@file{acconfig.h}, you still can, but you have less clutter if you 24100use the @code{AH_} macros. @xref{Autoheader Macros}. 24101 24102@node Changed Makefiles 24103@subsection Changed Makefiles 24104 24105Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in 24106your @file{Makefile.in} files, so they can take advantage of the values 24107of those variables in the environment when @command{configure} is run. 24108Doing this isn't necessary, but it's a convenience for users. 24109 24110Also add @samp{@@configure_input@@} in a comment to each input file for 24111@code{AC_OUTPUT}, so that the output files contain a comment saying 24112they were produced by @command{configure}. Automatically selecting the 24113right comment syntax for all the kinds of files that people call 24114@code{AC_OUTPUT} on became too much work. 24115 24116Add @file{config.log} and @file{config.cache} to the list of files you 24117remove in @code{distclean} targets. 24118 24119If you have the following in @file{Makefile.in}: 24120 24121@example 24122prefix = /usr/local 24123exec_prefix = $(prefix) 24124@end example 24125 24126@noindent 24127you must change it to: 24128 24129@example 24130prefix = @@prefix@@ 24131exec_prefix = @@exec_prefix@@ 24132@end example 24133 24134@noindent 24135The old behavior of replacing those variables without @samp{@@} 24136characters around them has been removed. 24137 24138@node Changed Macros 24139@subsection Changed Macros 24140 24141Many of the macros were renamed in Autoconf version 2. You can still 24142use the old names, but the new ones are clearer, and it's easier to find 24143the documentation for them. @xref{Obsolete Macros}, for a table showing the 24144new names for the old macros. Use the @command{autoupdate} program to 24145convert your @file{configure.ac} to using the new macro names. 24146@xref{autoupdate Invocation}. 24147 24148Some macros have been superseded by similar ones that do the job better, 24149but are not call-compatible. If you get warnings about calling obsolete 24150macros while running @command{autoconf}, you may safely ignore them, but 24151your @command{configure} script generally works better if you follow 24152the advice that is printed about what to replace the obsolete macros with. In 24153particular, the mechanism for reporting the results of tests has 24154changed. If you were using @command{echo} or @code{AC_VERBOSE} (perhaps 24155via @code{AC_COMPILE_CHECK}), your @command{configure} script's output 24156looks better if you switch to @code{AC_MSG_CHECKING} and 24157@code{AC_MSG_RESULT}. @xref{Printing Messages}. Those macros work best 24158in conjunction with cache variables. @xref{Caching Results}. 24159 24160 24161 24162@node Changed Results 24163@subsection Changed Results 24164 24165If you were checking the results of previous tests by examining the 24166shell variable @code{DEFS}, you need to switch to checking the values of 24167the cache variables for those tests. @code{DEFS} no longer exists while 24168@command{configure} is running; it is only created when generating output 24169files. This difference from version 1 is because properly quoting the 24170contents of that variable turned out to be too cumbersome and 24171inefficient to do every time @code{AC_DEFINE} is called. @xref{Cache 24172Variable Names}. 24173 24174For example, here is a @file{configure.ac} fragment written for Autoconf 24175version 1: 24176 24177@example 24178AC_HAVE_FUNCS(syslog) 24179case "$DEFS" in 24180*-DHAVE_SYSLOG*) ;; 24181*) # syslog is not in the default libraries. See if it's in some other. 24182 saved_LIBS="$LIBS" 24183 for lib in bsd socket inet; do 24184 AC_CHECKING(for syslog in -l$lib) 24185 LIBS="-l$lib $saved_LIBS" 24186 AC_HAVE_FUNCS(syslog) 24187 case "$DEFS" in 24188 *-DHAVE_SYSLOG*) break ;; 24189 *) ;; 24190 esac 24191 LIBS="$saved_LIBS" 24192 done ;; 24193esac 24194@end example 24195 24196Here is a way to write it for version 2: 24197 24198@example 24199AC_CHECK_FUNCS([syslog]) 24200if test "x$ac_cv_func_syslog" = xno; then 24201 # syslog is not in the default libraries. See if it's in some other. 24202 for lib in bsd socket inet; do 24203 AC_CHECK_LIB([$lib], [syslog], [AC_DEFINE([HAVE_SYSLOG]) 24204 LIBS="-l$lib $LIBS"; break]) 24205 done 24206fi 24207@end example 24208 24209If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding 24210backslashes before quotes, you need to remove them. It now works 24211predictably, and does not treat quotes (except back quotes) specially. 24212@xref{Setting Output Variables}. 24213 24214All of the Boolean shell variables set by Autoconf macros now use 24215@samp{yes} for the true value. Most of them use @samp{no} for false, 24216though for backward compatibility some use the empty string instead. If 24217you were relying on a shell variable being set to something like 1 or 24218@samp{t} for true, you need to change your tests. 24219 24220@node Changed Macro Writing 24221@subsection Changed Macro Writing 24222 24223When defining your own macros, you should now use @code{AC_DEFUN} 24224instead of @code{define}. @code{AC_DEFUN} automatically calls 24225@code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE} 24226do not interrupt other macros, to prevent nested @samp{checking@dots{}} 24227messages on the screen. There's no actual harm in continuing to use the 24228older way, but it's less convenient and attractive. @xref{Macro 24229Definitions}. 24230 24231You probably looked at the macros that came with Autoconf as a guide for 24232how to do things. It would be a good idea to take a look at the new 24233versions of them, as the style is somewhat improved and they take 24234advantage of some new features. 24235 24236If you were doing tricky things with undocumented Autoconf internals 24237(macros, variables, diversions), check whether you need to change 24238anything to account for changes that have been made. Perhaps you can 24239even use an officially supported technique in version 2 instead of 24240kludging. Or perhaps not. 24241 24242To speed up your locally written feature tests, add caching to them. 24243See whether any of your tests are of general enough usefulness to 24244encapsulate them into macros that you can share. 24245 24246 24247@node Autoconf 2.13 24248@section Upgrading From Version 2.13 24249@cindex Upgrading autoconf 24250@cindex Autoconf upgrading 24251 24252The introduction of the previous section (@pxref{Autoconf 1}) perfectly 24253suits this section@enddots{} 24254 24255@quotation 24256Autoconf version 2.50 is mostly backward compatible with version 2.13. 24257However, it introduces better ways to do some things, and doesn't 24258support some of the ugly things in version 2.13. So, depending on how 24259sophisticated your @file{configure.ac} files are, you might have to do 24260some manual work in order to upgrade to version 2.50. This chapter 24261points out some problems to watch for when upgrading. Also, perhaps 24262your @command{configure} scripts could benefit from some of the new 24263features in version 2.50; the changes are summarized in the file 24264@file{NEWS} in the Autoconf distribution. 24265@end quotation 24266 24267@menu 24268* Changed Quotation:: Broken code which used to work 24269* New Macros:: Interaction with foreign macros 24270* Hosts and Cross-Compilation:: Bugward compatibility kludges 24271* AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token 24272* AC_ACT_IFELSE vs AC_TRY_ACT:: A more generic scheme for testing sources 24273@end menu 24274 24275@node Changed Quotation 24276@subsection Changed Quotation 24277 24278The most important changes are invisible to you: the implementation of 24279most macros have completely changed. This allowed more factorization of 24280the code, better error messages, a higher uniformity of the user's 24281interface etc. Unfortunately, as a side effect, some construct which 24282used to (miraculously) work might break starting with Autoconf 2.50. 24283The most common culprit is bad quotation. 24284 24285For instance, in the following example, the message is not properly 24286quoted: 24287 24288@example 24289AC_INIT 24290AC_CHECK_HEADERS(foo.h, , 24291 AC_MSG_ERROR(cannot find foo.h, bailing out)) 24292AC_OUTPUT 24293@end example 24294 24295@noindent 24296Autoconf 2.13 simply ignores it: 24297 24298@example 24299$ @kbd{autoconf-2.13; ./configure --silent} 24300creating cache ./config.cache 24301configure: error: cannot find foo.h 24302$ 24303@end example 24304 24305@noindent 24306while Autoconf 2.50 produces a broken @file{configure}: 24307 24308@example 24309$ @kbd{autoconf-2.50; ./configure --silent} 24310configure: error: cannot find foo.h 24311./configure: exit: bad non-numeric arg `bailing' 24312./configure: exit: bad non-numeric arg `bailing' 24313$ 24314@end example 24315 24316The message needs to be quoted, and the @code{AC_MSG_ERROR} invocation 24317too! 24318 24319@example 24320AC_INIT([Example], [1.0], [bug-example@@example.org]) 24321AC_CHECK_HEADERS([foo.h], [], 24322 [AC_MSG_ERROR([cannot find foo.h, bailing out])]) 24323AC_OUTPUT 24324@end example 24325 24326Many many (and many more) Autoconf macros were lacking proper quotation, 24327including no less than@dots{} @code{AC_DEFUN} itself! 24328 24329@example 24330$ @kbd{cat configure.in} 24331AC_DEFUN([AC_PROG_INSTALL], 24332[# My own much better version 24333]) 24334AC_INIT 24335AC_PROG_INSTALL 24336AC_OUTPUT 24337$ @kbd{autoconf-2.13} 24338autoconf: Undefined macros: 24339***BUG in Autoconf--please report*** AC_FD_MSG 24340***BUG in Autoconf--please report*** AC_EPI 24341configure.in:1:AC_DEFUN([AC_PROG_INSTALL], 24342configure.in:5:AC_PROG_INSTALL 24343$ @kbd{autoconf-2.50} 24344$ 24345@end example 24346 24347 24348@node New Macros 24349@subsection New Macros 24350 24351@cindex undefined macro 24352@cindex @code{_m4_divert_diversion} 24353 24354While Autoconf was relatively dormant in the late 1990s, Automake 24355provided Autoconf-like macros for a while. Starting with Autoconf 2.50 24356in 2001, Autoconf provided 24357versions of these macros, integrated in the @code{AC_} namespace, 24358instead of @code{AM_}. But in order to ease the upgrading via 24359@command{autoupdate}, bindings to such @code{AM_} macros are provided. 24360 24361Unfortunately older versions of Automake (e.g., Automake 1.4) 24362did not quote the names of these macros. 24363Therefore, when @command{m4} finds something like 24364@samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, @dots{})} in @file{aclocal.m4}, 24365@code{AM_TYPE_PTRDIFF_T} is 24366expanded, replaced with its Autoconf definition. 24367 24368Fortunately Autoconf catches pre-@code{AC_INIT} expansions, and 24369complains, in its own words: 24370 24371@example 24372$ @kbd{cat configure.ac} 24373AC_INIT([Example], [1.0], [bug-example@@example.org]) 24374AM_TYPE_PTRDIFF_T 24375$ @kbd{aclocal-1.4} 24376$ @kbd{autoconf} 24377aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion 24378aclocal.m4:17: the top level 24379autom4te: m4 failed with exit status: 1 24380$ 24381@end example 24382 24383Modern versions of Automake no longer define most of these 24384macros, and properly quote the names of the remaining macros. 24385If you must use an old Automake, do not depend upon macros from Automake 24386as it is simply not its job 24387to provide macros (but the one it requires itself): 24388 24389@example 24390$ @kbd{cat configure.ac} 24391AC_INIT([Example], [1.0], [bug-example@@example.org]) 24392AM_TYPE_PTRDIFF_T 24393$ @kbd{rm aclocal.m4} 24394$ @kbd{autoupdate} 24395autoupdate: `configure.ac' is updated 24396$ @kbd{cat configure.ac} 24397AC_INIT([Example], [1.0], [bug-example@@example.org]) 24398AC_CHECK_TYPES([ptrdiff_t]) 24399$ @kbd{aclocal-1.4} 24400$ @kbd{autoconf} 24401$ 24402@end example 24403 24404 24405@node Hosts and Cross-Compilation 24406@subsection Hosts and Cross-Compilation 24407@cindex Cross compilation 24408 24409Based on the experience of compiler writers, and after long public 24410debates, many aspects of the cross-compilation chain have changed: 24411 24412@itemize @minus 24413@item 24414the relationship between the build, host, and target architecture types, 24415 24416@item 24417the command line interface for specifying them to @command{configure}, 24418 24419@item 24420the variables defined in @command{configure}, 24421 24422@item 24423the enabling of cross-compilation mode. 24424@end itemize 24425 24426@sp 1 24427 24428The relationship between build, host, and target have been cleaned up: 24429the chain of default is now simply: target defaults to host, host to 24430build, and build to the result of @command{config.guess}. Nevertheless, 24431in order to ease the transition from 2.13 to 2.50, the following 24432transition scheme is implemented. @emph{Do not rely on it}, as it will 24433be completely disabled in a couple of releases (we cannot keep it, as it 24434proves to cause more problems than it cures). 24435 24436They all default to the result of running @command{config.guess}, unless 24437you specify either @option{--build} or @option{--host}. In this case, 24438the default becomes the system type you specified. If you specify both, 24439and they're different, @command{configure} enters cross compilation 24440mode, so it doesn't run any tests that require execution. 24441 24442Hint: if you mean to override the result of @command{config.guess}, 24443prefer @option{--build} over @option{--host}. 24444 24445@sp 1 24446 24447For backward compatibility, @command{configure} accepts a system 24448type as an option by itself. Such an option overrides the 24449defaults for build, host, and target system types. The following 24450configure statement configures a cross toolchain that runs on 24451NetBSD/alpha but generates code for GNU Hurd/sparc, 24452which is also the build platform. 24453 24454@example 24455./configure --host=alpha-netbsd sparc-gnu 24456@end example 24457 24458@sp 1 24459 24460In Autoconf 2.13 and before, the variables @code{build}, @code{host}, 24461and @code{target} had a different semantics before and after the 24462invocation of @code{AC_CANONICAL_BUILD} etc. Now, the argument of 24463@option{--build} is strictly copied into @code{build_alias}, and is left 24464empty otherwise. After the @code{AC_CANONICAL_BUILD}, @code{build} is 24465set to the canonicalized build type. To ease the transition, before, 24466its contents is the same as that of @code{build_alias}. Do @emph{not} 24467rely on this broken feature. 24468 24469For consistency with the backward compatibility scheme exposed above, 24470when @option{--host} is specified but @option{--build} isn't, the build 24471system is assumed to be the same as @option{--host}, and 24472@samp{build_alias} is set to that value. Eventually, this 24473historically incorrect behavior will go away. 24474 24475@sp 1 24476 24477The former scheme to enable cross-compilation proved to cause more harm 24478than good, in particular, it used to be triggered too easily, leaving 24479regular end users puzzled in front of cryptic error messages. 24480@command{configure} could even enter cross-compilation mode only 24481because the compiler was not functional. This is mainly because 24482@command{configure} used to try to detect cross-compilation, instead of 24483waiting for an explicit flag from the user. 24484 24485Now, @command{configure} enters cross-compilation mode if and only if 24486@option{--host} is passed. 24487 24488That's the short documentation. To ease the transition between 2.13 and 24489its successors, a more complicated scheme is implemented. @emph{Do not 24490rely on the following}, as it will be removed in the near future. 24491 24492If you specify @option{--host}, but not @option{--build}, when 24493@command{configure} performs the first compiler test it tries to run 24494an executable produced by the compiler. If the execution fails, it 24495enters cross-compilation mode. This is fragile. Moreover, by the time 24496the compiler test is performed, it may be too late to modify the 24497build-system type: other tests may have already been performed. 24498Therefore, whenever you specify @option{--host}, be sure to specify 24499@option{--build} too. 24500 24501@example 24502./configure --build=i686-pc-linux-gnu --host=m68k-coff 24503@end example 24504 24505@noindent 24506enters cross-compilation mode. The former interface, which 24507consisted in setting the compiler to a cross-compiler without informing 24508@command{configure} is obsolete. For instance, @command{configure} 24509fails if it can't run the code generated by the specified compiler if you 24510configure as follows: 24511 24512@example 24513./configure CC=m68k-coff-gcc 24514@end example 24515 24516 24517@node AC_LIBOBJ vs LIBOBJS 24518@subsection @code{AC_LIBOBJ} vs.@: @code{LIBOBJS} 24519 24520Up to Autoconf 2.13, the replacement of functions was triggered via the 24521variable @code{LIBOBJS}. Since Autoconf 2.50, the macro 24522@code{AC_LIBOBJ} should be used instead (@pxref{Generic Functions}). 24523Starting at Autoconf 2.53, the use of @code{LIBOBJS} is an error. 24524 24525This change is mandated by the unification of the GNU Build System 24526components. In particular, the various fragile techniques used to parse 24527a @file{configure.ac} are all replaced with the use of traces. As a 24528consequence, any action must be traceable, which obsoletes critical 24529variable assignments. Fortunately, @code{LIBOBJS} was the only problem, 24530and it can even be handled gracefully (read, ``without your having to 24531change something''). 24532 24533There were two typical uses of @code{LIBOBJS}: asking for a replacement 24534function, and adjusting @code{LIBOBJS} for Automake and/or Libtool. 24535 24536@sp 1 24537 24538As for function replacement, the fix is immediate: use 24539@code{AC_LIBOBJ}. For instance: 24540 24541@example 24542LIBOBJS="$LIBOBJS fnmatch.o" 24543LIBOBJS="$LIBOBJS malloc.$ac_objext" 24544@end example 24545 24546@noindent 24547should be replaced with: 24548 24549@example 24550AC_LIBOBJ([fnmatch]) 24551AC_LIBOBJ([malloc]) 24552@end example 24553 24554@sp 1 24555 24556@ovindex LIBOBJDIR 24557When used with Automake 1.10 or newer, a suitable value for 24558@code{LIBOBJDIR} is set so that the @code{LIBOBJS} and @code{LTLIBOBJS} 24559can be referenced from any @file{Makefile.am}. Even without Automake, 24560arranging for @code{LIBOBJDIR} to be set correctly enables 24561referencing @code{LIBOBJS} and @code{LTLIBOBJS} in another directory. 24562The @code{LIBOBJDIR} feature is experimental. 24563 24564 24565@node AC_ACT_IFELSE vs AC_TRY_ACT 24566@subsection @code{AC_@var{ACT}_IFELSE} vs.@: @code{AC_TRY_@var{ACT}} 24567@c the anchor keeps the old node name, to try to avoid breaking links 24568@anchor{AC_FOO_IFELSE vs AC_TRY_FOO} 24569 24570@acindex{@var{ACT}_IFELSE} 24571@acindex{TRY_@var{ACT}} 24572Since Autoconf 2.50, internal codes uses @code{AC_PREPROC_IFELSE}, 24573@code{AC_COMPILE_IFELSE}, @code{AC_LINK_IFELSE}, and 24574@code{AC_RUN_IFELSE} on one hand and @code{AC_LANG_SOURCE}, 24575and @code{AC_LANG_PROGRAM} on the other hand instead of the deprecated 24576@code{AC_TRY_CPP}, @code{AC_TRY_COMPILE}, @code{AC_TRY_LINK}, and 24577@code{AC_TRY_RUN}. The motivations where: 24578@itemize @minus 24579@item 24580a more consistent interface: @code{AC_TRY_COMPILE} etc.@: were double 24581quoting their arguments; 24582 24583@item 24584the combinatoric explosion is solved by decomposing on the one hand the 24585generation of sources, and on the other hand executing the program; 24586 24587@item 24588this scheme helps supporting more languages than plain C and C++. 24589@end itemize 24590 24591In addition to the change of syntax, the philosophy has changed too: 24592while emphasis was put on speed at the expense of accuracy, today's 24593Autoconf promotes accuracy of the testing framework at, ahem@dots{}, the 24594expense of speed. 24595 24596 24597As a perfect example of what is @emph{not} to be done, here is how to 24598find out whether a header file contains a particular declaration, such 24599as a typedef, a structure, a structure member, or a function. Use 24600@code{AC_EGREP_HEADER} instead of running @code{grep} directly on the 24601header file; on some systems the symbol might be defined in another 24602header file that the file you are checking includes. 24603 24604As a (bad) example, here is how you should not check for C preprocessor 24605symbols, either defined by header files or predefined by the C 24606preprocessor: using @code{AC_EGREP_CPP}: 24607 24608@example 24609@group 24610AC_EGREP_CPP(yes, 24611[#ifdef _AIX 24612 yes 24613#endif 24614], is_aix=yes, is_aix=no) 24615@end group 24616@end example 24617 24618The above example, properly written would (i) use 24619@code{AC_LANG_PROGRAM}, and (ii) run the compiler: 24620 24621@example 24622@group 24623AC_COMPILE_IFELSE([AC_LANG_PROGRAM( 24624[[#ifndef _AIX 24625 error: This isn't AIX! 24626#endif 24627]])], 24628 [is_aix=yes], 24629 [is_aix=no]) 24630@end group 24631@end example 24632 24633 24634@c ============================= Generating Test Suites with Autotest 24635 24636@node Using Autotest 24637@chapter Generating Test Suites with Autotest 24638 24639@cindex Autotest 24640 24641@display 24642@strong{N.B.: This section describes a feature which is still 24643stabilizing. Although we believe that Autotest is useful as-is, this 24644documentation describes an interface which might change in the future: 24645do not depend upon Autotest without subscribing to the Autoconf mailing 24646lists.} 24647@end display 24648 24649It is paradoxical that portable projects depend on nonportable tools 24650to run their test suite. Autoconf by itself is the paragon of this 24651problem: although it aims at perfectly portability, up to 2.13 its 24652test suite was using DejaGNU, a rich and complex testing 24653framework, but which is far from being standard on Posix systems. 24654Worse yet, it was likely to be missing on the most fragile platforms, 24655the very platforms that are most likely to torture Autoconf and 24656exhibit deficiencies. 24657 24658To circumvent this problem, many package maintainers have developed their 24659own testing framework, based on simple shell scripts whose sole outputs 24660are exit status values describing whether the test succeeded. Most of 24661these tests share common patterns, and this can result in lots of 24662duplicated code and tedious maintenance. 24663 24664Following exactly the same reasoning that yielded to the inception of 24665Autoconf, Autotest provides a test suite generation framework, based on 24666M4 macros building a portable shell script. The suite itself is 24667equipped with automatic logging and tracing facilities which greatly 24668diminish the interaction with bug reporters, and simple timing reports. 24669 24670Autoconf itself has been using Autotest for years, and we do attest that 24671it has considerably improved the strength of the test suite and the 24672quality of bug reports. Other projects are known to use some generation 24673of Autotest, such as Bison, Free Recode, Free Wdiff, GNU Tar, each of 24674them with different needs, and this usage has validated Autotest as a general 24675testing framework. 24676 24677Nonetheless, compared to DejaGNU, Autotest is inadequate for 24678interactive tool testing, which is probably its main limitation. 24679 24680@menu 24681* Using an Autotest Test Suite:: Autotest and the user 24682* Writing Testsuites:: Autotest macros 24683* testsuite Invocation:: Running @command{testsuite} scripts 24684* Making testsuite Scripts:: Using autom4te to create @command{testsuite} 24685@end menu 24686 24687@node Using an Autotest Test Suite 24688@section Using an Autotest Test Suite 24689 24690@menu 24691* testsuite Scripts:: The concepts of Autotest 24692* Autotest Logs:: Their contents 24693@end menu 24694 24695@node testsuite Scripts 24696@subsection @command{testsuite} Scripts 24697 24698@cindex @command{testsuite} 24699 24700Generating testing or validation suites using Autotest is rather easy. 24701The whole validation suite is held in a file to be processed through 24702@command{autom4te}, itself using GNU M4 under the hood, to 24703produce a stand-alone Bourne shell script which then gets distributed. 24704Neither @command{autom4te} nor GNU M4 are needed at 24705the installer's end. 24706 24707@cindex test group 24708Each test of the validation suite should be part of some test group. A 24709@dfn{test group} is a sequence of interwoven tests that ought to be 24710executed together, usually because one test in the group creates data 24711files that a later test in the same group needs to read. Complex test 24712groups make later debugging more tedious. It is much better to 24713keep only a few tests per test group. Ideally there is only one test 24714per test group. 24715 24716For all but the simplest packages, some file such as @file{testsuite.at} 24717does not fully hold all test sources, as these are often easier to 24718maintain in separate files. Each of these separate files holds a single 24719test group, or a sequence of test groups all addressing some common 24720functionality in the package. In such cases, @file{testsuite.at} 24721merely initializes the validation suite, and sometimes does elementary 24722health checking, before listing include statements for all other test 24723files. The special file @file{package.m4}, containing the 24724identification of the package, is automatically included if found. 24725 24726A convenient alternative consists in moving all the global issues 24727(local Autotest macros, elementary health checking, and @code{AT_INIT} 24728invocation) into the file @code{local.at}, and making 24729@file{testsuite.at} be a simple list of @code{m4_include}s of sub test 24730suites. In such case, generating the whole test suite or pieces of it 24731is only a matter of choosing the @command{autom4te} command line 24732arguments. 24733 24734The validation scripts that Autotest produces are by convention called 24735@command{testsuite}. When run, @command{testsuite} executes each test 24736group in turn, producing only one summary line per test to say if that 24737particular test succeeded or failed. At end of all tests, summarizing 24738counters get printed. One debugging directory is left for each test 24739group which failed, if any: such directories are named 24740@file{testsuite.dir/@var{nn}}, where @var{nn} is the sequence number of 24741the test group, and they include: 24742 24743@itemize @bullet 24744@item a debugging script named @file{run} which reruns the test in 24745@dfn{debug mode} (@pxref{testsuite Invocation}). The automatic generation 24746of debugging scripts has the purpose of easing the chase for bugs. 24747 24748@item all the files created with @code{AT_DATA} 24749 24750@item all the Erlang source code files created with @code{AT_CHECK_EUNIT} 24751 24752@item a log of the run, named @file{testsuite.log} 24753@end itemize 24754 24755In the ideal situation, none of the tests fail, and consequently no 24756debugging directory is left behind for validation. 24757 24758It often happens in practice that individual tests in the validation 24759suite need to get information coming out of the configuration process. 24760Some of this information, common for all validation suites, is provided 24761through the file @file{atconfig}, automatically created by 24762@code{AC_CONFIG_TESTDIR}. For configuration information which your 24763testing environment specifically needs, you might prepare an optional 24764file named @file{atlocal.in}, instantiated by @code{AC_CONFIG_FILES}. 24765The configuration process produces @file{atconfig} and @file{atlocal} 24766out of these two input files, and these two produced files are 24767automatically read by the @file{testsuite} script. 24768 24769Here is a diagram showing the relationship between files. 24770 24771@noindent 24772Files used in preparing a software package for distribution: 24773 24774@example 24775 [package.m4] -->. 24776 \ 24777subfile-1.at ->. [local.at] ---->+ 24778 ... \ \ 24779subfile-i.at ---->-- testsuite.at -->-- autom4te* -->testsuite 24780 ... / 24781subfile-n.at ->' 24782@end example 24783 24784@noindent 24785Files used in configuring a software package: 24786 24787@example 24788 .--> atconfig 24789 / 24790[atlocal.in] --> config.status* --< 24791 \ 24792 `--> [atlocal] 24793@end example 24794 24795@noindent 24796Files created during test suite execution: 24797 24798@example 24799atconfig -->. .--> testsuite.log 24800 \ / 24801 >-- testsuite* --< 24802 / \ 24803[atlocal] ->' `--> [testsuite.dir] 24804@end example 24805 24806 24807@node Autotest Logs 24808@subsection Autotest Logs 24809 24810When run, the test suite creates a log file named after itself, e.g., a 24811test suite named @command{testsuite} creates @file{testsuite.log}. It 24812contains a lot of information, usually more than maintainers actually 24813need, but therefore most of the time it contains all that is needed: 24814 24815@table @asis 24816@item command line arguments 24817A bad but unfortunately widespread habit consists of 24818setting environment variables before the command, such as in 24819@samp{CC=my-home-grown-cc ./testsuite}. The test suite does not 24820know this change, hence (i) it cannot report it to you, and (ii) 24821it cannot preserve the value of @code{CC} for subsequent runs. 24822Autoconf faced exactly the same problem, and solved it by asking 24823users to pass the variable definitions as command line arguments. 24824Autotest requires this rule, too, but has no means to enforce it; the log 24825then contains a trace of the variables that were changed by the user. 24826 24827@item @file{ChangeLog} excerpts 24828The topmost lines of all the @file{ChangeLog} files found in the source 24829hierarchy. This is especially useful when bugs are reported against 24830development versions of the package, since the version string does not 24831provide sufficient information to know the exact state of the sources 24832the user compiled. Of course, this relies on the use of a 24833@file{ChangeLog}. 24834 24835@item build machine 24836Running a test suite in a cross-compile environment is not an easy task, 24837since it would mean having the test suite run on a machine @var{build}, 24838while running programs on a machine @var{host}. It is much simpler to 24839run both the test suite and the programs on @var{host}, but then, from 24840the point of view of the test suite, there remains a single environment, 24841@var{host} = @var{build}. The log contains relevant information on the 24842state of the @var{build} machine, including some important environment 24843variables. 24844@c FIXME: How about having an M4sh macro to say `hey, log the value 24845@c of `@dots{}'? This would help both Autoconf and Autotest. 24846 24847@item tested programs 24848The absolute file name and answers to @option{--version} of the tested 24849programs (see @ref{Writing Testsuites}, @code{AT_TESTED}). 24850 24851@item configuration log 24852The contents of @file{config.log}, as created by @command{configure}, 24853are appended. It contains the configuration flags and a detailed report 24854on the configuration itself. 24855@end table 24856 24857 24858@node Writing Testsuites 24859@section Writing @file{testsuite.at} 24860 24861The @file{testsuite.at} is a Bourne shell script making use of special 24862Autotest M4 macros. It often contains a call to @code{AT_INIT} near 24863its beginning followed by one call to @code{m4_include} per source file 24864for tests. Each such included file, or the remainder of 24865@file{testsuite.at} if include files are not used, contain a sequence of 24866test groups. Each test group begins with a call to @code{AT_SETUP}, 24867then an arbitrary number of shell commands or calls to @code{AT_CHECK}, 24868and then completes with a call to @code{AT_CLEANUP}. Multiple test 24869groups can be categorized by a call to @code{AT_BANNER}. 24870 24871All of the public Autotest macros have all-uppercase names in the 24872namespace @samp{^AT_} to prevent them from accidentally conflicting with 24873other text; Autoconf also reserves the namespace @samp{^_AT_} for 24874internal macros. All shell variables used in the testsuite for internal 24875purposes have mostly-lowercase names starting with @samp{at_}. Autotest 24876also uses here-document delimiters in the namespace @samp{^_AT[A-Z]}, and 24877makes use of the file system namespace @samp{^at-}. 24878 24879Since Autoconf is built on top of M4sugar (@pxref{Programming in 24880M4sugar}) and M4sh (@pxref{Programming in M4sh}), you must also be aware 24881of those namespaces (@samp{^_?\(m4\|AS\)_}). In general, you 24882@emph{should not use} the namespace of a package that does not own the 24883macro or shell code you are writing. 24884 24885@defmac AT_INIT (@ovar{name}) 24886@atindex{INIT} 24887@c FIXME: Not clear, plus duplication of the information. 24888Initialize Autotest. Giving a @var{name} to the test suite is 24889encouraged if your package includes several test suites. Before this 24890macro is called, @code{AT_PACKAGE_STRING} and 24891@code{AT_PACKAGE_BUGREPORT} must be defined, which are used to display 24892information about the testsuite to the user. Typically, these macros 24893are provided by a file @file{package.m4} built by @command{make} 24894(@pxref{Making testsuite Scripts}), in order to inherit the package 24895name, version, and bug reporting address from @file{configure.ac}. 24896@end defmac 24897 24898@defmac AT_COPYRIGHT (@var{copyright-notice}) 24899@atindex{COPYRIGHT} 24900@cindex Copyright Notice 24901State that, in addition to the Free Software Foundation's copyright on 24902the Autotest macros, parts of your test suite are covered by 24903@var{copyright-notice}. 24904 24905The @var{copyright-notice} shows up in both the head of 24906@command{testsuite} and in @samp{testsuite --version}. 24907@end defmac 24908 24909@defmac AT_ARG_OPTION (@var{options}, @var{help-text}, @ 24910 @ovar{action-if-given}, @ovar{action-if-not-given}) 24911@atindex{ARG_OPTION} 24912@vrindex at_arg_@var{option} 24913Accept options from the space-separated list @var{options}, a list that 24914has leading dashes removed from the options. Long options will be 24915prefixed with @samp{--}, single-character options with @samp{-}. The 24916first word in this list is the primary @var{option}, any others are 24917assumed to be short-hand aliases. The variable associated with it 24918is @code{at_arg_@var{option}}, with any dashes in @var{option} replaced 24919with underscores. 24920 24921If the user passes @option{--@var{option}} to the @command{testsuite}, 24922the variable will be set to @samp{:}. If the user does not pass the 24923option, or passes @option{--no-@var{option}}, then the variable will be 24924set to @samp{false}. 24925 24926@vrindex at_optarg 24927@vrindex at_optarg_@var{option} 24928@var{action-if-given} is run each time the option is encountered; here, 24929the variable @code{at_optarg} will be set to @samp{:} or @samp{false} as 24930appropriate. @code{at_optarg} is actually just a copy of 24931@code{at_arg_@var{option}}. 24932 24933@var{action-if-not-given} will be run once after option parsing is 24934complete and if no option from @var{options} was used. 24935 24936@var{help-text} is added to the end of the list of options shown in 24937@command{testsuite --help} (@pxref{AS_HELP_STRING}). 24938 24939It is recommended that you use a package-specific prefix to @var{options} 24940names in order to avoid clashes with future Autotest built-in options. 24941@end defmac 24942 24943@defmac AT_ARG_OPTION_ARG (@var{options}, @var{help-text}, @ 24944 @ovar{action-if-given}, @ovar{action-if-not-given}) 24945@atindex{ARG_OPTION_ARG} 24946@vrindex at_arg_@var{option} 24947Accept options with arguments from the space-separated list 24948@var{options}, a list that has leading dashes removed from the options. 24949Long options will be prefixed with @samp{--}, single-character options 24950with @samp{-}. The first word in this list is the primary @var{option}, 24951any others are assumed to be short-hand aliases. The variable associated 24952with it is @code{at_arg_@var{option}}, with any dashes in @var{option} 24953replaced with underscores. 24954 24955If the user passes @option{--@var{option}=@var{arg}} or 24956@option{--@var{option} @var{arg}} to the @command{testsuite}, the 24957variable will be set to @samp{@var{arg}}. 24958 24959@vrindex at_optarg 24960@var{action-if-given} is run each time the option is encountered; here, 24961the variable @code{at_optarg} will be set to @samp{@var{arg}}. 24962@code{at_optarg} is actually just a copy of @code{at_arg_@var{option}}. 24963 24964@var{action-if-not-given} will be run once after option parsing is 24965complete and if no option from @var{options} was used. 24966 24967@var{help-text} is added to the end of the list of options shown in 24968@command{testsuite --help} (@pxref{AS_HELP_STRING}). 24969 24970It is recommended that you use a package-specific prefix to @var{options} 24971names in order to avoid clashes with future Autotest built-in options. 24972@end defmac 24973 24974@defmac AT_COLOR_TESTS 24975@atindex{COLOR_TESTS} 24976Enable colored test results by default when the output is connected to 24977a terminal. 24978@end defmac 24979 24980@defmac AT_TESTED (@var{executables}) 24981@atindex{TESTED} 24982Log the file name and answer to @option{--version} of each program in 24983space-separated list @var{executables}. Several invocations register 24984new executables, in other words, don't fear registering one program 24985several times. 24986 24987Autotest test suites rely on @env{PATH} to find the tested program. 24988This avoids the need to generate absolute names of the various tools, and 24989makes it possible to test installed programs. Therefore, knowing which 24990programs are being exercised is crucial to understanding problems in 24991the test suite itself, or its occasional misuses. It is a good idea to 24992also subscribe foreign programs you depend upon, to avoid incompatible 24993diagnostics. 24994@end defmac 24995 24996@sp 1 24997 24998@defmac AT_BANNER (@var{test-category-name}) 24999@atindex{BANNER} 25000This macro identifies the start of a category of related test groups. 25001When the resulting @file{testsuite} is invoked with more than one test 25002group to run, its output will include a banner containing 25003@var{test-category-name} prior to any tests run from that category. The 25004banner should be no more than about 40 or 50 characters. A blank banner 25005indicates uncategorized tests; an empty line will be inserted after 25006tests from an earlier category, effectively ending that category. 25007@end defmac 25008 25009@defmac AT_SETUP (@var{test-group-name}) 25010@atindex{SETUP} 25011This macro starts a group of related tests, all to be executed in the 25012same subshell. It accepts a single argument, which holds a few words 25013(no more than about 30 or 40 characters) quickly describing the purpose 25014of the test group being started. @var{test-group-name} must not expand 25015to unbalanced quotes, although quadrigraphs can be used. 25016@end defmac 25017 25018@defmac AT_KEYWORDS (@var{keywords}) 25019@atindex{KEYWORDS} 25020Associate the space-separated list of @var{keywords} to the enclosing 25021test group. This makes it possible to run ``slices'' of the test suite. 25022For instance, if some of your test groups exercise some @samp{foo} 25023feature, then using @samp{AT_KEYWORDS(foo)} lets you run 25024@samp{./testsuite -k foo} to run exclusively these test groups. The 25025@var{test-group-name} of the test group is automatically recorded to 25026@code{AT_KEYWORDS}. 25027 25028Several invocations within a test group accumulate new keywords. In 25029other words, don't fear registering the same keyword several times in a 25030test group. 25031@end defmac 25032 25033@defmac AT_CAPTURE_FILE (@var{file}) 25034@atindex{CAPTURE_FILE} 25035If the current test group fails, log the contents of @var{file}. 25036Several identical calls within one test group have no additional effect. 25037@end defmac 25038 25039@defmac AT_FAIL_IF (@var{shell-condition}) 25040@atindex{FAIL_IF} 25041Make the test group fail and skip the rest of its execution, if 25042@var{shell-condition} is true. @var{shell-condition} is a shell expression 25043such as a @code{test} command. Tests before @command{AT_FAIL_IF} 25044will be executed and may still cause the test group to be skipped. 25045You can instantiate this macro many times from within the same test group. 25046 25047You should use this macro only for very simple failure conditions. If the 25048@var{shell-condition} could emit any kind of output you should instead 25049use @command{AT_CHECK} like 25050@example 25051AT_CHECK([if @var{shell-condition}; then exit 99; fi]) 25052@end example 25053@noindent 25054so that such output is properly recorded in the @file{testsuite.log} 25055file. 25056@end defmac 25057 25058@defmac AT_SKIP_IF (@var{shell-condition}) 25059@atindex{SKIP_IF} 25060Determine whether the test should be skipped because it requires 25061features that are unsupported on the machine under test. 25062@var{shell-condition} is a shell expression such as a @code{test} 25063command. Tests before @command{AT_SKIP_IF} will be executed 25064and may still cause the test group to fail. You can instantiate this 25065macro many times from within the same test group. 25066 25067You should use this macro only for very simple skip conditions. If the 25068@var{shell-condition} could emit any kind of output you should instead 25069use @command{AT_CHECK} like 25070@example 25071AT_CHECK([if @var{shell-condition}; then exit 77; fi]) 25072@end example 25073@noindent 25074so that such output is properly recorded in the @file{testsuite.log} 25075file. 25076@end defmac 25077 25078@defmac AT_XFAIL_IF (@var{shell-condition}) 25079@atindex{XFAIL_IF} 25080Determine whether the test is expected to fail because it is a known 25081bug (for unsupported features, you should skip the test). 25082@var{shell-condition} is a shell expression such as a @code{test} 25083command; you can instantiate this macro many times from within the 25084same test group, and one of the conditions is enough to turn 25085the test into an expected failure. 25086@end defmac 25087 25088@defmac AT_CLEANUP 25089@atindex{CLEANUP} 25090End the current test group. 25091@end defmac 25092 25093@sp 1 25094 25095@defmac AT_DATA (@var{file}, @var{contents}) 25096@atindex{DATA} 25097Initialize an input data @var{file} with given @var{contents}. Of 25098course, the @var{contents} have to be properly quoted between square 25099brackets to protect against included commas or spurious M4 25100expansion. @var{contents} must be empty or end with a newline. 25101@var{file} must 25102be a single shell word that expands into a single file name. 25103@end defmac 25104 25105@defmac AT_CHECK (@var{commands}, @dvar{status, 0}, @ovar{stdout}, @ 25106 @ovar{stderr}, @ovar{run-if-fail}, @ovar{run-if-pass}) 25107@defmacx AT_CHECK_UNQUOTED (@var{commands}, @dvar{status, 0}, @ovar{stdout}, @ 25108 @ovar{stderr}, @ovar{run-if-fail}, @ovar{run-if-pass}) 25109@atindex{CHECK} 25110@atindex{CHECK_UNQUOTED} 25111@vrindex at_status 25112Execute a test by performing given shell @var{commands} in a subshell. 25113@var{commands} is output as-is, so shell expansions are honored. These 25114commands should normally exit with @var{status}, while producing expected 25115@var{stdout} and @var{stderr} contents. If @var{commands} exit with 25116unexpected status 77, then the rest of the test group is skipped. If 25117@var{commands} exit with unexpected status 99, then the test group is 25118immediately failed. Otherwise, if this test fails, run shell commands 25119@var{run-if-fail} or, if this test passes, run shell commands 25120@var{run-if-pass}, both inside the current shell execution environment. 25121At the beginning of @var{run-if-fail} and @var{run-if-pass}, the status of 25122@var{commands} is available in the @code{at_status} shell variable. 25123 25124This macro must be invoked in between @code{AT_SETUP} and @code{AT_CLEANUP}. 25125 25126If @var{status} is the literal @samp{ignore}, then the corresponding 25127exit status is not checked, except for the special cases of 77 (skip) 25128and 99 (hard failure). The existence of hard failures allows one to 25129mark a test as an expected failure with @code{AT_XFAIL_IF} because a 25130feature has not yet been implemented, but to still distinguish between 25131gracefully handling the missing feature and dumping core. A hard 25132failure also inhibits post-test actions in @var{run-if-fail}. 25133 25134If the value of the @var{stdout} or @var{stderr} parameter is one of the 25135literals in the following table, then the test treats the output 25136according to the rules of that literal. Otherwise, the value of the 25137parameter is treated as text that must exactly match the output given by 25138@var{commands} on standard output and standard error (including an empty 25139parameter for no output); any differences are captured in the testsuite 25140log and the test is failed (unless an unexpected exit status of 77 25141skipped the test instead). The difference between @code{AT_CHECK} and 25142@code{AT_CHECK_UNQUOTED} is that only the latter performs shell variable 25143expansion (@samp{$}), command substitution (@samp{`}), and backslash 25144escaping (@samp{\}) on comparison text given in the @var{stdout} and 25145@var{stderr} arguments; if the text includes a trailing newline, this 25146would be the same as if it were specified via an unquoted 25147here-document. (However, there is no difference in the interpretation 25148of @var{commands}). 25149 25150@table @samp 25151@item ignore 25152The content of the output is ignored, but still captured in the test 25153group log (if the testsuite is run with option @option{-v}, the test 25154group log is displayed as the test is run; if the test group later 25155fails, the test group log is also copied into the overall testsuite 25156log). This action is valid for both @var{stdout} and @var{stderr}. 25157 25158@item ignore-nolog 25159The content of the output is ignored, and nothing is captured in the log 25160files. If @var{commands} are likely to produce binary output (including 25161long lines) or large amounts of output, then logging the output can make 25162it harder to locate details related to subsequent tests within the 25163group, and could potentially corrupt terminal display of a user running 25164@command{testsuite -v}. 25165 25166@item stdout 25167For the @var{stdout} parameter, capture the content of standard output 25168to both the file @file{stdout} and the test group log. Subsequent 25169commands in the test group can then post-process the file. This action 25170is often used when it is desired to use @command{grep} to look for a 25171substring in the output, or when the output must be post-processed to 25172normalize error messages into a common form. 25173 25174@item stderr 25175Like @samp{stdout}, except that it only works for the @var{stderr} 25176parameter, and the standard error capture file will be named 25177@file{stderr}. 25178 25179@item stdout-nolog 25180@itemx stderr-nolog 25181Like @samp{stdout} or @samp{stderr}, except that the captured output is 25182not duplicated into the test group log. This action is particularly 25183useful for an intermediate check that produces large amounts of data, 25184which will be followed by another check that filters down to the 25185relevant data, as it makes it easier to locate details in the log. 25186 25187@item expout 25188For the @var{stdout} parameter, compare standard output contents with 25189the previously created file @file{expout}, and list any differences in 25190the testsuite log. 25191 25192@item experr 25193Like @samp{expout}, except that it only works for the @var{stderr} 25194parameter, and the standard error contents are compared with 25195@file{experr}. 25196@end table 25197@end defmac 25198 25199@defmac AT_CHECK_EUNIT (@var{module}, @var{test-spec}, @ovar{erlflags}, @ 25200 @ovar{run-if-fail}, @ovar{run-if-pass}) 25201@atindex{CHECK_EUNIT} 25202Initialize and execute an Erlang module named @var{module} that performs 25203tests following the @var{test-spec} EUnit test specification. 25204@var{test-spec} must be a valid EUnit test specification, as defined in 25205the @uref{http://@/erlang.org/@/doc/@/apps/@/eunit/@/index.html, EUnit 25206Reference Manual}. @var{erlflags} are optional command-line options 25207passed to the Erlang interpreter to execute the test Erlang module. 25208Typically, @var{erlflags} defines at least the paths to directories 25209containing the compiled Erlang modules under test, as @samp{-pa path1 25210path2 ...}. 25211 25212For example, the unit tests associated with Erlang module @samp{testme}, 25213which compiled code is in subdirectory @file{src}, can be performed 25214with: 25215 25216@example 25217AT_CHECK_EUNIT([testme_testsuite], [@{module, testme@}], 25218 [-pa "$@{abs_top_builddir@}/src"]) 25219@end example 25220 25221This macro must be invoked in between @code{AT_SETUP} and @code{AT_CLEANUP}. 25222 25223Variables @code{ERL}, @code{ERLC}, and (optionally) @code{ERLCFLAGS} 25224must be defined as the path of the Erlang interpreter, the path of the 25225Erlang compiler, and the command-line flags to pass to the compiler, 25226respectively. Those variables should be configured in 25227@file{configure.ac} using the @command{AC_ERLANG_PATH_ERL} and 25228@command{AC_ERLANG_PATH_ERLC} macros, and the configured values of those 25229variables are automatically defined in the testsuite. If @code{ERL} or 25230@code{ERLC} is not defined, the test group is skipped. 25231 25232If the EUnit library cannot be found, i.e. if module @code{eunit} cannot 25233be loaded, the test group is skipped. Otherwise, if @var{test-spec} is 25234an invalid EUnit test specification, the test group fails. Otherwise, 25235if the EUnit test passes, shell commands @var{run-if-pass} are executed 25236or, if the EUnit test fails, shell commands @var{run-if-fail} are 25237executed and the test group fails. 25238 25239Only the generated test Erlang module is automatically compiled and 25240executed. If @var{test-spec} involves testing other Erlang modules, 25241e.g. module @samp{testme} in the example above, those modules must be 25242already compiled. 25243 25244If the testsuite is run in verbose mode, with option @option{--verbose}, 25245EUnit is also run in verbose mode to output more details about 25246individual unit tests. 25247@end defmac 25248 25249 25250@node testsuite Invocation 25251@section Running @command{testsuite} Scripts 25252@cindex @command{testsuite} 25253 25254Autotest test suites support the following options: 25255 25256@table @option 25257@item --help 25258@itemx -h 25259Display the list of options and exit successfully. 25260 25261@item --version 25262@itemx -V 25263Display the version of the test suite and exit successfully. 25264 25265@item --directory=@var{dir} 25266@itemx -C @var{dir} 25267Change the current directory to @var{dir} before creating any files. 25268Useful for running the testsuite in a subdirectory from a top-level 25269Makefile. 25270 25271@item --jobs@r{[}=@var{n}@r{]} 25272@itemx -j@ovar{n} 25273Run @var{n} tests in parallel, if possible. If @var{n} is not given, 25274run all given tests in parallel. Note that there should be no space 25275before the argument to @option{-j}, as @option{-j @var{number}} denotes 25276the separate arguments @option{-j} and @option{@var{number}}, see below. 25277 25278In parallel mode, the standard input device of the testsuite script is 25279not available to commands inside a test group. Furthermore, banner 25280lines are not printed, and the summary line for each test group is 25281output after the test group completes. Summary lines may appear 25282unordered. If verbose and trace output are enabled (see below), they 25283may appear intermixed from concurrently running tests. 25284 25285Parallel mode requires the @command{mkfifo} command to work, and will be 25286silently disabled otherwise. 25287 25288@item --clean 25289@itemx -c 25290Remove all the files the test suite might have created and exit. Meant 25291for @code{clean} Make targets. 25292 25293@item --list 25294@itemx -l 25295List all the tests (or only the selection), including their possible 25296keywords. 25297@end table 25298 25299@sp 1 25300 25301By default all tests are performed (or described with @option{--list}) 25302silently in the default environment, but the environment, set of tests, 25303and verbosity level can be tuned: 25304 25305@table @samp 25306@item @var{variable}=@var{value} 25307Set the environment @var{variable} to @var{value}. Use this rather 25308than @samp{FOO=foo ./testsuite} as debugging scripts would then run in a 25309different environment. 25310 25311@cindex @code{AUTOTEST_PATH} 25312The variable @code{AUTOTEST_PATH} specifies the testing path to prepend 25313to @env{PATH}. Relative directory names (not starting with 25314@samp{/}) are considered to be relative to the top level of the 25315package being built. All directories are made absolute, first 25316starting from the top level @emph{build} tree, then from the 25317@emph{source} tree. For instance @samp{./testsuite 25318AUTOTEST_PATH=tests:bin} for a @file{/src/foo-1.0} source package built 25319in @file{/tmp/foo} results in @samp{/tmp/foo/tests:/tmp/foo/bin} and 25320then @samp{/src/foo-1.0/tests:/src/foo-1.0/bin} being prepended to 25321@env{PATH}. 25322 25323@item @var{number} 25324@itemx @var{number}-@var{number} 25325@itemx @var{number}- 25326@itemx -@var{number} 25327Add the corresponding test groups, with obvious semantics, to the 25328selection. 25329 25330@item --keywords=@var{keywords} 25331@itemx -k @var{keywords} 25332Add to the selection the test groups with title or keywords (arguments 25333to @code{AT_SETUP} or @code{AT_KEYWORDS}) that match @emph{all} keywords 25334of the comma separated list @var{keywords}, case-insensitively. Use 25335@samp{!} immediately before the keyword to invert the selection for this 25336keyword. By default, the keywords match whole words; enclose them in 25337@samp{.*} to also match parts of words. 25338 25339For example, running 25340 25341@example 25342@kbd{./testsuite -k 'autoupdate,.*FUNC.*'} 25343@end example 25344 25345@noindent 25346selects all tests tagged @samp{autoupdate} @emph{and} with tags 25347containing @samp{FUNC} (as in @samp{AC_CHECK_FUNC}, @samp{AC_FUNC_ALLOCA}, 25348etc.), while 25349 25350@example 25351@kbd{./testsuite -k '!autoupdate' -k '.*FUNC.*'} 25352@end example 25353 25354@noindent 25355selects all tests not tagged @samp{autoupdate} @emph{or} with tags 25356containing @samp{FUNC}. 25357 25358@item --errexit 25359@itemx -e 25360If any test fails, immediately abort testing. This implies 25361@option{--debug}: post test group clean up, and top-level logging 25362are inhibited. This option is meant for the full test 25363suite, it is not really useful for generated debugging scripts. 25364If the testsuite is run in parallel mode using @option{--jobs}, 25365then concurrently running tests will finish before exiting. 25366 25367@item --verbose 25368@itemx -v 25369Force more verbosity in the detailed output of what is being done. This 25370is the default for debugging scripts. 25371 25372@item --color 25373@itemx --color@r{[}=never@r{|}auto@r{|}always@r{]} 25374Enable colored test results. Without an argument, or with @samp{always}, 25375test results will be colored. With @samp{never}, color mode is turned 25376off. Otherwise, if either the macro @code{AT_COLOR_TESTS} is used by 25377the testsuite author, or the argument @samp{auto} is given, then test 25378results are colored if standard output is connected to a terminal. 25379 25380@item --debug 25381@itemx -d 25382Do not remove the files after a test group was performed---but they are 25383still removed @emph{before}, therefore using this option is sane when 25384running several test groups. Create debugging scripts. Do not 25385overwrite the top-level 25386log (in order to preserve a supposedly existing full log file). This is 25387the default for debugging scripts, but it can also be useful to debug 25388the testsuite itself. 25389 25390@item --recheck 25391Add to the selection all test groups that failed or passed unexpectedly 25392during the last non-debugging test run. 25393 25394@item --trace 25395@itemx -x 25396Trigger shell tracing of the test groups. 25397@end table 25398 25399Besides these options accepted by every Autotest testsuite, the 25400testsuite author might have added package-specific options 25401via the @code{AT_ARG_OPTION} and @code{AT_ARG_OPTION_ARG} macros 25402(@pxref{Writing Testsuites}); refer to @command{testsuite --help} and 25403the package documentation for details. 25404 25405 25406@node Making testsuite Scripts 25407@section Making @command{testsuite} Scripts 25408 25409For putting Autotest into movement, you need some configuration and 25410makefile machinery. We recommend, at least if your package uses deep or 25411shallow hierarchies, that you use @file{tests/} as the name of the 25412directory holding all your tests and their makefile. Here is a 25413check list of things to do. 25414 25415@itemize @minus 25416 25417@item 25418@cindex @file{package.m4} 25419@atindex{PACKAGE_STRING} 25420@atindex{PACKAGE_BUGREPORT} 25421@atindex{PACKAGE_NAME} 25422@atindex{PACKAGE_TARNAME} 25423@atindex{PACKAGE_VERSION} 25424@atindex{PACKAGE_URL} 25425Make sure to create the file @file{package.m4}, which defines the 25426identity of the package. It must define @code{AT_PACKAGE_STRING}, the 25427full signature of the package, and @code{AT_PACKAGE_BUGREPORT}, the 25428address to which bug reports should be sent. For sake of completeness, 25429we suggest that you also define @code{AT_PACKAGE_NAME}, 25430@code{AT_PACKAGE_TARNAME}, @code{AT_PACKAGE_VERSION}, and 25431@code{AT_PACKAGE_URL}. 25432@xref{Initializing configure}, for a description of these variables. 25433Be sure to distribute @file{package.m4} and to put it into the source 25434hierarchy: the test suite ought to be shipped! See below for an example 25435@file{Makefile} excerpt. 25436 25437@item 25438Invoke @code{AC_CONFIG_TESTDIR}. 25439 25440@defmac AC_CONFIG_TESTDIR (@var{directory}, @dvar{test-path, directory}) 25441@acindex{CONFIG_TESTDIR} 25442An Autotest test suite is to be configured in @var{directory}. This 25443macro causes @file{@var{directory}/atconfig} to be created by 25444@command{config.status} and sets the default @code{AUTOTEST_PATH} to 25445@var{test-path} (@pxref{testsuite Invocation}). 25446@end defmac 25447 25448@item 25449Still within @file{configure.ac}, as appropriate, ensure that some 25450@code{AC_CONFIG_FILES} command includes substitution for 25451@file{tests/atlocal}. 25452 25453@item 25454The appropriate @file{Makefile} should be modified so the validation in 25455your package is triggered by @samp{make check}. An example is provided 25456below. 25457@end itemize 25458 25459With Automake, here is a minimal example for inclusion in 25460@file{tests/Makefile.am}, in order to link @samp{make check} with a 25461validation suite. 25462 25463@example 25464# The `:;' works around a Bash 3.2 bug when the output is not writable. 25465$(srcdir)/package.m4: $(top_srcdir)/configure.ac 25466 :;@{ \ 25467 echo '# Signature of the current package.' && \ 25468 echo 'm4_define([AT_PACKAGE_NAME],' && \ 25469 echo ' [$(PACKAGE_NAME)])' && \ 25470 echo 'm4_define([AT_PACKAGE_TARNAME],' && \ 25471 echo ' [$(PACKAGE_TARNAME)])' && \ 25472 echo 'm4_define([AT_PACKAGE_VERSION],' && \ 25473 echo ' [$(PACKAGE_VERSION)])' && \ 25474 echo 'm4_define([AT_PACKAGE_STRING],' && \ 25475 echo ' [$(PACKAGE_STRING)])' && \ 25476 echo 'm4_define([AT_PACKAGE_BUGREPORT],' && \ 25477 echo ' [$(PACKAGE_BUGREPORT)])'; \ 25478 echo 'm4_define([AT_PACKAGE_URL],' && \ 25479 echo ' [$(PACKAGE_URL)])'; \ 25480 @} >'$(srcdir)/package.m4' 25481 25482EXTRA_DIST = testsuite.at $(srcdir)/package.m4 $(TESTSUITE) atlocal.in 25483TESTSUITE = $(srcdir)/testsuite 25484 25485check-local: atconfig atlocal $(TESTSUITE) 25486 $(SHELL) '$(TESTSUITE)' $(TESTSUITEFLAGS) 25487 25488installcheck-local: atconfig atlocal $(TESTSUITE) 25489 $(SHELL) '$(TESTSUITE)' AUTOTEST_PATH='$(bindir)' \ 25490 $(TESTSUITEFLAGS) 25491 25492clean-local: 25493 test ! -f '$(TESTSUITE)' || \ 25494 $(SHELL) '$(TESTSUITE)' --clean 25495 25496AUTOM4TE = $(SHELL) $(srcdir)/build-aux/missing --run autom4te 25497AUTOTEST = $(AUTOM4TE) --language=autotest 25498$(TESTSUITE): $(srcdir)/testsuite.at $(srcdir)/package.m4 25499 $(AUTOTEST) -I '$(srcdir)' -o $@@.tmp $@@.at 25500 mv $@@.tmp $@@ 25501@end example 25502 25503Note that the built testsuite is distributed; this is necessary because 25504users might not have Autoconf installed, and thus would not be able to 25505rebuild it. Likewise, the use of @file{missing} provides the user with 25506a nicer error message if they modify a source file to the testsuite, and 25507accidentally trigger the rebuild rules. 25508 25509You might want to list explicitly the dependencies, i.e., the list of 25510the files @file{testsuite.at} includes. 25511 25512If you don't use Automake, you should include the above example in 25513@file{tests/@/Makefile.in}, along with additional lines inspired from 25514the following: 25515 25516@example 25517subdir = tests 25518PACKAGE_NAME = @@PACKAGE_NAME@@ 25519PACKAGE_TARNAME = @@PACKAGE_TARNAME@@ 25520PACKAGE_VERSION = @@PACKAGE_VERSION@@ 25521PACKAGE_STRING = @@PACKAGE_STRING@@ 25522PACKAGE_BUGREPORT = @@PACKAGE_BUGREPORT@@ 25523PACKAGE_URL = @@PACKAGE_URL@@ 25524 25525atconfig: $(top_builddir)/config.status 25526 cd $(top_builddir) && \ 25527 $(SHELL) ./config.status $(subdir)/$@@ 25528 25529atlocal: $(srcdir)/atlocal.in $(top_builddir)/config.status 25530 cd $(top_builddir) && \ 25531 $(SHELL) ./config.status $(subdir)/$@@ 25532@end example 25533 25534@noindent 25535and manage to have @code{$(EXTRA_DIST)} distributed. You will also want 25536to distribute the file @file{build-aux/@/missing} from the Automake 25537project; a copy of this file resides in the Autoconf source tree. 25538 25539With all this in place, and if you have not initialized @samp{TESTSUITEFLAGS} 25540within your makefile, you can fine-tune test suite execution with this 25541variable, for example: 25542 25543@example 25544make check TESTSUITEFLAGS='-v -d -x 75 -k AC_PROG_CC CFLAGS=-g' 25545@end example 25546 25547 25548 25549@c =============================== Frequent Autoconf Questions, with answers 25550 25551@node FAQ 25552@chapter Frequent Autoconf Questions, with answers 25553 25554Several questions about Autoconf come up occasionally. Here some of them 25555are addressed. 25556 25557@menu 25558* Distributing:: Distributing @command{configure} scripts 25559* Why GNU M4:: Why not use the standard M4? 25560* Bootstrapping:: Autoconf and GNU M4 require each other? 25561* Why Not Imake:: Why GNU uses @command{configure} instead of Imake 25562* Defining Directories:: Passing @code{datadir} to program 25563* Autom4te Cache:: What is it? Can I remove it? 25564* Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree 25565* Expanded Before Required:: Expanded Before Required 25566* Debugging:: Debugging @command{configure} scripts 25567@end menu 25568 25569@node Distributing 25570@section Distributing @command{configure} Scripts 25571@cindex License 25572 25573@display 25574What are the restrictions on distributing @command{configure} 25575scripts that Autoconf generates? How does that affect my 25576programs that use them? 25577@end display 25578 25579There are no restrictions on how the configuration scripts that Autoconf 25580produces may be distributed or used. In Autoconf version 1, they were 25581covered by the GNU General Public License. We still encourage 25582software authors to distribute their work under terms like those of the 25583GPL, but doing so is not required to use Autoconf. 25584 25585Of the other files that might be used with @command{configure}, 25586@file{config.h.in} is under whatever copyright you use for your 25587@file{configure.ac}. @file{config.sub} and @file{config.guess} have an 25588exception to the GPL when they are used with an Autoconf-generated 25589@command{configure} script, which permits you to distribute them under the 25590same terms as the rest of your package. @file{install-sh} is from the X 25591Consortium and is not copyrighted. 25592 25593@node Why GNU M4 25594@section Why Require GNU M4? 25595 25596@display 25597Why does Autoconf require GNU M4? 25598@end display 25599 25600Many M4 implementations have hard-coded limitations on the size and 25601number of macros that Autoconf exceeds. They also lack several 25602builtin macros that it would be difficult to get along without in a 25603sophisticated application like Autoconf, including: 25604 25605@example 25606m4_builtin 25607m4_indir 25608m4_bpatsubst 25609__file__ 25610__line__ 25611@end example 25612 25613Autoconf requires version 1.4.6 or later of GNU M4. 25614 25615Since only software maintainers need to use Autoconf, and since GNU 25616M4 is simple to configure and install, it seems reasonable to require 25617GNU M4 to be installed also. Many maintainers of GNU and 25618other free software already have most of the GNU utilities 25619installed, since they prefer them. 25620 25621@node Bootstrapping 25622@section How Can I Bootstrap? 25623@cindex Bootstrap 25624 25625@display 25626If Autoconf requires GNU M4 and GNU M4 has an Autoconf 25627@command{configure} script, how do I bootstrap? It seems like a chicken 25628and egg problem! 25629@end display 25630 25631This is a misunderstanding. Although GNU M4 does come with a 25632@command{configure} script produced by Autoconf, Autoconf is not required 25633in order to run the script and install GNU M4. Autoconf is only 25634required if you want to change the M4 @command{configure} script, which few 25635people have to do (mainly its maintainer). 25636 25637@node Why Not Imake 25638@section Why Not Imake? 25639@cindex Imake 25640 25641@display 25642Why not use Imake instead of @command{configure} scripts? 25643@end display 25644 25645Several people have written addressing this question, so 25646adaptations of their explanations are included here. 25647 25648The following answer is based on one written by Richard Pixley: 25649 25650@quotation 25651Autoconf generated scripts frequently work on machines that it has 25652never been set up to handle before. That is, it does a good job of 25653inferring a configuration for a new system. Imake cannot do this. 25654 25655Imake uses a common database of host specific data. For X11, this makes 25656sense because the distribution is made as a collection of tools, by one 25657central authority who has control over the database. 25658 25659GNU tools are not released this way. Each GNU tool has a 25660maintainer; these maintainers are scattered across the world. Using a 25661common database would be a maintenance nightmare. Autoconf may appear 25662to be this kind of database, but in fact it is not. Instead of listing 25663host dependencies, it lists program requirements. 25664 25665If you view the GNU suite as a collection of native tools, then the 25666problems are similar. But the GNU development tools can be 25667configured as cross tools in almost any host+target permutation. All of 25668these configurations can be installed concurrently. They can even be 25669configured to share host independent files across hosts. Imake doesn't 25670address these issues. 25671 25672Imake templates are a form of standardization. The GNU coding 25673standards address the same issues without necessarily imposing the same 25674restrictions. 25675@end quotation 25676 25677 25678Here is some further explanation, written by Per Bothner: 25679 25680@quotation 25681One of the advantages of Imake is that it is easy to generate large 25682makefiles using the @samp{#include} and macro mechanisms of @command{cpp}. 25683However, @code{cpp} is not programmable: it has limited conditional 25684facilities, and no looping. And @code{cpp} cannot inspect its 25685environment. 25686 25687All of these problems are solved by using @code{sh} instead of 25688@code{cpp}. The shell is fully programmable, has macro substitution, 25689can execute (or source) other shell scripts, and can inspect its 25690environment. 25691@end quotation 25692 25693 25694Paul Eggert elaborates more: 25695 25696@quotation 25697With Autoconf, installers need not assume that Imake itself is already 25698installed and working well. This may not seem like much of an advantage 25699to people who are accustomed to Imake. But on many hosts Imake is not 25700installed or the default installation is not working well, and requiring 25701Imake to install a package hinders the acceptance of that package on 25702those hosts. For example, the Imake template and configuration files 25703might not be installed properly on a host, or the Imake build procedure 25704might wrongly assume that all source files are in one big directory 25705tree, or the Imake configuration might assume one compiler whereas the 25706package or the installer needs to use another, or there might be a 25707version mismatch between the Imake expected by the package and the Imake 25708supported by the host. These problems are much rarer with Autoconf, 25709where each package comes with its own independent configuration 25710processor. 25711 25712Also, Imake often suffers from unexpected interactions between 25713@command{make} and the installer's C preprocessor. The fundamental problem 25714here is that the C preprocessor was designed to preprocess C programs, 25715not makefiles. This is much less of a problem with Autoconf, 25716which uses the general-purpose preprocessor M4, and where the 25717package's author (rather than the installer) does the preprocessing in a 25718standard way. 25719@end quotation 25720 25721 25722Finally, Mark Eichin notes: 25723 25724@quotation 25725Imake isn't all that extensible, either. In order to add new features to 25726Imake, you need to provide your own project template, and duplicate most 25727of the features of the existing one. This means that for a sophisticated 25728project, using the vendor-provided Imake templates fails to provide any 25729leverage---since they don't cover anything that your own project needs 25730(unless it is an X11 program). 25731 25732On the other side, though: 25733 25734The one advantage that Imake has over @command{configure}: 25735@file{Imakefile} files tend to be much shorter (likewise, less redundant) 25736than @file{Makefile.in} files. There is a fix to this, however---at least 25737for the Kerberos V5 tree, we've modified things to call in common 25738@file{post.in} and @file{pre.in} makefile fragments for the 25739entire tree. This means that a lot of common things don't have to be 25740duplicated, even though they normally are in @command{configure} setups. 25741@end quotation 25742 25743 25744@node Defining Directories 25745@section How Do I @code{#define} Installation Directories? 25746 25747@display 25748My program needs library files, installed in @code{datadir} and 25749similar. If I use 25750 25751@example 25752AC_DEFINE_UNQUOTED([DATADIR], [$datadir], 25753 [Define to the read-only architecture-independent 25754 data directory.]) 25755@end example 25756 25757@noindent 25758I get 25759 25760@example 25761#define DATADIR "$@{prefix@}/share" 25762@end example 25763@end display 25764 25765As already explained, this behavior is on purpose, mandated by the 25766GNU Coding Standards, see @ref{Installation Directory 25767Variables}. There are several means to achieve a similar goal: 25768 25769@itemize @minus 25770@item 25771Do not use @code{AC_DEFINE} but use your makefile to pass the 25772actual value of @code{datadir} via compilation flags. 25773@xref{Installation Directory Variables}, for the details. 25774 25775@item 25776This solution can be simplified when compiling a program: you may either 25777extend the @code{CPPFLAGS}: 25778 25779@example 25780CPPFLAGS = -DDATADIR='"$(datadir)"' @@CPPFLAGS@@ 25781@end example 25782 25783@noindent 25784If you are using Automake, you should use @code{AM_CPPFLAGS} instead: 25785 25786@example 25787AM_CPPFLAGS = -DDATADIR='"$(datadir)"' 25788@end example 25789 25790@noindent 25791Alternatively, create a dedicated header file: 25792 25793@example 25794DISTCLEANFILES = myprog-paths.h 25795myprog-paths.h: Makefile 25796 echo '#define DATADIR "$(datadir)"' >$@@ 25797@end example 25798 25799@noindent 25800The gnulib module @samp{configmake} provides such a header with all the 25801standard directory variables defined, @pxref{configmake,,, gnulib, GNU 25802Gnulib}. 25803 25804@item 25805Use @code{AC_DEFINE} but have @command{configure} compute the literal 25806value of @code{datadir} and others. Many people have wrapped macros to 25807automate this task; for an example, see the macro @code{AC_DEFINE_DIR} from 25808the @uref{http://@/www.gnu.org/@/software/@/autoconf-archive/, Autoconf Macro 25809Archive}. 25810 25811This solution does not conform to the GNU Coding Standards. 25812 25813@item 25814Note that all the previous solutions hard wire the absolute name of 25815these directories in the executables, which is not a good property. You 25816may try to compute the names relative to @code{prefix}, and try to 25817find @code{prefix} at runtime, this way your package is relocatable. 25818@end itemize 25819 25820 25821@node Autom4te Cache 25822@section What is @file{autom4te.cache}? 25823 25824@display 25825What is this directory @file{autom4te.cache}? Can I safely remove it? 25826@end display 25827 25828In the GNU Build System, @file{configure.ac} plays a central 25829role and is read by many tools: @command{autoconf} to create 25830@file{configure}, @command{autoheader} to create @file{config.h.in}, 25831@command{automake} to create @file{Makefile.in}, @command{autoscan} to 25832check the completeness of @file{configure.ac}, @command{autoreconf} to 25833check the GNU Build System components that are used. To 25834``read @file{configure.ac}'' actually means to compile it with M4, 25835which can be a long process for complex @file{configure.ac}. 25836 25837This is why all these tools, instead of running directly M4, invoke 25838@command{autom4te} (@pxref{autom4te Invocation}) which, while answering to 25839a specific demand, stores additional information in 25840@file{autom4te.cache} for future runs. For instance, if you run 25841@command{autoconf}, behind the scenes, @command{autom4te} also 25842stores information for the other tools, so that when you invoke 25843@command{autoheader} or @command{automake} etc., reprocessing 25844@file{configure.ac} is not needed. The speed up is frequently 30%, 25845and is increasing with the size of @file{configure.ac}. 25846 25847But it is and remains being simply a cache: you can safely remove it. 25848 25849@sp 1 25850 25851@display 25852Can I permanently get rid of it? 25853@end display 25854 25855The creation of this cache can be disabled from 25856@file{~/.autom4te.cfg}, see @ref{Customizing autom4te}, for more 25857details. You should be aware that disabling the cache slows down the 25858Autoconf test suite by 40%. The more GNU Build System 25859components are used, the more the cache is useful; for instance 25860running @samp{autoreconf -f} on the Core Utilities is twice slower without 25861the cache @emph{although @option{--force} implies that the cache is 25862not fully exploited}, and eight times slower than without 25863@option{--force}. 25864 25865 25866@node Present But Cannot Be Compiled 25867@section Header Present But Cannot Be Compiled 25868 25869The most important guideline to bear in mind when checking for 25870features is to mimic as much as possible the intended use. 25871Unfortunately, old versions of @code{AC_CHECK_HEADER} and 25872@code{AC_CHECK_HEADERS} failed to follow this idea, and called 25873the preprocessor, instead of the compiler, to check for headers. As a 25874result, incompatibilities between headers went unnoticed during 25875configuration, and maintainers finally had to deal with this issue 25876elsewhere. 25877 25878The transition began with Autoconf 2.56. As of Autoconf 2.64 both 25879checks are performed, and @command{configure} complains loudly if the 25880compiler and the preprocessor do not agree. However, only the compiler 25881result is considered. 25882 25883Consider the following example: 25884 25885@smallexample 25886$ @kbd{cat number.h} 25887typedef int number; 25888$ @kbd{cat pi.h} 25889const number pi = 3; 25890$ @kbd{cat configure.ac} 25891AC_INIT([Example], [1.0], [bug-example@@example.org]) 25892AC_CHECK_HEADERS([pi.h]) 25893$ @kbd{autoconf -Wall} 25894$ @kbd{./configure} 25895checking for gcc... gcc 25896checking for C compiler default output file name... a.out 25897checking whether the C compiler works... yes 25898checking whether we are cross compiling... no 25899checking for suffix of executables... 25900checking for suffix of object files... o 25901checking whether we are using the GNU C compiler... yes 25902checking whether gcc accepts -g... yes 25903checking for gcc option to accept ISO C89... none needed 25904checking how to run the C preprocessor... gcc -E 25905checking for grep that handles long lines and -e... grep 25906checking for egrep... grep -E 25907checking for ANSI C header files... yes 25908checking for sys/types.h... yes 25909checking for sys/stat.h... yes 25910checking for stdlib.h... yes 25911checking for string.h... yes 25912checking for memory.h... yes 25913checking for strings.h... yes 25914checking for inttypes.h... yes 25915checking for stdint.h... yes 25916checking for unistd.h... yes 25917checking pi.h usability... no 25918checking pi.h presence... yes 25919configure: WARNING: pi.h: present but cannot be compiled 25920configure: WARNING: pi.h: check for missing prerequisite headers? 25921configure: WARNING: pi.h: see the Autoconf documentation 25922configure: WARNING: pi.h: section "Present But Cannot Be Compiled" 25923configure: WARNING: pi.h: proceeding with the compiler's result 25924configure: WARNING: ## -------------------------------------- ## 25925configure: WARNING: ## Report this to bug-example@@example.org ## 25926configure: WARNING: ## -------------------------------------- ## 25927checking for pi.h... yes 25928@end smallexample 25929 25930@noindent 25931The proper way the handle this case is using the fourth argument 25932(@pxref{Generic Headers}): 25933 25934@example 25935$ @kbd{cat configure.ac} 25936AC_INIT([Example], [1.0], [bug-example@@example.org]) 25937AC_CHECK_HEADERS([number.h pi.h], [], [], 25938[[#ifdef HAVE_NUMBER_H 25939# include <number.h> 25940#endif 25941]]) 25942$ @kbd{autoconf -Wall} 25943$ @kbd{./configure} 25944checking for gcc... gcc 25945checking for C compiler default output... a.out 25946checking whether the C compiler works... yes 25947checking whether we are cross compiling... no 25948checking for suffix of executables... 25949checking for suffix of object files... o 25950checking whether we are using the GNU C compiler... yes 25951checking whether gcc accepts -g... yes 25952checking for gcc option to accept ANSI C... none needed 25953checking for number.h... yes 25954checking for pi.h... yes 25955@end example 25956 25957See @ref{Particular Headers}, for a list of headers with their 25958prerequisites. 25959 25960@node Expanded Before Required 25961@section Expanded Before Required 25962 25963@cindex expanded before required 25964Older versions of Autoconf silently built files with incorrect ordering 25965between dependent macros if an outer macro first expanded, then later 25966indirectly required, an inner macro. Starting with Autoconf 2.64, this 25967situation no longer generates out-of-order code, but results in 25968duplicate output and a syntax warning: 25969 25970@example 25971$ @kbd{cat configure.ac} 25972@result{}AC_DEFUN([TESTA], [[echo in A 25973@result{}if test -n "$SEEN_A" ; then echo duplicate ; fi 25974@result{}SEEN_A=:]]) 25975@result{}AC_DEFUN([TESTB], [AC_REQUIRE([TESTA])[echo in B 25976@result{}if test -z "$SEEN_A" ; then echo bug ; fi]]) 25977@result{}AC_DEFUN([TESTC], [AC_REQUIRE([TESTB])[echo in C]]) 25978@result{}AC_DEFUN([OUTER], [[echo in OUTER] 25979@result{}TESTA 25980@result{}TESTC]) 25981@result{}AC_INIT 25982@result{}OUTER 25983@result{}AC_OUTPUT 25984$ @kbd{autoconf} 25985@result{}configure.ac:11: warning: AC_REQUIRE: 25986@result{} `TESTA' was expanded before it was required 25987@result{}configure.ac:4: TESTB is expanded from... 25988@result{}configure.ac:6: TESTC is expanded from... 25989@result{}configure.ac:7: OUTER is expanded from... 25990@result{}configure.ac:11: the top level 25991@end example 25992 25993@noindent 25994To avoid this warning, decide what purpose the macro in question serves. 25995If it only needs to be expanded once (for example, if it provides 25996initialization text used by later macros), then the simplest fix is to 25997change the macro to be declared with @code{AC_DEFUN_ONCE} 25998(@pxref{One-Shot Macros}), although this only works in Autoconf 2.64 and 25999newer. A more portable fix is to change all 26000instances of direct calls to instead go through @code{AC_REQUIRE} 26001(@pxref{Prerequisite Macros}). If, instead, the macro is parameterized 26002by arguments or by the current definition of other macros in the m4 26003environment, then the macro should always be directly expanded instead 26004of required. 26005 26006For another case study, consider this example trimmed down from an 26007actual package. Originally, the package contained shell code and 26008multiple macro invocations at the top level of @file{configure.ac}: 26009 26010@example 26011AC_DEFUN([FOO], [AC_COMPILE_IFELSE([@dots{}])]) 26012foobar= 26013AC_PROG_CC 26014FOO 26015@end example 26016 26017@noindent 26018but that was getting complex, so the author wanted to offload some of 26019the text into a new macro in another file included via 26020@file{aclocal.m4}. The na@"ive approach merely wraps the text in a new 26021macro: 26022 26023@example 26024AC_DEFUN([FOO], [AC_COMPILE_IFELSE([@dots{}])]) 26025AC_DEFUN([BAR], [ 26026foobar= 26027AC_PROG_CC 26028FOO 26029]) 26030BAR 26031@end example 26032 26033@noindent 26034With older versions of Autoconf, the setting of @samp{foobar=} occurs 26035before the single compiler check, as the author intended. But with 26036Autoconf 2.64, this issues the ``expanded before it was required'' 26037warning for @code{AC_PROG_CC}, and outputs two copies of the compiler 26038check, one before @samp{foobar=}, and one after. To understand why this 26039is happening, remember that the use of @code{AC_COMPILE_IFELSE} includes 26040a call to @code{AC_REQUIRE([AC_PROG_CC])} under the hood. According to 26041the documented semantics of @code{AC_REQUIRE}, this means that 26042@code{AC_PROG_CC} @emph{must} occur before the body of the outermost 26043@code{AC_DEFUN}, which in this case is @code{BAR}, thus preceding the 26044use of @samp{foobar=}. The older versions of Autoconf were broken with 26045regards to the rules of @code{AC_REQUIRE}, which explains why the code 26046changed from one over to two copies of @code{AC_PROG_CC} when upgrading 26047autoconf. In other words, the author was unknowingly relying on a bug 26048exploit to get the desired results, and that exploit broke once the bug 26049was fixed. 26050 26051So, what recourse does the author have, to restore their intended 26052semantics of setting @samp{foobar=} prior to a single compiler check, 26053regardless of whether Autoconf 2.63 or 2.64 is used? One idea is to 26054remember that only @code{AC_DEFUN} is impacted by @code{AC_REQUIRE}; 26055there is always the possibility of using the lower-level 26056@code{m4_define}: 26057 26058@example 26059AC_DEFUN([FOO], [AC_COMPILE_IFELSE([@dots{}])]) 26060m4_define([BAR], [ 26061foobar= 26062AC_PROG_CC 26063FOO 26064]) 26065BAR 26066@end example 26067 26068@noindent 26069This works great if everything is in the same file. However, it does 26070not help in the case where the author wants to have @command{aclocal} 26071find the definition of @code{BAR} from its own file, since 26072@command{aclocal} requires the use of @code{AC_DEFUN}. In this case, a 26073better fix is to recognize that if @code{BAR} also uses 26074@code{AC_REQUIRE}, then there will no longer be direct expansion prior 26075to a subsequent require. Then, by creating yet another helper macro, 26076the author can once again guarantee a single invocation of 26077@code{AC_PROG_CC}, which will still occur after @code{foobar=}. The 26078author can also use @code{AC_BEFORE} to make sure no other macro 26079appearing before @code{BAR} has triggered an unwanted expansion of 26080@code{AC_PROG_CC}. 26081 26082@example 26083AC_DEFUN([FOO], [AC_COMPILE_IFELSE([@dots{}])]) 26084AC_DEFUN([BEFORE_CC], [ 26085foobar= 26086]) 26087AC_DEFUN([BAR], [ 26088AC_BEFORE([$0], [AC_PROG_CC])dnl 26089AC_REQUIRE([BEFORE_CC])dnl 26090AC_REQUIRE([AC_PROG_CC])dnl 26091FOO 26092]) 26093BAR 26094@end example 26095 26096 26097@node Debugging 26098@section Debugging @command{configure} scripts 26099 26100While in general, @command{configure} scripts generated by Autoconf 26101strive to be fairly portable to various systems, compilers, shells, and 26102other tools, it may still be necessary to debug a failing test, broken 26103script or makefile, or fix or override an incomplete, faulty, or erroneous 26104test, especially during macro development. Failures can occur at all levels, 26105in M4 syntax or semantics, shell script issues, or due to bugs in the 26106test or the tools invoked by @command{configure}. Together with the 26107rather arcane error message that @command{m4} and @command{make} may 26108produce when their input contains syntax errors, this can make debugging 26109rather painful. 26110 26111Nevertheless, here is a list of hints and strategies that may help: 26112 26113@itemize 26114@item 26115When @command{autoconf} fails, common causes for error include: 26116 26117@itemize 26118@item 26119mismatched or unbalanced parentheses or braces (@pxref{Balancing 26120Parentheses}), 26121 26122@item under- or overquoted macro arguments (@pxref{Autoconf 26123Language}, @pxref{Quoting and Parameters}, @pxref{Quotation and Nested 26124Macros}), 26125 26126@item spaces between macro name and opening parenthesis (@pxref{Autoconf 26127Language}). 26128@end itemize 26129 26130Typically, it helps to go back to the last working version of the input 26131and compare the differences for each of these errors. Another 26132possibility is to sprinkle pairs of @code{m4_traceon} and 26133@code{m4_traceoff} judiciously in the code, either without a parameter 26134or listing some macro names and watch @command{m4} expand its input 26135verbosely (@pxref{Debugging via autom4te}). 26136 26137@item 26138Sometimes @command{autoconf} succeeds but the generated 26139@command{configure} script has invalid shell syntax. You can detect this 26140case by running @samp{bash -n configure} or @samp{sh -n configure}. 26141If this command fails, the same tips apply, as if @command{autoconf} had 26142failed. 26143 26144@item 26145Debugging @command{configure} script execution may be done by sprinkling 26146pairs of @code{set -x} and @code{set +x} into the shell script before 26147and after the region that contains a bug. Running the whole script with 26148@samp{@var{shell} -vx ./configure 2>&1 | tee @var{log-file}} with a decent 26149@var{shell} may work, but produces lots of output. Here, it can help to 26150search for markers like @samp{checking for} a particular test in the 26151@var{log-file}. 26152 26153@item 26154Alternatively, you might use a shell with debugging capabilities like 26155@uref{http://bashdb.sourceforge.net/, bashdb}. 26156 26157@item 26158When @command{configure} tests produce invalid results for your system, 26159it may be necessary to override them: 26160 26161@itemize 26162@item 26163For programs, tools or libraries variables, preprocessor, compiler, or 26164linker flags, it is often sufficient to override them at @command{make} 26165run time with some care (@pxref{Macros and Submakes}). Since this 26166normally won't cause @command{configure} to be run again with these 26167changed settings, it may fail if the changed variable would have caused 26168different test results from @command{configure}, so this may work only 26169for simple differences. 26170 26171@item 26172Most tests which produce their result in a substituted variable allow to 26173override the test by setting the variable on the @command{configure} 26174command line (@pxref{Compilers and Options}, @pxref{Defining Variables}, 26175@pxref{Particular Systems}). 26176 26177@item 26178Many tests store their result in a cache variable (@pxref{Caching 26179Results}). This lets you override them either on the 26180@command{configure} command line as above, or through a primed cache or 26181site file (@pxref{Cache Files}, @pxref{Site Defaults}). The name of a 26182cache variable is documented with a test macro or may be inferred from 26183@ref{Cache Variable Names}; the precise semantics of undocumented 26184variables are often internal details, subject to change. 26185@end itemize 26186 26187@item 26188Alternatively, @command{configure} may produce invalid results because 26189of uncaught programming errors, in your package or in an upstream 26190library package. For example, when @code{AC_CHECK_LIB} fails to find a 26191library with a specified function, always check @file{config.log}. This 26192will reveal the exact error that produced the failing result: the 26193library linked by @code{AC_CHECK_LIB} probably has a fatal bug. 26194@end itemize 26195 26196Conversely, as macro author, you can make it easier for users of your 26197macro: 26198 26199@itemize 26200@item 26201by minimizing dependencies between tests and between test results as far 26202as possible, 26203 26204@item 26205by using @command{make} variables to factorize and allow 26206override of settings at @command{make} run time, 26207 26208@item 26209by honoring the GNU Coding Standards and not overriding flags 26210reserved for the user except temporarily during @command{configure} 26211tests, 26212 26213@item 26214by not requiring users of your macro to use the cache variables. 26215Instead, expose the result of the test via @var{run-if-true} and 26216@var{run-if-false} parameters. If the result is not a boolean, 26217then provide it through documented shell variables. 26218@end itemize 26219 26220 26221@c ===================================================== History of Autoconf. 26222 26223@node History 26224@chapter History of Autoconf 26225@cindex History of autoconf 26226 26227@emph{This chapter was written by the original author, David MacKenzie.} 26228 26229You may be wondering, Why was Autoconf originally written? How did it 26230get into its present form? (Why does it look like gorilla spit?) If 26231you're not wondering, then this chapter contains no information useful 26232to you, and you might as well skip it. If you @emph{are} wondering, 26233then let there be light@enddots{} 26234 26235@menu 26236* Genesis:: Prehistory and naming of @command{configure} 26237* Exodus:: The plagues of M4 and Perl 26238* Leviticus:: The priestly code of portability arrives 26239* Numbers:: Growth and contributors 26240* Deuteronomy:: Approaching the promises of easy configuration 26241@end menu 26242 26243@node Genesis 26244@section Genesis 26245 26246In June 1991 I was maintaining many of the GNU utilities for the 26247Free Software Foundation. As they were ported to more platforms and 26248more programs were added, the number of @option{-D} options that users 26249had to select in the makefile (around 20) became burdensome. 26250Especially for me---I had to test each new release on a bunch of 26251different systems. So I wrote a little shell script to guess some of 26252the correct settings for the fileutils package, and released it as part 26253of fileutils 2.0. That @command{configure} script worked well enough that 26254the next month I adapted it (by hand) to create similar @command{configure} 26255scripts for several other GNU utilities packages. Brian Berliner 26256also adapted one of my scripts for his CVS revision control system. 26257 26258Later that summer, I learned that Richard Stallman and Richard Pixley 26259were developing similar scripts to use in the GNU compiler tools; 26260so I adapted my @command{configure} scripts to support their evolving 26261interface: using the file name @file{Makefile.in} as the templates; 26262adding @samp{+srcdir}, the first option (of many); and creating 26263@file{config.status} files. 26264 26265@node Exodus 26266@section Exodus 26267 26268As I got feedback from users, I incorporated many improvements, using 26269Emacs to search and replace, cut and paste, similar changes in each of 26270the scripts. As I adapted more GNU utilities packages to use 26271@command{configure} scripts, updating them all by hand became impractical. 26272Rich Murphey, the maintainer of the GNU graphics utilities, sent me 26273mail saying that the @command{configure} scripts were great, and asking if 26274I had a tool for generating them that I could send him. No, I thought, 26275but I should! So I started to work out how to generate them. And the 26276journey from the slavery of hand-written @command{configure} scripts to the 26277abundance and ease of Autoconf began. 26278 26279Cygnus @command{configure}, which was being developed at around that time, 26280is table driven; it is meant to deal mainly with a discrete number of 26281system types with a small number of mainly unguessable features (such as 26282details of the object file format). The automatic configuration system 26283that Brian Fox had developed for Bash takes a similar approach. For 26284general use, it seems to me a hopeless cause to try to maintain an 26285up-to-date database of which features each variant of each operating 26286system has. It's easier and more reliable to check for most features on 26287the fly---especially on hybrid systems that people have hacked on 26288locally or that have patches from vendors installed. 26289 26290I considered using an architecture similar to that of Cygnus 26291@command{configure}, where there is a single @command{configure} script that 26292reads pieces of @file{configure.in} when run. But I didn't want to have 26293to distribute all of the feature tests with every package, so I settled 26294on having a different @command{configure} made from each 26295@file{configure.in} by a preprocessor. That approach also offered more 26296control and flexibility. 26297 26298I looked briefly into using the Metaconfig package, by Larry Wall, 26299Harlan Stenn, and Raphael Manfredi, but I decided not to for several 26300reasons. The @command{Configure} scripts it produces are interactive, 26301which I find quite inconvenient; I didn't like the ways it checked for 26302some features (such as library functions); I didn't know that it was 26303still being maintained, and the @command{Configure} scripts I had 26304seen didn't work on many modern systems (such as System V R4 and NeXT); 26305it wasn't flexible in what it could do in response to a feature's 26306presence or absence; I found it confusing to learn; and it was too big 26307and complex for my needs (I didn't realize then how much Autoconf would 26308eventually have to grow). 26309 26310I considered using Perl to generate my style of @command{configure} 26311scripts, but decided that M4 was better suited to the job of simple 26312textual substitutions: it gets in the way less, because output is 26313implicit. Plus, everyone already has it. (Initially I didn't rely on 26314the GNU extensions to M4.) Also, some of my friends at the 26315University of Maryland had recently been putting M4 front ends on 26316several programs, including @code{tvtwm}, and I was interested in trying 26317out a new language. 26318 26319@node Leviticus 26320@section Leviticus 26321 26322Since my @command{configure} scripts determine the system's capabilities 26323automatically, with no interactive user intervention, I decided to call 26324the program that generates them Autoconfig. But with a version number 26325tacked on, that name would be too long for old Unix file systems, 26326so I shortened it to Autoconf. 26327 26328In the fall of 1991 I called together a group of fellow questers after 26329the Holy Grail of portability (er, that is, alpha testers) to give me 26330feedback as I encapsulated pieces of my handwritten scripts in M4 macros 26331and continued to add features and improve the techniques used in the 26332checks. Prominent among the testers were Fran@,{c}ois Pinard, who came up 26333with the idea of making an Autoconf shell script to run M4 26334and check for unresolved macro calls; Richard Pixley, who suggested 26335running the compiler instead of searching the file system to find 26336include files and symbols, for more accurate results; Karl Berry, who 26337got Autoconf to configure @TeX{} and added the macro index to the 26338documentation; and Ian Lance Taylor, who added support for creating a C 26339header file as an alternative to putting @option{-D} options in a 26340makefile, so he could use Autoconf for his UUCP package. 26341The alpha testers cheerfully adjusted their files again and again as the 26342names and calling conventions of the Autoconf macros changed from 26343release to release. They all contributed many specific checks, great 26344ideas, and bug fixes. 26345 26346@node Numbers 26347@section Numbers 26348 26349In July 1992, after months of alpha testing, I released Autoconf 1.0, 26350and converted many GNU packages to use it. I was surprised by how 26351positive the reaction to it was. More people started using it than I 26352could keep track of, including people working on software that wasn't 26353part of the GNU Project (such as TCL, FSP, and Kerberos V5). 26354Autoconf continued to improve rapidly, as many people using the 26355@command{configure} scripts reported problems they encountered. 26356 26357Autoconf turned out to be a good torture test for M4 implementations. 26358Unix M4 started to dump core because of the length of the 26359macros that Autoconf defined, and several bugs showed up in GNU 26360M4 as well. Eventually, we realized that we needed to use some 26361features that only GNU M4 has. 4.3BSD M4, in 26362particular, has an impoverished set of builtin macros; the System V 26363version is better, but still doesn't provide everything we need. 26364 26365More development occurred as people put Autoconf under more stresses 26366(and to uses I hadn't anticipated). Karl Berry added checks for X11. 26367david zuhn contributed C++ support. Fran@,{c}ois Pinard made it diagnose 26368invalid arguments. Jim Blandy bravely coerced it into configuring 26369GNU Emacs, laying the groundwork for several later improvements. 26370Roland McGrath got it to configure the GNU C Library, wrote the 26371@command{autoheader} script to automate the creation of C header file 26372templates, and added a @option{--verbose} option to @command{configure}. 26373Noah Friedman added the @option{--autoconf-dir} option and 26374@code{AC_MACRODIR} environment variable. (He also coined the term 26375@dfn{autoconfiscate} to mean ``adapt a software package to use 26376Autoconf''.) Roland and Noah improved the quoting protection in 26377@code{AC_DEFINE} and fixed many bugs, especially when I got sick of 26378dealing with portability problems from February through June, 1993. 26379 26380@node Deuteronomy 26381@section Deuteronomy 26382 26383A long wish list for major features had accumulated, and the effect of 26384several years of patching by various people had left some residual 26385cruft. In April 1994, while working for Cygnus Support, I began a major 26386revision of Autoconf. I added most of the features of the Cygnus 26387@command{configure} that Autoconf had lacked, largely by adapting the 26388relevant parts of Cygnus @command{configure} with the help of david zuhn 26389and Ken Raeburn. These features include support for using 26390@file{config.sub}, @file{config.guess}, @option{--host}, and 26391@option{--target}; making links to files; and running @command{configure} 26392scripts in subdirectories. Adding these features enabled Ken to convert 26393GNU @code{as}, and Rob Savoye to convert DejaGNU, to using 26394Autoconf. 26395 26396I added more features in response to other peoples' requests. Many 26397people had asked for @command{configure} scripts to share the results of 26398the checks between runs, because (particularly when configuring a large 26399source tree, like Cygnus does) they were frustratingly slow. Mike 26400Haertel suggested adding site-specific initialization scripts. People 26401distributing software that had to unpack on MS-DOS asked for a way to 26402override the @file{.in} extension on the file names, which produced file 26403names like @file{config.h.in} containing two dots. Jim Avera did an 26404extensive examination of the problems with quoting in @code{AC_DEFINE} 26405and @code{AC_SUBST}; his insights led to significant improvements. 26406Richard Stallman asked that compiler output be sent to @file{config.log} 26407instead of @file{/dev/null}, to help people debug the Emacs 26408@command{configure} script. 26409 26410I made some other changes because of my dissatisfaction with the quality 26411of the program. I made the messages showing results of the checks less 26412ambiguous, always printing a result. I regularized the names of the 26413macros and cleaned up coding style inconsistencies. I added some 26414auxiliary utilities that I had developed to help convert source code 26415packages to use Autoconf. With the help of Fran@,{c}ois Pinard, I made 26416the macros not interrupt each others' messages. (That feature revealed 26417some performance bottlenecks in GNU M4, which he hastily 26418corrected!) I reorganized the documentation around problems people want 26419to solve. And I began a test suite, because experience had shown that 26420Autoconf has a pronounced tendency to regress when we change it. 26421 26422Again, several alpha testers gave invaluable feedback, especially 26423Fran@,{c}ois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn, 26424and Mark Eichin. 26425 26426Finally, version 2.0 was ready. And there was much rejoicing. (And I 26427have free time again. I think. Yeah, right.) 26428 26429 26430@c ========================================================== Appendices 26431 26432 26433@node GNU Free Documentation License 26434@appendix GNU Free Documentation License 26435 26436@include fdl.texi 26437 26438@node Indices 26439@appendix Indices 26440 26441@menu 26442* Environment Variable Index:: Index of environment variables used 26443* Output Variable Index:: Index of variables set in output files 26444* Preprocessor Symbol Index:: Index of C preprocessor symbols defined 26445* Cache Variable Index:: Index of documented cache variables 26446* Autoconf Macro Index:: Index of Autoconf macros 26447* M4 Macro Index:: Index of M4, M4sugar, and M4sh macros 26448* Autotest Macro Index:: Index of Autotest macros 26449* Program & Function Index:: Index of those with portability problems 26450* Concept Index:: General index 26451@end menu 26452 26453@node Environment Variable Index 26454@appendixsec Environment Variable Index 26455 26456This is an alphabetical list of the environment variables that might 26457influence Autoconf checks. 26458 26459@printindex ev 26460 26461@node Output Variable Index 26462@appendixsec Output Variable Index 26463 26464This is an alphabetical list of the variables that Autoconf can 26465substitute into files that it creates, typically one or more 26466makefiles. @xref{Setting Output Variables}, for more information 26467on how this is done. 26468 26469@printindex ov 26470 26471@node Preprocessor Symbol Index 26472@appendixsec Preprocessor Symbol Index 26473 26474This is an alphabetical list of the C preprocessor symbols that the 26475Autoconf macros define. To work with Autoconf, C source code needs to 26476use these names in @code{#if} or @code{#ifdef} directives. 26477 26478@printindex cv 26479 26480@node Cache Variable Index 26481@appendixsec Cache Variable Index 26482 26483This is an alphabetical list of documented cache variables used 26484by macros defined in Autoconf. Autoconf macros may use additional cache 26485variables internally. 26486@ifset shortindexflag 26487To make the list easier to use, the variables are listed without their 26488preceding @samp{ac_cv_}. 26489@end ifset 26490 26491@printindex CA 26492 26493@node Autoconf Macro Index 26494@appendixsec Autoconf Macro Index 26495 26496This is an alphabetical list of the Autoconf macros. 26497@ifset shortindexflag 26498To make the list easier to use, the macros are listed without their 26499preceding @samp{AC_}. 26500@end ifset 26501 26502@printindex AC 26503 26504@node M4 Macro Index 26505@appendixsec M4 Macro Index 26506 26507This is an alphabetical list of the M4, M4sugar, and M4sh macros. 26508@ifset shortindexflag 26509To make the list easier to use, the macros are listed without their 26510preceding @samp{m4_} or @samp{AS_}. The prefix is @samp{m4_} for 26511all-lowercase macro names and @samp{AS_} for all-uppercase macro 26512names. 26513@end ifset 26514 26515@printindex MS 26516 26517@node Autotest Macro Index 26518@appendixsec Autotest Macro Index 26519 26520This is an alphabetical list of the Autotest macros. 26521@ifset shortindexflag 26522To make the list easier to use, the macros are listed without their 26523preceding @samp{AT_}. 26524@end ifset 26525 26526@printindex AT 26527 26528@node Program & Function Index 26529@appendixsec Program and Function Index 26530 26531This is an alphabetical list of the programs and functions whose 26532portability is discussed in this document. 26533 26534@printindex pr 26535 26536@node Concept Index 26537@appendixsec Concept Index 26538 26539This is an alphabetical list of the files, tools, and concepts 26540introduced in this document. 26541 26542@printindex cp 26543 26544@bye 26545 26546@c LocalWords: texinfo setfilename autoconf texi settitle setchapternewpage 26547@c LocalWords: setcontentsaftertitlepage finalout ARG ovar varname dvar acx 26548@c LocalWords: makeinfo dvi defcodeindex ev ov CPP cv Autotest mv defindex fn 26549@c LocalWords: shortindexflag iftex ifset acindex ACindex ifclear ahindex fu 26550@c LocalWords: asindex MSindex atindex ATindex auindex hdrindex prindex FIXME 26551@c LocalWords: msindex alloca fnindex Aaarg indices FSF's dircategory ifnames 26552@c LocalWords: direntry autoscan autoreconf autoheader autoupdate config FDs 26553@c LocalWords: testsuite titlepage Elliston Demaille vskip filll ifnottex hmm 26554@c LocalWords: insertcopying Autoconf's detailmenu Automake Libtool Posix ois 26555@c LocalWords: Systemology Checkpointing Changequote INTERCAL changequote dfn 26556@c LocalWords: Quadrigraphs builtins Shellology acconfig Bugward LIBOBJ Imake 26557@c LocalWords: LIBOBJS IFELSE cindex flushright Pinard Metaconfig uref Simons 26558@c LocalWords: distclean uninstall noindent versioning Tromey dir 26559@c LocalWords: SAMS samp aclocal acsite underquoted emph itemx prepend SUBST 26560@c LocalWords: evindex automake Gettext autopoint gettext symlink libtoolize 26561@c LocalWords: defmac INIT tarname ovindex cvindex BUGREPORT PREREQ asis PROG 26562@c LocalWords: SRCDIR srcdir globbing afterwards cmds foos fooo foooo init cd 26563@c LocalWords: builddir timestamp src Imakefile chmod defvar CFLAGS CPPFLAGS 26564@c LocalWords: CXXFLAGS DEFS DHAVE defvarx FCFLAGS FFLAGS LDFLAGS bindir GCC 26565@c LocalWords: datadir datarootdir docdir dvidir htmldir libdir ifnothtml kbd 26566@c LocalWords: includedir infodir libexecdir localedir localstatedir mandir 26567@c LocalWords: oldincludedir pdfdir PDF psdir PostScript sbindir sysconfdir 26568@c LocalWords: sharedstatedir DDATADIR sed tmp pkgdatadir VPATH conf unistd 26569@c LocalWords: undef endif builtin FUNCS ifndef STACKSEG getb GETB YMP fubar 26570@c LocalWords: PRE dest SUBDIRS subdirs fi struct STDC stdlib stddef INTTYPES 26571@c LocalWords: inttypes STDINT stdint AWK AIX Solaris NeXT env EGREP FGREP yy 26572@c LocalWords: LEXLIB YYTEXT lfl nonportable Automake's LN RANLIB byacc INETD 26573@c LocalWords: inetd prog PROGS progs ranlib lmp lXt lX nsl gethostbyname UX 26574@c LocalWords: NextStep isinf isnan glibc IRIX sunmath lm lsunmath pre sizeof 26575@c LocalWords: ld inline malloc putenv setenv FreeBSD realloc SunOS MinGW 26576@c LocalWords: snprintf vsnprintf sprintf vsprintf sscanf gcc strerror ifdef 26577@c LocalWords: strnlen sysconf PAGESIZE unsetenv va fallback memcpy dst FUNC 26578@c LocalWords: PowerPC GNUC libPW pragma Olibcalls CHOWN chown CLOSEDIR VFORK 26579@c LocalWords: closedir FNMATCH fnmatch vfork FSEEKO LARGEFILE fseeko SVR sc 26580@c LocalWords: largefile GETGROUPS getgroups GETLOADAVG DGUX UMAX NLIST KMEM 26581@c LocalWords: SETGID getloadavg nlist GETMNTENT irix 26582@c LocalWords: getmntent UnixWare GETPGRP getpgid getpgrp Posix's pid LSTAT 26583@c LocalWords: lstat rpl MEMCMP memcmp OpenStep MBRTOWC mbrtowc MKTIME mktime 26584@c LocalWords: localtime MMAP mmap OBSTACK obstack obstacks ARGTYPES timeval 26585@c LocalWords: SETPGRP setpgrp defmacx Hurd SETVBUF setvbuf STRCOLL strcoll 26586@c LocalWords: STRTOD strtod DECL STRFTIME strftime SCO UTIME utime VPRINTF 26587@c LocalWords: DOPRNT vprintf doprnt sp unfixable LIBSOURCE LIBSOURCES Eggert 26588@c LocalWords: linux netinet ia Tru XFree DIRENT NDIR dirent ndir multitable 26589@c LocalWords: NAMLEN strlen namlen MKDEV SYSMACROS makedev RESOLV resolv DNS 26590@c LocalWords: inet structs NAMESER arpa NETDB netdb UTekV UTS GCC's kB 26591@c LocalWords: STDBOOL BOOL stdbool cplusplus bool Bool stdarg tm 26592@c LocalWords: ctype strchr strrchr rindex bcopy memmove memchr WEXITSTATUS 26593@c LocalWords: WIFEXITED TIOCGWINSZ GWINSZ termios preprocess preprocessable 26594@c LocalWords: DECLS strdup calloc BLKSIZE blksize RDEV rdev TZNAME tzname pw 26595@c LocalWords: passwd gecos pwd MBSTATE mbstate wchar RETSIGTYPE hup UID uid 26596@c LocalWords: gid ptrdiff uintmax EXEEXT OBJEXT Ae conftest AXP str 26597@c LocalWords: ALIGNOF WERROR Werror cpp HP's WorkShop egcs un fied stdc CXX 26598@c LocalWords: varargs BIGENDIAN Endianness SPARC endianness grep'ed CONST FC 26599@c LocalWords: const STRINGIZE stringizing PARAMS unprotoize protos KCC cxx 26600@c LocalWords: xlC aCC CXXCPP FREEFORM xlf FLIBS FCLIBS ish SRCEXT XTRA LFS 26601@c LocalWords: ISC lcposix MINIX Minix conditionalized inlines hw dD confdefs 26602@c LocalWords: fputs stdout PREPROC ar UFS HFS QNX realtime fstype STATVFS se 26603@c LocalWords: statvfs STATFS statfs func machfile hdr lelf raboof DEFUN GTK 26604@c LocalWords: GTKMM Grmph ified ine defn baz EOF qar Ahhh changecom algol io 26605@c LocalWords: changeword quadrigraphs quadrigraph dnl SGI atoi overquoting 26606@c LocalWords: Aas Wcross sep args namespace undefine bpatsubst popdef dquote 26607@c LocalWords: bregexp Overquote overquotation meisch maisch meische maische 26608@c LocalWords: miscian DIRNAME dirname MKDIR CATFILE XMKMF TRAVOLTA celsius 26609@c LocalWords: EMX emxos Emacsen Korn DYNIX subshell posix Ksh ksh Pdksh Zsh 26610@c LocalWords: pdksh zsh Allbery Lipe Kubota UWS zorglub stderr eval esac lfn 26611@c LocalWords: drivespec Posixy DJGPP doschk prettybird LPT pfew Zsh's yu yaa 26612@c LocalWords: yM uM aM firebird IP subdir misparses ok Unpatched abc bc zA 26613@c LocalWords: CDPATH DUALCASE LINENO prepass Subshells lineno NULLCMD cmp wc 26614@c LocalWords: MAILPATH scanset arg NetBSD Almquist printf expr cp 26615@c LocalWords: Oliva awk Aaaaarg cmd regex xfoo GNV OpenVMS VM 26616@c LocalWords: sparc Proulx nbar nfoo maxdepth acdilrtu TWG mc 26617@c LocalWords: mkdir exe uname OpenBSD Fileutils mktemp umask TMPDIR guid os 26618@c LocalWords: fooXXXXXX Unicos utimes hpux hppa unescaped 26619@c LocalWords: pmake DOS's gmake ifoo DESTDIR autoconfiscated pc coff mips gg 26620@c LocalWords: dec ultrix cpu wildcards rpcc rdtsc powerpc readline 26621@c LocalWords: withval vxworks gless localcache usr LOFF loff CYGWIN Cygwin 26622@c LocalWords: cygwin SIGLIST siglist SYSNDIR SYSDIR ptx lseq rusage elif MSC 26623@c LocalWords: lfoo POUNDBANG lsun NIS getpwnam SYSCALLS RSH INTL lintl aix 26624@c LocalWords: intl lx ldir syslog bsd EPI toolchain netbsd objext de KNR nn 26625@c LocalWords: fication LTLIBOBJS Wdiff TESTDIR atconfig atlocal akim XFAIL 26626@c LocalWords: ChangeLog prepended errexit smallexample TESTSUITEFLAGS GPL er 26627@c LocalWords: installcheck autotest indir Pixley Bothner Eichin Kerberos adl 26628@c LocalWords: DISTCLEANFILES preprocessor's fileutils Stallman Murphey Stenn 26629@c LocalWords: Manfredi Autoconfig TCL FSP david zuhn Blandy MACRODIR Raeburn 26630@c LocalWords: autoconfiscate Savoye Haertel Avera Meyering fdl appendixsec 26631@c LocalWords: printindex american LIBOBJDIR LibdirTest ERLCFLAGS OBJCFLAGS 26632@c LocalWords: VER Gnulib online xyes strcpy TYPEOF typeof OBJC objcc objc ln 26633@c LocalWords: GOBJC OTP ERLC erl valloc decr dumpdef errprint incr 26634@c LocalWords: esyscmd len maketemp pushdef substr syscmd sysval translit txt 26635@c LocalWords: sinclude foreach myvar tolower toupper uniq BASENAME STDIN 26636@c LocalWords: Dynix basename aname cname macroexpands xno xcheck 26637@c LocalWords: LIBREADLINE lreadline lncurses libreadline 26638 26639@c Local Variables: 26640@c fill-column: 72 26641@c ispell-local-dictionary: "american" 26642@c indent-tabs-mode: nil 26643@c whitespace-check-buffer-indent: nil 26644@c End: 26645