1\input texinfo @c -*-texinfo-*- 2@comment ======================================================== 3@comment %**start of header 4@setfilename autoconf.info 5@include version.texi 6@settitle Autoconf 7@setchapternewpage odd 8@ifnothtml 9@setcontentsaftertitlepage 10@end ifnothtml 11@finalout 12 13@c @ovar(ARG) 14@c ---------- 15@c The ARG is an optional argument. To be used for macro arguments in 16@c their documentation (@defmac). 17@macro ovar{varname} 18@r{[}@var{\varname\}@r{]}@c 19@end macro 20 21@c @dvar(ARG, DEFAULT) 22@c ------------------- 23@c The ARG is an optional argument, defaulting to DEFAULT. To be used 24@c for macro arguments in their documentation (@defmac). 25@macro dvar{varname, default} 26@r{[}@var{\varname\} = @samp{\default\}@r{]}@c 27@end macro 28 29@c Handling the indexes with Texinfo yields several different problems. 30@c 31@c Because we want to drop out the AC_ part of the macro names in the 32@c printed manual, but not in the other outputs, we need a layer above 33@c the usual @acindex{} etc. That's why we first define indexes such as 34@c acx meant to become the macro @acindex. First of all, using ``ac_'' 35@c does not work with makeinfo, and using ``ac1'' doesn't work with TeX. 36@c So use something more regular ``acx''. Then you finish with a printed 37@c index saying ``index is not existent''. Of course: you ought to use 38@c two letters :( So you use capitals. 39@c 40@c Second, when defining a macro in the TeX world, following spaces are 41@c eaten. But then, since we embed @acxindex commands that use the end 42@c of line as an end marker, the whole things wrecks itself. So make 43@c sure you do *force* an additional end of line, add a ``@c''. 44@c 45@c Finally, you might want to get rid of TeX expansion, using --expand 46@c with texi2dvi. But then you wake up an old problem: we use macros 47@c in @defmac etc. where TeX does perform the expansion, but not makeinfo. 48 49@c Define an environment variable index, for variables users may set 50@c in their environment or on the configure command line. 51@defcodeindex ev 52@c Define an output variable index, for commonly AC_SUBST'ed variables. 53@defcodeindex ov 54@c Define a cache variable index, for variables matching *_cv_*. 55@defcodeindex CA 56@c Other shell variables not fitting the above categories should be 57@c listed in the predefined vrindex, which we merge in the concept index. 58@syncodeindex vr cp 59@c Define a CPP preprocessor macro index, for #define'd strings. 60@defcodeindex cv 61@c Define an Autoconf macro index that @defmac doesn't write to. 62@defcodeindex AC 63@c Define an Autotest macro index that @defmac doesn't write to. 64@defcodeindex AT 65@c Define an M4sugar macro index that @defmac doesn't write to. 66@defcodeindex MS 67@c Define an index for *foreign* programs: `mv' etc. Used for the 68@c portability sections and so on. 69@defindex pr 70 71@c shortindexflag 72@c -------------- 73@c Shall we factor AC_ out of the Autoconf macro index etc.? 74@iftex 75@set shortindexflag 76@end iftex 77 78@c @acindex{MACRO} 79@c --------------- 80@c Registering an AC_\MACRO\. 81@ifset shortindexflag 82@macro acindex{macro} 83@ACindex \macro\ 84@c 85@end macro 86@end ifset 87@ifclear shortindexflag 88@macro acindex{macro} 89@ACindex AC_\macro\ 90@end macro 91@end ifclear 92 93@c @ahindex{MACRO} 94@c --------------- 95@c Registering an AH_\MACRO\. 96@macro ahindex{macro} 97@ACindex AH_\macro\ 98@c 99@end macro 100 101@c @asindex{MACRO} 102@c --------------- 103@c Registering an AS_\MACRO\. 104@ifset shortindexflag 105@macro asindex{macro} 106@MSindex \macro\ 107@c 108@end macro 109@end ifset 110@ifclear shortindexflag 111@macro asindex{macro} 112@MSindex AS_\macro\ 113@end macro 114@end ifclear 115 116@c @atindex{MACRO} 117@c --------------- 118@c Registering an AT_\MACRO\. 119@ifset shortindexflag 120@macro atindex{macro} 121@ATindex \macro\ 122@c 123@end macro 124@end ifset 125@ifclear shortindexflag 126@macro atindex{macro} 127@ATindex AT_\macro\ 128@end macro 129@end ifclear 130 131@c @auindex{MACRO} 132@c --------------- 133@c Registering an AU_\MACRO\. 134@macro auindex{macro} 135@ACindex AU_\macro\ 136@c 137@end macro 138 139@c @hdrindex{MACRO} 140@c ---------------- 141@c Indexing a header. 142@macro hdrindex{macro} 143@prindex @file{\macro\} 144@c 145@end macro 146 147@c @msindex{MACRO} 148@c --------------- 149@c Registering an m4_\MACRO\. 150@ifset shortindexflag 151@macro msindex{macro} 152@MSindex \macro\ 153@c 154@end macro 155@end ifset 156@ifclear shortindexflag 157@macro msindex{macro} 158@MSindex m4_\macro\ 159@end macro 160@end ifclear 161 162 163@c @caindex{VARIABLE} 164@c ------------------ 165@c Registering an ac_cv_\VARIABLE\ cache variable. 166@ifset shortindexflag 167@macro caindex{macro} 168@CAindex \macro\ 169@end macro 170@end ifset 171@ifclear shortindexflag 172@macro caindex{macro} 173@CAindex ac_cv_\macro\ 174@end macro 175@end ifclear 176 177@c Define an index for functions: `alloca' etc. Used for the 178@c portability sections and so on. We can't use `fn' (aka `fnindex), 179@c since `@defmac' goes into it => we'd get all the macros too. 180 181@c FIXME: Aaarg! It seems there are too many indices for TeX :( 182@c 183@c ! No room for a new @write . 184@c l.112 @defcodeindex fu 185@c 186@c so don't define yet another one :( Just put some tags before each 187@c @prindex which is actually a @funindex. 188@c 189@c @defcodeindex fu 190@c 191@c 192@c @c Put the programs and functions into their own index. 193@c @syncodeindex fu pr 194 195@comment %**end of header 196@comment ======================================================== 197 198@copying 199 200This manual (@value{UPDATED}) is for GNU Autoconf 201(version @value{VERSION}), 202a package for creating scripts to configure source code packages using 203templates and an M4 macro package. 204 205Copyright @copyright{} 1992-1996, 1998-2012 Free Software Foundation, 206Inc. 207 208@quotation 209Permission is granted to copy, distribute and/or modify this document 210under the terms of the GNU Free Documentation License, 211Version 1.3 or any later version published by the Free Software 212Foundation; with no Invariant Sections, no Front-Cover texts, and 213no Back-Cover Texts. A copy of the license is included in the section 214entitled ``GNU Free Documentation License.'' 215@end quotation 216@end copying 217 218 219 220@dircategory Software development 221@direntry 222* Autoconf: (autoconf). Create source code configuration scripts. 223@end direntry 224 225@dircategory Individual utilities 226@direntry 227* autoscan: (autoconf)autoscan Invocation. 228 Semi-automatic @file{configure.ac} writing 229* ifnames: (autoconf)ifnames Invocation. Listing conditionals in source. 230* autoconf-invocation: (autoconf)autoconf Invocation. 231 How to create configuration scripts 232* autoreconf: (autoconf)autoreconf Invocation. 233 Remaking multiple @command{configure} scripts 234* autoheader: (autoconf)autoheader Invocation. 235 How to create configuration templates 236* autom4te: (autoconf)autom4te Invocation. 237 The Autoconf executables backbone 238* configure: (autoconf)configure Invocation. Configuring a package. 239* autoupdate: (autoconf)autoupdate Invocation. 240 Automatic update of @file{configure.ac} 241* config.status: (autoconf)config.status Invocation. Recreating configurations. 242* testsuite: (autoconf)testsuite Invocation. Running an Autotest test suite. 243@end direntry 244 245@titlepage 246@title Autoconf 247@subtitle Creating Automatic Configuration Scripts 248@subtitle for version @value{VERSION}, @value{UPDATED} 249@author David MacKenzie 250@author Ben Elliston 251@author Akim Demaille 252@page 253@vskip 0pt plus 1filll 254@insertcopying 255@end titlepage 256 257@contents 258 259 260@ifnottex 261@node Top 262@top Autoconf 263@insertcopying 264@end ifnottex 265 266@c The master menu, created with texinfo-master-menu, goes here. 267 268@menu 269* Introduction:: Autoconf's purpose, strengths, and weaknesses 270* The GNU Build System:: A set of tools for portable software packages 271* Making configure Scripts:: How to organize and produce Autoconf scripts 272* Setup:: Initialization and output 273* Existing Tests:: Macros that check for particular features 274* Writing Tests:: How to write new feature checks 275* Results:: What to do with results from feature checks 276* Programming in M4:: Layers on top of which Autoconf is written 277* Programming in M4sh:: Shell portability layer 278* Writing Autoconf Macros:: Adding new macros to Autoconf 279* Portable Shell:: Shell script portability pitfalls 280* Portable Make:: Makefile portability pitfalls 281* Portable C and C++:: C and C++ portability pitfalls 282* Manual Configuration:: Selecting features that can't be guessed 283* Site Configuration:: Local defaults for @command{configure} 284* Running configure Scripts:: How to use the Autoconf output 285* config.status Invocation:: Recreating a configuration 286* Obsolete Constructs:: Kept for backward compatibility 287* Using Autotest:: Creating portable test suites 288* FAQ:: Frequent Autoconf Questions, with answers 289* History:: History of Autoconf 290* GNU Free Documentation License:: License for copying this manual 291* Indices:: Indices of symbols, concepts, etc. 292 293@detailmenu 294 --- The Detailed Node Listing --- 295 296The GNU Build System 297 298* Automake:: Escaping makefile hell 299* Gnulib:: The GNU portability library 300* Libtool:: Building libraries portably 301* Pointers:: More info on the GNU build system 302 303Making @command{configure} Scripts 304 305* Writing Autoconf Input:: What to put in an Autoconf input file 306* autoscan Invocation:: Semi-automatic @file{configure.ac} writing 307* ifnames Invocation:: Listing the conditionals in source code 308* autoconf Invocation:: How to create configuration scripts 309* autoreconf Invocation:: Remaking multiple @command{configure} scripts 310 311Writing @file{configure.ac} 312 313* Shell Script Compiler:: Autoconf as solution of a problem 314* Autoconf Language:: Programming in Autoconf 315* Autoconf Input Layout:: Standard organization of @file{configure.ac} 316 317Initialization and Output Files 318 319* Initializing configure:: Option processing etc. 320* Versioning:: Dealing with Autoconf versions 321* Notices:: Copyright, version numbers in @command{configure} 322* Input:: Where Autoconf should find files 323* Output:: Outputting results from the configuration 324* Configuration Actions:: Preparing the output based on results 325* Configuration Files:: Creating output files 326* Makefile Substitutions:: Using output variables in makefiles 327* Configuration Headers:: Creating a configuration header file 328* Configuration Commands:: Running arbitrary instantiation commands 329* Configuration Links:: Links depending on the configuration 330* Subdirectories:: Configuring independent packages together 331* Default Prefix:: Changing the default installation prefix 332 333Substitutions in Makefiles 334 335* Preset Output Variables:: Output variables that are always set 336* Installation Directory Variables:: Other preset output variables 337* Changed Directory Variables:: Warnings about @file{datarootdir} 338* Build Directories:: Supporting multiple concurrent compiles 339* Automatic Remaking:: Makefile rules for configuring 340 341Configuration Header Files 342 343* Header Templates:: Input for the configuration headers 344* autoheader Invocation:: How to create configuration templates 345* Autoheader Macros:: How to specify CPP templates 346 347Existing Tests 348 349* Common Behavior:: Macros' standard schemes 350* Alternative Programs:: Selecting between alternative programs 351* Files:: Checking for the existence of files 352* Libraries:: Library archives that might be missing 353* Library Functions:: C library functions that might be missing 354* Header Files:: Header files that might be missing 355* Declarations:: Declarations that may be missing 356* Structures:: Structures or members that might be missing 357* Types:: Types that might be missing 358* Compilers and Preprocessors:: Checking for compiling programs 359* System Services:: Operating system services 360* Posix Variants:: Special kludges for specific Posix variants 361* Erlang Libraries:: Checking for the existence of Erlang libraries 362 363Common Behavior 364 365* Standard Symbols:: Symbols defined by the macros 366* Default Includes:: Includes used by the generic macros 367 368Alternative Programs 369 370* Particular Programs:: Special handling to find certain programs 371* Generic Programs:: How to find other programs 372 373Library Functions 374 375* Function Portability:: Pitfalls with usual functions 376* Particular Functions:: Special handling to find certain functions 377* Generic Functions:: How to find other functions 378 379Header Files 380 381* Header Portability:: Collected knowledge on common headers 382* Particular Headers:: Special handling to find certain headers 383* Generic Headers:: How to find other headers 384 385Declarations 386 387* Particular Declarations:: Macros to check for certain declarations 388* Generic Declarations:: How to find other declarations 389 390Structures 391 392* Particular Structures:: Macros to check for certain structure members 393* Generic Structures:: How to find other structure members 394 395Types 396 397* Particular Types:: Special handling to find certain types 398* Generic Types:: How to find other types 399 400Compilers and Preprocessors 401 402* Specific Compiler Characteristics:: Some portability issues 403* Generic Compiler Characteristics:: Language independent tests and features 404* C Compiler:: Checking its characteristics 405* C++ Compiler:: Likewise 406* Objective C Compiler:: Likewise 407* Objective C++ Compiler:: Likewise 408* Erlang Compiler and Interpreter:: Likewise 409* Fortran Compiler:: Likewise 410* Go Compiler:: Likewise 411 412Writing Tests 413 414* Language Choice:: Selecting which language to use for testing 415* Writing Test Programs:: Forging source files for compilers 416* Running the Preprocessor:: Detecting preprocessor symbols 417* Running the Compiler:: Detecting language or header features 418* Running the Linker:: Detecting library features 419* Runtime:: Testing for runtime features 420* Systemology:: A zoology of operating systems 421* Multiple Cases:: Tests for several possible values 422 423Writing Test Programs 424 425* Guidelines:: General rules for writing test programs 426* Test Functions:: Avoiding pitfalls in test programs 427* Generating Sources:: Source program boilerplate 428 429Results of Tests 430 431* Defining Symbols:: Defining C preprocessor symbols 432* Setting Output Variables:: Replacing variables in output files 433* Special Chars in Variables:: Characters to beware of in variables 434* Caching Results:: Speeding up subsequent @command{configure} runs 435* Printing Messages:: Notifying @command{configure} users 436 437Caching Results 438 439* Cache Variable Names:: Shell variables used in caches 440* Cache Files:: Files @command{configure} uses for caching 441* Cache Checkpointing:: Loading and saving the cache file 442 443Programming in M4 444 445* M4 Quotation:: Protecting macros from unwanted expansion 446* Using autom4te:: The Autoconf executables backbone 447* Programming in M4sugar:: Convenient pure M4 macros 448* Debugging via autom4te:: Figuring out what M4 was doing 449 450M4 Quotation 451 452* Active Characters:: Characters that change the behavior of M4 453* One Macro Call:: Quotation and one macro call 454* Quoting and Parameters:: M4 vs. shell parameters 455* Quotation and Nested Macros:: Macros calling macros 456* Changequote is Evil:: Worse than INTERCAL: M4 + changequote 457* Quadrigraphs:: Another way to escape special characters 458* Balancing Parentheses:: Dealing with unbalanced parentheses 459* Quotation Rule Of Thumb:: One parenthesis, one quote 460 461Using @command{autom4te} 462 463* autom4te Invocation:: A GNU M4 wrapper 464* Customizing autom4te:: Customizing the Autoconf package 465 466Programming in M4sugar 467 468* Redefined M4 Macros:: M4 builtins changed in M4sugar 469* Diagnostic Macros:: Diagnostic messages from M4sugar 470* Diversion support:: Diversions in M4sugar 471* Conditional constructs:: Conditions in M4 472* Looping constructs:: Iteration in M4 473* Evaluation Macros:: More quotation and evaluation control 474* Text processing Macros:: String manipulation in M4 475* Number processing Macros:: Arithmetic computation in M4 476* Set manipulation Macros:: Set manipulation in M4 477* Forbidden Patterns:: Catching unexpanded macros 478 479Programming in M4sh 480 481* Common Shell Constructs:: Portability layer for common shell constructs 482* Polymorphic Variables:: Support for indirect variable names 483* Initialization Macros:: Macros to establish a sane shell environment 484* File Descriptor Macros:: File descriptor macros for input and output 485 486Writing Autoconf Macros 487 488* Macro Definitions:: Basic format of an Autoconf macro 489* Macro Names:: What to call your new macros 490* Reporting Messages:: Notifying @command{autoconf} users 491* Dependencies Between Macros:: What to do when macros depend on other macros 492* Obsoleting Macros:: Warning about old ways of doing things 493* Coding Style:: Writing Autoconf macros @`a la Autoconf 494 495Dependencies Between Macros 496 497* Prerequisite Macros:: Ensuring required information 498* Suggested Ordering:: Warning about possible ordering problems 499* One-Shot Macros:: Ensuring a macro is called only once 500 501Portable Shell Programming 502 503* Shellology:: A zoology of shells 504* Invoking the Shell:: Invoking the shell as a command 505* Here-Documents:: Quirks and tricks 506* File Descriptors:: FDs and redirections 507* Signal Handling:: Shells, signals, and headaches 508* File System Conventions:: File names 509* Shell Pattern Matching:: Pattern matching 510* Shell Substitutions:: Variable and command expansions 511* Assignments:: Varying side effects of assignments 512* Parentheses:: Parentheses in shell scripts 513* Slashes:: Slashes in shell scripts 514* Special Shell Variables:: Variables you should not change 515* Shell Functions:: What to look out for if you use them 516* Limitations of Builtins:: Portable use of not so portable /bin/sh 517* Limitations of Usual Tools:: Portable use of portable tools 518 519Portable Make Programming 520 521* $< in Ordinary Make Rules:: $< in ordinary rules 522* Failure in Make Rules:: Failing portably in rules 523* Special Chars in Names:: Special Characters in Macro Names 524* Backslash-Newline-Empty:: Empty lines after backslash-newline 525* Backslash-Newline Comments:: Spanning comments across line boundaries 526* Long Lines in Makefiles:: Line length limitations 527* Macros and Submakes:: @code{make macro=value} and submakes 528* The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues 529* The Make Macro SHELL:: @code{$(SHELL)} portability issues 530* Parallel Make:: Parallel @command{make} quirks 531* Comments in Make Rules:: Other problems with Make comments 532* Newlines in Make Rules:: Using literal newlines in rules 533* Comments in Make Macros:: Other problems with Make comments in macros 534* Trailing whitespace in Make Macros:: Macro substitution problems 535* Command-line Macros and whitespace:: Whitespace trimming of values 536* obj/ and Make:: Don't name a subdirectory @file{obj} 537* make -k Status:: Exit status of @samp{make -k} 538* VPATH and Make:: @code{VPATH} woes 539* Single Suffix Rules:: Single suffix rules and separated dependencies 540* Timestamps and Make:: Subsecond timestamp resolution 541 542@code{VPATH} and Make 543 544* Variables listed in VPATH:: @code{VPATH} must be literal on ancient hosts 545* VPATH and Double-colon:: Problems with @samp{::} on ancient hosts 546* $< in Explicit Rules:: @code{$<} does not work in ordinary rules 547* Automatic Rule Rewriting:: @code{VPATH} goes wild on Solaris 548* Tru64 Directory Magic:: @command{mkdir} goes wild on Tru64 549* Make Target Lookup:: More details about @code{VPATH} lookup 550 551Portable C and C++ Programming 552 553* Varieties of Unportability:: How to make your programs unportable 554* Integer Overflow:: When integers get too large 555* Preprocessor Arithmetic:: @code{#if} expression problems 556* Null Pointers:: Properties of null pointers 557* Buffer Overruns:: Subscript errors and the like 558* Volatile Objects:: @code{volatile} and signals 559* Floating Point Portability:: Portable floating-point arithmetic 560* Exiting Portably:: Exiting and the exit status 561 562Integer Overflow 563 564* Integer Overflow Basics:: Why integer overflow is a problem 565* Signed Overflow Examples:: Examples of code assuming wraparound 566* Optimization and Wraparound:: Optimizations that break uses of wraparound 567* Signed Overflow Advice:: Practical advice for signed overflow issues 568* Signed Integer Division:: @code{INT_MIN / -1} and @code{INT_MIN % -1} 569 570Manual Configuration 571 572* Specifying Target Triplets:: Specifying target triplets 573* Canonicalizing:: Getting the canonical system type 574* Using System Type:: What to do with the system type 575 576Site Configuration 577 578* Help Formatting:: Customizing @samp{configure --help} 579* External Software:: Working with other optional software 580* Package Options:: Selecting optional features 581* Pretty Help Strings:: Formatting help string 582* Option Checking:: Controlling checking of @command{configure} options 583* Site Details:: Configuring site details 584* Transforming Names:: Changing program names when installing 585* Site Defaults:: Giving @command{configure} local defaults 586 587Transforming Program Names When Installing 588 589* Transformation Options:: @command{configure} options to transform names 590* Transformation Examples:: Sample uses of transforming names 591* Transformation Rules:: Makefile uses of transforming names 592 593Running @command{configure} Scripts 594 595* Basic Installation:: Instructions for typical cases 596* Compilers and Options:: Selecting compilers and optimization 597* Multiple Architectures:: Compiling for multiple architectures at once 598* Installation Names:: Installing in different directories 599* Optional Features:: Selecting optional features 600* Particular Systems:: Particular systems 601* System Type:: Specifying the system type 602* Sharing Defaults:: Setting site-wide defaults for @command{configure} 603* Defining Variables:: Specifying the compiler etc. 604* configure Invocation:: Changing how @command{configure} runs 605 606Obsolete Constructs 607 608* Obsolete config.status Use:: Obsolete convention for @command{config.status} 609* acconfig Header:: Additional entries in @file{config.h.in} 610* autoupdate Invocation:: Automatic update of @file{configure.ac} 611* Obsolete Macros:: Backward compatibility macros 612* Autoconf 1:: Tips for upgrading your files 613* Autoconf 2.13:: Some fresher tips 614 615Upgrading From Version 1 616 617* Changed File Names:: Files you might rename 618* Changed Makefiles:: New things to put in @file{Makefile.in} 619* Changed Macros:: Macro calls you might replace 620* Changed Results:: Changes in how to check test results 621* Changed Macro Writing:: Better ways to write your own macros 622 623Upgrading From Version 2.13 624 625* Changed Quotation:: Broken code which used to work 626* New Macros:: Interaction with foreign macros 627* Hosts and Cross-Compilation:: Bugward compatibility kludges 628* AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token 629* AC_ACT_IFELSE vs AC_TRY_ACT:: A more generic scheme for testing sources 630 631Generating Test Suites with Autotest 632 633* Using an Autotest Test Suite:: Autotest and the user 634* Writing Testsuites:: Autotest macros 635* testsuite Invocation:: Running @command{testsuite} scripts 636* Making testsuite Scripts:: Using autom4te to create @command{testsuite} 637 638Using an Autotest Test Suite 639 640* testsuite Scripts:: The concepts of Autotest 641* Autotest Logs:: Their contents 642 643Frequent Autoconf Questions, with answers 644 645* Distributing:: Distributing @command{configure} scripts 646* Why GNU M4:: Why not use the standard M4? 647* Bootstrapping:: Autoconf and GNU M4 require each other? 648* Why Not Imake:: Why GNU uses @command{configure} instead of Imake 649* Defining Directories:: Passing @code{datadir} to program 650* Autom4te Cache:: What is it? Can I remove it? 651* Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree 652* Expanded Before Required:: Expanded Before Required 653* Debugging:: Debugging @command{configure} scripts 654 655History of Autoconf 656 657* Genesis:: Prehistory and naming of @command{configure} 658* Exodus:: The plagues of M4 and Perl 659* Leviticus:: The priestly code of portability arrives 660* Numbers:: Growth and contributors 661* Deuteronomy:: Approaching the promises of easy configuration 662 663Indices 664 665* Environment Variable Index:: Index of environment variables used 666* Output Variable Index:: Index of variables set in output files 667* Preprocessor Symbol Index:: Index of C preprocessor symbols defined 668* Cache Variable Index:: Index of documented cache variables 669* Autoconf Macro Index:: Index of Autoconf macros 670* M4 Macro Index:: Index of M4, M4sugar, and M4sh macros 671* Autotest Macro Index:: Index of Autotest macros 672* Program & Function Index:: Index of those with portability problems 673* Concept Index:: General index 674 675@end detailmenu 676@end menu 677 678@c ============================================================= Introduction. 679 680@node Introduction 681@chapter Introduction 682@cindex Introduction 683 684@flushright 685A physicist, an engineer, and a computer scientist were discussing the 686nature of God. ``Surely a Physicist,'' said the physicist, ``because 687early in the Creation, God made Light; and you know, Maxwell's 688equations, the dual nature of electromagnetic waves, the relativistic 689consequences@enddots{}'' ``An Engineer!,'' said the engineer, ``because 690before making Light, God split the Chaos into Land and Water; it takes a 691hell of an engineer to handle that big amount of mud, and orderly 692separation of solids from liquids@enddots{}'' The computer scientist 693shouted: ``And the Chaos, where do you think it was coming from, hmm?'' 694 695---Anonymous 696@end flushright 697@c (via Franc,ois Pinard) 698 699Autoconf is a tool for producing shell scripts that automatically 700configure software source code packages to adapt to many kinds of 701Posix-like systems. The configuration scripts produced by Autoconf 702are independent of Autoconf when they are run, so their users do not 703need to have Autoconf. 704 705The configuration scripts produced by Autoconf require no manual user 706intervention when run; they do not normally even need an argument 707specifying the system type. Instead, they individually test for the 708presence of each feature that the software package they are for might need. 709(Before each check, they print a one-line message stating what they are 710checking for, so the user doesn't get too bored while waiting for the 711script to finish.) As a result, they deal well with systems that are 712hybrids or customized from the more common Posix variants. There is 713no need to maintain files that list the features supported by each 714release of each variant of Posix. 715 716For each software package that Autoconf is used with, it creates a 717configuration script from a template file that lists the system features 718that the package needs or can use. After the shell code to recognize 719and respond to a system feature has been written, Autoconf allows it to 720be shared by many software packages that can use (or need) that feature. 721If it later turns out that the shell code needs adjustment for some 722reason, it needs to be changed in only one place; all of the 723configuration scripts can be regenerated automatically to take advantage 724of the updated code. 725 726@c "Those who do not understand Unix are condemned to reinvent it, poorly." 727@c --Henry Spencer, 1987 (see http://en.wikipedia.org/wiki/Unix_philosophy) 728Those who do not understand Autoconf are condemned to reinvent it, poorly. 729The primary goal of Autoconf is making the @emph{user's} life easier; 730making the @emph{maintainer's} life easier is only a secondary goal. 731Put another way, the primary goal is not to make the generation of 732@file{configure} automatic for package maintainers (although patches 733along that front are welcome, since package maintainers form the user 734base of Autoconf); rather, the goal is to make @file{configure} 735painless, portable, and predictable for the end user of each 736@dfn{autoconfiscated} package. And to this degree, Autoconf is highly 737successful at its goal --- most complaints to the Autoconf list are 738about difficulties in writing Autoconf input, and not in the behavior of 739the resulting @file{configure}. Even packages that don't use Autoconf 740will generally provide a @file{configure} script, and the most common 741complaint about these alternative home-grown scripts is that they fail 742to meet one or more of the GNU Coding Standards (@pxref{Configuration, , , 743standards, The GNU Coding Standards}) that users 744have come to expect from Autoconf-generated @file{configure} scripts. 745 746The Metaconfig package is similar in purpose to Autoconf, but the 747scripts it produces require manual user intervention, which is quite 748inconvenient when configuring large source trees. Unlike Metaconfig 749scripts, Autoconf scripts can support cross-compiling, if some care is 750taken in writing them. 751 752Autoconf does not solve all problems related to making portable 753software packages---for a more complete solution, it should be used in 754concert with other GNU build tools like Automake and 755Libtool. These other tools take on jobs like the creation of a 756portable, recursive makefile with all of the standard targets, 757linking of shared libraries, and so on. @xref{The GNU Build System}, 758for more information. 759 760Autoconf imposes some restrictions on the names of macros used with 761@code{#if} in C programs (@pxref{Preprocessor Symbol Index}). 762 763Autoconf requires GNU M4 version 1.4.6 or later in order to 764generate the scripts. It uses features that some versions of M4, 765including GNU M4 1.3, do not have. Autoconf works better 766with GNU M4 version 1.4.14 or later, though this is not 767required. 768 769@xref{Autoconf 1}, for information about upgrading from version 1. 770@xref{History}, for the story of Autoconf's development. @xref{FAQ}, 771for answers to some common questions about Autoconf. 772 773See the @uref{http://@/www.gnu.org/@/software/@/autoconf/, 774Autoconf web page} for up-to-date information, details on the mailing 775lists, pointers to a list of known bugs, etc. 776 777Mail suggestions to @email{autoconf@@gnu.org, the Autoconf mailing 778list}. Past suggestions are 779@uref{http://@/lists.gnu.org/@/archive/@/html/@/autoconf/, archived}. 780 781Mail bug reports to @email{bug-autoconf@@gnu.org, the 782Autoconf Bugs mailing list}. Past bug reports are 783@uref{http://@/lists.gnu.org/@/archive/@/html/@/bug-autoconf/, archived}. 784 785If possible, first check that your bug is 786not already solved in current development versions, and that it has not 787been reported yet. Be sure to include all the needed information and a 788short @file{configure.ac} that demonstrates the problem. 789 790Autoconf's development tree is accessible via @command{git}; see the 791@uref{http://@/savannah.gnu.org/@/projects/@/autoconf/, Autoconf 792Summary} for details, or view 793@uref{http://@/git.sv.gnu.org/@/gitweb/@/?p=autoconf.git, the actual 794repository}. Anonymous CVS access is also available, see 795@file{README} for more details. Patches relative to the 796current @command{git} version can be sent for review to the 797@email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}, with 798discussion on prior patches 799@uref{http://@/lists.gnu.org/@/archive/@/html/@/autoconf-@/patches/, 800archived}; and all commits are posted in the read-only 801@email{autoconf-commit@@gnu.org, Autoconf Commit mailing list}, which is 802also @uref{http://@/lists.gnu.org/@/archive/@/html/@/autoconf-commit/, 803archived}. 804 805Because of its mission, the Autoconf package itself 806includes only a set of often-used 807macros that have already demonstrated their usefulness. Nevertheless, 808if you wish to share your macros, or find existing ones, see the 809@uref{http://@/www.gnu.org/@/software/@/autoconf-archive/, Autoconf Macro 810Archive}, which is kindly run by @email{simons@@cryp.to, 811Peter Simons}. 812 813 814@c ================================================= The GNU Build System 815 816@node The GNU Build System 817@chapter The GNU Build System 818@cindex GNU build system 819 820Autoconf solves an important problem---reliable discovery of 821system-specific build and runtime information---but this is only one 822piece of the puzzle for the development of portable software. To this 823end, the GNU project has developed a suite of integrated 824utilities to finish the job Autoconf started: the GNU build 825system, whose most important components are Autoconf, Automake, and 826Libtool. In this chapter, we introduce you to those tools, point you 827to sources of more information, and try to convince you to use the 828entire GNU build system for your software. 829 830@menu 831* Automake:: Escaping makefile hell 832* Gnulib:: The GNU portability library 833* Libtool:: Building libraries portably 834* Pointers:: More info on the GNU build system 835@end menu 836 837@node Automake 838@section Automake 839 840The ubiquity of @command{make} means that a makefile is almost the 841only viable way to distribute automatic build rules for software, but 842one quickly runs into its numerous limitations. Its lack of 843support for automatic dependency tracking, recursive builds in 844subdirectories, reliable timestamps (e.g., for network file systems), and 845so on, mean that developers must painfully (and often incorrectly) 846reinvent the wheel for each project. Portability is non-trivial, thanks 847to the quirks of @command{make} on many systems. On top of all this is the 848manual labor required to implement the many standard targets that users 849have come to expect (@code{make install}, @code{make distclean}, 850@code{make uninstall}, etc.). Since you are, of course, using Autoconf, 851you also have to insert repetitive code in your @file{Makefile.in} to 852recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions 853provided by @command{configure}. Into this mess steps @dfn{Automake}. 854@cindex Automake 855 856Automake allows you to specify your build needs in a @file{Makefile.am} 857file with a vastly simpler and more powerful syntax than that of a plain 858makefile, and then generates a portable @file{Makefile.in} for 859use with Autoconf. For example, the @file{Makefile.am} to build and 860install a simple ``Hello world'' program might look like: 861 862@example 863bin_PROGRAMS = hello 864hello_SOURCES = hello.c 865@end example 866 867@noindent 868The resulting @file{Makefile.in} (~400 lines) automatically supports all 869the standard targets, the substitutions provided by Autoconf, automatic 870dependency tracking, @code{VPATH} building, and so on. @command{make} 871builds the @code{hello} program, and @code{make install} installs it 872in @file{/usr/local/bin} (or whatever prefix was given to 873@command{configure}, if not @file{/usr/local}). 874 875The benefits of Automake increase for larger packages (especially ones 876with subdirectories), but even for small programs the added convenience 877and portability can be substantial. And that's not all@enddots{} 878 879@node Gnulib 880@section Gnulib 881 882GNU software has a well-deserved reputation for running on 883many different types of systems. While our primary goal is to write 884software for the GNU system, many users and developers have 885been introduced to us through the systems that they were already using. 886 887@cindex Gnulib 888Gnulib is a central location for common GNU code, intended to 889be shared among free software packages. Its components are typically 890shared at the source level, rather than being a library that gets built, 891installed, and linked against. The idea is to copy files from Gnulib 892into your own source tree. There is no distribution tarball; developers 893should just grab source modules from the repository. The source files 894are available online, under various licenses, mostly GNU 895GPL or GNU LGPL. 896 897Gnulib modules typically contain C source code along with Autoconf 898macros used to configure the source code. For example, the Gnulib 899@code{stdbool} module implements a @file{stdbool.h} header that nearly 900conforms to C99, even on old-fashioned hosts that lack @file{stdbool.h}. 901This module contains a source file for the replacement header, along 902with an Autoconf macro that arranges to use the replacement header on 903old-fashioned systems. 904 905@node Libtool 906@section Libtool 907 908Often, one wants to build not only programs, but libraries, so that 909other programs can benefit from the fruits of your labor. Ideally, one 910would like to produce @emph{shared} (dynamically linked) libraries, 911which can be used by multiple programs without duplication on disk or in 912memory and can be updated independently of the linked programs. 913Producing shared libraries portably, however, is the stuff of 914nightmares---each system has its own incompatible tools, compiler flags, 915and magic incantations. Fortunately, GNU provides a solution: 916@dfn{Libtool}. 917@cindex Libtool 918 919Libtool handles all the requirements of building shared libraries for 920you, and at this time seems to be the @emph{only} way to do so with any 921portability. It also handles many other headaches, such as: the 922interaction of Make rules with the variable suffixes of 923shared libraries, linking reliably with shared libraries before they are 924installed by the superuser, and supplying a consistent versioning system 925(so that different versions of a library can be installed or upgraded 926without breaking binary compatibility). Although Libtool, like 927Autoconf, can be used without Automake, it is most simply utilized in 928conjunction with Automake---there, Libtool is used automatically 929whenever shared libraries are needed, and you need not know its syntax. 930 931@node Pointers 932@section Pointers 933 934Developers who are used to the simplicity of @command{make} for small 935projects on a single system might be daunted at the prospect of 936learning to use Automake and Autoconf. As your software is 937distributed to more and more users, however, you otherwise 938quickly find yourself putting lots of effort into reinventing the 939services that the GNU build tools provide, and making the 940same mistakes that they once made and overcame. (Besides, since 941you're already learning Autoconf, Automake is a piece of cake.) 942 943There are a number of places that you can go to for more information on 944the GNU build tools. 945 946@itemize @minus 947 948@item Web 949 950The project home pages for 951@uref{http://@/www@/.gnu@/.org/@/software/@/autoconf/, Autoconf}, 952@uref{http://@/www@/.gnu@/.org/@/software/@/automake/, Automake}, 953@uref{http://@/www@/.gnu@/.org/@/software/@/gnulib/, Gnulib}, and 954@uref{http://@/www@/.gnu@/.org/@/software/@/libtool/, Libtool}. 955 956@item Automake Manual 957 958@xref{Top, , Automake, automake, GNU Automake}, for more 959information on Automake. 960 961@item Books 962 963The book @cite{GNU Autoconf, Automake and 964Libtool}@footnote{@cite{GNU Autoconf, Automake and Libtool}, 965by G. V. Vaughan, B. Elliston, T. Tromey, and I. L. Taylor. SAMS (originally 966New Riders), 2000, ISBN 1578701902.} describes the complete GNU 967build environment. You can also find 968@uref{http://@/sources.redhat.com/@/autobook/, the entire book on-line}. 969 970@end itemize 971 972@c ================================================= Making configure Scripts. 973 974@node Making configure Scripts 975@chapter Making @command{configure} Scripts 976@cindex @file{aclocal.m4} 977@cindex @command{configure} 978 979The configuration scripts that Autoconf produces are by convention 980called @command{configure}. When run, @command{configure} creates several 981files, replacing configuration parameters in them with appropriate 982values. The files that @command{configure} creates are: 983 984@itemize @minus 985@item 986one or more @file{Makefile} files, usually one in each subdirectory of the 987package (@pxref{Makefile Substitutions}); 988 989@item 990optionally, a C header file, the name of which is configurable, 991containing @code{#define} directives (@pxref{Configuration Headers}); 992 993@item 994a shell script called @file{config.status} that, when run, recreates 995the files listed above (@pxref{config.status Invocation}); 996 997@item 998an optional shell script normally called @file{config.cache} 999(created when using @samp{configure --config-cache}) that 1000saves the results of running many of the tests (@pxref{Cache Files}); 1001 1002@item 1003a file called @file{config.log} containing any messages produced by 1004compilers, to help debugging if @command{configure} makes a mistake. 1005@end itemize 1006 1007@cindex @file{configure.in} 1008@cindex @file{configure.ac} 1009To create a @command{configure} script with Autoconf, you need to write an 1010Autoconf input file @file{configure.ac} (or @file{configure.in}) and run 1011@command{autoconf} on it. If you write your own feature tests to 1012supplement those that come with Autoconf, you might also write files 1013called @file{aclocal.m4} and @file{acsite.m4}. If you use a C header 1014file to contain @code{#define} directives, you might also run 1015@command{autoheader}, and you can distribute the generated file 1016@file{config.h.in} with the package. 1017 1018Here is a diagram showing how the files that can be used in 1019configuration are produced. Programs that are executed are suffixed by 1020@samp{*}. Optional files are enclosed in square brackets (@samp{[]}). 1021@command{autoconf} and @command{autoheader} also read the installed Autoconf 1022macro files (by reading @file{autoconf.m4}). 1023 1024@noindent 1025Files used in preparing a software package for distribution, when using 1026just Autoconf: 1027@example 1028your source files --> [autoscan*] --> [configure.scan] --> configure.ac 1029 1030@group 1031configure.ac --. 1032 | .------> autoconf* -----> configure 1033[aclocal.m4] --+---+ 1034 | `-----> [autoheader*] --> [config.h.in] 1035[acsite.m4] ---' 1036@end group 1037 1038Makefile.in 1039@end example 1040 1041@noindent 1042Additionally, if you use Automake, the following additional productions 1043come into play: 1044 1045@example 1046@group 1047[acinclude.m4] --. 1048 | 1049[local macros] --+--> aclocal* --> aclocal.m4 1050 | 1051configure.ac ----' 1052@end group 1053 1054@group 1055configure.ac --. 1056 +--> automake* --> Makefile.in 1057Makefile.am ---' 1058@end group 1059@end example 1060 1061@noindent 1062Files used in configuring a software package: 1063@example 1064@group 1065 .-------------> [config.cache] 1066configure* ------------+-------------> config.log 1067 | 1068[config.h.in] -. v .-> [config.h] -. 1069 +--> config.status* -+ +--> make* 1070Makefile.in ---' `-> Makefile ---' 1071@end group 1072@end example 1073 1074@menu 1075* Writing Autoconf Input:: What to put in an Autoconf input file 1076* autoscan Invocation:: Semi-automatic @file{configure.ac} writing 1077* ifnames Invocation:: Listing the conditionals in source code 1078* autoconf Invocation:: How to create configuration scripts 1079* autoreconf Invocation:: Remaking multiple @command{configure} scripts 1080@end menu 1081 1082@node Writing Autoconf Input 1083@section Writing @file{configure.ac} 1084 1085To produce a @command{configure} script for a software package, create a 1086file called @file{configure.ac} that contains invocations of the 1087Autoconf macros that test the system features your package needs or can 1088use. Autoconf macros already exist to check for many features; see 1089@ref{Existing Tests}, for their descriptions. For most other features, 1090you can use Autoconf template macros to produce custom checks; see 1091@ref{Writing Tests}, for information about them. For especially tricky 1092or specialized features, @file{configure.ac} might need to contain some 1093hand-crafted shell commands; see @ref{Portable Shell, , Portable Shell 1094Programming}. The @command{autoscan} program can give you a good start 1095in writing @file{configure.ac} (@pxref{autoscan Invocation}, for more 1096information). 1097 1098Previous versions of Autoconf promoted the name @file{configure.in}, 1099which is somewhat ambiguous (the tool needed to process this file is not 1100described by its extension), and introduces a slight confusion with 1101@file{config.h.in} and so on (for which @samp{.in} means ``to be 1102processed by @command{configure}''). Using @file{configure.ac} is now 1103preferred. 1104 1105@menu 1106* Shell Script Compiler:: Autoconf as solution of a problem 1107* Autoconf Language:: Programming in Autoconf 1108* Autoconf Input Layout:: Standard organization of @file{configure.ac} 1109@end menu 1110 1111@node Shell Script Compiler 1112@subsection A Shell Script Compiler 1113 1114Just as for any other computer language, in order to properly program 1115@file{configure.ac} in Autoconf you must understand @emph{what} problem 1116the language tries to address and @emph{how} it does so. 1117 1118The problem Autoconf addresses is that the world is a mess. After all, 1119you are using Autoconf in order to have your package compile easily on 1120all sorts of different systems, some of them being extremely hostile. 1121Autoconf itself bears the price for these differences: @command{configure} 1122must run on all those systems, and thus @command{configure} must limit itself 1123to their lowest common denominator of features. 1124 1125Naturally, you might then think of shell scripts; who needs 1126@command{autoconf}? A set of properly written shell functions is enough to 1127make it easy to write @command{configure} scripts by hand. Sigh! 1128Unfortunately, even in 2008, where shells without any function support are 1129far and few between, there are pitfalls to avoid when making use of them. 1130Also, finding a Bourne shell that accepts shell functions is not trivial, 1131even though there is almost always one on interesting porting targets. 1132 1133So, what is really needed is some kind of compiler, @command{autoconf}, 1134that takes an Autoconf program, @file{configure.ac}, and transforms it 1135into a portable shell script, @command{configure}. 1136 1137How does @command{autoconf} perform this task? 1138 1139There are two obvious possibilities: creating a brand new language or 1140extending an existing one. The former option is attractive: all 1141sorts of optimizations could easily be implemented in the compiler and 1142many rigorous checks could be performed on the Autoconf program 1143(e.g., rejecting any non-portable construct). Alternatively, you can 1144extend an existing language, such as the @code{sh} (Bourne shell) 1145language. 1146 1147Autoconf does the latter: it is a layer on top of @code{sh}. It was 1148therefore most convenient to implement @command{autoconf} as a macro 1149expander: a program that repeatedly performs @dfn{macro expansions} on 1150text input, replacing macro calls with macro bodies and producing a pure 1151@code{sh} script in the end. Instead of implementing a dedicated 1152Autoconf macro expander, it is natural to use an existing 1153general-purpose macro language, such as M4, and implement the extensions 1154as a set of M4 macros. 1155 1156 1157@node Autoconf Language 1158@subsection The Autoconf Language 1159@cindex quotation 1160 1161The Autoconf language differs from many other computer 1162languages because it treats actual code the same as plain text. Whereas 1163in C, for instance, data and instructions have different syntactic 1164status, in Autoconf their status is rigorously the same. Therefore, we 1165need a means to distinguish literal strings from text to be expanded: 1166quotation. 1167 1168When calling macros that take arguments, there must not be any white 1169space between the macro name and the open parenthesis. 1170 1171@example 1172AC_INIT ([oops], [1.0]) # incorrect 1173AC_INIT([hello], [1.0]) # good 1174@end example 1175 1176Arguments should 1177be enclosed within the quote characters @samp{[} and @samp{]}, and be 1178separated by commas. Any leading blanks or newlines in arguments are ignored, 1179unless they are quoted. You should always quote an argument that 1180might contain a macro name, comma, parenthesis, or a leading blank or 1181newline. This rule applies recursively for every macro 1182call, including macros called from other macros. For more details on 1183quoting rules, see @ref{Programming in M4}. 1184 1185For instance: 1186 1187@example 1188AC_CHECK_HEADER([stdio.h], 1189 [AC_DEFINE([HAVE_STDIO_H], [1], 1190 [Define to 1 if you have <stdio.h>.])], 1191 [AC_MSG_ERROR([sorry, can't do anything for you])]) 1192@end example 1193 1194@noindent 1195is quoted properly. You may safely simplify its quotation to: 1196 1197@example 1198AC_CHECK_HEADER([stdio.h], 1199 [AC_DEFINE([HAVE_STDIO_H], 1, 1200 [Define to 1 if you have <stdio.h>.])], 1201 [AC_MSG_ERROR([sorry, can't do anything for you])]) 1202@end example 1203 1204@noindent 1205because @samp{1} cannot contain a macro call. Here, the argument of 1206@code{AC_MSG_ERROR} must be quoted; otherwise, its comma would be 1207interpreted as an argument separator. Also, the second and third arguments 1208of @samp{AC_CHECK_HEADER} must be quoted, since they contain 1209macro calls. The three arguments @samp{HAVE_STDIO_H}, @samp{stdio.h}, 1210and @samp{Define to 1 if you have <stdio.h>.} do not need quoting, but 1211if you unwisely defined a macro with a name like @samp{Define} or 1212@samp{stdio} then they would need quoting. Cautious Autoconf users 1213would keep the quotes, but many Autoconf users find such precautions 1214annoying, and would rewrite the example as follows: 1215 1216@example 1217AC_CHECK_HEADER(stdio.h, 1218 [AC_DEFINE(HAVE_STDIO_H, 1, 1219 [Define to 1 if you have <stdio.h>.])], 1220 [AC_MSG_ERROR([sorry, can't do anything for you])]) 1221@end example 1222 1223@noindent 1224This is safe, so long as you adopt good naming conventions and do not 1225define macros with names like @samp{HAVE_STDIO_H}, @samp{stdio}, or 1226@samp{h}. Though it is also safe here to omit the quotes around 1227@samp{Define to 1 if you have <stdio.h>.} this is not recommended, as 1228message strings are more likely to inadvertently contain commas. 1229 1230The following example is wrong and dangerous, as it is underquoted: 1231 1232@example 1233AC_CHECK_HEADER(stdio.h, 1234 AC_DEFINE(HAVE_STDIO_H, 1, 1235 Define to 1 if you have <stdio.h>.), 1236 AC_MSG_ERROR([sorry, can't do anything for you])) 1237@end example 1238 1239In other cases, you may have to use text that also resembles a macro 1240call. You must quote that text even when it is not passed as a macro 1241argument. For example, these two approaches in @file{configure.ac} 1242(quoting just the potential problems, or quoting the entire line) will 1243protect your script in case autoconf ever adds a macro @code{AC_DC}: 1244 1245@example 1246echo "Hard rock was here! --[AC_DC]" 1247[echo "Hard rock was here! --AC_DC"] 1248@end example 1249 1250@noindent 1251which results in this text in @file{configure}: 1252 1253@example 1254echo "Hard rock was here! --AC_DC" 1255echo "Hard rock was here! --AC_DC" 1256@end example 1257 1258@noindent 1259When you use the same text in a macro argument, you must therefore have 1260an extra quotation level (since one is stripped away by the macro 1261substitution). In general, then, it is a good idea to @emph{use double 1262quoting for all literal string arguments}, either around just the 1263problematic portions, or over the entire argument: 1264 1265@example 1266AC_MSG_WARN([[AC_DC] stinks --Iron Maiden]) 1267AC_MSG_WARN([[AC_DC stinks --Iron Maiden]]) 1268@end example 1269 1270However, the above example triggers a warning about a possibly 1271unexpanded macro when running @command{autoconf}, because it collides 1272with the namespace of macros reserved for the Autoconf language. To be 1273really safe, you can use additional escaping (either a quadrigraph, or 1274creative shell constructs) to silence that particular warning: 1275 1276@example 1277echo "Hard rock was here! --AC""_DC" 1278AC_MSG_WARN([[AC@@&t@@_DC stinks --Iron Maiden]]) 1279@end example 1280 1281You are now able to understand one of the constructs of Autoconf that 1282has been continually misunderstood@enddots{} The rule of thumb is that 1283@emph{whenever you expect macro expansion, expect quote expansion}; 1284i.e., expect one level of quotes to be lost. For instance: 1285 1286@example 1287AC_COMPILE_IFELSE(AC_LANG_SOURCE([char b[10];]), [], 1288 [AC_MSG_ERROR([you lose])]) 1289@end example 1290 1291@noindent 1292is incorrect: here, the first argument of @code{AC_LANG_SOURCE} is 1293@samp{char b[10];} and is expanded once, which results in 1294@samp{char b10;}; and the @code{AC_LANG_SOURCE} is also expanded prior 1295to being passed to @code{AC_COMPILE_IFELSE}. (There was an idiom common 1296in Autoconf's past to 1297address this issue via the M4 @code{changequote} primitive, but do not 1298use it!) Let's take a closer look: the author meant the first argument 1299to be understood as a literal, and therefore it must be quoted twice; 1300likewise, the intermediate @code{AC_LANG_SOURCE} macro should be quoted 1301once so that it is only expanded after the rest of the body of 1302@code{AC_COMPILE_IFELSE} is in place: 1303 1304@example 1305AC_COMPILE_IFELSE([AC_LANG_SOURCE([[char b[10];]])], [], 1306 [AC_MSG_ERROR([you lose])]) 1307@end example 1308 1309@noindent 1310Voil@`a, you actually produce @samp{char b[10];} this time! 1311 1312On the other hand, descriptions (e.g., the last parameter of 1313@code{AC_DEFINE} or @code{AS_HELP_STRING}) are not literals---they 1314are subject to line breaking, for example---and should not be double quoted. 1315Even if these descriptions are short and are not actually broken, double 1316quoting them yields weird results. 1317 1318Some macros take optional arguments, which this documentation represents 1319as @ovar{arg} (not to be confused with the quote characters). You may 1320just leave them empty, or use @samp{[]} to make the emptiness of the 1321argument explicit, or you may simply omit the trailing commas. The 1322three lines below are equivalent: 1323 1324@example 1325AC_CHECK_HEADERS([stdio.h], [], [], []) 1326AC_CHECK_HEADERS([stdio.h],,,) 1327AC_CHECK_HEADERS([stdio.h]) 1328@end example 1329 1330It is best to put each macro call on its own line in 1331@file{configure.ac}. Most of the macros don't add extra newlines; they 1332rely on the newline after the macro call to terminate the commands. 1333This approach makes the generated @command{configure} script a little 1334easier to read by not inserting lots of blank lines. It is generally 1335safe to set shell variables on the same line as a macro call, because 1336the shell allows assignments without intervening newlines. 1337 1338You can include comments in @file{configure.ac} files by starting them 1339with the @samp{#}. For example, it is helpful to begin 1340@file{configure.ac} files with a line like this: 1341 1342@example 1343# Process this file with autoconf to produce a configure script. 1344@end example 1345 1346@node Autoconf Input Layout 1347@subsection Standard @file{configure.ac} Layout 1348 1349The order in which @file{configure.ac} calls the Autoconf macros is not 1350important, with a few exceptions. Every @file{configure.ac} must 1351contain a call to @code{AC_INIT} before the checks, and a call to 1352@code{AC_OUTPUT} at the end (@pxref{Output}). Additionally, some macros 1353rely on other macros having been called first, because they check 1354previously set values of some variables to decide what to do. These 1355macros are noted in the individual descriptions (@pxref{Existing 1356Tests}), and they also warn you when @command{configure} is created if they 1357are called out of order. 1358 1359To encourage consistency, here is a suggested order for calling the 1360Autoconf macros. Generally speaking, the things near the end of this 1361list are those that could depend on things earlier in it. For example, 1362library functions could be affected by types and libraries. 1363 1364@display 1365@group 1366Autoconf requirements 1367@code{AC_INIT(@var{package}, @var{version}, @var{bug-report-address})} 1368information on the package 1369checks for programs 1370checks for libraries 1371checks for header files 1372checks for types 1373checks for structures 1374checks for compiler characteristics 1375checks for library functions 1376checks for system services 1377@code{AC_CONFIG_FILES(@r{[}@var{file@dots{}}@r{]})} 1378@code{AC_OUTPUT} 1379@end group 1380@end display 1381 1382 1383@node autoscan Invocation 1384@section Using @command{autoscan} to Create @file{configure.ac} 1385@cindex @command{autoscan} 1386 1387The @command{autoscan} program can help you create and/or maintain a 1388@file{configure.ac} file for a software package. @command{autoscan} 1389examines source files in the directory tree rooted at a directory given 1390as a command line argument, or the current directory if none is given. 1391It searches the source files for common portability problems and creates 1392a file @file{configure.scan} which is a preliminary @file{configure.ac} 1393for that package, and checks a possibly existing @file{configure.ac} for 1394completeness. 1395 1396When using @command{autoscan} to create a @file{configure.ac}, you 1397should manually examine @file{configure.scan} before renaming it to 1398@file{configure.ac}; it probably needs some adjustments. 1399Occasionally, @command{autoscan} outputs a macro in the wrong order 1400relative to another macro, so that @command{autoconf} produces a warning; 1401you need to move such macros manually. Also, if you want the package to 1402use a configuration header file, you must add a call to 1403@code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}). You might 1404also have to change or add some @code{#if} directives to your program in 1405order to make it work with Autoconf (@pxref{ifnames Invocation}, for 1406information about a program that can help with that job). 1407 1408When using @command{autoscan} to maintain a @file{configure.ac}, simply 1409consider adding its suggestions. The file @file{autoscan.log} 1410contains detailed information on why a macro is requested. 1411 1412@command{autoscan} uses several data files (installed along with Autoconf) 1413to determine which macros to output when it finds particular symbols in 1414a package's source files. These data files all have the same format: 1415each line consists of a symbol, one or more blanks, and the Autoconf macro to 1416output if that symbol is encountered. Lines starting with @samp{#} are 1417comments. 1418 1419@command{autoscan} accepts the following options: 1420 1421@table @option 1422@item --help 1423@itemx -h 1424Print a summary of the command line options and exit. 1425 1426@item --version 1427@itemx -V 1428Print the version number of Autoconf and exit. 1429 1430@item --verbose 1431@itemx -v 1432Print the names of the files it examines and the potentially interesting 1433symbols it finds in them. This output can be voluminous. 1434 1435@item --debug 1436@itemx -d 1437Don't remove temporary files. 1438 1439@item --include=@var{dir} 1440@itemx -I @var{dir} 1441Append @var{dir} to the include path. Multiple invocations accumulate. 1442 1443@item --prepend-include=@var{dir} 1444@itemx -B @var{dir} 1445Prepend @var{dir} to the include path. Multiple invocations accumulate. 1446@end table 1447 1448@node ifnames Invocation 1449@section Using @command{ifnames} to List Conditionals 1450@cindex @command{ifnames} 1451 1452@command{ifnames} can help you write @file{configure.ac} for a software 1453package. It prints the identifiers that the package already uses in C 1454preprocessor conditionals. If a package has already been set up to have 1455some portability, @command{ifnames} can thus help you figure out what its 1456@command{configure} needs to check for. It may help fill in some gaps in a 1457@file{configure.ac} generated by @command{autoscan} (@pxref{autoscan 1458Invocation}). 1459 1460@command{ifnames} scans all of the C source files named on the command line 1461(or the standard input, if none are given) and writes to the standard 1462output a sorted list of all the identifiers that appear in those files 1463in @code{#if}, @code{#elif}, @code{#ifdef}, or @code{#ifndef} 1464directives. It prints each identifier on a line, followed by a 1465space-separated list of the files in which that identifier occurs. 1466 1467@noindent 1468@command{ifnames} accepts the following options: 1469 1470@table @option 1471@item --help 1472@itemx -h 1473Print a summary of the command line options and exit. 1474 1475@item --version 1476@itemx -V 1477Print the version number of Autoconf and exit. 1478@end table 1479 1480@node autoconf Invocation 1481@section Using @command{autoconf} to Create @command{configure} 1482@cindex @command{autoconf} 1483 1484To create @command{configure} from @file{configure.ac}, run the 1485@command{autoconf} program with no arguments. @command{autoconf} processes 1486@file{configure.ac} with the M4 macro processor, using the 1487Autoconf macros. If you give @command{autoconf} an argument, it reads that 1488file instead of @file{configure.ac} and writes the configuration script 1489to the standard output instead of to @command{configure}. If you give 1490@command{autoconf} the argument @option{-}, it reads from the standard 1491input instead of @file{configure.ac} and writes the configuration script 1492to the standard output. 1493 1494The Autoconf macros are defined in several files. Some of the files are 1495distributed with Autoconf; @command{autoconf} reads them first. Then it 1496looks for the optional file @file{acsite.m4} in the directory that 1497contains the distributed Autoconf macro files, and for the optional file 1498@file{aclocal.m4} in the current directory. Those files can contain 1499your site's or the package's own Autoconf macro definitions 1500(@pxref{Writing Autoconf Macros}, for more information). If a macro is 1501defined in more than one of the files that @command{autoconf} reads, the 1502last definition it reads overrides the earlier ones. 1503 1504@command{autoconf} accepts the following options: 1505 1506@table @option 1507@item --help 1508@itemx -h 1509Print a summary of the command line options and exit. 1510 1511@item --version 1512@itemx -V 1513Print the version number of Autoconf and exit. 1514 1515@item --verbose 1516@itemx -v 1517Report processing steps. 1518 1519@item --debug 1520@itemx -d 1521Don't remove the temporary files. 1522 1523@item --force 1524@itemx -f 1525Remake @file{configure} even if newer than its input files. 1526 1527@item --include=@var{dir} 1528@itemx -I @var{dir} 1529Append @var{dir} to the include path. Multiple invocations accumulate. 1530 1531@item --prepend-include=@var{dir} 1532@itemx -B @var{dir} 1533Prepend @var{dir} to the include path. Multiple invocations accumulate. 1534 1535@item --output=@var{file} 1536@itemx -o @var{file} 1537Save output (script or trace) to @var{file}. The file @option{-} stands 1538for the standard output. 1539 1540@item --warnings=@var{category} 1541@itemx -W @var{category} 1542@evindex WARNINGS 1543Report the warnings related to @var{category} (which can actually be a 1544comma separated list). @xref{Reporting Messages}, macro 1545@code{AC_DIAGNOSE}, for a comprehensive list of categories. Special 1546values include: 1547 1548@table @samp 1549@item all 1550report all the warnings 1551 1552@item none 1553report none 1554 1555@item error 1556treats warnings as errors 1557 1558@item no-@var{category} 1559disable warnings falling into @var{category} 1560@end table 1561 1562Warnings about @samp{syntax} are enabled by default, and the environment 1563variable @env{WARNINGS}, a comma separated list of categories, is 1564honored as well. Passing @option{-W @var{category}} actually behaves as if 1565you had passed @option{--warnings syntax,$WARNINGS,@var{category}}. To 1566disable the defaults and @env{WARNINGS}, and then 1567enable warnings about obsolete constructs, use @option{-W 1568none,obsolete}. 1569 1570@cindex Back trace 1571@cindex Macro invocation stack 1572Because @command{autoconf} uses @command{autom4te} behind the scenes, it 1573displays a back trace for errors, but not for warnings; if you want 1574them, just pass @option{-W error}. @xref{autom4te Invocation}, for some 1575examples. 1576 1577@item --trace=@var{macro}[:@var{format}] 1578@itemx -t @var{macro}[:@var{format}] 1579Do not create the @command{configure} script, but list the calls to 1580@var{macro} according to the @var{format}. Multiple @option{--trace} 1581arguments can be used to list several macros. Multiple @option{--trace} 1582arguments for a single macro are not cumulative; instead, you should 1583just make @var{format} as long as needed. 1584 1585The @var{format} is a regular string, with newlines if desired, and 1586several special escape codes. It defaults to @samp{$f:$l:$n:$%}; see 1587@ref{autom4te Invocation}, for details on the @var{format}. 1588 1589@item --initialization 1590@itemx -i 1591By default, @option{--trace} does not trace the initialization of the 1592Autoconf macros (typically the @code{AC_DEFUN} definitions). This 1593results in a noticeable speedup, but can be disabled by this option. 1594@end table 1595 1596 1597It is often necessary to check the content of a @file{configure.ac} 1598file, but parsing it yourself is extremely fragile and error-prone. It 1599is suggested that you rely upon @option{--trace} to scan 1600@file{configure.ac}. For instance, to find the list of variables that 1601are substituted, use: 1602 1603@example 1604@group 1605$ @kbd{autoconf -t AC_SUBST} 1606configure.ac:2:AC_SUBST:ECHO_C 1607configure.ac:2:AC_SUBST:ECHO_N 1608configure.ac:2:AC_SUBST:ECHO_T 1609@i{More traces deleted} 1610@end group 1611@end example 1612 1613@noindent 1614The example below highlights the difference between @samp{$@@}, 1615@samp{$*}, and @samp{$%}. 1616 1617@example 1618@group 1619$ @kbd{cat configure.ac} 1620AC_DEFINE(This, is, [an 1621[example]]) 1622$ @kbd{autoconf -t 'AC_DEFINE:@@: $@@} 1623*: $* 1624%: $%' 1625@@: [This],[is],[an 1626[example]] 1627*: This,is,an 1628[example] 1629%: This:is:an [example] 1630@end group 1631@end example 1632 1633@noindent 1634The @var{format} gives you a lot of freedom: 1635 1636@example 1637@group 1638$ @kbd{autoconf -t 'AC_SUBST:$$ac_subst@{"$1"@} = "$f:$l";'} 1639$ac_subst@{"ECHO_C"@} = "configure.ac:2"; 1640$ac_subst@{"ECHO_N"@} = "configure.ac:2"; 1641$ac_subst@{"ECHO_T"@} = "configure.ac:2"; 1642@i{More traces deleted} 1643@end group 1644@end example 1645 1646@noindent 1647A long @var{separator} can be used to improve the readability of complex 1648structures, and to ease their parsing (for instance when no single 1649character is suitable as a separator): 1650 1651@example 1652@group 1653$ @kbd{autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*'} 1654ACLOCAL|:::::|aclocal|:::::|$missing_dir 1655AUTOCONF|:::::|autoconf|:::::|$missing_dir 1656AUTOMAKE|:::::|automake|:::::|$missing_dir 1657@i{More traces deleted} 1658@end group 1659@end example 1660 1661@node autoreconf Invocation 1662@section Using @command{autoreconf} to Update @command{configure} Scripts 1663@cindex @command{autoreconf} 1664 1665Installing the various components of the GNU Build System can be 1666tedious: running @command{autopoint} for Gettext, @command{automake} for 1667@file{Makefile.in} etc.@: in each directory. It may be needed either 1668because some tools such as @command{automake} have been updated on your 1669system, or because some of the sources such as @file{configure.ac} have 1670been updated, or finally, simply in order to install the GNU Build 1671System in a fresh tree. 1672 1673@command{autoreconf} runs @command{autoconf}, @command{autoheader}, 1674@command{aclocal}, @command{automake}, @command{libtoolize}, and 1675@command{autopoint} (when appropriate) repeatedly to update the 1676GNU Build System in the specified directories and their 1677subdirectories (@pxref{Subdirectories}). By default, it only remakes 1678those files that are older than their sources. The environment variables 1679@env{AUTOM4TE}, @env{AUTOCONF}, @env{AUTOHEADER}, @env{AUTOMAKE}, 1680@env{ACLOCAL}, @env{AUTOPOINT}, @env{LIBTOOLIZE}, @env{M4}, and @env{MAKE} 1681may be used to override the invocation of the respective tools. 1682 1683If you install a new version of some tool, you can make 1684@command{autoreconf} remake @emph{all} of the files by giving it the 1685@option{--force} option. 1686 1687@xref{Automatic Remaking}, for Make rules to automatically 1688rebuild @command{configure} scripts when their source files change. That 1689method handles the timestamps of configuration header templates 1690properly, but does not pass @option{--autoconf-dir=@var{dir}} or 1691@option{--localdir=@var{dir}}. 1692 1693@cindex Gettext 1694@cindex @command{autopoint} 1695Gettext supplies the @command{autopoint} command to add translation 1696infrastructure to a source package. If you use @command{autopoint}, 1697your @file{configure.ac} should invoke both @code{AM_GNU_GETTEXT} and 1698@code{AM_GNU_GETTEXT_VERSION(@var{gettext-version})}. @xref{autopoint 1699Invocation, , Invoking the @code{autopoint} Program, gettext, 1700GNU @code{gettext} utilities}, for further details. 1701 1702@noindent 1703@command{autoreconf} accepts the following options: 1704 1705@table @option 1706@item --help 1707@itemx -h 1708Print a summary of the command line options and exit. 1709 1710@item --version 1711@itemx -V 1712Print the version number of Autoconf and exit. 1713 1714@item --verbose 1715@itemx -v 1716Print the name of each directory @command{autoreconf} examines and the 1717commands it runs. If given two or more times, pass @option{--verbose} 1718to subordinate tools that support it. 1719 1720@item --debug 1721@itemx -d 1722Don't remove the temporary files. 1723 1724@item --force 1725@itemx -f 1726Remake even @file{configure} scripts and configuration headers that are 1727newer than their input files (@file{configure.ac} and, if present, 1728@file{aclocal.m4}). 1729 1730@item --install 1731@itemx -i 1732Install the missing auxiliary files in the package. By default, files 1733are copied; this can be changed with @option{--symlink}. 1734 1735If deemed appropriate, this option triggers calls to 1736@samp{automake --add-missing}, 1737@samp{libtoolize}, @samp{autopoint}, etc. 1738 1739@item --no-recursive 1740Do not rebuild files in subdirectories to configure (see @ref{Subdirectories}, 1741macro @code{AC_CONFIG_SUBDIRS}). 1742 1743@item --symlink 1744@itemx -s 1745When used with @option{--install}, install symbolic links to the missing 1746auxiliary files instead of copying them. 1747 1748@item --make 1749@itemx -m 1750When the directories were configured, update the configuration by 1751running @samp{./config.status --recheck && ./config.status}, and then 1752run @samp{make}. 1753 1754@item --include=@var{dir} 1755@itemx -I @var{dir} 1756Append @var{dir} to the include path. Multiple invocations accumulate. 1757Passed on to @command{aclocal}, @command{autoconf} and 1758@command{autoheader} internally. 1759 1760@item --prepend-include=@var{dir} 1761@itemx -B @var{dir} 1762Prepend @var{dir} to the include path. Multiple invocations accumulate. 1763Passed on to @command{autoconf} and @command{autoheader} internally. 1764 1765@item --warnings=@var{category} 1766@itemx -W @var{category} 1767@evindex WARNINGS 1768Report the warnings related to @var{category} (which can actually be a 1769comma separated list). 1770 1771@table @samp 1772@item cross 1773related to cross compilation issues. 1774 1775@item obsolete 1776report the uses of obsolete constructs. 1777 1778@item portability 1779portability issues 1780 1781@item syntax 1782dubious syntactic constructs. 1783 1784@item all 1785report all the warnings 1786 1787@item none 1788report none 1789 1790@item error 1791treats warnings as errors 1792 1793@item no-@var{category} 1794disable warnings falling into @var{category} 1795@end table 1796 1797Warnings about @samp{syntax} are enabled by default, and the environment 1798variable @env{WARNINGS}, a comma separated list of categories, is 1799honored as well. Passing @option{-W @var{category}} actually behaves as if 1800you had passed @option{--warnings syntax,$WARNINGS,@var{category}}. To 1801disable the defaults and @env{WARNINGS}, and then 1802enable warnings about obsolete constructs, use @option{-W 1803none,obsolete}. 1804@end table 1805 1806If you want @command{autoreconf} to pass flags that are not listed here 1807on to @command{aclocal}, set @code{ACLOCAL_AMFLAGS} in your @file{Makefile.am}. 1808Due to a limitation in the Autoconf implementation these flags currently 1809must be set on a single line in @file{Makefile.am}, without any 1810backslash-newlines. 1811 1812@c ========================================= Initialization and Output Files. 1813 1814@node Setup 1815@chapter Initialization and Output Files 1816 1817Autoconf-generated @command{configure} scripts need some information about 1818how to initialize, such as how to find the package's source files and 1819about the output files to produce. The following sections describe the 1820initialization and the creation of output files. 1821 1822@menu 1823* Initializing configure:: Option processing etc. 1824* Versioning:: Dealing with Autoconf versions 1825* Notices:: Copyright, version numbers in @command{configure} 1826* Input:: Where Autoconf should find files 1827* Output:: Outputting results from the configuration 1828* Configuration Actions:: Preparing the output based on results 1829* Configuration Files:: Creating output files 1830* Makefile Substitutions:: Using output variables in makefiles 1831* Configuration Headers:: Creating a configuration header file 1832* Configuration Commands:: Running arbitrary instantiation commands 1833* Configuration Links:: Links depending on the configuration 1834* Subdirectories:: Configuring independent packages together 1835* Default Prefix:: Changing the default installation prefix 1836@end menu 1837 1838@node Initializing configure 1839@section Initializing @command{configure} 1840 1841Every @command{configure} script must call @code{AC_INIT} before doing 1842anything else that produces output. Calls to silent macros, such as 1843@code{AC_DEFUN}, may also occur prior to @code{AC_INIT}, although these 1844are generally used via @file{aclocal.m4}, since that is implicitly 1845included before the start of @file{configure.ac}. The only other 1846required macro is @code{AC_OUTPUT} (@pxref{Output}). 1847 1848@anchor{AC_INIT} 1849@defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report}, @ 1850 @ovar{tarname}, @ovar{url}) 1851@acindex{INIT} 1852Process any command-line arguments and perform initialization 1853and verification. 1854 1855Set the name of the @var{package} and its @var{version}. These are 1856typically used in @option{--version} support, including that of 1857@command{configure}. The optional argument @var{bug-report} should be 1858the email to which users should send bug reports. The package 1859@var{tarname} differs from @var{package}: the latter designates the full 1860package name (e.g., @samp{GNU Autoconf}), while the former is meant for 1861distribution tar ball names (e.g., @samp{autoconf}). It defaults to 1862@var{package} with @samp{GNU } stripped, lower-cased, and all characters 1863other than alphanumerics and underscores are changed to @samp{-}. If 1864provided, @var{url} should be the home page for the package. 1865 1866The arguments of @code{AC_INIT} must be static, i.e., there should not 1867be any shell computation, quotes, or newlines, but they can be computed 1868by M4. This is because the package information strings are expanded at 1869M4 time into several contexts, and must give the same text at shell time 1870whether used in single-quoted strings, double-quoted strings, quoted 1871here-documents, or unquoted here-documents. It is permissible to use 1872@code{m4_esyscmd} or @code{m4_esyscmd_s} for computing a version string 1873that changes with every commit to a version control system (in fact, 1874Autoconf does just that, for all builds of the development tree made 1875between releases). 1876 1877The following M4 macros (e.g., @code{AC_PACKAGE_NAME}), output variables 1878(e.g., @code{PACKAGE_NAME}), and preprocessor symbols (e.g., 1879@code{PACKAGE_NAME}), are defined by @code{AC_INIT}: 1880 1881@table @asis 1882@item @code{AC_PACKAGE_NAME}, @code{PACKAGE_NAME} 1883@acindex{PACKAGE_NAME} 1884@ovindex PACKAGE_NAME 1885@cvindex PACKAGE_NAME 1886Exactly @var{package}. 1887 1888@item @code{AC_PACKAGE_TARNAME}, @code{PACKAGE_TARNAME} 1889@acindex{PACKAGE_TARNAME} 1890@ovindex PACKAGE_TARNAME 1891@cvindex PACKAGE_TARNAME 1892Exactly @var{tarname}, possibly generated from @var{package}. 1893 1894@item @code{AC_PACKAGE_VERSION}, @code{PACKAGE_VERSION} 1895@acindex{PACKAGE_VERSION} 1896@ovindex PACKAGE_VERSION 1897@cvindex PACKAGE_VERSION 1898Exactly @var{version}. 1899 1900@item @code{AC_PACKAGE_STRING}, @code{PACKAGE_STRING} 1901@acindex{PACKAGE_STRING} 1902@ovindex PACKAGE_STRING 1903@cvindex PACKAGE_STRING 1904Exactly @samp{@var{package} @var{version}}. 1905 1906@item @code{AC_PACKAGE_BUGREPORT}, @code{PACKAGE_BUGREPORT} 1907@acindex{PACKAGE_BUGREPORT} 1908@ovindex PACKAGE_BUGREPORT 1909@cvindex PACKAGE_BUGREPORT 1910Exactly @var{bug-report}, if one was provided. Typically an email 1911address, or URL to a bug management web page. 1912 1913@item @code{AC_PACKAGE_URL}, @code{PACKAGE_URL} 1914@acindex{PACKAGE_URL} 1915@ovindex PACKAGE_URL 1916@cvindex PACKAGE_URL 1917Exactly @var{url}, if one was provided. If @var{url} was empty, but 1918@var{package} begins with @samp{GNU }, then this defaults to 1919@samp{http://@/www.gnu.org/@/software/@/@var{tarname}/}, otherwise, no URL is 1920assumed. 1921@end table 1922@end defmac 1923 1924If your @command{configure} script does its own option processing, it 1925should inspect @samp{$@@} or @samp{$*} immediately after calling 1926@code{AC_INIT}, because other Autoconf macros liberally use the 1927@command{set} command to process strings, and this has the side effect 1928of updating @samp{$@@} and @samp{$*}. However, we suggest that you use 1929standard macros like @code{AC_ARG_ENABLE} instead of attempting to 1930implement your own option processing. @xref{Site Configuration}. 1931 1932@node Versioning 1933@section Dealing with Autoconf versions 1934@cindex Autoconf version 1935@cindex version, Autoconf 1936 1937The following optional macros can be used to help choose the minimum 1938version of Autoconf that can successfully compile a given 1939@file{configure.ac}. 1940 1941@defmac AC_PREREQ (@var{version}) 1942@acindex{PREREQ} 1943@cindex Version 1944Ensure that a recent enough version of Autoconf is being used. If the 1945version of Autoconf being used to create @command{configure} is 1946earlier than @var{version}, print an error message to the standard 1947error output and exit with failure (exit status is 63). For example: 1948 1949@example 1950AC_PREREQ([@value{VERSION}]) 1951@end example 1952 1953This macro may be used before @code{AC_INIT}. 1954@end defmac 1955 1956@defmac AC_AUTOCONF_VERSION 1957@acindex{AUTOCONF_VERSION} 1958This macro was introduced in Autoconf 2.62. It identifies the version 1959of Autoconf that is currently parsing the input file, in a format 1960suitable for @code{m4_version_compare} (@pxref{m4_version_compare}); in 1961other words, for this release of Autoconf, its value is 1962@samp{@value{VERSION}}. One potential use of this macro is for writing 1963conditional fallbacks based on when a feature was added to Autoconf, 1964rather than using @code{AC_PREREQ} to require the newer version of 1965Autoconf. However, remember that the Autoconf philosophy favors feature 1966checks over version checks. 1967 1968You should not expand this macro directly; use 1969@samp{m4_defn([AC_AUTOCONF_VERSION])} instead. This is because some 1970users might 1971have a beta version of Autoconf installed, with arbitrary letters 1972included in its version string. This means it is possible for the 1973version string to contain the name of a defined macro, such that 1974expanding @code{AC_AUTOCONF_VERSION} would trigger the expansion of that 1975macro during rescanning, and change the version string to be different 1976than what you intended to check. 1977@end defmac 1978 1979@node Notices 1980@section Notices in @command{configure} 1981@cindex Notices in @command{configure} 1982 1983The following macros manage version numbers for @command{configure} 1984scripts. Using them is optional. 1985 1986@defmac AC_COPYRIGHT (@var{copyright-notice}) 1987@acindex{COPYRIGHT} 1988@cindex Copyright Notice 1989State that, in addition to the Free Software Foundation's copyright on 1990the Autoconf macros, parts of your @command{configure} are covered by the 1991@var{copyright-notice}. 1992 1993The @var{copyright-notice} shows up in both the head of 1994@command{configure} and in @samp{configure --version}. 1995@end defmac 1996 1997 1998@defmac AC_REVISION (@var{revision-info}) 1999@acindex{REVISION} 2000@cindex Revision 2001Copy revision stamp @var{revision-info} into the @command{configure} 2002script, with any dollar signs or double-quotes removed. This macro lets 2003you put a revision stamp from @file{configure.ac} into @command{configure} 2004without RCS or CVS changing it when you check in 2005@command{configure}. That way, you can determine easily which revision of 2006@file{configure.ac} a particular @command{configure} corresponds to. 2007 2008For example, this line in @file{configure.ac}: 2009 2010@c The @w prevents RCS from changing the example in the manual. 2011@example 2012AC_REVISION([@w{$}Revision: 1.30 $]) 2013@end example 2014 2015@noindent 2016produces this in @command{configure}: 2017 2018@example 2019#!/bin/sh 2020# From configure.ac Revision: 1.30 2021@end example 2022@end defmac 2023 2024 2025@node Input 2026@section Finding @command{configure} Input 2027 2028@anchor{AC_CONFIG_SRCDIR} 2029@defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir}) 2030@acindex{CONFIG_SRCDIR} 2031@var{unique-file-in-source-dir} is some file that is in the package's 2032source directory; @command{configure} checks for this file's existence to 2033make sure that the directory that it is told contains the source code in 2034fact does. Occasionally people accidentally specify the wrong directory 2035with @option{--srcdir}; this is a safety check. @xref{configure 2036Invocation}, for more information. 2037@end defmac 2038 2039 2040@c FIXME: Remove definitively once --install explained. 2041@c 2042@c Small packages may store all their macros in @code{aclocal.m4}. As the 2043@c set of macros grows, or for maintenance reasons, a maintainer may prefer 2044@c to split the macros in several files. In this case, Autoconf must be 2045@c told which files to load, and in which order. 2046@c 2047@c @defmac AC_INCLUDE (@var{file}@dots{}) 2048@c @acindex{INCLUDE} 2049@c @c FIXME: There is no longer shell globbing. 2050@c Read the macro definitions that appear in the listed files. A list of 2051@c space-separated file names or shell globbing patterns is expected. The 2052@c files are read in the order they're listed. 2053@c 2054@c Because the order of definition of macros is important (only the last 2055@c definition of a macro is used), beware that it is @code{AC_INIT} that 2056@c loads @file{acsite.m4} and @file{aclocal.m4}. Note that 2057@c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within 2058@c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in 2059@c the latter case, non-macro lines from included files may end up in the 2060@c @file{configure} script, whereas in the former case, they'd be discarded 2061@c just like any text that appear before @code{AC_INIT}. 2062@c @end defmac 2063 2064Packages that do manual configuration or use the @command{install} program 2065might need to tell @command{configure} where to find some other shell 2066scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places 2067it looks are correct for most cases. 2068 2069@defmac AC_CONFIG_AUX_DIR (@var{dir}) 2070@acindex{CONFIG_AUX_DIR} 2071Use the auxiliary build tools (e.g., @file{install-sh}, 2072@file{config.sub}, @file{config.guess}, Cygnus @command{configure}, 2073Automake and Libtool scripts, etc.)@: that are in directory @var{dir}. 2074These are auxiliary files used in configuration. @var{dir} can be 2075either absolute or relative to @file{@var{srcdir}}. The default is 2076@file{@var{srcdir}} or @file{@var{srcdir}/..} or 2077@file{@var{srcdir}/../..}, whichever is the first that contains 2078@file{install-sh}. The other files are not checked for, so that using 2079@code{AC_PROG_INSTALL} does not automatically require distributing the 2080other auxiliary files. It checks for @file{install.sh} also, but that 2081name is obsolete because some @command{make} have a rule that creates 2082@file{install} from it if there is no makefile. 2083 2084The auxiliary directory is commonly named @file{build-aux}. 2085If you need portability to DOS variants, do not name the 2086auxiliary directory @file{aux}. @xref{File System Conventions}. 2087@end defmac 2088 2089@defmac AC_REQUIRE_AUX_FILE (@var{file}) 2090@acindex{REQUIRE_AUX_FILE} 2091Declares that @var{file} is expected in the directory defined above. In 2092Autoconf proper, this macro does nothing: its sole purpose is to be 2093traced by third-party tools to produce a list of expected auxiliary 2094files. For instance it is called by macros like @code{AC_PROG_INSTALL} 2095(@pxref{Particular Programs}) or @code{AC_CANONICAL_BUILD} 2096(@pxref{Canonicalizing}) to register the auxiliary files they need. 2097@end defmac 2098 2099Similarly, packages that use @command{aclocal} should declare where 2100local macros can be found using @code{AC_CONFIG_MACRO_DIR}. 2101 2102@defmac AC_CONFIG_MACRO_DIR (@var{dir}) 2103@acindex{CONFIG_MACRO_DIR} 2104Specify @var{dir} as the location of additional local Autoconf macros. 2105This macro is intended for use by future versions of commands like 2106@command{autoreconf} that trace macro calls. It should be called 2107directly from @file{configure.ac} so that tools that install macros for 2108@command{aclocal} can find the macros' declarations. 2109 2110Note that if you use @command{aclocal} from Automake to generate 2111@file{aclocal.m4}, you must also set @code{ACLOCAL_AMFLAGS = -I 2112@var{dir}} in your top-level @file{Makefile.am}. Due to a limitation in 2113the Autoconf implementation of @command{autoreconf}, these include 2114directives currently must be set on a single line in @file{Makefile.am}, 2115without any backslash-newlines. 2116@end defmac 2117 2118 2119@node Output 2120@section Outputting Files 2121@cindex Outputting files 2122 2123Every Autoconf script, e.g., @file{configure.ac}, should finish by 2124calling @code{AC_OUTPUT}. That is the macro that generates and runs 2125@file{config.status}, which in turn creates the makefiles and any 2126other files resulting from configuration. This is the only required 2127macro besides @code{AC_INIT} (@pxref{Input}). 2128 2129@anchor{AC_OUTPUT} 2130@defmac AC_OUTPUT 2131@acindex{OUTPUT} 2132@cindex Instantiation 2133Generate @file{config.status} and launch it. Call this macro once, at 2134the end of @file{configure.ac}. 2135 2136@file{config.status} performs all the configuration actions: all the 2137output files (see @ref{Configuration Files}, macro 2138@code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers}, 2139macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration 2140Commands}, macro @code{AC_CONFIG_COMMANDS}), links (see 2141@ref{Configuration Links}, macro @code{AC_CONFIG_LINKS}), subdirectories 2142to configure (see @ref{Subdirectories}, macro @code{AC_CONFIG_SUBDIRS}) 2143are honored. 2144 2145The location of your @code{AC_OUTPUT} invocation is the exact point 2146where configuration actions are taken: any code afterwards is 2147executed by @command{configure} once @command{config.status} was run. If 2148you want to bind actions to @command{config.status} itself 2149(independently of whether @command{configure} is being run), see 2150@ref{Configuration Commands, , Running Arbitrary Configuration 2151Commands}. 2152@end defmac 2153 2154Historically, the usage of @code{AC_OUTPUT} was somewhat different. 2155@xref{Obsolete Macros}, for a description of the arguments that 2156@code{AC_OUTPUT} used to support. 2157 2158 2159If you run @command{make} in subdirectories, you should run it using the 2160@command{make} variable @code{MAKE}. Most versions of @command{make} set 2161@code{MAKE} to the name of the @command{make} program plus any options it 2162was given. (But many do not include in it the values of any variables 2163set on the command line, so those are not passed on automatically.) 2164Some old versions of @command{make} do not set this variable. The 2165following macro allows you to use it even with those versions. 2166 2167@anchor{AC_PROG_MAKE_SET} 2168@defmac AC_PROG_MAKE_SET 2169@acindex{PROG_MAKE_SET} 2170@ovindex SET_MAKE 2171If the Make command, @code{$MAKE} if set or else @samp{make}, predefines 2172@code{$(MAKE)}, define output variable @code{SET_MAKE} to be empty. 2173Otherwise, define @code{SET_MAKE} to a macro definition that sets 2174@code{$(MAKE)}, such as @samp{MAKE=make}. Calls @code{AC_SUBST} for 2175@code{SET_MAKE}. 2176@end defmac 2177 2178If you use this macro, place a line like this in each @file{Makefile.in} 2179that runs @command{MAKE} on other directories: 2180 2181@example 2182@@SET_MAKE@@ 2183@end example 2184 2185 2186 2187@node Configuration Actions 2188@section Performing Configuration Actions 2189@cindex Configuration actions 2190 2191@file{configure} is designed so that it appears to do everything itself, 2192but there is actually a hidden slave: @file{config.status}. 2193@file{configure} is in charge of examining your system, but it is 2194@file{config.status} that actually takes the proper actions based on the 2195results of @file{configure}. The most typical task of 2196@file{config.status} is to @emph{instantiate} files. 2197 2198@acindex{CONFIG_@var{ITEMS}} 2199This section describes the common behavior of the four standard 2200instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS}, 2201@code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}. They all 2202have this prototype: 2203 2204@c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something 2205@c awful. 2206@example 2207AC_CONFIG_@var{ITEMS}(@var{tag}@dots{}, @r{[}@var{commands}@r{]}, @r{[}@var{init-cmds}@r{]}) 2208@end example 2209 2210@noindent 2211where the arguments are: 2212 2213@table @var 2214@item tag@dots{} 2215A blank-or-newline-separated list of tags, which are typically the names of 2216the files to instantiate. 2217 2218You are encouraged to use literals as @var{tags}. In particular, you 2219should avoid 2220 2221@example 2222@dots{} && my_foos="$my_foos fooo" 2223@dots{} && my_foos="$my_foos foooo" 2224AC_CONFIG_@var{ITEMS}([$my_foos]) 2225@end example 2226 2227@noindent 2228and use this instead: 2229 2230@example 2231@dots{} && AC_CONFIG_@var{ITEMS}([fooo]) 2232@dots{} && AC_CONFIG_@var{ITEMS}([foooo]) 2233@end example 2234 2235The macros @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use 2236special @var{tag} values: they may have the form @samp{@var{output}} or 2237@samp{@var{output}:@var{inputs}}. The file @var{output} is instantiated 2238from its templates, @var{inputs} (defaulting to @samp{@var{output}.in}). 2239 2240@samp{AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk])}, 2241for example, asks for 2242the creation of the file @file{Makefile} that contains the expansion of the 2243output variables in the concatenation of @file{boiler/top.mk} and 2244@file{boiler/bot.mk}. 2245 2246The special value @samp{-} might be used to denote the standard output 2247when used in @var{output}, or the standard input when used in the 2248@var{inputs}. You most probably don't need to use this in 2249@file{configure.ac}, but it is convenient when using the command line 2250interface of @file{./config.status}, see @ref{config.status Invocation}, 2251for more details. 2252 2253The @var{inputs} may be absolute or relative file names. In the latter 2254case they are first looked for in the build tree, and then in the source 2255tree. Input files should be text files, and a line length below 2000 2256bytes should be safe. 2257 2258@item commands 2259Shell commands output literally into @file{config.status}, and 2260associated with a tag that the user can use to tell @file{config.status} 2261which commands to run. The commands are run each time a @var{tag} 2262request is given to @file{config.status}, typically each time the file 2263@file{@var{tag}} is created. 2264 2265The variables set during the execution of @command{configure} are 2266@emph{not} available here: you first need to set them via the 2267@var{init-cmds}. Nonetheless the following variables are precomputed: 2268 2269@table @code 2270@item srcdir 2271@vrindex srcdir 2272The name of the top source directory, assuming that the working 2273directory is the top build directory. This 2274is what the @command{configure} option @option{--srcdir} sets. 2275 2276@item ac_top_srcdir 2277@vrindex ac_top_srcdir 2278The name of the top source directory, assuming that the working 2279directory is the current build directory. 2280 2281@item ac_top_build_prefix 2282@vrindex ac_top_build_prefix 2283The name of the top build directory, assuming that the working 2284directory is the current build directory. 2285It can be empty, or else ends with a slash, so that you may concatenate 2286it. 2287 2288@item ac_srcdir 2289@vrindex ac_srcdir 2290The name of the corresponding source directory, assuming that the 2291working directory is the current build directory. 2292 2293@item tmp 2294@vrindex tmp 2295The name of a temporary directory within the build tree, which you 2296can use if you need to create additional temporary files. The 2297directory is cleaned up when @command{config.status} is done or 2298interrupted. Please use package-specific file name prefixes to 2299avoid clashing with files that @command{config.status} may use 2300internally. 2301@end table 2302 2303@noindent 2304The @dfn{current} directory refers to the directory (or 2305pseudo-directory) containing the input part of @var{tags}. For 2306instance, running 2307 2308@example 2309AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [@dots{}], [@dots{}]) 2310@end example 2311 2312@noindent 2313 with @option{--srcdir=../package} produces the following values: 2314 2315@example 2316# Argument of --srcdir 2317srcdir='../package' 2318# Reversing deep/dir 2319ac_top_build_prefix='../../' 2320# Concatenation of $ac_top_build_prefix and srcdir 2321ac_top_srcdir='../../../package' 2322# Concatenation of $ac_top_srcdir and deep/dir 2323ac_srcdir='../../../package/deep/dir' 2324@end example 2325 2326@noindent 2327independently of @samp{in/in.in}. 2328 2329@item init-cmds 2330Shell commands output @emph{unquoted} near the beginning of 2331@file{config.status}, and executed each time @file{config.status} runs 2332(regardless of the tag). Because they are unquoted, for example, 2333@samp{$var} is output as the value of @code{var}. @var{init-cmds} 2334is typically used by @file{configure} to give @file{config.status} some 2335variables it needs to run the @var{commands}. 2336 2337You should be extremely cautious in your variable names: all the 2338@var{init-cmds} share the same name space and may overwrite each other 2339in unpredictable ways. Sorry@enddots{} 2340@end table 2341 2342All these macros can be called multiple times, with different 2343@var{tag} values, of course! 2344 2345 2346@node Configuration Files 2347@section Creating Configuration Files 2348@cindex Creating configuration files 2349@cindex Configuration file creation 2350 2351Be sure to read the previous section, @ref{Configuration Actions}. 2352 2353@anchor{AC_CONFIG_FILES} 2354@defmac AC_CONFIG_FILES (@var{file}@dots{}, @ovar{cmds}, @ovar{init-cmds}) 2355@acindex{CONFIG_FILES} 2356Make @code{AC_OUTPUT} create each @file{@var{file}} by copying an input 2357file (by default @file{@var{file}.in}), substituting the output variable 2358values. 2359@c Before we used to have this feature, which was later rejected 2360@c because it complicates the writing of makefiles: 2361@c If the file would be unchanged, it is left untouched, to preserve 2362@c timestamp. 2363This macro is one of the instantiating macros; see @ref{Configuration 2364Actions}. @xref{Makefile Substitutions}, for more information on using 2365output variables. @xref{Setting Output Variables}, for more information 2366on creating them. This macro creates the directory that the file is in 2367if it doesn't exist. Usually, makefiles are created this way, 2368but other files, such as @file{.gdbinit}, can be specified as well. 2369 2370Typical calls to @code{AC_CONFIG_FILES} look like this: 2371 2372@example 2373AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile]) 2374AC_CONFIG_FILES([autoconf], [chmod +x autoconf]) 2375@end example 2376 2377You can override an input file name by appending to @var{file} a 2378colon-separated list of input files. Examples: 2379 2380@example 2381AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk] 2382 [lib/Makefile:boiler/lib.mk]) 2383@end example 2384 2385@noindent 2386Doing this allows you to keep your file names acceptable to 2387DOS variants, or 2388to prepend and/or append boilerplate to the file. 2389@end defmac 2390 2391 2392 2393@node Makefile Substitutions 2394@section Substitutions in Makefiles 2395@cindex Substitutions in makefiles 2396@cindex Makefile substitutions 2397 2398Each subdirectory in a distribution that contains something to be 2399compiled or installed should come with a file @file{Makefile.in}, from 2400which @command{configure} creates a file @file{Makefile} in that directory. 2401To create @file{Makefile}, @command{configure} performs a simple variable 2402substitution, replacing occurrences of @samp{@@@var{variable}@@} in 2403@file{Makefile.in} with the value that @command{configure} has determined 2404for that variable. Variables that are substituted into output files in 2405this way are called @dfn{output variables}. They are ordinary shell 2406variables that are set in @command{configure}. To make @command{configure} 2407substitute a particular variable into the output files, the macro 2408@code{AC_SUBST} must be called with that variable name as an argument. 2409Any occurrences of @samp{@@@var{variable}@@} for other variables are 2410left unchanged. @xref{Setting Output Variables}, for more information 2411on creating output variables with @code{AC_SUBST}. 2412 2413A software package that uses a @command{configure} script should be 2414distributed with a file @file{Makefile.in}, but no makefile; that 2415way, the user has to properly configure the package for the local system 2416before compiling it. 2417 2418@xref{Makefile Conventions, , Makefile Conventions, standards, The 2419GNU Coding Standards}, for more information on what to put in 2420makefiles. 2421 2422@menu 2423* Preset Output Variables:: Output variables that are always set 2424* Installation Directory Variables:: Other preset output variables 2425* Changed Directory Variables:: Warnings about @file{datarootdir} 2426* Build Directories:: Supporting multiple concurrent compiles 2427* Automatic Remaking:: Makefile rules for configuring 2428@end menu 2429 2430@node Preset Output Variables 2431@subsection Preset Output Variables 2432@cindex Output variables 2433 2434Some output variables are preset by the Autoconf macros. Some of the 2435Autoconf macros set additional output variables, which are mentioned in 2436the descriptions for those macros. @xref{Output Variable Index}, for a 2437complete list of output variables. @xref{Installation Directory 2438Variables}, for the list of the preset ones related to installation 2439directories. Below are listed the other preset ones, many of which are 2440precious variables (@pxref{Setting Output Variables}, 2441@code{AC_ARG_VAR}). 2442 2443The preset variables which are available during @file{config.status} 2444(@pxref{Configuration Actions}) may also be used during 2445@command{configure} tests. For example, it is permissible to reference 2446@samp{$srcdir} when constructing a list of directories to pass via 2447option @option{-I} during a compiler feature check. When used in this 2448manner, coupled with the fact that @command{configure} is always run 2449from the top build directory, it is sufficient to use just 2450@samp{$srcdir} instead of @samp{$top_srcdir}. 2451 2452@c Just say no to ASCII sorting! We're humans, not computers. 2453@c These variables are listed as they would be in a dictionary: 2454@c actor 2455@c Actress 2456@c actress 2457 2458@defvar CFLAGS 2459@evindex CFLAGS 2460@ovindex CFLAGS 2461Debugging and optimization options for the C compiler. If it is not set 2462in the environment when @command{configure} runs, the default value is set 2463when you call @code{AC_PROG_CC} (or empty if you don't). @command{configure} 2464uses this variable when compiling or linking programs to test for C features. 2465 2466If a compiler option affects only the behavior of the preprocessor 2467(e.g., @option{-D@var{name}}), it should be put into @code{CPPFLAGS} 2468instead. If it affects only the linker (e.g., @option{-L@var{directory}}), 2469it should be put into @code{LDFLAGS} instead. If it 2470affects only the compiler proper, @code{CFLAGS} is the natural home for 2471it. If an option affects multiple phases of the compiler, though, 2472matters get tricky. One approach to put such options directly into 2473@code{CC}, e.g., @code{CC='gcc -m64'}. Another is to put them into both 2474@code{CPPFLAGS} and @code{LDFLAGS}, but not into @code{CFLAGS}. 2475 2476However, remember that some @file{Makefile} variables are reserved by 2477the GNU Coding Standards for the use of the ``user''---the person 2478building the package. For instance, @code{CFLAGS} is one such variable. 2479 2480Sometimes package developers are tempted to set user variables such as 2481@code{CFLAGS} because it appears to make their job easier. However, the 2482package itself should never set a user variable, particularly not to 2483include switches that are required for proper compilation of the 2484package. Since these variables are documented as being for the package 2485builder, that person rightfully expects to be able to override any of 2486these variables at build time. If the package developer needs to add 2487switches without interfering with the user, the proper way to do that is 2488to introduce an additional variable. Automake makes this easy by 2489introducing @code{AM_CFLAGS} (@pxref{Flag Variables Ordering, , , 2490automake, GNU Automake}), but the concept is the same even if 2491Automake is not used. 2492@end defvar 2493 2494@defvar configure_input 2495@ovindex configure_input 2496A comment saying that the file was generated automatically by 2497@command{configure} and giving the name of the input file. 2498@code{AC_OUTPUT} adds a comment line containing this variable to the top 2499of every makefile it creates. For other files, you should 2500reference this variable in a comment at the top of each input file. For 2501example, an input shell script should begin like this: 2502 2503@example 2504#!/bin/sh 2505# @@configure_input@@ 2506@end example 2507 2508@noindent 2509The presence of that line also reminds people editing the file that it 2510needs to be processed by @command{configure} in order to be used. 2511@end defvar 2512 2513@defvar CPPFLAGS 2514@evindex CPPFLAGS 2515@ovindex CPPFLAGS 2516Preprocessor options for the C, C++, Objective C, and Objective C++ 2517preprocessors and compilers. If 2518it is not set in the environment when @command{configure} runs, the default 2519value is empty. @command{configure} uses this variable when preprocessing 2520or compiling programs to test for C, C++, Objective C, and Objective C++ 2521features. 2522 2523This variable's contents should contain options like @option{-I}, 2524@option{-D}, and @option{-U} that affect only the behavior of the 2525preprocessor. Please see the explanation of @code{CFLAGS} for what you 2526can do if an option affects other phases of the compiler as well. 2527 2528Currently, @command{configure} always links as part of a single 2529invocation of the compiler that also preprocesses and compiles, so it 2530uses this variable also when linking programs. However, it is unwise to 2531depend on this behavior because the GNU Coding Standards do 2532not require it and many packages do not use @code{CPPFLAGS} when linking 2533programs. 2534 2535@xref{Special Chars in Variables}, for limitations that @code{CPPFLAGS} 2536might run into. 2537@end defvar 2538 2539@defvar CXXFLAGS 2540@evindex CXXFLAGS 2541@ovindex CXXFLAGS 2542Debugging and optimization options for the C++ compiler. It acts like 2543@code{CFLAGS}, but for C++ instead of C. 2544@end defvar 2545 2546@defvar DEFS 2547@ovindex DEFS 2548@option{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADERS} 2549is called, @command{configure} replaces @samp{@@DEFS@@} with 2550@option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}). This 2551variable is not defined while @command{configure} is performing its tests, 2552only when creating the output files. @xref{Setting Output Variables}, for 2553how to check the results of previous tests. 2554@end defvar 2555 2556@defvar ECHO_C 2557@defvarx ECHO_N 2558@defvarx ECHO_T 2559@ovindex ECHO_C 2560@ovindex ECHO_N 2561@ovindex ECHO_T 2562How does one suppress the trailing newline from @command{echo} for 2563question-answer message pairs? These variables provide a way: 2564 2565@example 2566echo $ECHO_N "And the winner is... $ECHO_C" 2567sleep 100000000000 2568echo "$@{ECHO_T@}dead." 2569@end example 2570 2571@noindent 2572Some old and uncommon @command{echo} implementations offer no means to 2573achieve this, in which case @code{ECHO_T} is set to tab. You might not 2574want to use it. 2575@end defvar 2576 2577@defvar ERLCFLAGS 2578@evindex ERLCFLAGS 2579@ovindex ERLCFLAGS 2580Debugging and optimization options for the Erlang compiler. If it is not set 2581in the environment when @command{configure} runs, the default value is empty. 2582@command{configure} uses this variable when compiling 2583programs to test for Erlang features. 2584@end defvar 2585 2586@defvar FCFLAGS 2587@evindex FCFLAGS 2588@ovindex FCFLAGS 2589Debugging and optimization options for the Fortran compiler. If it 2590is not set in the environment when @command{configure} runs, the default 2591value is set when you call @code{AC_PROG_FC} (or empty if you don't). 2592@command{configure} uses this variable when compiling or linking 2593programs to test for Fortran features. 2594@end defvar 2595 2596@defvar FFLAGS 2597@evindex FFLAGS 2598@ovindex FFLAGS 2599Debugging and optimization options for the Fortran 77 compiler. If it 2600is not set in the environment when @command{configure} runs, the default 2601value is set when you call @code{AC_PROG_F77} (or empty if you don't). 2602@command{configure} uses this variable when compiling or linking 2603programs to test for Fortran 77 features. 2604@end defvar 2605 2606@defvar LDFLAGS 2607@evindex LDFLAGS 2608@ovindex LDFLAGS 2609Options for the linker. If it is not set 2610in the environment when @command{configure} runs, the default value is empty. 2611@command{configure} uses this variable when linking programs to test for 2612C, C++, Objective C, Objective C++, Fortran, and Go features. 2613 2614This variable's contents should contain options like @option{-s} and 2615@option{-L} that affect only the behavior of the linker. Please see the 2616explanation of @code{CFLAGS} for what you can do if an option also 2617affects other phases of the compiler. 2618 2619Don't use this variable to pass library names 2620(@option{-l}) to the linker; use @code{LIBS} instead. 2621@end defvar 2622 2623@defvar LIBS 2624@evindex LIBS 2625@ovindex LIBS 2626@option{-l} options to pass to the linker. The default value is empty, 2627but some Autoconf macros may prepend extra libraries to this variable if 2628those libraries are found and provide necessary functions, see 2629@ref{Libraries}. @command{configure} uses this variable when linking 2630programs to test for C, C++, Objective C, Objective C++, Fortran, and Go 2631features. 2632@end defvar 2633 2634@defvar OBJCFLAGS 2635@evindex OBJCFLAGS 2636@ovindex OBJCFLAGS 2637Debugging and optimization options for the Objective C compiler. It 2638acts like @code{CFLAGS}, but for Objective C instead of C. 2639@end defvar 2640 2641@defvar OBJCXXFLAGS 2642@evindex OBJCXXFLAGS 2643@ovindex OBJCXXFLAGS 2644Debugging and optimization options for the Objective C++ compiler. It 2645acts like @code{CXXFLAGS}, but for Objective C++ instead of C++. 2646@end defvar 2647 2648@defvar GOFLAGS 2649@evindex GOFLAGS 2650@ovindex GOFLAGS 2651Debugging and optimization options for the Go compiler. It acts like 2652@code{CFLAGS}, but for Go instead of C. 2653@end defvar 2654 2655@defvar builddir 2656@ovindex builddir 2657Rigorously equal to @samp{.}. Added for symmetry only. 2658@end defvar 2659 2660@defvar abs_builddir 2661@ovindex abs_builddir 2662Absolute name of @code{builddir}. 2663@end defvar 2664 2665@defvar top_builddir 2666@ovindex top_builddir 2667The relative name of the top level of the current build tree. In the 2668top-level directory, this is the same as @code{builddir}. 2669@end defvar 2670 2671@defvar top_build_prefix 2672@ovindex top_build_prefix 2673The relative name of the top level of the current build tree with final 2674slash if nonempty. This is the same as @code{top_builddir}, except that 2675it contains zero or more runs of @code{../}, so it should not be 2676appended with a slash for concatenation. This helps for @command{make} 2677implementations that otherwise do not treat @file{./file} and @file{file} 2678as equal in the toplevel build directory. 2679@end defvar 2680 2681@defvar abs_top_builddir 2682@ovindex abs_top_builddir 2683Absolute name of @code{top_builddir}. 2684@end defvar 2685 2686@defvar srcdir 2687@ovindex srcdir 2688The name of the directory that contains the source code for 2689that makefile. 2690@end defvar 2691 2692@defvar abs_srcdir 2693@ovindex abs_srcdir 2694Absolute name of @code{srcdir}. 2695@end defvar 2696 2697@defvar top_srcdir 2698@ovindex top_srcdir 2699The name of the top-level source code directory for the 2700package. In the top-level directory, this is the same as @code{srcdir}. 2701@end defvar 2702 2703@defvar abs_top_srcdir 2704@ovindex abs_top_srcdir 2705Absolute name of @code{top_srcdir}. 2706@end defvar 2707 2708@node Installation Directory Variables 2709@subsection Installation Directory Variables 2710@cindex Installation directories 2711@cindex Directories, installation 2712 2713The following variables specify the directories for 2714package installation, see @ref{Directory Variables, , Variables for 2715Installation Directories, standards, The GNU Coding 2716Standards}, for more information. Each variable corresponds to an 2717argument of @command{configure}; trailing slashes are stripped so that 2718expressions such as @samp{$@{prefix@}/lib} expand with only one slash 2719between directory names. See the end of this section for 2720details on when and how to use these variables. 2721 2722@defvar bindir 2723@ovindex bindir 2724The directory for installing executables that users run. 2725@end defvar 2726 2727@defvar datadir 2728@ovindex datadir 2729The directory for installing idiosyncratic read-only 2730architecture-independent data. 2731@end defvar 2732 2733@defvar datarootdir 2734@ovindex datarootdir 2735The root of the directory tree for read-only architecture-independent 2736data files. 2737@end defvar 2738 2739@defvar docdir 2740@ovindex docdir 2741The directory for installing documentation files (other than Info and 2742man). 2743@end defvar 2744 2745@defvar dvidir 2746@ovindex dvidir 2747The directory for installing documentation files in DVI format. 2748@end defvar 2749 2750@defvar exec_prefix 2751@ovindex exec_prefix 2752The installation prefix for architecture-dependent files. By default 2753it's the same as @code{prefix}. You should avoid installing anything 2754directly to @code{exec_prefix}. However, the default value for 2755directories containing architecture-dependent files should be relative 2756to @code{exec_prefix}. 2757@end defvar 2758 2759@defvar htmldir 2760@ovindex htmldir 2761The directory for installing HTML documentation. 2762@end defvar 2763 2764@defvar includedir 2765@ovindex includedir 2766The directory for installing C header files. 2767@end defvar 2768 2769@defvar infodir 2770@ovindex infodir 2771The directory for installing documentation in Info format. 2772@end defvar 2773 2774@defvar libdir 2775@ovindex libdir 2776The directory for installing object code libraries. 2777@end defvar 2778 2779@defvar libexecdir 2780@ovindex libexecdir 2781The directory for installing executables that other programs run. 2782@end defvar 2783 2784@defvar localedir 2785@ovindex localedir 2786The directory for installing locale-dependent but 2787architecture-independent data, such as message catalogs. This directory 2788usually has a subdirectory per locale. 2789@end defvar 2790 2791@defvar localstatedir 2792@ovindex localstatedir 2793The directory for installing modifiable single-machine data. 2794@end defvar 2795 2796@defvar mandir 2797@ovindex mandir 2798The top-level directory for installing documentation in man format. 2799@end defvar 2800 2801@defvar oldincludedir 2802@ovindex oldincludedir 2803The directory for installing C header files for non-GCC compilers. 2804@end defvar 2805 2806@defvar pdfdir 2807@ovindex pdfdir 2808The directory for installing PDF documentation. 2809@end defvar 2810 2811@defvar prefix 2812@ovindex prefix 2813The common installation prefix for all files. If @code{exec_prefix} 2814is defined to a different value, @code{prefix} is used only for 2815architecture-independent files. 2816@end defvar 2817 2818@defvar psdir 2819@ovindex psdir 2820The directory for installing PostScript documentation. 2821@end defvar 2822 2823@defvar sbindir 2824@ovindex sbindir 2825The directory for installing executables that system 2826administrators run. 2827@end defvar 2828 2829@defvar sharedstatedir 2830@ovindex sharedstatedir 2831The directory for installing modifiable architecture-independent data. 2832@end defvar 2833 2834@defvar sysconfdir 2835@ovindex sysconfdir 2836The directory for installing read-only single-machine data. 2837@end defvar 2838 2839 2840Most of these variables have values that rely on @code{prefix} or 2841@code{exec_prefix}. It is deliberate that the directory output 2842variables keep them unexpanded: typically @samp{@@datarootdir@@} is 2843replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}, and 2844@samp{@@datadir@@} is replaced by @samp{$@{datarootdir@}}. 2845 2846This behavior is mandated by the GNU Coding Standards, so that when 2847the user runs: 2848 2849@table @samp 2850@item make 2851she can still specify a different prefix from the one specified to 2852@command{configure}, in which case, if needed, the package should hard 2853code dependencies corresponding to the make-specified prefix. 2854 2855@item make install 2856she can specify a different installation location, in which case the 2857package @emph{must} still depend on the location which was compiled in 2858(i.e., never recompile when @samp{make install} is run). This is an 2859extremely important feature, as many people may decide to install all 2860the files of a package grouped together, and then install links from 2861the final locations to there. 2862@end table 2863 2864In order to support these features, it is essential that 2865@code{datarootdir} remains defined as @samp{$@{prefix@}/share}, 2866so that its value can be expanded based 2867on the current value of @code{prefix}. 2868 2869A corollary is that you should not use these variables except in 2870makefiles. For instance, instead of trying to evaluate @code{datadir} 2871in @file{configure} and hard-coding it in makefiles using 2872e.g., @samp{AC_DEFINE_UNQUOTED([DATADIR], ["$datadir"], [Data directory.])}, 2873you should add 2874@option{-DDATADIR='$(datadir)'} to your makefile's definition of 2875@code{CPPFLAGS} (@code{AM_CPPFLAGS} if you are also using Automake). 2876 2877Similarly, you should not rely on @code{AC_CONFIG_FILES} to replace 2878@code{bindir} and friends in your shell scripts and other files; instead, 2879let @command{make} manage their replacement. For instance Autoconf 2880ships templates of its shell scripts ending with @samp{.in}, and uses a 2881makefile snippet similar to the following to build scripts like 2882@command{autoheader} and @command{autom4te}: 2883 2884@example 2885@group 2886edit = sed \ 2887 -e 's|@@bindir[@@]|$(bindir)|g' \ 2888 -e 's|@@pkgdatadir[@@]|$(pkgdatadir)|g' \ 2889 -e 's|@@prefix[@@]|$(prefix)|g' 2890@end group 2891 2892@group 2893autoheader autom4te: Makefile 2894 rm -f $@@ $@@.tmp 2895 srcdir=''; \ 2896 test -f ./$@@.in || srcdir=$(srcdir)/; \ 2897 $(edit) $$@{srcdir@}$@@.in >$@@.tmp 2898@c $$ restore font-lock 2899 chmod +x $@@.tmp 2900 chmod a-w $@@.tmp 2901 mv $@@.tmp $@@ 2902@end group 2903 2904@group 2905autoheader: $(srcdir)/autoheader.in 2906autom4te: $(srcdir)/autom4te.in 2907@end group 2908@end example 2909 2910Some details are noteworthy: 2911 2912@table @asis 2913@item @samp{@@bindir[@@]} 2914The brackets prevent @command{configure} from replacing 2915@samp{@@bindir@@} in the Sed expression itself. 2916Brackets are preferable to a backslash here, since 2917Posix says @samp{\@@} is not portable. 2918 2919@item @samp{$(bindir)} 2920Don't use @samp{@@bindir@@}! Use the matching makefile variable 2921instead. 2922 2923@item @samp{$(pkgdatadir)} 2924The example takes advantage of the variable @samp{$(pkgdatadir)} 2925provided by Automake; it is equivalent to @samp{$(datadir)/$(PACKAGE)}. 2926 2927@item @samp{/} 2928Don't use @samp{/} in the Sed expressions that replace file names since 2929most likely the 2930variables you use, such as @samp{$(bindir)}, contain @samp{/}. 2931Use a shell metacharacter instead, such as @samp{|}. 2932 2933@item special characters 2934File names, file name components, and the value of @code{VPATH} should 2935not contain shell metacharacters or white 2936space. @xref{Special Chars in Variables}. 2937 2938@item dependency on @file{Makefile} 2939Since @code{edit} uses values that depend on the configuration specific 2940values (@code{prefix}, etc.)@: and not only on @code{VERSION} and so forth, 2941the output depends on @file{Makefile}, not @file{configure.ac}. 2942 2943@item @samp{$@@} 2944The main rule is generic, and uses @samp{$@@} extensively to 2945avoid the need for multiple copies of the rule. 2946 2947@item Separated dependencies and single suffix rules 2948You can't use them! The above snippet cannot be (portably) rewritten 2949as: 2950 2951@example 2952autoconf autoheader: Makefile 2953@group 2954.in: 2955 rm -f $@@ $@@.tmp 2956 $(edit) $< >$@@.tmp 2957 chmod +x $@@.tmp 2958 mv $@@.tmp $@@ 2959@end group 2960@end example 2961 2962@xref{Single Suffix Rules}, for details. 2963 2964@item @samp{$(srcdir)} 2965Be sure to specify the name of the source directory, 2966otherwise the package won't support separated builds. 2967@end table 2968 2969For the more specific installation of Erlang libraries, the following variables 2970are defined: 2971 2972@defvar ERLANG_INSTALL_LIB_DIR 2973@ovindex ERLANG_INSTALL_LIB_DIR 2974@acindex{ERLANG_SUBST_INSTALL_LIB_DIR} 2975The common parent directory of Erlang library installation directories. 2976This variable is set by calling the @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR} 2977macro in @file{configure.ac}. 2978@end defvar 2979 2980@defvar ERLANG_INSTALL_LIB_DIR_@var{library} 2981@ovindex ERLANG_INSTALL_LIB_DIR_@var{library} 2982@acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR} 2983The installation directory for Erlang library @var{library}. 2984This variable is set by using the 2985@samp{AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR} 2986macro in @file{configure.ac}. 2987@end defvar 2988 2989@xref{Erlang Libraries}, for details. 2990 2991 2992@node Changed Directory Variables 2993@subsection Changed Directory Variables 2994@cindex @file{datarootdir} 2995 2996In Autoconf 2.60, the set of directory variables has changed, and the 2997defaults of some variables have been adjusted 2998(@pxref{Installation Directory Variables}) to changes in the 2999GNU Coding Standards. Notably, @file{datadir}, @file{infodir}, and 3000@file{mandir} are now expressed in terms of @file{datarootdir}. If you are 3001upgrading from an earlier Autoconf version, you may need to adjust your files 3002to ensure that the directory variables are substituted correctly 3003(@pxref{Defining Directories}), and that a definition of @file{datarootdir} is 3004in place. For example, in a @file{Makefile.in}, adding 3005 3006@example 3007datarootdir = @@datarootdir@@ 3008@end example 3009 3010@noindent 3011is usually sufficient. If you use Automake to create @file{Makefile.in}, 3012it will add this for you. 3013 3014To help with the transition, Autoconf warns about files that seem to use 3015@code{datarootdir} without defining it. In some cases, it then expands 3016the value of @code{$datarootdir} in substitutions of the directory 3017variables. The following example shows such a warning: 3018 3019@example 3020$ @kbd{cat configure.ac} 3021AC_INIT 3022AC_CONFIG_FILES([Makefile]) 3023AC_OUTPUT 3024$ @kbd{cat Makefile.in} 3025prefix = @@prefix@@ 3026datadir = @@datadir@@ 3027$ @kbd{autoconf} 3028$ @kbd{configure} 3029configure: creating ./config.status 3030config.status: creating Makefile 3031config.status: WARNING: 3032 Makefile.in seems to ignore the --datarootdir setting 3033$ @kbd{cat Makefile} 3034prefix = /usr/local 3035datadir = $@{prefix@}/share 3036@end example 3037 3038Usually one can easily change the file to accommodate both older and newer 3039Autoconf releases: 3040 3041@example 3042$ @kbd{cat Makefile.in} 3043prefix = @@prefix@@ 3044datarootdir = @@datarootdir@@ 3045datadir = @@datadir@@ 3046$ @kbd{configure} 3047configure: creating ./config.status 3048config.status: creating Makefile 3049$ @kbd{cat Makefile} 3050prefix = /usr/local 3051datarootdir = $@{prefix@}/share 3052datadir = $@{datarootdir@} 3053@end example 3054 3055@acindex{DATAROOTDIR_CHECKED} 3056In some cases, however, the checks may not be able to detect that a suitable 3057initialization of @code{datarootdir} is in place, or they may fail to detect 3058that such an initialization is necessary in the output file. If, after 3059auditing your package, there are still spurious @file{configure} warnings about 3060@code{datarootdir}, you may add the line 3061 3062@example 3063AC_DEFUN([AC_DATAROOTDIR_CHECKED]) 3064@end example 3065 3066@noindent 3067to your @file{configure.ac} to disable the warnings. This is an exception 3068to the usual rule that you should not define a macro whose name begins with 3069@code{AC_} (@pxref{Macro Names}). 3070 3071 3072 3073@node Build Directories 3074@subsection Build Directories 3075@cindex Build directories 3076@cindex Directories, build 3077 3078You can support compiling a software package for several architectures 3079simultaneously from the same copy of the source code. The object files 3080for each architecture are kept in their own directory. 3081 3082To support doing this, @command{make} uses the @code{VPATH} variable to 3083find the files that are in the source directory. GNU Make 3084can do this. Most other recent @command{make} programs can do this as 3085well, though they may have difficulties and it is often simpler to 3086recommend GNU @command{make} (@pxref{VPATH and Make}). Older 3087@command{make} programs do not support @code{VPATH}; when using them, the 3088source code must be in the same directory as the object files. 3089 3090If you are using GNU Automake, the remaining details in this 3091section are already covered for you, based on the contents of your 3092@file{Makefile.am}. But if you are using Autoconf in isolation, then 3093supporting @code{VPATH} requires the following in your 3094@file{Makefile.in}: 3095 3096@example 3097srcdir = @@srcdir@@ 3098VPATH = @@srcdir@@ 3099@end example 3100 3101Do not set @code{VPATH} to the value of another variable (@pxref{Variables 3102listed in VPATH}. 3103 3104@command{configure} substitutes the correct value for @code{srcdir} when 3105it produces @file{Makefile}. 3106 3107Do not use the @command{make} variable @code{$<}, which expands to the 3108file name of the file in the source directory (found with @code{VPATH}), 3109except in implicit rules. (An implicit rule is one such as @samp{.c.o}, 3110which tells how to create a @file{.o} file from a @file{.c} file.) Some 3111versions of @command{make} do not set @code{$<} in explicit rules; they 3112expand it to an empty value. 3113 3114Instead, Make command lines should always refer to source 3115files by prefixing them with @samp{$(srcdir)/}. For example: 3116 3117@example 3118time.info: time.texinfo 3119 $(MAKEINFO) '$(srcdir)/time.texinfo' 3120@end example 3121 3122@node Automatic Remaking 3123@subsection Automatic Remaking 3124@cindex Automatic remaking 3125@cindex Remaking automatically 3126 3127You can put rules like the following in the top-level @file{Makefile.in} 3128for a package to automatically update the configuration information when 3129you change the configuration files. This example includes all of the 3130optional files, such as @file{aclocal.m4} and those related to 3131configuration header files. Omit from the @file{Makefile.in} rules for 3132any of these files that your package does not use. 3133 3134The @samp{$(srcdir)/} prefix is included because of limitations in the 3135@code{VPATH} mechanism. 3136 3137The @file{stamp-} files are necessary because the timestamps of 3138@file{config.h.in} and @file{config.h} are not changed if remaking 3139them does not change their contents. This feature avoids unnecessary 3140recompilation. You should include the file @file{stamp-h.in} in your 3141package's distribution, so that @command{make} considers 3142@file{config.h.in} up to date. Don't use @command{touch} 3143(@pxref{touch, , Limitations of Usual Tools}); instead, use 3144@command{echo} (using 3145@command{date} would cause needless differences, hence CVS 3146conflicts, etc.). 3147 3148@example 3149@group 3150$(srcdir)/configure: configure.ac aclocal.m4 3151 cd '$(srcdir)' && autoconf 3152 3153# autoheader might not change config.h.in, so touch a stamp file. 3154$(srcdir)/config.h.in: stamp-h.in 3155$(srcdir)/stamp-h.in: configure.ac aclocal.m4 3156 cd '$(srcdir)' && autoheader 3157 echo timestamp > '$(srcdir)/stamp-h.in' 3158 3159config.h: stamp-h 3160stamp-h: config.h.in config.status 3161 ./config.status 3162 3163Makefile: Makefile.in config.status 3164 ./config.status 3165 3166config.status: configure 3167 ./config.status --recheck 3168@end group 3169@end example 3170 3171@noindent 3172(Be careful if you copy these lines directly into your makefile, as you 3173need to convert the indented lines to start with the tab character.) 3174 3175In addition, you should use 3176 3177@example 3178AC_CONFIG_FILES([stamp-h], [echo timestamp > stamp-h]) 3179@end example 3180 3181@noindent 3182so @file{config.status} ensures that @file{config.h} is considered up to 3183date. @xref{Output}, for more information about @code{AC_OUTPUT}. 3184 3185@xref{config.status Invocation}, for more examples of handling 3186configuration-related dependencies. 3187 3188@node Configuration Headers 3189@section Configuration Header Files 3190@cindex Configuration Header 3191@cindex @file{config.h} 3192 3193When a package contains more than a few tests that define C preprocessor 3194symbols, the command lines to pass @option{-D} options to the compiler 3195can get quite long. This causes two problems. One is that the 3196@command{make} output is hard to visually scan for errors. More 3197seriously, the command lines can exceed the length limits of some 3198operating systems. As an alternative to passing @option{-D} options to 3199the compiler, @command{configure} scripts can create a C header file 3200containing @samp{#define} directives. The @code{AC_CONFIG_HEADERS} 3201macro selects this kind of output. Though it can be called anywhere 3202between @code{AC_INIT} and @code{AC_OUTPUT}, it is customary to call 3203it right after @code{AC_INIT}. 3204 3205The package should @samp{#include} the configuration header file before 3206any other header files, to prevent inconsistencies in declarations (for 3207example, if it redefines @code{const}). 3208 3209To provide for VPATH builds, remember to pass the C compiler a @option{-I.} 3210option (or @option{-I..}; whichever directory contains @file{config.h}). 3211Even if you use @samp{#include "config.h"}, the preprocessor searches only 3212the directory of the currently read file, i.e., the source directory, not 3213the build directory. 3214 3215With the appropriate @option{-I} option, you can use 3216@samp{#include <config.h>}. Actually, it's a good habit to use it, 3217because in the rare case when the source directory contains another 3218@file{config.h}, the build directory should be searched first. 3219 3220 3221@defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds}) 3222@acindex{CONFIG_HEADERS} 3223@cvindex HAVE_CONFIG_H 3224This macro is one of the instantiating macros; see @ref{Configuration 3225Actions}. Make @code{AC_OUTPUT} create the file(s) in the 3226blank-or-newline-separated list @var{header} containing C preprocessor 3227@code{#define} statements, and replace @samp{@@DEFS@@} in generated 3228files with @option{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}. 3229The usual name for @var{header} is @file{config.h}. 3230 3231If @var{header} already exists and its contents are identical to what 3232@code{AC_OUTPUT} would put in it, it is left alone. Doing this allows 3233making some changes in the configuration without needlessly causing 3234object files that depend on the header file to be recompiled. 3235 3236Usually the input file is named @file{@var{header}.in}; however, you can 3237override the input file name by appending to @var{header} a 3238colon-separated list of input files. For example, you might need to make 3239the input file name acceptable to DOS variants: 3240 3241@example 3242AC_CONFIG_HEADERS([config.h:config.hin]) 3243@end example 3244 3245@end defmac 3246 3247@defmac AH_HEADER 3248@ahindex{HEADER} 3249This macro is defined as the name of the first declared config header 3250and undefined if no config headers have been declared up to this point. 3251A third-party macro may, for example, require use of a config header 3252without invoking AC_CONFIG_HEADERS twice, like this: 3253 3254@example 3255AC_CONFIG_COMMANDS_PRE( 3256 [m4_ifndef([AH_HEADER], [AC_CONFIG_HEADERS([config.h])])]) 3257@end example 3258 3259@end defmac 3260 3261@xref{Configuration Actions}, for more details on @var{header}. 3262 3263@menu 3264* Header Templates:: Input for the configuration headers 3265* autoheader Invocation:: How to create configuration templates 3266* Autoheader Macros:: How to specify CPP templates 3267@end menu 3268 3269@node Header Templates 3270@subsection Configuration Header Templates 3271@cindex Configuration Header Template 3272@cindex Header templates 3273@cindex @file{config.h.in} 3274 3275Your distribution should contain a template file that looks as you want 3276the final header file to look, including comments, with @code{#undef} 3277statements which are used as hooks. For example, suppose your 3278@file{configure.ac} makes these calls: 3279 3280@example 3281AC_CONFIG_HEADERS([conf.h]) 3282AC_CHECK_HEADERS([unistd.h]) 3283@end example 3284 3285@noindent 3286Then you could have code like the following in @file{conf.h.in}. 3287The @file{conf.h} created by @command{configure} defines @samp{HAVE_UNISTD_H} 3288to 1, if and only if the system has @file{unistd.h}. 3289 3290@example 3291@group 3292/* Define as 1 if you have unistd.h. */ 3293#undef HAVE_UNISTD_H 3294@end group 3295@end example 3296 3297The format of the template file is stricter than what the C preprocessor 3298is required to accept. A directive line should contain only whitespace, 3299@samp{#undef}, and @samp{HAVE_UNISTD_H}. The use of @samp{#define} 3300instead of @samp{#undef}, or of comments on the same line as 3301@samp{#undef}, is strongly discouraged. Each hook should only be listed 3302once. Other preprocessor lines, such as @samp{#ifdef} or 3303@samp{#include}, are copied verbatim from the template into the 3304generated header. 3305 3306Since it is a tedious task to keep a template header up to date, you may 3307use @command{autoheader} to generate it, see @ref{autoheader Invocation}. 3308 3309During the instantiation of the header, each @samp{#undef} line in the 3310template file for each symbol defined by @samp{AC_DEFINE} is changed to an 3311appropriate @samp{#define}. If the corresponding @samp{AC_DEFINE} has not 3312been executed during the @command{configure} run, the @samp{#undef} line is 3313commented out. (This is important, e.g., for @samp{_POSIX_SOURCE}: 3314on many systems, it can be implicitly defined by the compiler, and 3315undefining it in the header would then break compilation of subsequent 3316headers.) 3317 3318Currently, @emph{all} remaining @samp{#undef} lines in the header 3319template are commented out, whether or not there was a corresponding 3320@samp{AC_DEFINE} for the macro name; but this behavior is not guaranteed 3321for future releases of Autoconf. 3322 3323Generally speaking, since you should not use @samp{#define}, and you 3324cannot guarantee whether a @samp{#undef} directive in the header 3325template will be converted to a @samp{#define} or commented out in the 3326generated header file, the template file cannot be used for conditional 3327definition effects. Consequently, if you need to use the construct 3328 3329@example 3330@group 3331#ifdef THIS 3332# define THAT 3333#endif 3334@end group 3335@end example 3336 3337@noindent 3338you must place it outside of the template. 3339If you absolutely need to hook it to the config header itself, please put 3340the directives to a separate file, and @samp{#include} that file from the 3341config header template. If you are using @command{autoheader}, you would 3342probably use @samp{AH_BOTTOM} to append the @samp{#include} directive. 3343 3344 3345@node autoheader Invocation 3346@subsection Using @command{autoheader} to Create @file{config.h.in} 3347@cindex @command{autoheader} 3348 3349The @command{autoheader} program can create a template file of C 3350@samp{#define} statements for @command{configure} to use. 3351It searches for the first invocation of @code{AC_CONFIG_HEADERS} in 3352@file{configure} sources to determine the name of the template. 3353(If the first call of @code{AC_CONFIG_HEADERS} specifies more than one 3354input file name, @command{autoheader} uses the first one.) 3355 3356It is recommended that only one input file is used. If you want to append 3357a boilerplate code, it is preferable to use 3358@samp{AH_BOTTOM([#include <conf_post.h>])}. 3359File @file{conf_post.h} is not processed during the configuration then, 3360which make things clearer. Analogically, @code{AH_TOP} can be used to 3361prepend a boilerplate code. 3362 3363In order to do its job, @command{autoheader} needs you to document all 3364of the symbols that you might use. Typically this is done via an 3365@code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED} call whose first argument 3366is a literal symbol and whose third argument describes the symbol 3367(@pxref{Defining Symbols}). Alternatively, you can use 3368@code{AH_TEMPLATE} (@pxref{Autoheader Macros}), or you can supply a 3369suitable input file for a subsequent configuration header file. 3370Symbols defined by Autoconf's builtin tests are already documented properly; 3371you need to document only those that you 3372define yourself. 3373 3374You might wonder why @command{autoheader} is needed: after all, why 3375would @command{configure} need to ``patch'' a @file{config.h.in} to 3376produce a @file{config.h} instead of just creating @file{config.h} from 3377scratch? Well, when everything rocks, the answer is just that we are 3378wasting our time maintaining @command{autoheader}: generating 3379@file{config.h} directly is all that is needed. When things go wrong, 3380however, you'll be thankful for the existence of @command{autoheader}. 3381 3382The fact that the symbols are documented is important in order to 3383@emph{check} that @file{config.h} makes sense. The fact that there is a 3384well-defined list of symbols that should be defined (or not) is 3385also important for people who are porting packages to environments where 3386@command{configure} cannot be run: they just have to @emph{fill in the 3387blanks}. 3388 3389But let's come back to the point: the invocation of @command{autoheader}@dots{} 3390 3391If you give @command{autoheader} an argument, it uses that file instead 3392of @file{configure.ac} and writes the header file to the standard output 3393instead of to @file{config.h.in}. If you give @command{autoheader} an 3394argument of @option{-}, it reads the standard input instead of 3395@file{configure.ac} and writes the header file to the standard output. 3396 3397@command{autoheader} accepts the following options: 3398 3399@table @option 3400@item --help 3401@itemx -h 3402Print a summary of the command line options and exit. 3403 3404@item --version 3405@itemx -V 3406Print the version number of Autoconf and exit. 3407 3408@item --verbose 3409@itemx -v 3410Report processing steps. 3411 3412@item --debug 3413@itemx -d 3414Don't remove the temporary files. 3415 3416@item --force 3417@itemx -f 3418Remake the template file even if newer than its input files. 3419 3420@item --include=@var{dir} 3421@itemx -I @var{dir} 3422Append @var{dir} to the include path. Multiple invocations accumulate. 3423 3424@item --prepend-include=@var{dir} 3425@itemx -B @var{dir} 3426Prepend @var{dir} to the include path. Multiple invocations accumulate. 3427 3428@item --warnings=@var{category} 3429@itemx -W @var{category} 3430@evindex WARNINGS 3431Report the warnings related to @var{category} (which can actually be a 3432comma separated list). Current categories include: 3433 3434@table @samp 3435@item obsolete 3436report the uses of obsolete constructs 3437 3438@item all 3439report all the warnings 3440 3441@item none 3442report none 3443 3444@item error 3445treats warnings as errors 3446 3447@item no-@var{category} 3448disable warnings falling into @var{category} 3449@end table 3450 3451@end table 3452 3453 3454 3455@node Autoheader Macros 3456@subsection Autoheader Macros 3457@cindex Autoheader macros 3458 3459@command{autoheader} scans @file{configure.ac} and figures out which C 3460preprocessor symbols it might define. It knows how to generate 3461templates for symbols defined by @code{AC_CHECK_HEADERS}, 3462@code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional 3463symbol, you must define a template for it. If there are missing 3464templates, @command{autoheader} fails with an error message. 3465 3466The template for a @var{symbol} is created 3467by @command{autoheader} from 3468the @var{description} argument to an @code{AC_DEFINE}; 3469see @ref{Defining Symbols}. 3470 3471For special needs, you can use the following macros. 3472 3473 3474@defmac AH_TEMPLATE (@var{key}, @var{description}) 3475@ahindex{TEMPLATE} 3476Tell @command{autoheader} to generate a template for @var{key}. This macro 3477generates standard templates just like @code{AC_DEFINE} when a 3478@var{description} is given. 3479 3480For example: 3481 3482@example 3483AH_TEMPLATE([CRAY_STACKSEG_END], 3484 [Define to one of _getb67, GETB67, getb67 3485 for Cray-2 and Cray-YMP systems. This 3486 function is required for alloca.c support 3487 on those systems.]) 3488@end example 3489 3490@noindent 3491generates the following template, with the description properly 3492justified. 3493 3494@example 3495/* Define to one of _getb67, GETB67, getb67 for Cray-2 and 3496 Cray-YMP systems. This function is required for alloca.c 3497 support on those systems. */ 3498#undef CRAY_STACKSEG_END 3499@end example 3500@end defmac 3501 3502 3503@defmac AH_VERBATIM (@var{key}, @var{template}) 3504@ahindex{VERBATIM} 3505Tell @command{autoheader} to include the @var{template} as-is in the header 3506template file. This @var{template} is associated with the @var{key}, 3507which is used to sort all the different templates and guarantee their 3508uniqueness. It should be a symbol that can be defined via @code{AC_DEFINE}. 3509@end defmac 3510 3511 3512@defmac AH_TOP (@var{text}) 3513@ahindex{TOP} 3514Include @var{text} at the top of the header template file. 3515@end defmac 3516 3517 3518@defmac AH_BOTTOM (@var{text}) 3519@ahindex{BOTTOM} 3520Include @var{text} at the bottom of the header template file. 3521@end defmac 3522 3523 3524Please note that @var{text} gets included ``verbatim'' to the template file, 3525not to the resulting config header, so it can easily get mangled when the 3526template is processed. There is rarely a need for something other than 3527 3528@example 3529AH_BOTTOM([#include <custom.h>]) 3530@end example 3531 3532 3533 3534@node Configuration Commands 3535@section Running Arbitrary Configuration Commands 3536@cindex Configuration commands 3537@cindex Commands for configuration 3538 3539You can execute arbitrary commands before, during, and after 3540@file{config.status} is run. The three following macros accumulate the 3541commands to run when they are called multiple times. 3542@code{AC_CONFIG_COMMANDS} replaces the obsolete macro 3543@code{AC_OUTPUT_COMMANDS}; see @ref{Obsolete Macros}, for details. 3544 3545@anchor{AC_CONFIG_COMMANDS} 3546@defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds}) 3547@acindex{CONFIG_COMMANDS} 3548Specify additional shell commands to run at the end of 3549@file{config.status}, and shell commands to initialize any variables 3550from @command{configure}. Associate the commands with @var{tag}. 3551Since typically the @var{cmds} create a file, @var{tag} should 3552naturally be the name of that file. If needed, the directory hosting 3553@var{tag} is created. This macro is one of the instantiating macros; 3554see @ref{Configuration Actions}. 3555 3556Here is an unrealistic example: 3557@example 3558fubar=42 3559AC_CONFIG_COMMANDS([fubar], 3560 [echo this is extra $fubar, and so on.], 3561 [fubar=$fubar]) 3562@end example 3563 3564Here is a better one: 3565@example 3566AC_CONFIG_COMMANDS([timestamp], [date >timestamp]) 3567@end example 3568@end defmac 3569 3570The following two macros look similar, but in fact they are not of the same 3571breed: they are executed directly by @file{configure}, so you cannot use 3572@file{config.status} to rerun them. 3573 3574@c Yet it is good to leave them here. The user sees them together and 3575@c decides which best fits their needs. 3576 3577@defmac AC_CONFIG_COMMANDS_PRE (@var{cmds}) 3578@acindex{CONFIG_COMMANDS_PRE} 3579Execute the @var{cmds} right before creating @file{config.status}. 3580 3581This macro presents the last opportunity to call @code{AC_SUBST}, 3582@code{AC_DEFINE}, or @code{AC_CONFIG_@var{ITEMS}} macros. 3583@end defmac 3584 3585@defmac AC_CONFIG_COMMANDS_POST (@var{cmds}) 3586@acindex{CONFIG_COMMANDS_POST} 3587Execute the @var{cmds} right after creating @file{config.status}. 3588@end defmac 3589 3590 3591 3592 3593@node Configuration Links 3594@section Creating Configuration Links 3595@cindex Configuration links 3596@cindex Links for configuration 3597 3598You may find it convenient to create links whose destinations depend upon 3599results of tests. One can use @code{AC_CONFIG_COMMANDS} but the 3600creation of relative symbolic links can be delicate when the package is 3601built in a directory different from the source directory. 3602 3603@anchor{AC_CONFIG_LINKS} 3604@defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @ 3605 @ovar{init-cmds}) 3606@acindex{CONFIG_LINKS} 3607@cindex Links 3608Make @code{AC_OUTPUT} link each of the existing files @var{source} to 3609the corresponding link name @var{dest}. Makes a symbolic link if 3610possible, otherwise a hard link if possible, otherwise a copy. The 3611@var{dest} and @var{source} names should be relative to the top level 3612source or build directory. This macro is one of the instantiating 3613macros; see @ref{Configuration Actions}. 3614 3615For example, this call: 3616 3617@example 3618AC_CONFIG_LINKS([host.h:config/$machine.h 3619 object.h:config/$obj_format.h]) 3620@end example 3621 3622@noindent 3623creates in the current directory @file{host.h} as a link to 3624@file{@var{srcdir}/config/$machine.h}, and @file{object.h} as a 3625link to @file{@var{srcdir}/config/$obj_format.h}. 3626 3627The tempting value @samp{.} for @var{dest} is invalid: it makes it 3628impossible for @samp{config.status} to guess the links to establish. 3629 3630One can then run: 3631@example 3632./config.status host.h object.h 3633@end example 3634@noindent 3635to create the links. 3636@end defmac 3637 3638 3639 3640@node Subdirectories 3641@section Configuring Other Packages in Subdirectories 3642@cindex Configure subdirectories 3643@cindex Subdirectory configure 3644 3645In most situations, calling @code{AC_OUTPUT} is sufficient to produce 3646makefiles in subdirectories. However, @command{configure} scripts 3647that control more than one independent package can use 3648@code{AC_CONFIG_SUBDIRS} to run @command{configure} scripts for other 3649packages in subdirectories. 3650 3651@defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{}) 3652@acindex{CONFIG_SUBDIRS} 3653@ovindex subdirs 3654Make @code{AC_OUTPUT} run @command{configure} in each subdirectory 3655@var{dir} in the given blank-or-newline-separated list. Each @var{dir} should 3656be a literal, i.e., please do not use: 3657 3658@example 3659@c If you change this example, adjust tests/torture.at:Non-literal AC_CONFIG_SUBDIRS. 3660if test "x$package_foo_enabled" = xyes; then 3661 my_subdirs="$my_subdirs foo" 3662fi 3663AC_CONFIG_SUBDIRS([$my_subdirs]) 3664@end example 3665 3666@noindent 3667because this prevents @samp{./configure --help=recursive} from 3668displaying the options of the package @code{foo}. Instead, you should 3669write: 3670 3671@example 3672if test "x$package_foo_enabled" = xyes; then 3673 AC_CONFIG_SUBDIRS([foo]) 3674fi 3675@end example 3676 3677If a given @var{dir} is not found at @command{configure} run time, a 3678warning is reported; if the subdirectory is optional, write: 3679 3680@example 3681if test -d "$srcdir/foo"; then 3682 AC_CONFIG_SUBDIRS([foo]) 3683fi 3684@end example 3685 3686@c NB: Yes, below we mean configure.in, not configure.ac. 3687If a given @var{dir} contains @command{configure.gnu}, it is run instead 3688of @command{configure}. This is for packages that might use a 3689non-Autoconf script @command{Configure}, which can't be called through a 3690wrapper @command{configure} since it would be the same file on 3691case-insensitive file systems. Likewise, if a @var{dir} contains 3692@file{configure.in} but no @command{configure}, the Cygnus 3693@command{configure} script found by @code{AC_CONFIG_AUX_DIR} is used. 3694 3695The subdirectory @command{configure} scripts are given the same command 3696line options that were given to this @command{configure} script, with minor 3697changes if needed, which include: 3698 3699@itemize @minus 3700@item 3701adjusting a relative name for the cache file; 3702 3703@item 3704adjusting a relative name for the source directory; 3705 3706@item 3707propagating the current value of @code{$prefix}, including if it was 3708defaulted, and if the default values of the top level and of the subdirectory 3709@file{configure} differ. 3710@end itemize 3711 3712This macro also sets the output variable @code{subdirs} to the list of 3713directories @samp{@var{dir} @dots{}}. Make rules can use 3714this variable to determine which subdirectories to recurse into. 3715 3716This macro may be called multiple times. 3717@end defmac 3718 3719@node Default Prefix 3720@section Default Prefix 3721@cindex Install prefix 3722@cindex Prefix for install 3723 3724By default, @command{configure} sets the prefix for files it installs to 3725@file{/usr/local}. The user of @command{configure} can select a different 3726prefix using the @option{--prefix} and @option{--exec-prefix} options. 3727There are two ways to change the default: when creating 3728@command{configure}, and when running it. 3729 3730Some software packages might want to install in a directory other than 3731@file{/usr/local} by default. To accomplish that, use the 3732@code{AC_PREFIX_DEFAULT} macro. 3733 3734@defmac AC_PREFIX_DEFAULT (@var{prefix}) 3735@acindex{PREFIX_DEFAULT} 3736Set the default installation prefix to @var{prefix} instead of 3737@file{/usr/local}. 3738@end defmac 3739 3740It may be convenient for users to have @command{configure} guess the 3741installation prefix from the location of a related program that they 3742have already installed. If you wish to do that, you can call 3743@code{AC_PREFIX_PROGRAM}. 3744 3745@anchor{AC_PREFIX_PROGRAM} 3746@defmac AC_PREFIX_PROGRAM (@var{program}) 3747@acindex{PREFIX_PROGRAM} 3748If the user did not specify an installation prefix (using the 3749@option{--prefix} option), guess a value for it by looking for 3750@var{program} in @env{PATH}, the way the shell does. If @var{program} 3751is found, set the prefix to the parent of the directory containing 3752@var{program}, else default the prefix as described above 3753(@file{/usr/local} or @code{AC_PREFIX_DEFAULT}). For example, if 3754@var{program} is @code{gcc} and the @env{PATH} contains 3755@file{/usr/local/gnu/bin/gcc}, set the prefix to @file{/usr/local/gnu}. 3756@end defmac 3757 3758 3759 3760@c ======================================================== Existing tests 3761 3762@node Existing Tests 3763@chapter Existing Tests 3764 3765These macros test for particular system features that packages might 3766need or want to use. If you need to test for a kind of feature that 3767none of these macros check for, you can probably do it by calling 3768primitive test macros with appropriate arguments (@pxref{Writing 3769Tests}). 3770 3771These tests print messages telling the user which feature they're 3772checking for, and what they find. They cache their results for future 3773@command{configure} runs (@pxref{Caching Results}). 3774 3775Some of these macros set output variables. @xref{Makefile 3776Substitutions}, for how to get their values. The phrase ``define 3777@var{name}'' is used below as a shorthand to mean ``define the C 3778preprocessor symbol @var{name} to the value 1''. @xref{Defining 3779Symbols}, for how to get those symbol definitions into your program. 3780 3781@menu 3782* Common Behavior:: Macros' standard schemes 3783* Alternative Programs:: Selecting between alternative programs 3784* Files:: Checking for the existence of files 3785* Libraries:: Library archives that might be missing 3786* Library Functions:: C library functions that might be missing 3787* Header Files:: Header files that might be missing 3788* Declarations:: Declarations that may be missing 3789* Structures:: Structures or members that might be missing 3790* Types:: Types that might be missing 3791* Compilers and Preprocessors:: Checking for compiling programs 3792* System Services:: Operating system services 3793* Posix Variants:: Special kludges for specific Posix variants 3794* Erlang Libraries:: Checking for the existence of Erlang libraries 3795@end menu 3796 3797@node Common Behavior 3798@section Common Behavior 3799@cindex Common autoconf behavior 3800 3801Much effort has been expended to make Autoconf easy to learn. The most 3802obvious way to reach this goal is simply to enforce standard interfaces 3803and behaviors, avoiding exceptions as much as possible. Because of 3804history and inertia, unfortunately, there are still too many exceptions 3805in Autoconf; nevertheless, this section describes some of the common 3806rules. 3807 3808@menu 3809* Standard Symbols:: Symbols defined by the macros 3810* Default Includes:: Includes used by the generic macros 3811@end menu 3812 3813@node Standard Symbols 3814@subsection Standard Symbols 3815@cindex Standard symbols 3816 3817All the generic macros that @code{AC_DEFINE} a symbol as a result of 3818their test transform their @var{argument} values to a standard alphabet. 3819First, @var{argument} is converted to upper case and any asterisks 3820(@samp{*}) are each converted to @samp{P}. Any remaining characters 3821that are not alphanumeric are converted to underscores. 3822 3823For instance, 3824 3825@example 3826AC_CHECK_TYPES([struct $Expensive*]) 3827@end example 3828 3829@noindent 3830defines the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check 3831succeeds. 3832 3833 3834@node Default Includes 3835@subsection Default Includes 3836@cindex Default includes 3837@cindex Includes, default 3838 3839Several tests depend upon a set of header files. Since these headers 3840are not universally available, tests actually have to provide a set of 3841protected includes, such as: 3842 3843@example 3844@group 3845#ifdef TIME_WITH_SYS_TIME 3846# include <sys/time.h> 3847# include <time.h> 3848#else 3849# ifdef HAVE_SYS_TIME_H 3850# include <sys/time.h> 3851# else 3852# include <time.h> 3853# endif 3854#endif 3855@end group 3856@end example 3857 3858@noindent 3859Unless you know exactly what you are doing, you should avoid using 3860unconditional includes, and check the existence of the headers you 3861include beforehand (@pxref{Header Files}). 3862 3863Most generic macros use the following macro to provide the default set 3864of includes: 3865 3866@defmac AC_INCLUDES_DEFAULT (@ovar{include-directives}) 3867@acindex{INCLUDES_DEFAULT} 3868Expand to @var{include-directives} if defined, otherwise to: 3869 3870@example 3871@group 3872#include <stdio.h> 3873#ifdef HAVE_SYS_TYPES_H 3874# include <sys/types.h> 3875#endif 3876#ifdef HAVE_SYS_STAT_H 3877# include <sys/stat.h> 3878#endif 3879#ifdef STDC_HEADERS 3880# include <stdlib.h> 3881# include <stddef.h> 3882#else 3883# ifdef HAVE_STDLIB_H 3884# include <stdlib.h> 3885# endif 3886#endif 3887#ifdef HAVE_STRING_H 3888# if !defined STDC_HEADERS && defined HAVE_MEMORY_H 3889# include <memory.h> 3890# endif 3891# include <string.h> 3892#endif 3893#ifdef HAVE_STRINGS_H 3894# include <strings.h> 3895#endif 3896#ifdef HAVE_INTTYPES_H 3897# include <inttypes.h> 3898#endif 3899#ifdef HAVE_STDINT_H 3900# include <stdint.h> 3901#endif 3902#ifdef HAVE_UNISTD_H 3903# include <unistd.h> 3904#endif 3905@end group 3906@end example 3907 3908If the default includes are used, then check for the presence of these 3909headers and their compatibility, i.e., you don't need to run 3910@code{AC_HEADER_STDC}, nor check for @file{stdlib.h} etc. 3911 3912These headers are checked for in the same order as they are included. 3913For instance, on some systems @file{string.h} and @file{strings.h} both 3914exist, but conflict. Then @code{HAVE_STRING_H} is defined, not 3915@code{HAVE_STRINGS_H}. 3916@end defmac 3917 3918@node Alternative Programs 3919@section Alternative Programs 3920@cindex Programs, checking 3921 3922These macros check for the presence or behavior of particular programs. 3923They are used to choose between several alternative programs and to 3924decide what to do once one has been chosen. If there is no macro 3925specifically defined to check for a program you need, and you don't need 3926to check for any special properties of it, then you can use one of the 3927general program-check macros. 3928 3929@menu 3930* Particular Programs:: Special handling to find certain programs 3931* Generic Programs:: How to find other programs 3932@end menu 3933 3934@node Particular Programs 3935@subsection Particular Program Checks 3936 3937These macros check for particular programs---whether they exist, and 3938in some cases whether they support certain features. 3939 3940@defmac AC_PROG_AWK 3941@acindex{PROG_AWK} 3942@ovindex AWK 3943@caindex prog_AWK 3944Check for @code{gawk}, @code{mawk}, @code{nawk}, and @code{awk}, in that 3945order, and set output variable @code{AWK} to the first one that is found. 3946It tries @code{gawk} first because that is reported to be the 3947best implementation. The result can be overridden by setting the 3948variable @code{AWK} or the cache variable @code{ac_cv_prog_AWK}. 3949 3950Using this macro is sufficient to avoid the pitfalls of traditional 3951@command{awk} (@pxref{awk, , Limitations of Usual Tools}). 3952@end defmac 3953 3954@defmac AC_PROG_GREP 3955@acindex{PROG_GREP} 3956@ovindex GREP 3957@caindex prog_GREP 3958Look for the best available @code{grep} or @code{ggrep} that accepts the 3959longest input lines possible, and that supports multiple @option{-e} options. 3960Set the output variable @code{GREP} to whatever is chosen. 3961@xref{grep, , Limitations of Usual Tools}, for more information about 3962portability problems with the @command{grep} command family. The result 3963can be overridden by setting the @code{GREP} variable and is cached in the 3964@code{ac_cv_path_GREP} variable. 3965@end defmac 3966 3967@defmac AC_PROG_EGREP 3968@acindex{PROG_EGREP} 3969@ovindex EGREP 3970@caindex prog_EGREP 3971Check whether @code{$GREP -E} works, or else look for the best available 3972@code{egrep} or @code{gegrep} that accepts the longest input lines possible. 3973Set the output variable @code{EGREP} to whatever is chosen. The result 3974can be overridden by setting the @code{EGREP} variable and is cached in the 3975@code{ac_cv_path_EGREP} variable. 3976@end defmac 3977 3978@defmac AC_PROG_FGREP 3979@acindex{PROG_FGREP} 3980@ovindex FGREP 3981@caindex prog_FGREP 3982Check whether @code{$GREP -F} works, or else look for the best available 3983@code{fgrep} or @code{gfgrep} that accepts the longest input lines possible. 3984Set the output variable @code{FGREP} to whatever is chosen. The result 3985can be overridden by setting the @code{FGREP} variable and is cached in the 3986@code{ac_cv_path_FGREP} variable. 3987@end defmac 3988 3989@defmac AC_PROG_INSTALL 3990@acindex{PROG_INSTALL} 3991@ovindex INSTALL 3992@ovindex INSTALL_PROGRAM 3993@ovindex INSTALL_DATA 3994@ovindex INSTALL_SCRIPT 3995@caindex path_install 3996Set output variable @code{INSTALL} to the name of a BSD-compatible 3997@command{install} program, if one is found in the current @env{PATH}. 3998Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c}, 3999checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its 4000default directories) to determine @var{dir} (@pxref{Output}). Also set 4001the variables @code{INSTALL_PROGRAM} and @code{INSTALL_SCRIPT} to 4002@samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}. 4003 4004@samp{@@INSTALL@@} is special, as its value may vary for different 4005configuration files. 4006 4007This macro screens out various instances of @command{install} known not to 4008work. It prefers to find a C program rather than a shell script, for 4009speed. Instead of @file{install-sh}, it can also use @file{install.sh}, 4010but that name is obsolete because some @command{make} programs have a rule 4011that creates @file{install} from it if there is no makefile. Further, this 4012macro requires @command{install} to be able to install multiple files into a 4013target directory in a single invocation. 4014 4015Autoconf comes with a copy of @file{install-sh} that you can use. If 4016you use @code{AC_PROG_INSTALL}, you must include either 4017@file{install-sh} or @file{install.sh} in your distribution; otherwise 4018@command{configure} produces an error message saying it can't find 4019them---even if the system you're on has a good @command{install} program. 4020This check is a safety measure to prevent you from accidentally leaving 4021that file out, which would prevent your package from installing on 4022systems that don't have a BSD-compatible @command{install} program. 4023 4024If you need to use your own installation program because it has features 4025not found in standard @command{install} programs, there is no reason to use 4026@code{AC_PROG_INSTALL}; just put the file name of your program into your 4027@file{Makefile.in} files. 4028 4029The result of the test can be overridden by setting the variable 4030@code{INSTALL} or the cache variable @code{ac_cv_path_install}. 4031@end defmac 4032 4033@defmac AC_PROG_MKDIR_P 4034@acindex{PROG_MKDIR_P} 4035@ovindex MKDIR_P 4036@caindex path_mkdir 4037Set output variable @code{MKDIR_P} to a program that ensures that for 4038each argument, a directory named by this argument exists, creating it 4039and its parent directories if needed, and without race conditions when 4040two instances of the program attempt to make the same directory at 4041nearly the same time. 4042 4043This macro uses the @samp{mkdir -p} command if possible. Otherwise, it 4044falls back on invoking @command{install-sh} with the @option{-d} option, 4045so your package should 4046contain @file{install-sh} as described under @code{AC_PROG_INSTALL}. 4047An @file{install-sh} file that predates Autoconf 2.60 or Automake 1.10 4048is vulnerable to race conditions, so if you want to support parallel 4049installs from 4050different packages into the same directory you need to make sure you 4051have an up-to-date @file{install-sh}. In particular, be careful about 4052using @samp{autoreconf -if} if your Automake predates Automake 1.10. 4053 4054This macro is related to the @code{AS_MKDIR_P} macro (@pxref{Programming 4055in M4sh}), but it sets an output variable intended for use in other 4056files, whereas @code{AS_MKDIR_P} is intended for use in scripts like 4057@command{configure}. Also, @code{AS_MKDIR_P} does not accept options, 4058but @code{MKDIR_P} supports the @option{-m} option, e.g., a makefile 4059might invoke @code{$(MKDIR_P) -m 0 dir} to create an inaccessible 4060directory, and conversely a makefile should use @code{$(MKDIR_P) -- 4061$(FOO)} if @var{FOO} might yield a value that begins with @samp{-}. 4062Finally, @code{AS_MKDIR_P} does not check for race condition 4063vulnerability, whereas @code{AC_PROG_MKDIR_P} does. 4064 4065@samp{@@MKDIR_P@@} is special, as its value may vary for different 4066configuration files. 4067 4068The result of the test can be overridden by setting the variable 4069@code{MKDIR_P} or the cache variable @code{ac_cv_path_mkdir}. 4070@end defmac 4071 4072@anchor{AC_PROG_LEX} 4073@defmac AC_PROG_LEX 4074@acindex{PROG_LEX} 4075@ovindex LEX 4076@ovindex LEXLIB 4077@cvindex YYTEXT_POINTER 4078@ovindex LEX_OUTPUT_ROOT 4079@caindex prog_LEX 4080If @code{flex} is found, set output variable @code{LEX} to @samp{flex} 4081and @code{LEXLIB} to @option{-lfl}, if that library is in a standard 4082place. Otherwise set @code{LEX} to @samp{lex} and @code{LEXLIB} to 4083@option{-ll}, if found. If neither variant is available, set @code{LEX} 4084to @samp{:}; for packages that ship the generated @file{file.yy.c} 4085alongside the source @file{file.l}, this default allows users without a 4086lexer generator to still build the package even if the timestamp for 4087@file{file.l} is inadvertently changed. 4088 4089Define @code{YYTEXT_POINTER} if @code{yytext} defaults to @samp{char *} instead 4090of to @samp{char []}. Also set output variable @code{LEX_OUTPUT_ROOT} to 4091the base of the file name that the lexer generates; usually 4092@file{lex.yy}, but sometimes something else. These results vary 4093according to whether @code{lex} or @code{flex} is being used. 4094 4095You are encouraged to use Flex in your sources, since it is both more 4096pleasant to use than plain Lex and the C source it produces is portable. 4097In order to ensure portability, however, you must either provide a 4098function @code{yywrap} or, if you don't use it (e.g., your scanner has 4099no @samp{#include}-like feature), simply include a @samp{%noyywrap} 4100statement in the scanner's source. Once this done, the scanner is 4101portable (unless @emph{you} felt free to use nonportable constructs) and 4102does not depend on any library. In this case, and in this case only, it 4103is suggested that you use this Autoconf snippet: 4104 4105@example 4106AC_PROG_LEX 4107if test "x$LEX" != xflex; then 4108 LEX="$SHELL $missing_dir/missing flex" 4109 AC_SUBST([LEX_OUTPUT_ROOT], [lex.yy]) 4110 AC_SUBST([LEXLIB], ['']) 4111fi 4112@end example 4113 4114The shell script @command{missing} can be found in the Automake 4115distribution. 4116 4117Remember that the user may have supplied an alternate location in 4118@env{LEX}, so if Flex is required, it is better to check that the user 4119provided something sufficient by parsing the output of @samp{$LEX 4120--version} than by simply relying on @code{test "x$LEX" = xflex}. 4121 4122To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes 4123(indirectly) this macro twice, which causes an annoying but benign 4124``@code{AC_PROG_LEX} invoked multiple times'' warning. Future versions 4125of Automake will fix this issue; meanwhile, just ignore this message. 4126 4127As part of running the test, this macro may delete any file in the 4128configuration directory named @file{lex.yy.c} or @file{lexyy.c}. 4129 4130The result of this test can be influenced by setting the variable 4131@code{LEX} or the cache variable @code{ac_cv_prog_LEX}. 4132@end defmac 4133 4134@anchor{AC_PROG_LN_S} 4135@defmac AC_PROG_LN_S 4136@acindex{PROG_LN_S} 4137@ovindex LN_S 4138If @samp{ln -s} works on the current file system (the operating system 4139and file system support symbolic links), set the output variable 4140@code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set 4141@code{LN_S} to @samp{ln}, and otherwise set it to @samp{cp -pR}. 4142 4143If you make a link in a directory other than the current directory, its 4144meaning depends on whether @samp{ln} or @samp{ln -s} is used. To safely 4145create links using @samp{$(LN_S)}, either find out which form is used 4146and adjust the arguments, or always invoke @code{ln} in the directory 4147where the link is to be created. 4148 4149In other words, it does not work to do: 4150@example 4151$(LN_S) foo /x/bar 4152@end example 4153 4154Instead, do: 4155 4156@example 4157(cd /x && $(LN_S) foo bar) 4158@end example 4159@end defmac 4160 4161@defmac AC_PROG_RANLIB 4162@acindex{PROG_RANLIB} 4163@ovindex RANLIB 4164@c @caindex prog_RANLIB 4165@c @caindex prog_ac_ct_RANLIB 4166Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib} 4167is found, and otherwise to @samp{:} (do nothing). 4168@end defmac 4169 4170@defmac AC_PROG_SED 4171@acindex{PROG_SED} 4172@ovindex SED 4173@caindex path_SED 4174Set output variable @code{SED} to a Sed implementation that conforms to 4175Posix and does not have arbitrary length limits. Report an error if no 4176acceptable Sed is found. @xref{sed, , Limitations of Usual Tools}, for more 4177information about portability problems with Sed. 4178 4179The result of this test can be overridden by setting the @code{SED} variable 4180and is cached in the @code{ac_cv_path_SED} variable. 4181@end defmac 4182 4183@defmac AC_PROG_YACC 4184@acindex{PROG_YACC} 4185@evindex YACC 4186@evindex YFLAGS 4187@ovindex YACC 4188@caindex prog_YACC 4189If @code{bison} is found, set output variable @code{YACC} to @samp{bison 4190-y}. Otherwise, if @code{byacc} is found, set @code{YACC} to 4191@samp{byacc}. Otherwise set @code{YACC} to @samp{yacc}. 4192The result of this test can be influenced by setting the variable 4193@code{YACC} or the cache variable @code{ac_cv_prog_YACC}. 4194@end defmac 4195 4196@node Generic Programs 4197@subsection Generic Program and File Checks 4198 4199These macros are used to find programs not covered by the ``particular'' 4200test macros. If you need to check the behavior of a program as well as 4201find out whether it is present, you have to write your own test for it 4202(@pxref{Writing Tests}). By default, these macros use the environment 4203variable @env{PATH}. If you need to check for a program that might not 4204be in the user's @env{PATH}, you can pass a modified path to use 4205instead, like this: 4206 4207@example 4208AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd], 4209 [$PATH$PATH_SEPARATOR/usr/libexec$PATH_SEPARATOR]dnl 4210[/usr/sbin$PATH_SEPARATOR/usr/etc$PATH_SEPARATOR/etc]) 4211@end example 4212 4213You are strongly encouraged to declare the @var{variable} passed to 4214@code{AC_CHECK_PROG} etc.@: as precious. @xref{Setting Output Variables}, 4215@code{AC_ARG_VAR}, for more details. 4216 4217@anchor{AC_CHECK_PROG} 4218@defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @ 4219 @var{value-if-found}, @ovar{value-if-not-found}, @dvar{path, $PATH}, @ 4220 @ovar{reject}) 4221@acindex{CHECK_PROG} 4222@caindex prog_@var{variable} 4223Check whether program @var{prog-to-check-for} exists in @var{path}. If 4224it is found, set @var{variable} to @var{value-if-found}, otherwise to 4225@var{value-if-not-found}, if given. Always pass over @var{reject} (an 4226absolute file name) even if it is the first found in the search path; in 4227that case, set @var{variable} using the absolute file name of the 4228@var{prog-to-check-for} found that is not @var{reject}. If 4229@var{variable} was already set, do nothing. Calls @code{AC_SUBST} for 4230@var{variable}. The result of this test can be overridden by setting the 4231@var{variable} variable or the cache variable 4232@code{ac_cv_prog_@var{variable}}. 4233@end defmac 4234 4235@anchor{AC_CHECK_PROGS} 4236@defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @ 4237 @ovar{value-if-not-found}, @dvar{path, $PATH}) 4238@acindex{CHECK_PROGS} 4239@caindex prog_@var{variable} 4240Check for each program in the blank-separated list 4241@var{progs-to-check-for} existing in the @var{path}. If one is found, set 4242@var{variable} to the name of that program. Otherwise, continue 4243checking the next program in the list. If none of the programs in the 4244list are found, set @var{variable} to @var{value-if-not-found}; if 4245@var{value-if-not-found} is not specified, the value of @var{variable} 4246is not changed. Calls @code{AC_SUBST} for @var{variable}. The result of 4247this test can be overridden by setting the @var{variable} variable or the 4248cache variable @code{ac_cv_prog_@var{variable}}. 4249@end defmac 4250 4251@defmac AC_CHECK_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @ 4252 @ovar{value-if-not-found}, @dvar{path, $PATH}) 4253@acindex{CHECK_TARGET_TOOL} 4254Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for} 4255with a prefix of the target type as determined by 4256@code{AC_CANONICAL_TARGET}, followed by a dash (@pxref{Canonicalizing}). 4257If the tool cannot be found with a prefix, and if the build and target 4258types are equal, then it is also searched for without a prefix. 4259 4260As noted in @ref{Specifying Target Triplets}, the 4261target is rarely specified, because most of the time it is the same 4262as the host: it is the type of system for which any compiler tool in 4263the package produces code. What this macro looks for is, 4264for example, @emph{a tool @r{(assembler, linker, etc.)}@: that the 4265compiler driver @r{(@command{gcc} for the GNU C Compiler)} 4266uses to produce objects, archives or executables}. 4267@end defmac 4268 4269@defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for}, @ 4270 @ovar{value-if-not-found}, @dvar{path, $PATH}) 4271@acindex{CHECK_TOOL} 4272@c @caindex prog_@var{VARIABLE} 4273@c @caindex prog_ac_ct_@var{VARIABLE} 4274Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for} 4275with a prefix of the host type as specified by @option{--host}, followed by a 4276dash. For example, if the user runs 4277@samp{configure --build=x86_64-gnu --host=i386-gnu}, then this call: 4278@example 4279AC_CHECK_TOOL([RANLIB], [ranlib], [:]) 4280@end example 4281@noindent 4282sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in 4283@var{path}, or otherwise to @samp{ranlib} if that program exists in 4284@var{path}, or to @samp{:} if neither program exists. 4285 4286When cross-compiling, this macro will issue a warning if no program 4287prefixed with the host type could be found. 4288For more information, see @ref{Specifying Target Triplets}. 4289@end defmac 4290 4291@defmac AC_CHECK_TARGET_TOOLS (@var{variable}, @var{progs-to-check-for}, @ 4292 @ovar{value-if-not-found}, @dvar{path, $PATH}) 4293@acindex{CHECK_TARGET_TOOLS} 4294Like @code{AC_CHECK_TARGET_TOOL}, each of the tools in the list 4295@var{progs-to-check-for} are checked with a prefix of the target type as 4296determined by @code{AC_CANONICAL_TARGET}, followed by a dash 4297(@pxref{Canonicalizing}). If none of the tools can be found with a 4298prefix, and if the build and target types are equal, then the first one 4299without a prefix is used. If a tool is found, set @var{variable} to 4300the name of that program. If none of the tools in the list are found, 4301set @var{variable} to @var{value-if-not-found}; if @var{value-if-not-found} 4302is not specified, the value of @var{variable} is not changed. Calls 4303@code{AC_SUBST} for @var{variable}. 4304@end defmac 4305 4306@defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @ 4307 @ovar{value-if-not-found}, @dvar{path, $PATH}) 4308@acindex{CHECK_TOOLS} 4309Like @code{AC_CHECK_TOOL}, each of the tools in the list 4310@var{progs-to-check-for} are checked with a prefix of the host type as 4311determined by @code{AC_CANONICAL_HOST}, followed by a dash 4312(@pxref{Canonicalizing}). If none of the tools can be found with a 4313prefix, then the first one without a prefix is used. If a tool is found, 4314set @var{variable} to the name of that program. If none of the tools in 4315the list are found, set @var{variable} to @var{value-if-not-found}; if 4316@var{value-if-not-found} is not specified, the value of @var{variable} 4317is not changed. Calls @code{AC_SUBST} for @var{variable}. 4318 4319When cross-compiling, this macro will issue a warning if no program 4320prefixed with the host type could be found. 4321For more information, see @ref{Specifying Target Triplets}. 4322@end defmac 4323 4324@anchor{AC_PATH_PROG} 4325@defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for}, @ 4326 @ovar{value-if-not-found}, @dvar{path, $PATH}) 4327@acindex{PATH_PROG} 4328@caindex path_@var{variable} 4329Like @code{AC_CHECK_PROG}, but set @var{variable} to the absolute 4330name of @var{prog-to-check-for} if found. The result of this test 4331can be overridden by setting the @var{variable} variable. A positive 4332result of this test is cached in the @code{ac_cv_path_@var{variable}} 4333variable. 4334@end defmac 4335 4336@anchor{AC_PATH_PROGS} 4337@defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for}, @ 4338 @ovar{value-if-not-found}, @dvar{path, $PATH}) 4339@acindex{PATH_PROGS} 4340@caindex path_@var{variable} 4341Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for} 4342are found, set @var{variable} to the absolute name of the program 4343found. The result of this test can be overridden by setting the 4344@var{variable} variable. A positive result of this test is cached in 4345the @code{ac_cv_path_@var{variable}} variable. 4346@end defmac 4347 4348@defmac AC_PATH_PROGS_FEATURE_CHECK (@var{variable}, @ 4349 @var{progs-to-check-for}, @var{feature-test}, @ 4350 @ovar{action-if-not-found}, @dvar{path, $PATH}) 4351@acindex{PATH_PROGS_FEATURE_CHECK} 4352@caindex path_@var{variable} 4353@vrindex ac_path_@var{variable} 4354@vrindex ac_path_@var{variable}_found 4355This macro was introduced in Autoconf 2.62. If @var{variable} is not 4356empty, then set the cache variable @code{ac_cv_path_@var{variable}} to 4357its value. Otherwise, check for each program in the blank-separated 4358list @var{progs-to-check-for} existing in @var{path}. For each program 4359found, execute @var{feature-test} with @code{ac_path_@var{variable}} 4360set to the absolute name of the candidate program. If no invocation of 4361@var{feature-test} sets the shell variable 4362@code{ac_cv_path_@var{variable}}, then @var{action-if-not-found} is 4363executed. @var{feature-test} will be run even when 4364@code{ac_cv_path_@var{variable}} is set, to provide the ability to 4365choose a better candidate found later in @var{path}; to accept the 4366current setting and bypass all further checks, @var{feature-test} can 4367execute @code{ac_path_@var{variable}_found=:}. 4368 4369Note that this macro has some subtle differences from 4370@code{AC_CHECK_PROGS}. It is designed to be run inside 4371@code{AC_CACHE_VAL}, therefore, it should have no side effects. In 4372particular, @var{variable} is not set to the final value of 4373@code{ac_cv_path_@var{variable}}, nor is @code{AC_SUBST} automatically 4374run. Also, on failure, any action can be performed, whereas 4375@code{AC_CHECK_PROGS} only performs 4376@code{@var{variable}=@var{value-if-not-found}}. 4377 4378Here is an example, similar to what Autoconf uses in its own configure 4379script. It will search for an implementation of @command{m4} that 4380supports the @code{indir} builtin, even if it goes by the name 4381@command{gm4} or is not the first implementation on @env{PATH}. 4382 4383@example 4384AC_CACHE_CHECK([for m4 that supports indir], [ac_cv_path_M4], 4385 [AC_PATH_PROGS_FEATURE_CHECK([M4], [m4 gm4], 4386 [[m4out=`echo 'changequote([,])indir([divnum])' | $ac_path_M4` 4387 test "x$m4out" = x0 \ 4388 && ac_cv_path_M4=$ac_path_M4 ac_path_M4_found=:]], 4389 [AC_MSG_ERROR([could not find m4 that supports indir])])]) 4390AC_SUBST([M4], [$ac_cv_path_M4]) 4391@end example 4392@end defmac 4393 4394@defmac AC_PATH_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @ 4395 @ovar{value-if-not-found}, @dvar{path, $PATH}) 4396@acindex{PATH_TARGET_TOOL} 4397Like @code{AC_CHECK_TARGET_TOOL}, but set @var{variable} to the absolute 4398name of the program if it is found. 4399@end defmac 4400 4401@defmac AC_PATH_TOOL (@var{variable}, @var{prog-to-check-for}, @ 4402 @ovar{value-if-not-found}, @dvar{path, $PATH}) 4403@acindex{PATH_TOOL} 4404Like @code{AC_CHECK_TOOL}, but set @var{variable} to the absolute 4405name of the program if it is found. 4406 4407When cross-compiling, this macro will issue a warning if no program 4408prefixed with the host type could be found. 4409For more information, see @ref{Specifying Target Triplets}. 4410@end defmac 4411 4412 4413@node Files 4414@section Files 4415@cindex File, checking 4416 4417You might also need to check for the existence of files. Before using 4418these macros, ask yourself whether a runtime test might not be a better 4419solution. Be aware that, like most Autoconf macros, they test a feature 4420of the host machine, and therefore, they die when cross-compiling. 4421 4422@defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @ 4423 @ovar{action-if-not-found}) 4424@acindex{CHECK_FILE} 4425@caindex file_@var{file} 4426Check whether file @var{file} exists on the native system. If it is 4427found, execute @var{action-if-found}, otherwise do 4428@var{action-if-not-found}, if given. The result of this test is cached 4429in the @code{ac_cv_file_@var{file}} variable, with characters not 4430suitable for a variable name mapped to underscores. 4431@end defmac 4432 4433@defmac AC_CHECK_FILES (@var{files}, @ovar{action-if-found}, @ 4434 @ovar{action-if-not-found}) 4435@acindex{CHECK_FILES} 4436@caindex file_@var{file} 4437Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}. 4438Additionally, defines @samp{HAVE_@var{file}} (@pxref{Standard Symbols}) 4439for each file found. The results of each test are cached in the 4440@code{ac_cv_file_@var{file}} variable, with characters not suitable for 4441a variable name mapped to underscores. 4442@end defmac 4443 4444 4445@node Libraries 4446@section Library Files 4447@cindex Library, checking 4448 4449The following macros check for the presence of certain C, C++, Fortran, 4450or Go library archive files. 4451 4452@anchor{AC_CHECK_LIB} 4453@defmac AC_CHECK_LIB (@var{library}, @var{function}, @ 4454 @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries}) 4455@acindex{CHECK_LIB} 4456@caindex lib_@var{library}_@var{function} 4457Test whether the library @var{library} is available by trying to link 4458a test program that calls function @var{function} with the library. 4459@var{function} should be a function provided by the library. 4460Use the base 4461name of the library; e.g., to check for @option{-lmp}, use @samp{mp} as 4462the @var{library} argument. 4463 4464@var{action-if-found} is a list of shell commands to run if the link 4465with the library succeeds; @var{action-if-not-found} is a list of shell 4466commands to run if the link fails. If @var{action-if-found} is not 4467specified, the default action prepends @option{-l@var{library}} to 4468@code{LIBS} and defines @samp{HAVE_LIB@var{library}} (in all 4469capitals). This macro is intended to support building @code{LIBS} in 4470a right-to-left (least-dependent to most-dependent) fashion such that 4471library dependencies are satisfied as a natural side effect of 4472consecutive tests. Linkers are sensitive to library ordering 4473so the order in which @code{LIBS} is generated is important to reliable 4474detection of libraries. 4475 4476If linking with @var{library} results in unresolved symbols that would 4477be resolved by linking with additional libraries, give those libraries 4478as the @var{other-libraries} argument, separated by spaces: 4479e.g., @option{-lXt -lX11}. Otherwise, this macro may fail to detect 4480that @var{library} is present, because linking the test program can 4481fail with unresolved symbols. The @var{other-libraries} argument 4482should be limited to cases where it is desirable to test for one library 4483in the presence of another that is not already in @code{LIBS}. 4484 4485@code{AC_CHECK_LIB} requires some care in usage, and should be avoided 4486in some common cases. Many standard functions like @code{gethostbyname} 4487appear in the standard C library on some hosts, and in special libraries 4488like @code{nsl} on other hosts. On some hosts the special libraries 4489contain variant implementations that you may not want to use. These 4490days it is normally better to use @code{AC_SEARCH_LIBS([gethostbyname], 4491[nsl])} instead of @code{AC_CHECK_LIB([nsl], [gethostbyname])}. 4492 4493The result of this test is cached in the 4494@code{ac_cv_lib_@var{library}_@var{function}} variable. 4495@end defmac 4496 4497@anchor{AC_SEARCH_LIBS} 4498@defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}, @ 4499 @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries}) 4500@acindex{SEARCH_LIBS} 4501@caindex search_@var{function} 4502Search for a library defining @var{function} if it's not already 4503available. This equates to calling 4504@samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])])} first with 4505no libraries, then for each library listed in @var{search-libs}. 4506 4507Prepend @option{-l@var{library}} to @code{LIBS} for the first library found 4508to contain @var{function}, and run @var{action-if-found}. If the 4509function is not found, run @var{action-if-not-found}. 4510 4511If linking with @var{library} results in unresolved symbols that would 4512be resolved by linking with additional libraries, give those libraries 4513as the @var{other-libraries} argument, separated by spaces: 4514e.g., @option{-lXt -lX11}. Otherwise, this macro fails to detect 4515that @var{function} is present, because linking the test program 4516always fails with unresolved symbols. 4517 4518The result of this test is cached in the 4519@code{ac_cv_search_@var{function}} variable as @samp{none required} if 4520@var{function} is already available, as @samp{no} if no library 4521containing @var{function} was found, otherwise as the 4522@option{-l@var{library}} option that needs to be prepended to @code{LIBS}. 4523@end defmac 4524 4525 4526 4527@node Library Functions 4528@section Library Functions 4529 4530The following macros check for particular C library functions. 4531If there is no macro specifically defined to check for a function you need, 4532and you don't need to check for any special properties of 4533it, then you can use one of the general function-check macros. 4534 4535@menu 4536* Function Portability:: Pitfalls with usual functions 4537* Particular Functions:: Special handling to find certain functions 4538* Generic Functions:: How to find other functions 4539@end menu 4540 4541@node Function Portability 4542@subsection Portability of C Functions 4543@cindex Portability of C functions 4544@cindex C function portability 4545 4546Most usual functions can either be missing, or be buggy, or be limited 4547on some architectures. This section tries to make an inventory of these 4548portability issues. By definition, this list always requires 4549additions. A much more complete list is maintained by the Gnulib 4550project (@pxref{Gnulib}), covering @ref{Function Substitutes, , 4551Current Posix Functions, gnulib, GNU gnulib}, @ref{Legacy Function 4552Substitutes, , Legacy Functions, gnulib, GNU gnulib}, and @ref{Glibc 4553Function Substitutes, , Glibc Functions, gnulib, GNU gnulib}. Please 4554help us keep the gnulib list as complete as possible. 4555 4556@table @asis 4557@item @code{exit} 4558@c @fuindex exit 4559@prindex @code{exit} 4560On ancient hosts, @code{exit} returned @code{int}. 4561This is because @code{exit} predates @code{void}, and there was a long 4562tradition of it returning @code{int}. 4563 4564On current hosts, the problem more likely is that @code{exit} is not 4565declared, due to C++ problems of some sort or another. For this reason 4566we suggest that test programs not invoke @code{exit}, but return from 4567@code{main} instead. 4568 4569@item @code{free} 4570@c @fuindex free 4571@prindex @code{free} 4572The C standard says a call @code{free (NULL)} does nothing, but 4573some old systems don't support this (e.g., NextStep). 4574 4575@item @code{isinf} 4576@itemx @code{isnan} 4577@c @fuindex isinf 4578@c @fuindex isnan 4579@prindex @code{isinf} 4580@prindex @code{isnan} 4581The C99 standard says that @code{isinf} and @code{isnan} are 4582macros. On some systems just macros are available 4583(e.g., HP-UX and Solaris 10), on 4584some systems both macros and functions (e.g., glibc 2.3.2), and on some 4585systems only functions (e.g., IRIX 6 and Solaris 9). In some cases 4586these functions are declared in nonstandard headers like 4587@code{<sunmath.h>} and defined in non-default libraries like 4588@option{-lm} or @option{-lsunmath}. 4589 4590The C99 @code{isinf} and @code{isnan} macros work correctly with 4591@code{long double} arguments, but pre-C99 systems that use functions 4592typically assume @code{double} arguments. On such a system, 4593@code{isinf} incorrectly returns true for a finite @code{long double} 4594argument that is outside the range of @code{double}. 4595 4596The best workaround for these issues is to use gnulib modules 4597@code{isinf} and @code{isnan} (@pxref{Gnulib}). But a lighter weight 4598solution involves code like the following. 4599 4600@smallexample 4601#include <math.h> 4602 4603#ifndef isnan 4604# define isnan(x) \ 4605 (sizeof (x) == sizeof (long double) ? isnan_ld (x) \ 4606 : sizeof (x) == sizeof (double) ? isnan_d (x) \ 4607 : isnan_f (x)) 4608static inline int isnan_f (float x) @{ return x != x; @} 4609static inline int isnan_d (double x) @{ return x != x; @} 4610static inline int isnan_ld (long double x) @{ return x != x; @} 4611#endif 4612 4613#ifndef isinf 4614# define isinf(x) \ 4615 (sizeof (x) == sizeof (long double) ? isinf_ld (x) \ 4616 : sizeof (x) == sizeof (double) ? isinf_d (x) \ 4617 : isinf_f (x)) 4618static inline int isinf_f (float x) 4619@{ return !isnan (x) && isnan (x - x); @} 4620static inline int isinf_d (double x) 4621@{ return !isnan (x) && isnan (x - x); @} 4622static inline int isinf_ld (long double x) 4623@{ return !isnan (x) && isnan (x - x); @} 4624#endif 4625@end smallexample 4626 4627Use @code{AC_C_INLINE} (@pxref{C Compiler}) so that this code works on 4628compilers that lack the @code{inline} keyword. Some optimizing 4629compilers mishandle these definitions, but systems with that bug 4630typically have many other floating point corner-case compliance problems 4631anyway, so it's probably not worth worrying about. 4632 4633@item @code{malloc} 4634@c @fuindex malloc 4635@prindex @code{malloc} 4636The C standard says a call @code{malloc (0)} is implementation 4637dependent. It can return either @code{NULL} or a new non-null pointer. 4638The latter is more common (e.g., the GNU C Library) but is by 4639no means universal. @code{AC_FUNC_MALLOC} 4640can be used to insist on non-@code{NULL} (@pxref{Particular Functions}). 4641 4642@item @code{putenv} 4643@c @fuindex putenv 4644@prindex @code{putenv} 4645Posix prefers @code{setenv} to @code{putenv}; among other things, 4646@code{putenv} is not required of all Posix implementations, but 4647@code{setenv} is. 4648 4649Posix specifies that @code{putenv} puts the given string directly in 4650@code{environ}, but some systems make a copy of it instead (e.g., 4651glibc 2.0, or BSD). And when a copy is made, @code{unsetenv} might 4652not free it, causing a memory leak (e.g., FreeBSD 4). 4653 4654On some systems @code{putenv ("FOO")} removes @samp{FOO} from the 4655environment, but this is not standard usage and it dumps core 4656on some systems (e.g., AIX). 4657 4658On MinGW, a call @code{putenv ("FOO=")} removes @samp{FOO} from the 4659environment, rather than inserting it with an empty value. 4660 4661@item @code{realloc} 4662@c @fuindex realloc 4663@prindex @code{realloc} 4664The C standard says a call @code{realloc (NULL, size)} is equivalent 4665to @code{malloc (size)}, but some old systems don't support this (e.g., 4666NextStep). 4667 4668@item @code{signal} handler 4669@c @fuindex signal 4670@prindex @code{signal} 4671@prindex @code{sigaction} 4672Normally @code{signal} takes a handler function with a return type of 4673@code{void}, but some old systems required @code{int} instead. Any 4674actual @code{int} value returned is not used; this is only a 4675difference in the function prototype demanded. 4676 4677All systems we know of in current use return @code{void}. The 4678@code{int} was to support K&R C, where of course @code{void} is not 4679available. The obsolete macro @code{AC_TYPE_SIGNAL} 4680(@pxref{AC_TYPE_SIGNAL}) can be used to establish the correct type in 4681all cases. 4682 4683In most cases, it is more robust to use @code{sigaction} when it is 4684available, rather than @code{signal}. 4685 4686@item @code{snprintf} 4687@c @fuindex snprintf 4688@prindex @code{snprintf} 4689@c @fuindex vsnprintf 4690@prindex @code{vsnprintf} 4691The C99 standard says that if the output array isn't big enough 4692and if no other errors occur, @code{snprintf} and @code{vsnprintf} 4693truncate the output and return the number of bytes that ought to have 4694been produced. Some older systems return the truncated length (e.g., 4695GNU C Library 2.0.x or IRIX 6.5), some a negative value 4696(e.g., earlier GNU C Library versions), and some the buffer 4697length without truncation (e.g., 32-bit Solaris 7). Also, some buggy 4698older systems ignore the length and overrun the buffer (e.g., 64-bit 4699Solaris 7). 4700 4701@item @code{sprintf} 4702@c @fuindex sprintf 4703@prindex @code{sprintf} 4704@c @fuindex vsprintf 4705@prindex @code{vsprintf} 4706The C standard says @code{sprintf} and @code{vsprintf} return the 4707number of bytes written. On some ancient systems (SunOS 4 for 4708instance) they return the buffer pointer instead, but these no 4709longer need to be worried about. 4710 4711@item @code{sscanf} 4712@c @fuindex sscanf 4713@prindex @code{sscanf} 4714On various old systems, e.g., HP-UX 9, @code{sscanf} requires 4715that its 4716input string be writable (though it doesn't actually change it). This 4717can be a problem when using @command{gcc} since it normally puts 4718constant strings in read-only memory (@pxref{Incompatibilities, 4719Incompatibilities of GCC, , gcc, Using and 4720Porting the GNU Compiler Collection}). Apparently in some cases even 4721having format strings read-only can be a problem. 4722 4723@item @code{strerror_r} 4724@c @fuindex strerror_r 4725@prindex @code{strerror_r} 4726Posix specifies that @code{strerror_r} returns an @code{int}, but many 4727systems (e.g., GNU C Library version 2.2.4) provide a 4728different version returning a @code{char *}. @code{AC_FUNC_STRERROR_R} 4729can detect which is in use (@pxref{Particular Functions}). 4730 4731@item @code{strnlen} 4732@c @fuindex strnlen 4733@prindex @code{strnlen} 4734AIX 4.3 provides a broken version which produces the 4735following results: 4736 4737@example 4738strnlen ("foobar", 0) = 0 4739strnlen ("foobar", 1) = 3 4740strnlen ("foobar", 2) = 2 4741strnlen ("foobar", 3) = 1 4742strnlen ("foobar", 4) = 0 4743strnlen ("foobar", 5) = 6 4744strnlen ("foobar", 6) = 6 4745strnlen ("foobar", 7) = 6 4746strnlen ("foobar", 8) = 6 4747strnlen ("foobar", 9) = 6 4748@end example 4749 4750@item @code{sysconf} 4751@c @fuindex sysconf 4752@prindex @code{sysconf} 4753@code{_SC_PAGESIZE} is standard, but some older systems (e.g., HP-UX 47549) have @code{_SC_PAGE_SIZE} instead. This can be tested with 4755@code{#ifdef}. 4756 4757@item @code{unlink} 4758@c @fuindex unlink 4759@prindex @code{unlink} 4760The Posix spec says that @code{unlink} causes the given file to be 4761removed only after there are no more open file handles for it. Some 4762non-Posix hosts have trouble with this requirement, though, 4763and some DOS variants even corrupt the file system. 4764 4765@item @code{unsetenv} 4766@c @fuindex unsetenv 4767@prindex @code{unsetenv} 4768On MinGW, @code{unsetenv} is not available, but a variable @samp{FOO} 4769can be removed with a call @code{putenv ("FOO=")}, as described under 4770@code{putenv} above. 4771 4772@item @code{va_copy} 4773@c @fuindex va_copy 4774@prindex @code{va_copy} 4775The C99 standard provides @code{va_copy} for copying 4776@code{va_list} variables. It may be available in older environments 4777too, though possibly as @code{__va_copy} (e.g., @command{gcc} in strict 4778pre-C99 mode). These can be tested with @code{#ifdef}. A fallback to 4779@code{memcpy (&dst, &src, sizeof (va_list))} gives maximum 4780portability. 4781 4782@item @code{va_list} 4783@c @fuindex va_list 4784@prindex @code{va_list} 4785@code{va_list} is not necessarily just a pointer. It can be a 4786@code{struct} (e.g., @command{gcc} on Alpha), which means @code{NULL} is 4787not portable. Or it can be an array (e.g., @command{gcc} in some 4788PowerPC configurations), which means as a function parameter it can be 4789effectively call-by-reference and library routines might modify the 4790value back in the caller (e.g., @code{vsnprintf} in the GNU C Library 47912.1). 4792 4793@item Signed @code{>>} 4794Normally the C @code{>>} right shift of a signed type replicates the 4795high bit, giving a so-called ``arithmetic'' shift. But care should be 4796taken since Standard C doesn't require that behavior. On those 4797few processors without a native arithmetic shift (for instance Cray 4798vector systems) zero bits may be shifted in, the same as a shift of an 4799unsigned type. 4800 4801@item Integer @code{/} 4802C divides signed integers by truncating their quotient toward zero, 4803yielding the same result as Fortran. However, before C99 the standard 4804allowed C implementations to take the floor or ceiling of the quotient 4805in some cases. Hardly any implementations took advantage of this 4806freedom, though, and it's probably not worth worrying about this issue 4807nowadays. 4808@end table 4809 4810 4811@node Particular Functions 4812@subsection Particular Function Checks 4813@cindex Function, checking 4814 4815These macros check for particular C functions---whether they exist, and 4816in some cases how they respond when given certain arguments. 4817 4818@anchor{AC_FUNC_ALLOCA} 4819@defmac AC_FUNC_ALLOCA 4820@acindex{FUNC_ALLOCA} 4821@cvindex C_ALLOCA 4822@cvindex HAVE_ALLOCA_H 4823@ovindex ALLOCA 4824@c @fuindex alloca 4825@prindex @code{alloca} 4826@hdrindex{alloca.h} 4827@c @caindex working_alloca_h 4828Check how to get @code{alloca}. Tries to get a builtin version by 4829checking for @file{alloca.h} or the predefined C preprocessor macros 4830@code{__GNUC__} and @code{_AIX}. If this macro finds @file{alloca.h}, 4831it defines @code{HAVE_ALLOCA_H}. 4832 4833If those attempts fail, it looks for the function in the standard C 4834library. If any of those methods succeed, it defines 4835@code{HAVE_ALLOCA}. Otherwise, it sets the output variable 4836@code{ALLOCA} to @samp{$@{LIBOBJDIR@}alloca.o} and defines 4837@code{C_ALLOCA} (so programs can periodically call @samp{alloca (0)} to 4838garbage collect). This variable is separate from @code{LIBOBJS} so 4839multiple programs can share the value of @code{ALLOCA} without needing 4840to create an actual library, in case only some of them use the code in 4841@code{LIBOBJS}. The @samp{$@{LIBOBJDIR@}} prefix serves the same 4842purpose as in @code{LIBOBJS} (@pxref{AC_LIBOBJ vs LIBOBJS}). 4843 4844This macro does not try to get @code{alloca} from the System V R3 4845@file{libPW} or the System V R4 @file{libucb} because those libraries 4846contain some incompatible functions that cause trouble. Some versions 4847do not even contain @code{alloca} or contain a buggy version. If you 4848still want to use their @code{alloca}, use @code{ar} to extract 4849@file{alloca.o} from them instead of compiling @file{alloca.c}. 4850 4851Source files that use @code{alloca} should start with a piece of code 4852like the following, to declare it properly. 4853 4854@example 4855@group 4856#ifdef STDC_HEADERS 4857# include <stdlib.h> 4858# include <stddef.h> 4859#else 4860# ifdef HAVE_STDLIB_H 4861# include <stdlib.h> 4862# endif 4863#endif 4864#ifdef HAVE_ALLOCA_H 4865# include <alloca.h> 4866#elif !defined alloca 4867# ifdef __GNUC__ 4868# define alloca __builtin_alloca 4869# elif defined _AIX 4870# define alloca __alloca 4871# elif defined _MSC_VER 4872# include <malloc.h> 4873# define alloca _alloca 4874# elif !defined HAVE_ALLOCA 4875# ifdef __cplusplus 4876extern "C" 4877# endif 4878void *alloca (size_t); 4879# endif 4880#endif 4881@end group 4882@end example 4883@end defmac 4884 4885@defmac AC_FUNC_CHOWN 4886@acindex{FUNC_CHOWN} 4887@cvindex HAVE_CHOWN 4888@c @fuindex chown 4889@prindex @code{chown} 4890@caindex func_chown_works 4891If the @code{chown} function is available and works (in particular, it 4892should accept @option{-1} for @code{uid} and @code{gid}), define 4893@code{HAVE_CHOWN}. The result of this macro is cached in the 4894@code{ac_cv_func_chown_works} variable. 4895@end defmac 4896 4897@anchor{AC_FUNC_CLOSEDIR_VOID} 4898@defmac AC_FUNC_CLOSEDIR_VOID 4899@acindex{FUNC_CLOSEDIR_VOID} 4900@cvindex CLOSEDIR_VOID 4901@c @fuindex closedir 4902@prindex @code{closedir} 4903@caindex func_closedir_void 4904If the @code{closedir} function does not return a meaningful value, 4905define @code{CLOSEDIR_VOID}. Otherwise, callers ought to check its 4906return value for an error indicator. 4907 4908Currently this test is implemented by running a test program. When 4909cross compiling the pessimistic assumption that @code{closedir} does not 4910return a meaningful value is made. 4911 4912The result of this macro is cached in the @code{ac_cv_func_closedir_void} 4913variable. 4914 4915This macro is obsolescent, as @code{closedir} returns a meaningful value 4916on current systems. New programs need not use this macro. 4917@end defmac 4918 4919@defmac AC_FUNC_ERROR_AT_LINE 4920@acindex{FUNC_ERROR_AT_LINE} 4921@c @fuindex error_at_line 4922@prindex @code{error_at_line} 4923@caindex lib_error_at_line 4924If the @code{error_at_line} function is not found, require an 4925@code{AC_LIBOBJ} replacement of @samp{error}. 4926 4927The result of this macro is cached in the @code{ac_cv_lib_error_at_line} 4928variable. 4929 4930The @code{AC_FUNC_ERROR_AT_LINE} macro is obsolescent. New programs 4931should use Gnulib's @code{error} module. @xref{Gnulib}. 4932@end defmac 4933 4934@defmac AC_FUNC_FNMATCH 4935@acindex{FUNC_FNMATCH} 4936@c @fuindex fnmatch 4937@prindex @code{fnmatch} 4938@caindex func_fnmatch_works 4939If the @code{fnmatch} function conforms to Posix, define 4940@code{HAVE_FNMATCH}. Detect common implementation bugs, for example, 4941the bugs in Solaris 2.4. 4942 4943Unlike the other specific 4944@code{AC_FUNC} macros, @code{AC_FUNC_FNMATCH} does not replace a 4945broken/missing @code{fnmatch}. This is for historical reasons. 4946See @code{AC_REPLACE_FNMATCH} below. 4947 4948The result of this macro is cached in the @code{ac_cv_func_fnmatch_works} 4949variable. 4950 4951This macro is obsolescent. New programs should use Gnulib's 4952@code{fnmatch-posix} module. @xref{Gnulib}. 4953@end defmac 4954 4955@defmac AC_FUNC_FNMATCH_GNU 4956@acindex{FUNC_FNMATCH_GNU} 4957@c @fuindex fnmatch 4958@prindex @code{fnmatch} 4959@caindex func_fnmatch_gnu 4960Behave like @code{AC_REPLACE_FNMATCH} (@emph{replace}) but also test 4961whether @code{fnmatch} supports GNU extensions. Detect common 4962implementation bugs, for example, the bugs in the GNU C 4963Library 2.1. 4964 4965The result of this macro is cached in the @code{ac_cv_func_fnmatch_gnu} 4966variable. 4967 4968This macro is obsolescent. New programs should use Gnulib's 4969@code{fnmatch-gnu} module. @xref{Gnulib}. 4970@end defmac 4971 4972@anchor{AC_FUNC_FORK} 4973@defmac AC_FUNC_FORK 4974@acindex{FUNC_FORK} 4975@cvindex HAVE_VFORK_H 4976@cvindex HAVE_WORKING_FORK 4977@cvindex HAVE_WORKING_VFORK 4978@cvindex vfork 4979@c @fuindex fork 4980@prindex @code{fork} 4981@c @fuindex vfork 4982@prindex @code{vfork} 4983@hdrindex{vfork.h} 4984@c @caindex func_fork 4985@c @caindex func_fork_works 4986This macro checks for the @code{fork} and @code{vfork} functions. If a 4987working @code{fork} is found, define @code{HAVE_WORKING_FORK}. This macro 4988checks whether @code{fork} is just a stub by trying to run it. 4989 4990If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working 4991@code{vfork} is found, define @code{HAVE_WORKING_VFORK}. Otherwise, 4992define @code{vfork} to be @code{fork} for backward compatibility with 4993previous versions of @command{autoconf}. This macro checks for several known 4994errors in implementations of @code{vfork} and considers the system to not 4995have a working @code{vfork} if it detects any of them. It is not considered 4996to be an implementation error if a child's invocation of @code{signal} 4997modifies the parent's signal handler, since child processes rarely change 4998their signal handlers. 4999 5000Since this macro defines @code{vfork} only for backward compatibility with 5001previous versions of @command{autoconf} you're encouraged to define it 5002yourself in new code: 5003@example 5004@group 5005#ifndef HAVE_WORKING_VFORK 5006# define vfork fork 5007#endif 5008@end group 5009@end example 5010 5011The results of this macro are cached in the @code{ac_cv_func_fork_works} 5012and @code{ac_cv_func_vfork_works} variables. In order to override the 5013test, you also need to set the @code{ac_cv_func_fork} and 5014@code{ac_cv_func_vfork} variables. 5015@end defmac 5016 5017@defmac AC_FUNC_FSEEKO 5018@acindex{FUNC_FSEEKO} 5019@cvindex _LARGEFILE_SOURCE 5020@cvindex HAVE_FSEEKO 5021@c @fuindex fseeko 5022@prindex @code{fseeko} 5023@c @fuindex ftello 5024@prindex @code{ftello} 5025@c @caindex sys_largefile_source 5026If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}. 5027Define @code{_LARGEFILE_SOURCE} if necessary to make the prototype 5028visible on some systems (e.g., glibc 2.2). Otherwise linkage problems 5029may occur when compiling with @code{AC_SYS_LARGEFILE} on 5030largefile-sensitive systems where @code{off_t} does not default to a 503164bit entity. All systems with @code{fseeko} also supply @code{ftello}. 5032@end defmac 5033 5034@defmac AC_FUNC_GETGROUPS 5035@acindex{FUNC_GETGROUPS} 5036@cvindex HAVE_GETGROUPS 5037@ovindex GETGROUPS_LIBS 5038@c @fuindex getgroups 5039@prindex @code{getgroups} 5040@caindex func_getgroups_works 5041If the @code{getgroups} function is available and works (unlike on 5042Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define 5043@code{HAVE_GETGROUPS}. Set @code{GETGROUPS_LIBS} to any libraries 5044needed to get that function. This macro runs @code{AC_TYPE_GETGROUPS}. 5045@end defmac 5046 5047@anchor{AC_FUNC_GETLOADAVG} 5048@defmac AC_FUNC_GETLOADAVG 5049@acindex{FUNC_GETLOADAVG} 5050@cvindex SVR4 5051@cvindex DGUX 5052@cvindex UMAX 5053@cvindex UMAX4_3 5054@cvindex HAVE_NLIST_H 5055@cvindex NLIST_NAME_UNION 5056@cvindex GETLOADAVG_PRIVILEGED 5057@cvindex NEED_SETGID 5058@cvindex C_GETLOADAVG 5059@ovindex LIBOBJS 5060@ovindex NEED_SETGID 5061@ovindex KMEM_GROUP 5062@ovindex GETLOADAVG_LIBS 5063@c @fuindex getloadavg 5064@prindex @code{getloadavg} 5065Check how to get the system load averages. To perform its tests 5066properly, this macro needs the file @file{getloadavg.c}; therefore, be 5067sure to set the @code{AC_LIBOBJ} replacement directory properly (see 5068@ref{Generic Functions}, @code{AC_CONFIG_LIBOBJ_DIR}). 5069 5070If the system has the @code{getloadavg} function, define 5071@code{HAVE_GETLOADAVG}, and set @code{GETLOADAVG_LIBS} to any libraries 5072necessary to get that function. Also add @code{GETLOADAVG_LIBS} to 5073@code{LIBS}. Otherwise, require an @code{AC_LIBOBJ} replacement for 5074@samp{getloadavg} with source code in @file{@var{dir}/getloadavg.c}, and 5075possibly define several other C preprocessor macros and output 5076variables: 5077 5078@enumerate 5079@item 5080Define @code{C_GETLOADAVG}. 5081 5082@item 5083Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on 5084those systems. 5085 5086@item 5087@hdrindex{nlist.h} 5088If @file{nlist.h} is found, define @code{HAVE_NLIST_H}. 5089 5090@item 5091If @samp{struct nlist} has an @samp{n_un.n_name} member, define 5092@code{HAVE_STRUCT_NLIST_N_UN_N_NAME}. The obsolete symbol 5093@code{NLIST_NAME_UNION} is still defined, but do not depend upon it. 5094 5095@item 5096Programs may need to be installed set-group-ID (or set-user-ID) for 5097@code{getloadavg} to work. In this case, define 5098@code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID} 5099to @samp{true} (and otherwise to @samp{false}), and set 5100@code{KMEM_GROUP} to the name of the group that should own the installed 5101program. 5102@end enumerate 5103 5104The @code{AC_FUNC_GETLOADAVG} macro is obsolescent. New programs should 5105use Gnulib's @code{getloadavg} module. @xref{Gnulib}. 5106@end defmac 5107 5108@anchor{AC_FUNC_GETMNTENT} 5109@defmac AC_FUNC_GETMNTENT 5110@acindex{FUNC_GETMNTENT} 5111@cvindex HAVE_GETMNTENT 5112@c @fuindex getmntent 5113@prindex @code{getmntent} 5114@caindex search_getmntent 5115Check for @code{getmntent} in the standard C library, and then in the 5116@file{sun}, @file{seq}, and @file{gen} libraries, for UNICOS, 5117IRIX 4, PTX, and UnixWare, respectively. Then, if 5118@code{getmntent} is available, define @code{HAVE_GETMNTENT} and set 5119@code{ac_cv_func_getmntent} to @code{yes}. Otherwise set 5120@code{ac_cv_func_getmntent} to @code{no}. 5121 5122The result of this macro can be overridden by setting the cache variable 5123@code{ac_cv_search_getmntent}. 5124@end defmac 5125 5126@defmac AC_FUNC_GETPGRP 5127@acindex{FUNC_GETPGRP} 5128@cvindex GETPGRP_VOID 5129@c @fuindex getpgid 5130@c @fuindex getpgrp 5131@prindex @code{getpgid} 5132@prindex @code{getpgrp} 5133@caindex func_getpgrp_void 5134Define @code{GETPGRP_VOID} if it is an error to pass 0 to 5135@code{getpgrp}; this is the Posix behavior. On older BSD 5136systems, you must pass 0 to @code{getpgrp}, as it takes an argument and 5137behaves like Posix's @code{getpgid}. 5138 5139@example 5140#ifdef GETPGRP_VOID 5141 pid = getpgrp (); 5142#else 5143 pid = getpgrp (0); 5144#endif 5145@end example 5146 5147This macro does not check whether 5148@code{getpgrp} exists at all; if you need to work in that situation, 5149first call @code{AC_CHECK_FUNC} for @code{getpgrp}. 5150 5151The result of this macro is cached in the @code{ac_cv_func_getpgrp_void} 5152variable. 5153 5154This macro is obsolescent, as current systems have a @code{getpgrp} 5155whose signature conforms to Posix. New programs need not use this macro. 5156@end defmac 5157 5158@defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK 5159@acindex{FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK} 5160@cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK 5161@c @fuindex lstat 5162@prindex @code{lstat} 5163@caindex func_lstat_dereferences_slashed_symlink 5164If @file{link} is a symbolic link, then @code{lstat} should treat 5165@file{link/} the same as @file{link/.}. However, many older 5166@code{lstat} implementations incorrectly ignore trailing slashes. 5167 5168It is safe to assume that if @code{lstat} incorrectly ignores 5169trailing slashes, then other symbolic-link-aware functions like 5170@code{unlink} also incorrectly ignore trailing slashes. 5171 5172If @code{lstat} behaves properly, define 5173@code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an 5174@code{AC_LIBOBJ} replacement of @code{lstat}. 5175 5176The result of this macro is cached in the 5177@code{ac_cv_func_lstat_dereferences_slashed_symlink} variable. 5178 5179The @code{AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK} macro is obsolescent. 5180New programs should use Gnulib's @code{lstat} module. @xref{Gnulib}. 5181@end defmac 5182 5183@defmac AC_FUNC_MALLOC 5184@acindex{FUNC_MALLOC} 5185@cvindex HAVE_MALLOC 5186@cvindex malloc 5187@c @fuindex malloc 5188@prindex @code{malloc} 5189@caindex func_malloc_0_nonnull 5190If the @code{malloc} function is compatible with the GNU C 5191library @code{malloc} (i.e., @samp{malloc (0)} returns a valid 5192pointer), define @code{HAVE_MALLOC} to 1. Otherwise define 5193@code{HAVE_MALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for 5194@samp{malloc}, and define @code{malloc} to @code{rpl_malloc} so that the 5195native @code{malloc} is not used in the main project. 5196 5197Typically, the replacement file @file{malloc.c} should look like (note 5198the @samp{#undef malloc}): 5199 5200@verbatim 5201#include <config.h> 5202#undef malloc 5203 5204#include <sys/types.h> 5205 5206void *malloc (); 5207 5208/* Allocate an N-byte block of memory from the heap. 5209 If N is zero, allocate a 1-byte block. */ 5210 5211void * 5212rpl_malloc (size_t n) 5213{ 5214 if (n == 0) 5215 n = 1; 5216 return malloc (n); 5217} 5218@end verbatim 5219 5220The result of this macro is cached in the 5221@code{ac_cv_func_malloc_0_nonnull} variable. 5222@end defmac 5223 5224@defmac AC_FUNC_MBRTOWC 5225@acindex{FUNC_MBRTOWC} 5226@cvindex HAVE_MBRTOWC 5227@c @fuindex mbrtowc 5228@prindex @code{mbrtowc} 5229@caindex func_mbrtowc 5230Define @code{HAVE_MBRTOWC} to 1 if the function @code{mbrtowc} and the 5231type @code{mbstate_t} are properly declared. 5232 5233The result of this macro is cached in the @code{ac_cv_func_mbrtowc} 5234variable. 5235@end defmac 5236 5237@defmac AC_FUNC_MEMCMP 5238@acindex{FUNC_MEMCMP} 5239@ovindex LIBOBJS 5240@c @fuindex memcmp 5241@prindex @code{memcmp} 5242@caindex func_memcmp_working 5243If the @code{memcmp} function is not available, or does not work on 52448-bit data (like the one on SunOS 4.1.3), or fails when comparing 16 5245bytes or more and with at least one buffer not starting on a 4-byte 5246boundary (such as the one on NeXT x86 OpenStep), require an 5247@code{AC_LIBOBJ} replacement for @samp{memcmp}. 5248 5249The result of this macro is cached in the 5250@code{ac_cv_func_memcmp_working} variable. 5251 5252This macro is obsolescent, as current systems have a working 5253@code{memcmp}. New programs need not use this macro. 5254@end defmac 5255 5256@defmac AC_FUNC_MKTIME 5257@acindex{FUNC_MKTIME} 5258@ovindex LIBOBJS 5259@c @fuindex mktime 5260@prindex @code{mktime} 5261@caindex func_working_mktime 5262If the @code{mktime} function is not available, or does not work 5263correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}. 5264For the purposes of this test, @code{mktime} should conform to the 5265Posix standard and should be the inverse of 5266@code{localtime}. 5267 5268The result of this macro is cached in the 5269@code{ac_cv_func_working_mktime} variable. 5270 5271The @code{AC_FUNC_MKTIME} macro is obsolescent. New programs should 5272use Gnulib's @code{mktime} module. @xref{Gnulib}. 5273@end defmac 5274 5275@anchor{AC_FUNC_MMAP} 5276@defmac AC_FUNC_MMAP 5277@acindex{FUNC_MMAP} 5278@cvindex HAVE_MMAP 5279@c @fuindex mmap 5280@prindex @code{mmap} 5281@caindex func_mmap_fixed_mapped 5282If the @code{mmap} function exists and works correctly, define 5283@code{HAVE_MMAP}. This checks only private fixed mapping of already-mapped 5284memory. 5285 5286The result of this macro is cached in the 5287@code{ac_cv_func_mmap_fixed_mapped} variable. 5288@end defmac 5289 5290@defmac AC_FUNC_OBSTACK 5291@acindex{FUNC_OBSTACK} 5292@cvindex HAVE_OBSTACK 5293@cindex obstack 5294@caindex func_obstack 5295If the obstacks are found, define @code{HAVE_OBSTACK}, else require an 5296@code{AC_LIBOBJ} replacement for @samp{obstack}. 5297 5298The result of this macro is cached in the @code{ac_cv_func_obstack} 5299variable. 5300@end defmac 5301 5302@defmac AC_FUNC_REALLOC 5303@acindex{FUNC_REALLOC} 5304@cvindex HAVE_REALLOC 5305@cvindex realloc 5306@c @fuindex realloc 5307@prindex @code{realloc} 5308@caindex func_realloc_0_nonnull 5309If the @code{realloc} function is compatible with the GNU C 5310library @code{realloc} (i.e., @samp{realloc (NULL, 0)} returns a 5311valid pointer), define @code{HAVE_REALLOC} to 1. Otherwise define 5312@code{HAVE_REALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for 5313@samp{realloc}, and define @code{realloc} to @code{rpl_realloc} so that 5314the native @code{realloc} is not used in the main project. See 5315@code{AC_FUNC_MALLOC} for details. 5316 5317The result of this macro is cached in the 5318@code{ac_cv_func_realloc_0_nonnull} variable. 5319@end defmac 5320 5321@defmac AC_FUNC_SELECT_ARGTYPES 5322@acindex{FUNC_SELECT_ARGTYPES} 5323@cvindex SELECT_TYPE_ARG1 5324@cvindex SELECT_TYPE_ARG234 5325@cvindex SELECT_TYPE_ARG5 5326@c @fuindex select 5327@prindex @code{select} 5328@c @caindex func_select_args 5329Determines the correct type to be passed for each of the 5330@code{select} function's arguments, and defines those types 5331in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and 5332@code{SELECT_TYPE_ARG5} respectively. @code{SELECT_TYPE_ARG1} defaults 5333to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *}, 5334and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}. 5335 5336This macro is obsolescent, as current systems have a @code{select} whose 5337signature conforms to Posix. New programs need not use this macro. 5338@end defmac 5339 5340@defmac AC_FUNC_SETPGRP 5341@acindex{FUNC_SETPGRP} 5342@cvindex SETPGRP_VOID 5343@c @fuindex setpgrp 5344@prindex @code{setpgrp} 5345@caindex func_setpgrp_void 5346If @code{setpgrp} takes no argument (the Posix version), define 5347@code{SETPGRP_VOID}. Otherwise, it is the BSD version, which takes 5348two process IDs as arguments. This macro does not check whether 5349@code{setpgrp} exists at all; if you need to work in that situation, 5350first call @code{AC_CHECK_FUNC} for @code{setpgrp}. 5351 5352The result of this macro is cached in the @code{ac_cv_func_setpgrp_void} 5353variable. 5354 5355This macro is obsolescent, as current systems have a @code{setpgrp} 5356whose signature conforms to Posix. New programs need not use this macro. 5357@end defmac 5358 5359@defmac AC_FUNC_STAT 5360@defmacx AC_FUNC_LSTAT 5361@acindex{FUNC_STAT} 5362@acindex{FUNC_LSTAT} 5363@cvindex HAVE_STAT_EMPTY_STRING_BUG 5364@cvindex HAVE_LSTAT_EMPTY_STRING_BUG 5365@c @fuindex stat 5366@prindex @code{stat} 5367@c @fuindex lstat 5368@prindex @code{lstat} 5369@caindex func_stat_empty_string_bug 5370@caindex func_lstat_empty_string_bug 5371Determine whether @code{stat} or @code{lstat} have the bug that it 5372succeeds when given the zero-length file name as argument. The @code{stat} 5373and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do 5374this. 5375 5376If it does, then define @code{HAVE_STAT_EMPTY_STRING_BUG} (or 5377@code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ} 5378replacement of it. 5379 5380The results of these macros are cached in the 5381@code{ac_cv_func_stat_empty_string_bug} and the 5382@code{ac_cv_func_lstat_empty_string_bug} variables, respectively. 5383 5384These macros are obsolescent, as no current systems have the bug. 5385New programs need not use these macros. 5386@end defmac 5387 5388@anchor{AC_FUNC_STRCOLL} 5389@defmac AC_FUNC_STRCOLL 5390@acindex{FUNC_STRCOLL} 5391@cvindex HAVE_STRCOLL 5392@c @fuindex strcoll 5393@prindex @code{strcoll} 5394@caindex func_strcoll_works 5395If the @code{strcoll} function exists and works correctly, define 5396@code{HAVE_STRCOLL}. This does a bit more than 5397@samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect 5398definitions of @code{strcoll} that should not be used. 5399 5400The result of this macro is cached in the @code{ac_cv_func_strcoll_works} 5401variable. 5402@end defmac 5403 5404@defmac AC_FUNC_STRERROR_R 5405@acindex{FUNC_STRERROR_R} 5406@cvindex HAVE_STRERROR_R 5407@cvindex HAVE_DECL_STRERROR_R 5408@cvindex STRERROR_R_CHAR_P 5409@c @fuindex strerror_r 5410@caindex func_strerror_r_char_p 5411@prindex @code{strerror_r} 5412If @code{strerror_r} is available, define @code{HAVE_STRERROR_R}, and if 5413it is declared, define @code{HAVE_DECL_STRERROR_R}. If it returns a 5414@code{char *} message, define @code{STRERROR_R_CHAR_P}; otherwise it 5415returns an @code{int} error number. The Thread-Safe Functions option of 5416Posix requires @code{strerror_r} to return @code{int}, but 5417many systems (including, for example, version 2.2.4 of the GNU C 5418Library) return a @code{char *} value that is not necessarily equal to 5419the buffer argument. 5420 5421The result of this macro is cached in the 5422@code{ac_cv_func_strerror_r_char_p} variable. 5423@end defmac 5424 5425@anchor{AC_FUNC_STRFTIME} 5426@defmac AC_FUNC_STRFTIME 5427@acindex{FUNC_STRFTIME} 5428@cvindex HAVE_STRFTIME 5429@c @fuindex strftime 5430@prindex @code{strftime} 5431Check for @code{strftime} in the @file{intl} library, for SCO Unix. 5432Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}. 5433 5434This macro is obsolescent, as no current systems require the @file{intl} 5435library for @code{strftime}. New programs need not use this macro. 5436@end defmac 5437 5438@defmac AC_FUNC_STRTOD 5439@acindex{FUNC_STRTOD} 5440@ovindex POW_LIB 5441@c @fuindex strtod 5442@prindex @code{strtod} 5443@caindex func_strtod 5444@caindex func_pow 5445If the @code{strtod} function does not exist or doesn't work correctly, 5446ask for an @code{AC_LIBOBJ} replacement of @samp{strtod}. In this case, 5447because @file{strtod.c} is likely to need @samp{pow}, set the output 5448variable @code{POW_LIB} to the extra library needed. 5449 5450This macro caches its result in the @code{ac_cv_func_strtod} variable 5451and depends upon the result in the @code{ac_cv_func_pow} variable. 5452 5453The @code{AC_FUNC_STRTOD} macro is obsolescent. New programs should 5454use Gnulib's @code{strtod} module. @xref{Gnulib}. 5455@end defmac 5456 5457@defmac AC_FUNC_STRTOLD 5458@acindex{FUNC_STRTOLD} 5459@cvindex HAVE_STRTOLD 5460@prindex @code{strtold} 5461@caindex func_strtold 5462If the @code{strtold} function exists and conforms to C99, define 5463@code{HAVE_STRTOLD}. 5464 5465This macro caches its result in the @code{ac_cv_func_strtold} variable. 5466@end defmac 5467 5468@defmac AC_FUNC_STRNLEN 5469@acindex{FUNC_STRNLEN} 5470@cvindex HAVE_STRNLEN 5471@c @fuindex strnlen 5472@prindex @code{strnlen} 5473@caindex func_strnlen_working 5474If the @code{strnlen} function is not available, or is buggy (like the one 5475from AIX 4.3), require an @code{AC_LIBOBJ} replacement for it. 5476 5477This macro caches its result in the @code{ac_cv_func_strnlen_working} 5478variable. 5479@end defmac 5480 5481@anchor{AC_FUNC_UTIME_NULL} 5482@defmac AC_FUNC_UTIME_NULL 5483@acindex{FUNC_UTIME_NULL} 5484@cvindex HAVE_UTIME_NULL 5485@c @fuindex utime 5486@prindex @code{utime} 5487@caindex func_utime_null 5488If @samp{utime (@var{file}, NULL)} sets @var{file}'s timestamp to 5489the present, define @code{HAVE_UTIME_NULL}. 5490 5491This macro caches its result in the @code{ac_cv_func_utime_null} 5492variable. 5493 5494This macro is obsolescent, as all current systems have a @code{utime} 5495that behaves this way. New programs need not use this macro. 5496@end defmac 5497 5498@anchor{AC_FUNC_VPRINTF} 5499@defmac AC_FUNC_VPRINTF 5500@acindex{FUNC_VPRINTF} 5501@cvindex HAVE_VPRINTF 5502@cvindex HAVE_DOPRNT 5503@c @fuindex vprintf 5504@prindex @code{vprintf} 5505@c @fuindex vsprintf 5506@prindex @code{vsprintf} 5507If @code{vprintf} is found, define @code{HAVE_VPRINTF}. Otherwise, if 5508@code{_doprnt} is found, define @code{HAVE_DOPRNT}. (If @code{vprintf} 5509is available, you may assume that @code{vfprintf} and @code{vsprintf} 5510are also available.) 5511 5512This macro is obsolescent, as all current systems have @code{vprintf}. 5513New programs need not use this macro. 5514@end defmac 5515 5516@defmac AC_REPLACE_FNMATCH 5517@acindex{REPLACE_FNMATCH} 5518@c @fuindex fnmatch 5519@prindex @code{fnmatch} 5520@hdrindex{fnmatch.h} 5521@caindex func_fnmatch_works 5522If the @code{fnmatch} function does not conform to Posix (see 5523@code{AC_FUNC_FNMATCH}), ask for its @code{AC_LIBOBJ} replacement. 5524 5525The files @file{fnmatch.c}, @file{fnmatch_loop.c}, and @file{fnmatch_.h} 5526in the @code{AC_LIBOBJ} replacement directory are assumed to contain a 5527copy of the source code of GNU @code{fnmatch}. If necessary, 5528this source code is compiled as an @code{AC_LIBOBJ} replacement, and the 5529@file{fnmatch_.h} file is linked to @file{fnmatch.h} so that it can be 5530included in place of the system @code{<fnmatch.h>}. 5531 5532This macro caches its result in the @code{ac_cv_func_fnmatch_works} 5533variable. 5534 5535This macro is obsolescent, as it assumes the use of particular source 5536files. New programs should use Gnulib's @code{fnmatch-posix} module, 5537which provides this macro along with the source files. @xref{Gnulib}. 5538@end defmac 5539 5540 5541 5542@node Generic Functions 5543@subsection Generic Function Checks 5544 5545These macros are used to find functions not covered by the ``particular'' 5546test macros. If the functions might be in libraries other than the 5547default C library, first call @code{AC_CHECK_LIB} for those libraries. 5548If you need to check the behavior of a function as well as find out 5549whether it is present, you have to write your own test for 5550it (@pxref{Writing Tests}). 5551 5552@anchor{AC_CHECK_FUNC} 5553@defmac AC_CHECK_FUNC (@var{function}, @ovar{action-if-found}, @ 5554 @ovar{action-if-not-found}) 5555@acindex{CHECK_FUNC} 5556@caindex func_@var{function} 5557If C function @var{function} is available, run shell commands 5558@var{action-if-found}, otherwise @var{action-if-not-found}. If you just 5559want to define a symbol if the function is available, consider using 5560@code{AC_CHECK_FUNCS} instead. This macro checks for functions with C 5561linkage even when @code{AC_LANG(C++)} has been called, since C is more 5562standardized than C++. (@pxref{Language Choice}, for more information 5563about selecting the language for checks.) 5564 5565This macro caches its result in the @code{ac_cv_func_@var{function}} 5566variable. 5567@end defmac 5568 5569@anchor{AC_CHECK_FUNCS} 5570@defmac AC_CHECK_FUNCS (@var{function}@dots{}, @ovar{action-if-found}, @ 5571 @ovar{action-if-not-found}) 5572@acindex{CHECK_FUNCS} 5573@cvindex HAVE_@var{function} 5574For each @var{function} enumerated in the blank-or-newline-separated argument 5575list, define @code{HAVE_@var{function}} (in all capitals) if it is available. 5576If @var{action-if-found} is given, it is additional shell code to 5577execute when one of the functions is found. You can give it a value of 5578@samp{break} to break out of the loop on the first match. If 5579@var{action-if-not-found} is given, it is executed when one of the 5580functions is not found. 5581 5582Results are cached for each @var{function} as in @code{AC_CHECK_FUNC}. 5583@end defmac 5584 5585@defmac AC_CHECK_FUNCS_ONCE (@var{function}@dots{}) 5586@acindex{CHECK_FUNCS_ONCE} 5587@cvindex HAVE_@var{function} 5588For each @var{function} enumerated in the blank-or-newline-separated argument 5589list, define @code{HAVE_@var{function}} (in all capitals) if it is available. 5590This is a once-only variant of @code{AC_CHECK_FUNCS}. It generates the 5591checking code at most once, so that @command{configure} is smaller and 5592faster; but the checks cannot be conditionalized and are always done once, 5593early during the @command{configure} run. 5594@end defmac 5595 5596@sp 1 5597 5598Autoconf follows a philosophy that was formed over the years by those 5599who have struggled for portability: isolate the portability issues in 5600specific files, and then program as if you were in a Posix 5601environment. Some functions may be missing or unfixable, and your 5602package must be ready to replace them. 5603 5604Suitable replacements for many such problem functions are available from 5605Gnulib (@pxref{Gnulib}). 5606 5607@defmac AC_LIBOBJ (@var{function}) 5608@acindex{LIBOBJ} 5609@ovindex LIBOBJS 5610Specify that @samp{@var{function}.c} must be included in the executables 5611to replace a missing or broken implementation of @var{function}. 5612 5613@vrindex ac_objext 5614Technically, it adds @samp{@var{function}.$ac_objext} to the output 5615variable @code{LIBOBJS} if it is not already in, and calls 5616@code{AC_LIBSOURCE} for @samp{@var{function}.c}. You should not 5617directly change @code{LIBOBJS}, since this is not traceable. 5618@end defmac 5619 5620@defmac AC_LIBSOURCE (@var{file}) 5621@acindex{LIBSOURCE} 5622Specify that @var{file} might be needed to compile the project. If you 5623need to know what files might be needed by a @file{configure.ac}, you 5624should trace @code{AC_LIBSOURCE}. @var{file} must be a literal. 5625 5626This macro is called automatically from @code{AC_LIBOBJ}, but you must 5627call it explicitly if you pass a shell variable to @code{AC_LIBOBJ}. In 5628that case, since shell variables cannot be traced statically, you must 5629pass to @code{AC_LIBSOURCE} any possible files that the shell variable 5630might cause @code{AC_LIBOBJ} to need. For example, if you want to pass 5631a variable @code{$foo_or_bar} to @code{AC_LIBOBJ} that holds either 5632@code{"foo"} or @code{"bar"}, you should do: 5633 5634@example 5635AC_LIBSOURCE([foo.c]) 5636AC_LIBSOURCE([bar.c]) 5637AC_LIBOBJ([$foo_or_bar]) 5638@end example 5639 5640@noindent 5641There is usually a way to avoid this, however, and you are encouraged to 5642simply call @code{AC_LIBOBJ} with literal arguments. 5643 5644Note that this macro replaces the obsolete @code{AC_LIBOBJ_DECL}, with 5645slightly different semantics: the old macro took the function name, 5646e.g., @code{foo}, as its argument rather than the file name. 5647@end defmac 5648 5649@defmac AC_LIBSOURCES (@var{files}) 5650@acindex{LIBSOURCES} 5651Like @code{AC_LIBSOURCE}, but accepts one or more @var{files} in a 5652comma-separated M4 list. Thus, the above example might be rewritten: 5653 5654@example 5655AC_LIBSOURCES([foo.c, bar.c]) 5656AC_LIBOBJ([$foo_or_bar]) 5657@end example 5658@end defmac 5659 5660@defmac AC_CONFIG_LIBOBJ_DIR (@var{directory}) 5661@acindex{CONFIG_LIBOBJ_DIR} 5662Specify that @code{AC_LIBOBJ} replacement files are to be found in 5663@var{directory}, a name relative to the top level of the 5664source tree. The replacement directory defaults to @file{.}, the top 5665level directory, and the most typical value is @file{lib}, corresponding 5666to @samp{AC_CONFIG_LIBOBJ_DIR([lib])}. 5667 5668@command{configure} might need to know the replacement directory for the 5669following reasons: (i) some checks use the replacement files, (ii) some 5670macros bypass broken system headers by installing links to the 5671replacement headers (iii) when used in conjunction with Automake, 5672within each makefile, @var{directory} is used as a relative path 5673from @code{$(top_srcdir)} to each object named in @code{LIBOBJS} and 5674@code{LTLIBOBJS}, etc. 5675@end defmac 5676 5677@sp 1 5678 5679It is common to merely check for the existence of a function, and ask 5680for its @code{AC_LIBOBJ} replacement if missing. The following macro is 5681a convenient shorthand. 5682 5683@defmac AC_REPLACE_FUNCS (@var{function}@dots{}) 5684@acindex{REPLACE_FUNCS} 5685@cvindex HAVE_@var{function} 5686@ovindex LIBOBJS 5687Like @code{AC_CHECK_FUNCS}, but uses @samp{AC_LIBOBJ(@var{function})} as 5688@var{action-if-not-found}. You can declare your replacement function by 5689enclosing the prototype in @samp{#ifndef HAVE_@var{function}}. If the 5690system has the function, it probably declares it in a header file you 5691should be including, so you shouldn't redeclare it lest your declaration 5692conflict. 5693@end defmac 5694 5695@node Header Files 5696@section Header Files 5697@cindex Header, checking 5698 5699The following macros check for the presence of certain C header files. 5700If there is no macro specifically defined to check for a header file you need, 5701and you don't need to check for any special properties of 5702it, then you can use one of the general header-file check macros. 5703 5704@menu 5705* Header Portability:: Collected knowledge on common headers 5706* Particular Headers:: Special handling to find certain headers 5707* Generic Headers:: How to find other headers 5708@end menu 5709 5710@node Header Portability 5711@subsection Portability of Headers 5712@cindex Portability of headers 5713@cindex Header portability 5714 5715This section documents some collected knowledge about common headers, 5716and the problems they cause. By definition, this list always requires 5717additions. A much more complete list is maintained by the Gnulib 5718project (@pxref{Gnulib}), covering @ref{Header File Substitutes, , 5719Posix Headers, gnulib, GNU gnulib} and @ref{Glibc Header File 5720Substitutes, , Glibc Headers, gnulib, GNU gnulib}. Please help us keep 5721the gnulib list as complete as possible. 5722 5723@table @asis 5724 5725@item @file{limits.h} 5726C99 says that @file{limits.h} defines @code{LLONG_MIN}, 5727@code{LLONG_MAX}, and @code{ULLONG_MAX}, but many almost-C99 5728environments (e.g., default GCC 4.0.2 + glibc 2.4) do not 5729define them. 5730 5731@item @file{inttypes.h} vs.@: @file{stdint.h} 5732@hdrindex{inttypes.h} 5733@hdrindex{stdint.h} 5734The C99 standard says that @file{inttypes.h} includes 5735@file{stdint.h}, so there's no need to include @file{stdint.h} 5736separately in a standard environment. Some implementations have 5737@file{inttypes.h} but not @file{stdint.h} (e.g., Solaris 7), but we don't 5738know of any implementation that has @file{stdint.h} but not 5739@file{inttypes.h}. 5740 5741@item @file{linux/irda.h} 5742@hdrindex{linux/irda.h} 5743It requires @file{linux/types.h} and @file{sys/socket.h}. 5744 5745@item @file{linux/random.h} 5746@hdrindex{linux/random.h} 5747It requires @file{linux/types.h}. 5748 5749@item @file{net/if.h} 5750@hdrindex{net/if.h} 5751On Darwin, this file requires that @file{sys/socket.h} be included 5752beforehand. One should run: 5753 5754@example 5755AC_CHECK_HEADERS([sys/socket.h]) 5756AC_CHECK_HEADERS([net/if.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{netinet/if_ether.h} 5773@hdrindex{netinet/if_ether.h} 5774On Darwin, this file requires that @file{stdio.h} and 5775@file{sys/socket.h} be included beforehand. One should run: 5776 5777@example 5778AC_CHECK_HEADERS([sys/socket.h]) 5779AC_CHECK_HEADERS([netinet/if_ether.h], [], [], 5780[#include <stdio.h> 5781#ifdef STDC_HEADERS 5782# include <stdlib.h> 5783# include <stddef.h> 5784#else 5785# ifdef HAVE_STDLIB_H 5786# include <stdlib.h> 5787# endif 5788#endif 5789#ifdef HAVE_SYS_SOCKET_H 5790# include <sys/socket.h> 5791#endif 5792]) 5793@end example 5794 5795@item @file{stdint.h} 5796See above, item @file{inttypes.h} vs.@: @file{stdint.h}. 5797 5798@item @file{stdlib.h} 5799@hdrindex{stdlib.h} 5800On many systems (e.g., Darwin), @file{stdio.h} is a prerequisite. 5801 5802@item @file{sys/mount.h} 5803@hdrindex{sys/mount.h} 5804On FreeBSD 4.8 on ia32 and using gcc version 2.95.4, 5805@file{sys/params.h} is a prerequisite. 5806 5807@item @file{sys/ptem.h} 5808@hdrindex{sys/ptem.h} 5809On Solaris 8, @file{sys/stream.h} is a prerequisite. 5810 5811@item @file{sys/socket.h} 5812@hdrindex{sys/socket.h} 5813On Darwin, @file{stdlib.h} is a prerequisite. 5814 5815@item @file{sys/ucred.h} 5816@hdrindex{sys/ucred.h} 5817On Tru64 5.1, @file{sys/types.h} is a prerequisite. 5818 5819@item @file{X11/extensions/scrnsaver.h} 5820@hdrindex{X11/extensions/scrnsaver.h} 5821Using XFree86, this header requires @file{X11/Xlib.h}, which is probably 5822so required that you might not even consider looking for it. 5823 5824@example 5825AC_CHECK_HEADERS([X11/extensions/scrnsaver.h], [], [], 5826[[#include <X11/Xlib.h> 5827]]) 5828@end example 5829@end table 5830 5831 5832@node Particular Headers 5833@subsection Particular Header Checks 5834 5835These macros check for particular system header files---whether they 5836exist, and in some cases whether they declare certain symbols. 5837 5838@defmac AC_CHECK_HEADER_STDBOOL 5839@acindex{CHECK_HEADER_STDBOOL} 5840@cvindex HAVE__BOOL 5841@hdrindex{stdbool.h} 5842@caindex header_stdbool_h 5843Check whether @file{stdbool.h} exists and conforms to C99, and cache the 5844result in the @code{ac_cv_header_stdbool_h} variable. If the type 5845@code{_Bool} is defined, define @code{HAVE__BOOL} to 1. 5846 5847This macro is intended for use by Gnulib (@pxref{Gnulib}) and other 5848packages that supply a substitute @file{stdbool.h} on platforms lacking 5849a conforming one. The @code{AC_HEADER_STDBOOL} macro is better for code 5850that explicitly checks for @file{stdbool.h}. 5851@end defmac 5852 5853@defmac AC_HEADER_ASSERT 5854@acindex{HEADER_ASSERT} 5855@cvindex NDEBUG 5856@hdrindex{assert.h} 5857Check whether to enable assertions in the style of @file{assert.h}. 5858Assertions are enabled by default, but the user can override this by 5859invoking @command{configure} with the @option{--disable-assert} option. 5860@end defmac 5861 5862@anchor{AC_HEADER_DIRENT} 5863@defmac AC_HEADER_DIRENT 5864@acindex{HEADER_DIRENT} 5865@cvindex HAVE_DIRENT_H 5866@cvindex HAVE_NDIR_H 5867@cvindex HAVE_SYS_DIR_H 5868@cvindex HAVE_SYS_NDIR_H 5869@hdrindex{dirent.h} 5870@hdrindex{sys/ndir.h} 5871@hdrindex{sys/dir.h} 5872@hdrindex{ndir.h} 5873Check for the following header files. For the first one that is 5874found and defines @samp{DIR}, define the listed C preprocessor macro: 5875 5876@multitable {@file{sys/ndir.h}} {@code{HAVE_SYS_NDIR_H}} 5877@item @file{dirent.h} @tab @code{HAVE_DIRENT_H} 5878@item @file{sys/ndir.h} @tab @code{HAVE_SYS_NDIR_H} 5879@item @file{sys/dir.h} @tab @code{HAVE_SYS_DIR_H} 5880@item @file{ndir.h} @tab @code{HAVE_NDIR_H} 5881@end multitable 5882 5883The directory-library declarations in your source code should look 5884something like the following: 5885 5886@example 5887@group 5888#include <sys/types.h> 5889#ifdef HAVE_DIRENT_H 5890# include <dirent.h> 5891# define NAMLEN(dirent) strlen ((dirent)->d_name) 5892#else 5893# define dirent direct 5894# define NAMLEN(dirent) ((dirent)->d_namlen) 5895# ifdef HAVE_SYS_NDIR_H 5896# include <sys/ndir.h> 5897# endif 5898# ifdef HAVE_SYS_DIR_H 5899# include <sys/dir.h> 5900# endif 5901# ifdef HAVE_NDIR_H 5902# include <ndir.h> 5903# endif 5904#endif 5905@end group 5906@end example 5907 5908Using the above declarations, the program would declare variables to be 5909of type @code{struct dirent}, not @code{struct direct}, and would access 5910the length of a directory entry name by passing a pointer to a 5911@code{struct dirent} to the @code{NAMLEN} macro. 5912 5913This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries. 5914 5915This macro is obsolescent, as all current systems with directory 5916libraries have @code{<dirent.h>}. New programs need not use this macro. 5917 5918Also see @code{AC_STRUCT_DIRENT_D_INO} and 5919@code{AC_STRUCT_DIRENT_D_TYPE} (@pxref{Particular Structures}). 5920@end defmac 5921 5922@anchor{AC_HEADER_MAJOR} 5923@defmac AC_HEADER_MAJOR 5924@acindex{HEADER_MAJOR} 5925@cvindex MAJOR_IN_MKDEV 5926@cvindex MAJOR_IN_SYSMACROS 5927@hdrindex{sys/mkdev.h} 5928@hdrindex{sys/sysmacros.h} 5929If @file{sys/types.h} does not define @code{major}, @code{minor}, and 5930@code{makedev}, but @file{sys/mkdev.h} does, define 5931@code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define 5932@code{MAJOR_IN_SYSMACROS}. 5933@end defmac 5934 5935@defmac AC_HEADER_RESOLV 5936@acindex{HEADER_RESOLV} 5937@cvindex HAVE_RESOLV_H 5938@hdrindex{resolv.h} 5939Checks for header @file{resolv.h}, checking for prerequisites first. 5940To properly use @file{resolv.h}, your code should contain something like 5941the following: 5942 5943@verbatim 5944#ifdef HAVE_SYS_TYPES_H 5945# include <sys/types.h> 5946#endif 5947#ifdef HAVE_NETINET_IN_H 5948# include <netinet/in.h> /* inet_ functions / structs */ 5949#endif 5950#ifdef HAVE_ARPA_NAMESER_H 5951# include <arpa/nameser.h> /* DNS HEADER struct */ 5952#endif 5953#ifdef HAVE_NETDB_H 5954# include <netdb.h> 5955#endif 5956#include <resolv.h> 5957@end verbatim 5958@end defmac 5959 5960@anchor{AC_HEADER_STAT} 5961@defmac AC_HEADER_STAT 5962@acindex{HEADER_STAT} 5963@cvindex STAT_MACROS_BROKEN 5964@hdrindex{sys/stat.h} 5965If the macros @code{S_ISDIR}, @code{S_ISREG}, etc.@: defined in 5966@file{sys/stat.h} do not work properly (returning false positives), 5967define @code{STAT_MACROS_BROKEN}. This is the case on Tektronix UTekV, 5968Amdahl UTS and Motorola System V/88. 5969 5970This macro is obsolescent, as no current systems have the bug. 5971New programs need not use this macro. 5972@end defmac 5973 5974@defmac AC_HEADER_STDBOOL 5975@acindex{HEADER_STDBOOL} 5976@cvindex HAVE_STDBOOL_H 5977@cvindex HAVE__BOOL 5978@hdrindex{stdbool.h} 5979@caindex header_stdbool_h 5980If @file{stdbool.h} exists and conforms to C99, define 5981@code{HAVE_STDBOOL_H} to 1; if the type @code{_Bool} is defined, define 5982@code{HAVE__BOOL} to 1. To fulfill the C99 requirements, your 5983program could contain the following code: 5984 5985@example 5986@group 5987#ifdef HAVE_STDBOOL_H 5988# include <stdbool.h> 5989#else 5990# ifndef HAVE__BOOL 5991# ifdef __cplusplus 5992typedef bool _Bool; 5993# else 5994# define _Bool signed char 5995# endif 5996# endif 5997# define bool _Bool 5998# define false 0 5999# define true 1 6000# define __bool_true_false_are_defined 1 6001#endif 6002@end group 6003@end example 6004 6005Alternatively you can use the @samp{stdbool} package of Gnulib 6006(@pxref{Gnulib}). It simplifies your code so that it can say just 6007@code{#include <stdbool.h>}, and it adds support for less-common 6008platforms. 6009 6010This macro caches its result in the @code{ac_cv_header_stdbool_h} 6011variable. 6012 6013This macro differs from @code{AC_CHECK_HEADER_STDBOOL} only in that it 6014defines @code{HAVE_STDBOOL_H} whereas @code{AC_CHECK_HEADER_STDBOOL} 6015does not. 6016@end defmac 6017 6018@anchor{AC_HEADER_STDC} 6019@defmac AC_HEADER_STDC 6020@acindex{HEADER_STDC} 6021@cvindex STDC_HEADERS 6022@hdrindex{stdlib.h} 6023@hdrindex{stdarg.h} 6024@hdrindex{string.h} 6025@hdrindex{float.h} 6026@hdrindex{ctype.h} 6027@caindex header_stdc 6028Define @code{STDC_HEADERS} if the system has C header files 6029conforming to ANSI C89 (ISO C90). 6030Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h}, 6031@file{string.h}, and @file{float.h}; if the system has those, it 6032probably has the rest of the C89 header files. This macro also 6033checks whether @file{string.h} declares @code{memchr} (and thus 6034presumably the other @code{mem} functions), whether @file{stdlib.h} 6035declare @code{free} (and thus presumably @code{malloc} and other related 6036functions), and whether the @file{ctype.h} macros work on characters 6037with the high bit set, as the C standard requires. 6038 6039If you use this macro, your code can refer to @code{STDC_HEADERS} to 6040determine whether the system has conforming header files (and probably C 6041library functions). 6042 6043This macro caches its result in the @code{ac_cv_header_stdc} variable. 6044 6045This macro is obsolescent, as current systems have conforming header 6046files. New programs need not use this macro. 6047 6048@hdrindex{string.h} 6049@hdrindex{strings.h} 6050Nowadays @file{string.h} is part of the C standard and declares functions like 6051@code{strcpy}, and @file{strings.h} is standardized by Posix and declares 6052BSD functions like @code{bcopy}; but 6053historically, string functions were a major sticking point in this area. 6054If you still want to worry about portability to ancient systems without 6055standard headers, there is so much variation 6056that it is probably easier to declare the functions you use than to 6057figure out exactly what the system header files declare. Some ancient systems 6058contained a mix of functions from the C standard and from BSD; 6059some were mostly standard but lacked @samp{memmove}; some defined the 6060BSD functions as macros in @file{string.h} or 6061@file{strings.h}; some had only the BSD functions but 6062@file{string.h}; some declared the memory functions in @file{memory.h}, 6063some in @file{string.h}; etc. It is probably sufficient to check for 6064one string function and one memory function; if the library had the 6065standard versions of those then it probably had most of the others. 6066If you put the following in @file{configure.ac}: 6067 6068@example 6069# This example is obsolescent. 6070# Nowadays you can omit these macro calls. 6071AC_HEADER_STDC 6072AC_CHECK_FUNCS([strchr memcpy]) 6073@end example 6074 6075@noindent 6076then, in your code, you can use declarations like this: 6077 6078@example 6079@group 6080/* This example is obsolescent. 6081 Nowadays you can just #include <string.h>. */ 6082#ifdef STDC_HEADERS 6083# include <string.h> 6084#else 6085# ifndef HAVE_STRCHR 6086# define strchr index 6087# define strrchr rindex 6088# endif 6089char *strchr (), *strrchr (); 6090# ifndef HAVE_MEMCPY 6091# define memcpy(d, s, n) bcopy ((s), (d), (n)) 6092# define memmove(d, s, n) bcopy ((s), (d), (n)) 6093# endif 6094#endif 6095@end group 6096@end example 6097 6098@noindent 6099If you use a function like @code{memchr}, @code{memset}, @code{strtok}, 6100or @code{strspn}, which have no BSD equivalent, then macros don't 6101suffice to port to ancient hosts; you must provide an implementation of 6102each function. An easy 6103way to incorporate your implementations only when needed (since the ones 6104in system C libraries may be hand optimized) is to, taking @code{memchr} 6105for example, put it in @file{memchr.c} and use 6106@samp{AC_REPLACE_FUNCS([memchr])}. 6107@end defmac 6108 6109@defmac AC_HEADER_SYS_WAIT 6110@acindex{HEADER_SYS_WAIT} 6111@cvindex HAVE_SYS_WAIT_H 6112@hdrindex{sys/wait.h} 6113@caindex header_sys_wait_h 6114If @file{sys/wait.h} exists and is compatible with Posix, define 6115@code{HAVE_SYS_WAIT_H}. Incompatibility can occur if @file{sys/wait.h} 6116does not exist, or if it uses the old BSD @code{union wait} instead 6117of @code{int} to store a status value. If @file{sys/wait.h} is not 6118Posix compatible, then instead of including it, define the 6119Posix macros with their usual interpretations. Here is an 6120example: 6121 6122@example 6123@group 6124#include <sys/types.h> 6125#ifdef HAVE_SYS_WAIT_H 6126# include <sys/wait.h> 6127#endif 6128#ifndef WEXITSTATUS 6129# define WEXITSTATUS(stat_val) ((unsigned int) (stat_val) >> 8) 6130#endif 6131#ifndef WIFEXITED 6132# define WIFEXITED(stat_val) (((stat_val) & 255) == 0) 6133#endif 6134@end group 6135@end example 6136 6137@noindent 6138This macro caches its result in the @code{ac_cv_header_sys_wait_h} 6139variable. 6140 6141This macro is obsolescent, as current systems are compatible with Posix. 6142New programs need not use this macro. 6143@end defmac 6144 6145@cvindex _POSIX_VERSION 6146@hdrindex{unistd.h} 6147@code{_POSIX_VERSION} is defined when @file{unistd.h} is included on 6148Posix systems. If there is no @file{unistd.h}, it is definitely 6149not a Posix system. However, some non-Posix systems do 6150have @file{unistd.h}. 6151 6152The way to check whether the system supports Posix is: 6153 6154@example 6155@group 6156#ifdef HAVE_UNISTD_H 6157# include <sys/types.h> 6158# include <unistd.h> 6159#endif 6160 6161#ifdef _POSIX_VERSION 6162/* Code for Posix systems. */ 6163#endif 6164@end group 6165@end example 6166 6167@anchor{AC_HEADER_TIME} 6168@defmac AC_HEADER_TIME 6169@acindex{HEADER_TIME} 6170@cvindex TIME_WITH_SYS_TIME 6171@hdrindex{time.h} 6172@hdrindex{sys/time.h} 6173@caindex header_time 6174If a program may include both @file{time.h} and @file{sys/time.h}, 6175define @code{TIME_WITH_SYS_TIME}. On some ancient systems, 6176@file{sys/time.h} included @file{time.h}, but @file{time.h} was not 6177protected against multiple inclusion, so programs could not explicitly 6178include both files. This macro is useful in programs that use, for 6179example, @code{struct timeval} as well as 6180@code{struct tm}. It is best used in conjunction with 6181@code{HAVE_SYS_TIME_H}, which can be checked for using 6182@code{AC_CHECK_HEADERS([sys/time.h])}. 6183 6184@example 6185@group 6186#ifdef TIME_WITH_SYS_TIME 6187# include <sys/time.h> 6188# include <time.h> 6189#else 6190# ifdef HAVE_SYS_TIME_H 6191# include <sys/time.h> 6192# else 6193# include <time.h> 6194# endif 6195#endif 6196@end group 6197@end example 6198 6199@noindent 6200This macro caches its result in the @code{ac_cv_header_time} variable. 6201 6202This macro is obsolescent, as current systems can include both files 6203when they exist. New programs need not use this macro. 6204@end defmac 6205 6206 6207@defmac AC_HEADER_TIOCGWINSZ 6208@acindex{HEADER_TIOCGWINSZ} 6209@cvindex GWINSZ_IN_SYS_IOCTL 6210@hdrindex{sys/ioctl.h} 6211@hdrindex{termios.h} 6212@c FIXME: I need clarifications from Jim. 6213If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then 6214define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be 6215found in @file{<termios.h>}. 6216 6217Use: 6218 6219@example 6220@group 6221#ifdef HAVE_TERMIOS_H 6222# include <termios.h> 6223#endif 6224 6225#ifdef GWINSZ_IN_SYS_IOCTL 6226# include <sys/ioctl.h> 6227#endif 6228@end group 6229@end example 6230@end defmac 6231 6232@node Generic Headers 6233@subsection Generic Header Checks 6234 6235These macros are used to find system header files not covered by the 6236``particular'' test macros. If you need to check the contents of a header 6237as well as find out whether it is present, you have to write your own 6238test for it (@pxref{Writing Tests}). 6239 6240@anchor{AC_CHECK_HEADER} 6241@defmac AC_CHECK_HEADER (@var{header-file}, @ovar{action-if-found}, @ 6242 @ovar{action-if-not-found}, @ovar{includes}) 6243@acindex{CHECK_HEADER} 6244@caindex header_@var{header-file} 6245If the system header file @var{header-file} is compilable, execute shell 6246commands @var{action-if-found}, otherwise execute 6247@var{action-if-not-found}. If you just want to define a symbol if the 6248header file is available, consider using @code{AC_CHECK_HEADERS} 6249instead. 6250 6251@var{includes} is decoded to determine the appropriate include 6252directives. If omitted or empty, @file{configure} will check for both header 6253existence (with the preprocessor) and usability (with the compiler), 6254using @code{AC_INCLUDES_DEFAULT} for the compile test. If 6255there is a discrepancy between the results, a warning is issued to the 6256user, and the compiler results are favored (@pxref{Present But 6257Cannot Be Compiled}). In general, favoring the compiler results means 6258that a header will be treated as not found even though the file exists, 6259because you did not provide enough prerequisites. 6260 6261Providing a non-empty @var{includes} argument allows the code to provide 6262any prerequisites prior to including the header under test; it is common 6263to use the argument @code{AC_INCLUDES_DEFAULT} (@pxref{Default 6264Includes}). With an explicit fourth argument, no preprocessor test is 6265needed. As a special case, an @var{includes} of exactly @samp{-} 6266triggers the older preprocessor check, which merely determines existence 6267of the file in the preprocessor search path; this should only be used as 6268a last resort (it is safer to determine the actual prerequisites and 6269perform a compiler check, or else use @code{AC_PREPROC_IFELSE} to make 6270it obvious that only a preprocessor check is desired). 6271 6272This macro caches its result in the @code{ac_cv_header_@var{header-file}} 6273variable, with characters not suitable for a variable name mapped to 6274underscores. 6275@end defmac 6276 6277@anchor{AC_CHECK_HEADERS} 6278@defmac AC_CHECK_HEADERS (@var{header-file}@dots{}, @ 6279 @ovar{action-if-found}, @ovar{action-if-not-found}, @ 6280 @ovar{includes}) 6281@acindex{CHECK_HEADERS} 6282@cvindex HAVE_@var{header} 6283@caindex header_@var{header-file} 6284For each given system header file @var{header-file} in the 6285blank-separated argument list that exists, define 6286@code{HAVE_@var{header-file}} (in all capitals). If @var{action-if-found} 6287is given, it is additional shell code to execute when one of the header 6288files is found. You can give it a value of @samp{break} to break out of 6289the loop on the first match. If @var{action-if-not-found} is given, it 6290is executed when one of the header files is not found. 6291 6292@var{includes} is interpreted as in @code{AC_CHECK_HEADER}, in order to 6293choose the set of preprocessor directives supplied before the header 6294under test. 6295 6296This macro caches its result in the @code{ac_cv_header_@var{header-file}} 6297variable, with characters not suitable for a variable name mapped to 6298underscores. 6299@end defmac 6300 6301Previous versions of Autoconf merely checked whether the header was 6302accepted by the preprocessor. This was changed because the old test was 6303inappropriate for typical uses. Headers are typically used to compile, 6304not merely to preprocess, and the old behavior sometimes accepted 6305headers that clashed at compile-time (@pxref{Present But Cannot Be 6306Compiled}). If you need to check whether a header is preprocessable, 6307you can use @code{AC_PREPROC_IFELSE} (@pxref{Running the Preprocessor}). 6308 6309Actually requiring a header to compile improves the robustness of the 6310test, but it also requires 6311that you make sure that headers that must be included before the 6312@var{header-file} be part of the @var{includes}, (@pxref{Default 6313Includes}). If looking for @file{bar.h}, which requires that 6314@file{foo.h} be included before if it exists, we suggest the following 6315scheme: 6316 6317@verbatim 6318AC_CHECK_HEADERS([foo.h]) 6319AC_CHECK_HEADERS([bar.h], [], [], 6320[#ifdef HAVE_FOO_H 6321# include <foo.h> 6322#endif 6323]) 6324@end verbatim 6325 6326The following variant generates smaller, faster @command{configure} 6327files if you do not need the full power of @code{AC_CHECK_HEADERS}. 6328 6329@defmac AC_CHECK_HEADERS_ONCE (@var{header-file}@dots{}) 6330@acindex{CHECK_HEADERS_ONCE} 6331@cvindex HAVE_@var{header} 6332For each given system header file @var{header-file} in the 6333blank-separated argument list that exists, define 6334@code{HAVE_@var{header-file}} (in all capitals). 6335This is a once-only variant of @code{AC_CHECK_HEADERS}. It generates the 6336checking code at most once, so that @command{configure} is smaller and 6337faster; but the checks cannot be conditionalized and are always done once, 6338early during the @command{configure} run. Thus, this macro is only safe 6339for checking headers that do not have prerequisites beyond what 6340@code{AC_INCLUDES_DEFAULT} provides. 6341@end defmac 6342 6343@node Declarations 6344@section Declarations 6345@cindex Declaration, checking 6346 6347The following macros check for the declaration of variables and 6348functions. If there is no macro specifically defined to check for a 6349symbol you need, then you can use the general macros (@pxref{Generic 6350Declarations}) or, for more complex tests, you may use 6351@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}). 6352 6353@menu 6354* Particular Declarations:: Macros to check for certain declarations 6355* Generic Declarations:: How to find other declarations 6356@end menu 6357 6358@node Particular Declarations 6359@subsection Particular Declaration Checks 6360 6361There are no specific macros for declarations. 6362 6363@node Generic Declarations 6364@subsection Generic Declaration Checks 6365 6366These macros are used to find declarations not covered by the ``particular'' 6367test macros. 6368 6369@defmac AC_CHECK_DECL (@var{symbol}, @ovar{action-if-found}, @ 6370 @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT}) 6371@acindex{CHECK_DECL} 6372@caindex have_decl_@var{symbol} 6373If @var{symbol} (a function, variable, or constant) is not declared in 6374@var{includes} and a declaration is needed, run the shell commands 6375@var{action-if-not-found}, otherwise @var{action-if-found}. 6376@var{includes} is a series of include directives, defaulting to 6377@code{AC_INCLUDES_DEFAULT} (@pxref{Default Includes}), which are used 6378prior to the declaration under test. 6379 6380This macro actually tests whether @var{symbol} is defined as a macro or 6381can be used as an r-value, not whether it is really declared, because it 6382is much safer to avoid introducing extra declarations when they are not 6383needed. In order to facilitate use of C++ and overloaded function 6384declarations, it is possible to specify function argument types in 6385parentheses for types which can be zero-initialized: 6386 6387@example 6388AC_CHECK_DECL([basename(char *)]) 6389@end example 6390 6391This macro caches its result in the @code{ac_cv_have_decl_@var{symbol}} 6392variable, with characters not suitable for a variable name mapped to 6393underscores. 6394@end defmac 6395 6396@anchor{AC_CHECK_DECLS} 6397@defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @ 6398 @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT}) 6399@acindex{CHECK_DECLS} 6400@cvindex HAVE_DECL_@var{symbol} 6401@caindex have_decl_@var{symbol} 6402For each of the @var{symbols} (@emph{comma}-separated list with optional 6403function argument types for C++ overloads), define 6404@code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if 6405@var{symbol} is declared, otherwise to @samp{0}. If 6406@var{action-if-not-found} is given, it is additional shell code to 6407execute when one of the function declarations is needed, otherwise 6408@var{action-if-found} is executed. 6409 6410@var{includes} is a series of include directives, defaulting to 6411@code{AC_INCLUDES_DEFAULT} (@pxref{Default Includes}), which are used 6412prior to the declarations under test. 6413 6414This macro uses an M4 list as first argument: 6415@example 6416AC_CHECK_DECLS([strdup]) 6417AC_CHECK_DECLS([strlen]) 6418AC_CHECK_DECLS([malloc, realloc, calloc, free]) 6419AC_CHECK_DECLS([j0], [], [], [[#include <math.h>]]) 6420AC_CHECK_DECLS([[basename(char *)], [dirname(char *)]]) 6421@end example 6422 6423Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not 6424declared, @code{HAVE_DECL_@var{symbol}} is defined to @samp{0} instead 6425of leaving @code{HAVE_DECL_@var{symbol}} undeclared. When you are 6426@emph{sure} that the check was performed, use 6427@code{HAVE_DECL_@var{symbol}} in @code{#if}: 6428 6429@example 6430#if !HAVE_DECL_SYMBOL 6431extern char *symbol; 6432#endif 6433@end example 6434 6435@noindent 6436If the test may have not been performed, however, because it is safer 6437@emph{not} to declare a symbol than to use a declaration that conflicts 6438with the system's one, you should use: 6439 6440@example 6441#if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC 6442void *malloc (size_t *s); 6443#endif 6444@end example 6445 6446@noindent 6447You fall into the second category only in extreme situations: either 6448your files may be used without being configured, or they are used during 6449the configuration. In most cases the traditional approach is enough. 6450 6451This macro caches its results in @code{ac_cv_have_decl_@var{symbol}} 6452variables, with characters not suitable for a variable name mapped to 6453underscores. 6454@end defmac 6455 6456@defmac AC_CHECK_DECLS_ONCE (@var{symbols}) 6457@acindex{CHECK_DECLS_ONCE} 6458@cvindex HAVE_DECL_@var{symbol} 6459For each of the @var{symbols} (@emph{comma}-separated list), define 6460@code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if 6461@var{symbol} is declared in the default include files, otherwise to 6462@samp{0}. This is a once-only variant of @code{AC_CHECK_DECLS}. It 6463generates the checking code at most once, so that @command{configure} is 6464smaller and faster; but the checks cannot be conditionalized and are 6465always done once, early during the @command{configure} run. 6466@end defmac 6467 6468 6469@node Structures 6470@section Structures 6471@cindex Structure, checking 6472 6473The following macros check for the presence of certain members in C 6474structures. If there is no macro specifically defined to check for a 6475member you need, then you can use the general structure-member macros 6476(@pxref{Generic Structures}) or, for more complex tests, you may use 6477@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}). 6478 6479@menu 6480* Particular Structures:: Macros to check for certain structure members 6481* Generic Structures:: How to find other structure members 6482@end menu 6483 6484@node Particular Structures 6485@subsection Particular Structure Checks 6486 6487The following macros check for certain structures or structure members. 6488 6489@defmac AC_STRUCT_DIRENT_D_INO 6490@acindex{STRUCT_DIRENT_D_INO} 6491@cvindex HAVE_STRUCT_DIRENT_D_INO 6492@c @caindex header_dirent_dirent_h 6493@c @caindex member_struct_dirent_d_ino 6494Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular 6495Headers}). Then, if @code{struct dirent} contains a @code{d_ino} 6496member, define @code{HAVE_STRUCT_DIRENT_D_INO}. 6497 6498@code{HAVE_STRUCT_DIRENT_D_INO} indicates only the presence of 6499@code{d_ino}, not whether its contents are always reliable. 6500Traditionally, a zero @code{d_ino} indicated a deleted directory entry, 6501though current systems hide this detail from the user and never return 6502zero @code{d_ino} values. 6503Many current systems report an incorrect @code{d_ino} for a directory 6504entry that is a mount point. 6505@end defmac 6506 6507@defmac AC_STRUCT_DIRENT_D_TYPE 6508@acindex{STRUCT_DIRENT_D_TYPE} 6509@cvindex HAVE_STRUCT_DIRENT_D_TYPE 6510@c @caindex header_dirent_dirent_h 6511@c @caindex member_struct_dirent_d_type 6512Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular 6513Headers}). Then, if @code{struct dirent} contains a @code{d_type} 6514member, define @code{HAVE_STRUCT_DIRENT_D_TYPE}. 6515@end defmac 6516 6517@anchor{AC_STRUCT_ST_BLOCKS} 6518@defmac AC_STRUCT_ST_BLOCKS 6519@acindex{STRUCT_ST_BLOCKS} 6520@cvindex HAVE_STRUCT_STAT_ST_BLOCKS 6521@cvindex HAVE_ST_BLOCKS 6522@ovindex LIBOBJS 6523@caindex member_struct_stat_st_blocks 6524If @code{struct stat} contains an @code{st_blocks} member, define 6525@code{HAVE_STRUCT_STAT_ST_BLOCKS}. Otherwise, require an 6526@code{AC_LIBOBJ} replacement of @samp{fileblocks}. The former name, 6527@code{HAVE_ST_BLOCKS} is to be avoided, as its support will cease in the 6528future. 6529 6530This macro caches its result in the @code{ac_cv_member_struct_stat_st_blocks} 6531variable. 6532@end defmac 6533 6534@defmac AC_STRUCT_TM 6535@acindex{STRUCT_TM} 6536@cvindex TM_IN_SYS_TIME 6537@hdrindex{time.h} 6538@hdrindex{sys/time.h} 6539If @file{time.h} does not define @code{struct tm}, define 6540@code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h} 6541had better define @code{struct tm}. 6542 6543This macro is obsolescent, as @file{time.h} defines @code{struct tm} in 6544current systems. New programs need not use this macro. 6545@end defmac 6546 6547@anchor{AC_STRUCT_TIMEZONE} 6548@defmac AC_STRUCT_TIMEZONE 6549@acindex{STRUCT_TIMEZONE} 6550@cvindex HAVE_DECL_TZNAME 6551@cvindex HAVE_STRUCT_TM_TM_ZONE 6552@cvindex HAVE_TM_ZONE 6553@cvindex HAVE_TZNAME 6554@c @caindex member_struct_tm_tm_zone 6555@c @caindex struct_tm 6556Figure out how to get the current timezone. If @code{struct tm} has a 6557@code{tm_zone} member, define @code{HAVE_STRUCT_TM_TM_ZONE} (and the 6558obsoleted @code{HAVE_TM_ZONE}). Otherwise, if the external array 6559@code{tzname} is found, define @code{HAVE_TZNAME}; if it is declared, 6560define @code{HAVE_DECL_TZNAME}. 6561@end defmac 6562 6563@node Generic Structures 6564@subsection Generic Structure Checks 6565 6566These macros are used to find structure members not covered by the 6567``particular'' test macros. 6568 6569@defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @ 6570 @ovar{action-if-found}, @ovar{action-if-not-found}, @ 6571 @dvar{includes, AC_INCLUDES_DEFAULT}) 6572@acindex{CHECK_MEMBER} 6573@caindex member_@var{aggregate}_@var{member} 6574Check whether @var{member} is a member of the aggregate @var{aggregate}. 6575If no @var{includes} are specified, the default includes are used 6576(@pxref{Default Includes}). 6577 6578@example 6579AC_CHECK_MEMBER([struct passwd.pw_gecos], [], 6580 [AC_MSG_ERROR([we need `passwd.pw_gecos'])], 6581 [[#include <pwd.h>]]) 6582@end example 6583 6584You can use this macro for submembers: 6585 6586@example 6587AC_CHECK_MEMBER(struct top.middle.bot) 6588@end example 6589 6590This macro caches its result in the 6591@code{ac_cv_member_@var{aggregate}_@var{member}} variable, with 6592characters not suitable for a variable name mapped to underscores. 6593@end defmac 6594 6595@anchor{AC_CHECK_MEMBERS} 6596@defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @ 6597 @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT}) 6598@acindex{CHECK_MEMBERS} 6599@cvindex HAVE_@var{aggregate}_@var{member} 6600Check for the existence of each @samp{@var{aggregate}.@var{member}} of 6601@var{members} using the previous macro. When @var{member} belongs to 6602@var{aggregate}, define @code{HAVE_@var{aggregate}_@var{member}} (in all 6603capitals, with spaces and dots replaced by underscores). If 6604@var{action-if-found} is given, it is executed for each of the found 6605members. If @var{action-if-not-found} is given, it is executed for each 6606of the members that could not be found. 6607 6608@var{includes} is a series of include directives, defaulting to 6609@code{AC_INCLUDES_DEFAULT} (@pxref{Default Includes}), which are used 6610prior to the members under test. 6611 6612This macro uses M4 lists: 6613@example 6614AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize]) 6615@end example 6616@end defmac 6617 6618 6619@node Types 6620@section Types 6621@cindex Types 6622@cindex C types 6623 6624The following macros check for C types, either builtin or typedefs. If 6625there is no macro specifically defined to check for a type you need, and 6626you don't need to check for any special properties of it, then you can 6627use a general type-check macro. 6628 6629@menu 6630* Particular Types:: Special handling to find certain types 6631* Generic Types:: How to find other types 6632@end menu 6633 6634@node Particular Types 6635@subsection Particular Type Checks 6636 6637@hdrindex{sys/types.h} 6638@hdrindex{stdlib.h} 6639@hdrindex{stdint.h} 6640@hdrindex{inttypes.h} 6641These macros check for particular C types in @file{sys/types.h}, 6642@file{stdlib.h}, @file{stdint.h}, @file{inttypes.h} and others, if they 6643exist. 6644 6645The Gnulib @code{stdint} module is an alternate way to define many of 6646these symbols; it is useful if you prefer your code to assume a 6647C99-or-better environment. @xref{Gnulib}. 6648 6649@anchor{AC_TYPE_GETGROUPS} 6650@defmac AC_TYPE_GETGROUPS 6651@acindex{TYPE_GETGROUPS} 6652@cvindex GETGROUPS_T 6653@caindex type_getgroups 6654Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int} 6655is the base type of the array argument to @code{getgroups}. 6656 6657This macro caches the base type in the @code{ac_cv_type_getgroups} 6658variable. 6659@end defmac 6660 6661@defmac AC_TYPE_INT8_T 6662@acindex{TYPE_INT8_T} 6663@cvindex HAVE_INT8_T 6664@cvindex int8_t 6665@caindex c_int8_t 6666If @file{stdint.h} or @file{inttypes.h} does not define the type 6667@code{int8_t}, define @code{int8_t} to a signed 6668integer type that is exactly 8 bits wide and that uses two's complement 6669representation, if such a type exists. 6670If you are worried about porting to hosts that lack such a type, you can 6671use the results of this macro in C89-or-later code as follows: 6672 6673@example 6674#if HAVE_STDINT_H 6675# include <stdint.h> 6676#endif 6677#if defined INT8_MAX || defined int8_t 6678 @emph{code using int8_t} 6679#else 6680 @emph{complicated alternative using >8-bit 'signed char'} 6681#endif 6682@end example 6683 6684This macro caches the type in the @code{ac_cv_c_int8_t} variable. 6685@end defmac 6686 6687@defmac AC_TYPE_INT16_T 6688@acindex{TYPE_INT16_T} 6689@cvindex HAVE_INT16_T 6690@cvindex int16_t 6691@caindex c_int16_t 6692This is like @code{AC_TYPE_INT8_T}, except for 16-bit integers. 6693@end defmac 6694 6695@defmac AC_TYPE_INT32_T 6696@acindex{TYPE_INT32_T} 6697@cvindex HAVE_INT32_T 6698@cvindex int32_t 6699@caindex c_int32_t 6700This is like @code{AC_TYPE_INT8_T}, except for 32-bit integers. 6701@end defmac 6702 6703@defmac AC_TYPE_INT64_T 6704@acindex{TYPE_INT64_T} 6705@cvindex HAVE_INT64_T 6706@cvindex int64_t 6707@caindex c_int64_t 6708This is like @code{AC_TYPE_INT8_T}, except for 64-bit integers. 6709@end defmac 6710 6711@defmac AC_TYPE_INTMAX_T 6712@acindex{TYPE_INTMAX_T} 6713@cvindex HAVE_INTMAX_T 6714@cvindex intmax_t 6715@c @caindex type_intmax_t 6716If @file{stdint.h} or @file{inttypes.h} defines the type @code{intmax_t}, 6717define @code{HAVE_INTMAX_T}. Otherwise, define @code{intmax_t} to the 6718widest signed integer type. 6719@end defmac 6720 6721@defmac AC_TYPE_INTPTR_T 6722@acindex{TYPE_INTPTR_T} 6723@cvindex HAVE_INTPTR_T 6724@cvindex intptr_t 6725@c @caindex type_intptr_t 6726If @file{stdint.h} or @file{inttypes.h} defines the type @code{intptr_t}, 6727define @code{HAVE_INTPTR_T}. Otherwise, define @code{intptr_t} to a 6728signed integer type wide enough to hold a pointer, if such a type 6729exists. 6730@end defmac 6731 6732@defmac AC_TYPE_LONG_DOUBLE 6733@acindex{TYPE_LONG_DOUBLE} 6734@cvindex HAVE_LONG_DOUBLE 6735@caindex type_long_double 6736If the C compiler supports a working @code{long double} type, define 6737@code{HAVE_LONG_DOUBLE}. The @code{long double} type might have the 6738same range and precision as @code{double}. 6739 6740This macro caches its result in the @code{ac_cv_type_long_double} 6741variable. 6742 6743This macro is obsolescent, as current C compilers support @code{long 6744double}. New programs need not use this macro. 6745@end defmac 6746 6747@defmac AC_TYPE_LONG_DOUBLE_WIDER 6748@acindex{TYPE_LONG_DOUBLE_WIDER} 6749@cvindex HAVE_LONG_DOUBLE_WIDER 6750@caindex type_long_double_wider 6751If the C compiler supports a working @code{long double} type with more 6752range or precision than the @code{double} type, define 6753@code{HAVE_LONG_DOUBLE_WIDER}. 6754 6755This macro caches its result in the @code{ac_cv_type_long_double_wider} 6756variable. 6757@end defmac 6758 6759@defmac AC_TYPE_LONG_LONG_INT 6760@acindex{TYPE_LONG_LONG_INT} 6761@cvindex HAVE_LONG_LONG_INT 6762@caindex type_long_long_int 6763If the C compiler supports a working @code{long long int} type, define 6764@code{HAVE_LONG_LONG_INT}. However, this test does not test 6765@code{long long int} values in preprocessor @code{#if} expressions, 6766because too many compilers mishandle such expressions. 6767@xref{Preprocessor Arithmetic}. 6768 6769This macro caches its result in the @code{ac_cv_type_long_long_int} 6770variable. 6771@end defmac 6772 6773@defmac AC_TYPE_MBSTATE_T 6774@acindex{TYPE_MBSTATE_T} 6775@cvindex mbstate_t 6776@hdrindex{wchar.h} 6777@caindex type_mbstate_t 6778Define @code{HAVE_MBSTATE_T} if @code{<wchar.h>} declares the 6779@code{mbstate_t} type. Also, define @code{mbstate_t} to be a type if 6780@code{<wchar.h>} does not declare it. 6781 6782This macro caches its result in the @code{ac_cv_type_mbstate_t} 6783variable. 6784@end defmac 6785 6786@anchor{AC_TYPE_MODE_T} 6787@defmac AC_TYPE_MODE_T 6788@acindex{TYPE_MODE_T} 6789@cvindex mode_t 6790@caindex type_mode_t 6791Define @code{mode_t} to a suitable type, if standard headers do not 6792define it. 6793 6794This macro caches its result in the @code{ac_cv_type_mode_t} variable. 6795@end defmac 6796 6797@anchor{AC_TYPE_OFF_T} 6798@defmac AC_TYPE_OFF_T 6799@acindex{TYPE_OFF_T} 6800@cvindex off_t 6801@caindex type_off_t 6802Define @code{off_t} to a suitable type, if standard headers do not 6803define it. 6804 6805This macro caches its result in the @code{ac_cv_type_off_t} variable. 6806@end defmac 6807 6808@anchor{AC_TYPE_PID_T} 6809@defmac AC_TYPE_PID_T 6810@acindex{TYPE_PID_T} 6811@cvindex pid_t 6812@caindex type_pid_t 6813Define @code{pid_t} to a suitable type, if standard headers do not 6814define it. 6815 6816This macro caches its result in the @code{ac_cv_type_pid_t} variable. 6817@end defmac 6818 6819@anchor{AC_TYPE_SIZE_T} 6820@defmac AC_TYPE_SIZE_T 6821@acindex{TYPE_SIZE_T} 6822@cvindex size_t 6823@caindex type_size_t 6824Define @code{size_t} to a suitable type, if standard headers do not 6825define it. 6826 6827This macro caches its result in the @code{ac_cv_type_size_t} variable. 6828@end defmac 6829 6830@defmac AC_TYPE_SSIZE_T 6831@acindex{TYPE_SSIZE_T} 6832@cvindex ssize_t 6833@caindex type_ssize_t 6834Define @code{ssize_t} to a suitable type, if standard headers do not 6835define it. 6836 6837This macro caches its result in the @code{ac_cv_type_ssize_t} variable. 6838@end defmac 6839 6840@anchor{AC_TYPE_UID_T} 6841@defmac AC_TYPE_UID_T 6842@acindex{TYPE_UID_T} 6843@cvindex uid_t 6844@cvindex gid_t 6845@caindex type_uid_t 6846Define @code{uid_t} and @code{gid_t} to suitable types, if standard 6847headers do not define them. 6848 6849This macro caches its result in the @code{ac_cv_type_uid_t} variable. 6850@end defmac 6851 6852@defmac AC_TYPE_UINT8_T 6853@acindex{TYPE_UINT8_T} 6854@cvindex HAVE_UINT8_T 6855@cvindex uint8_t 6856@caindex c_uint8_t 6857If @file{stdint.h} or @file{inttypes.h} does not define the type 6858@code{uint8_t}, define @code{uint8_t} to an 6859unsigned integer type that is exactly 8 bits wide, if such a type 6860exists. 6861This is like @code{AC_TYPE_INT8_T}, except for unsigned integers. 6862@end defmac 6863 6864@defmac AC_TYPE_UINT16_T 6865@acindex{TYPE_UINT16_T} 6866@cvindex HAVE_UINT16_T 6867@cvindex uint16_t 6868@caindex c_uint16_t 6869This is like @code{AC_TYPE_UINT8_T}, except for 16-bit integers. 6870@end defmac 6871 6872@defmac AC_TYPE_UINT32_T 6873@acindex{TYPE_UINT32_T} 6874@cvindex HAVE_UINT32_T 6875@cvindex uint32_t 6876@caindex c_uint32_t 6877This is like @code{AC_TYPE_UINT8_T}, except for 32-bit integers. 6878@end defmac 6879 6880@defmac AC_TYPE_UINT64_T 6881@acindex{TYPE_UINT64_T} 6882@cvindex HAVE_UINT64_T 6883@cvindex uint64_t 6884@caindex c_uint64_t 6885This is like @code{AC_TYPE_UINT8_T}, except for 64-bit integers. 6886@end defmac 6887 6888@defmac AC_TYPE_UINTMAX_T 6889@acindex{TYPE_UINTMAX_T} 6890@cvindex HAVE_UINTMAX_T 6891@cvindex uintmax_t 6892@c @caindex type_uintmax_t 6893If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintmax_t}, 6894define @code{HAVE_UINTMAX_T}. Otherwise, define @code{uintmax_t} to the 6895widest unsigned integer type. 6896@end defmac 6897 6898@defmac AC_TYPE_UINTPTR_T 6899@acindex{TYPE_UINTPTR_T} 6900@cvindex HAVE_UINTPTR_T 6901@cvindex uintptr_t 6902@c @caindex type_uintptr_t 6903If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintptr_t}, 6904define @code{HAVE_UINTPTR_T}. Otherwise, define @code{uintptr_t} to an 6905unsigned integer type wide enough to hold a pointer, if such a type 6906exists. 6907@end defmac 6908 6909@defmac AC_TYPE_UNSIGNED_LONG_LONG_INT 6910@acindex{TYPE_UNSIGNED_LONG_LONG_INT} 6911@cvindex HAVE_UNSIGNED_LONG_LONG_INT 6912@caindex type_unsigned_long_long_int 6913If the C compiler supports a working @code{unsigned long long int} type, 6914define @code{HAVE_UNSIGNED_LONG_LONG_INT}. However, this test does not test 6915@code{unsigned long long int} values in preprocessor @code{#if} expressions, 6916because too many compilers mishandle such expressions. 6917@xref{Preprocessor Arithmetic}. 6918 6919This macro caches its result in the @code{ac_cv_type_unsigned_long_long_int} 6920variable. 6921@end defmac 6922 6923@node Generic Types 6924@subsection Generic Type Checks 6925 6926These macros are used to check for types not covered by the ``particular'' 6927test macros. 6928 6929@defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @ 6930 @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT}) 6931@acindex{CHECK_TYPE} 6932@caindex type_@var{type} 6933Check whether @var{type} is defined. It may be a compiler builtin type 6934or defined by the @var{includes}. @var{includes} is a series of include 6935directives, defaulting to @code{AC_INCLUDES_DEFAULT} (@pxref{Default 6936Includes}), which are used prior to the type under test. 6937 6938In C, @var{type} must be a type-name, so that the expression @samp{sizeof 6939(@var{type})} is valid (but @samp{sizeof ((@var{type}))} is not). The 6940same test is applied when compiling for C++, which means that in C++ 6941@var{type} should be a type-id and should not be an anonymous 6942@samp{struct} or @samp{union}. 6943 6944This macro caches its result in the @code{ac_cv_type_@var{type}} 6945variable, with @samp{*} mapped to @samp{p} and other characters not 6946suitable for a variable name mapped to underscores. 6947@end defmac 6948 6949 6950@defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @ 6951 @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT}) 6952@acindex{CHECK_TYPES} 6953@cvindex HAVE_@var{type} 6954For each @var{type} of the @var{types} that is defined, define 6955@code{HAVE_@var{type}} (in all capitals). Each @var{type} must follow 6956the rules of @code{AC_CHECK_TYPE}. If no @var{includes} are 6957specified, the default includes are used (@pxref{Default Includes}). If 6958@var{action-if-found} is given, it is additional shell code to execute 6959when one of the types is found. If @var{action-if-not-found} is given, 6960it is executed when one of the types is not found. 6961 6962This macro uses M4 lists: 6963@example 6964AC_CHECK_TYPES([ptrdiff_t]) 6965AC_CHECK_TYPES([unsigned long long int, uintmax_t]) 6966AC_CHECK_TYPES([float_t], [], [], [[#include <math.h>]]) 6967@end example 6968 6969@end defmac 6970 6971Autoconf, up to 2.13, used to provide to another version of 6972@code{AC_CHECK_TYPE}, broken by design. In order to keep backward 6973compatibility, a simple heuristic, quite safe but not totally, is 6974implemented. In case of doubt, read the documentation of the former 6975@code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}. 6976 6977 6978@node Compilers and Preprocessors 6979@section Compilers and Preprocessors 6980@cindex Compilers 6981@cindex Preprocessors 6982 6983@ovindex EXEEXT 6984All the tests for compilers (@code{AC_PROG_CC}, @code{AC_PROG_CXX}, 6985@code{AC_PROG_F77}) define the output variable @code{EXEEXT} based on 6986the output of the compiler, typically to the empty string if 6987Posix and @samp{.exe} if a DOS variant. 6988 6989@ovindex OBJEXT 6990They also define the output variable @code{OBJEXT} based on the 6991output of the compiler, after @file{.c} files have been excluded, typically 6992to @samp{o} if Posix, @samp{obj} if a DOS variant. 6993 6994If the compiler being used does not produce executables, the tests fail. If 6995the executables can't be run, and cross-compilation is not enabled, they 6996fail too. @xref{Manual Configuration}, for more on support for cross 6997compiling. 6998 6999@menu 7000* Specific Compiler Characteristics:: Some portability issues 7001* Generic Compiler Characteristics:: Language independent tests and features 7002* C Compiler:: Checking its characteristics 7003* C++ Compiler:: Likewise 7004* Objective C Compiler:: Likewise 7005* Objective C++ Compiler:: Likewise 7006* Erlang Compiler and Interpreter:: Likewise 7007* Fortran Compiler:: Likewise 7008* Go Compiler:: Likewise 7009@end menu 7010 7011@node Specific Compiler Characteristics 7012@subsection Specific Compiler Characteristics 7013 7014Some compilers exhibit different behaviors. 7015 7016@table @asis 7017@item Static/Dynamic Expressions 7018Autoconf relies on a trick to extract one bit of information from the C 7019compiler: using negative array sizes. For instance the following 7020excerpt of a C source demonstrates how to test whether @samp{int} objects are 4 7021bytes wide: 7022 7023@example 7024static int test_array[sizeof (int) == 4 ? 1 : -1]; 7025@end example 7026 7027@noindent 7028To our knowledge, there is a single compiler that does not support this 7029trick: the HP C compilers (the real ones, not only the 7030``bundled'') on HP-UX 11.00. 7031They incorrectly reject the above program with the diagnostic 7032``Variable-length arrays cannot have static storage.'' 7033This bug comes from HP compilers' mishandling of @code{sizeof (int)}, 7034not from the @code{? 1 : -1}, and 7035Autoconf works around this problem by casting @code{sizeof (int)} to 7036@code{long int} before comparing it. 7037@end table 7038 7039@node Generic Compiler Characteristics 7040@subsection Generic Compiler Characteristics 7041 7042@anchor{AC_CHECK_SIZEOF} 7043@defmac AC_CHECK_SIZEOF (@var{type-or-expr}, @ovar{unused}, @ 7044 @dvar{includes, AC_INCLUDES_DEFAULT}) 7045@acindex{CHECK_SIZEOF} 7046@cvindex SIZEOF_@var{type-or-expr} 7047@caindex sizeof_@var{type-or-expr} 7048Define @code{SIZEOF_@var{type-or-expr}} (@pxref{Standard Symbols}) to be 7049the size in bytes of @var{type-or-expr}, which may be either a type or 7050an expression returning a value that has a size. If the expression 7051@samp{sizeof (@var{type-or-expr})} is invalid, the result is 0. 7052@var{includes} is a series of include directives, defaulting to 7053@code{AC_INCLUDES_DEFAULT} (@pxref{Default Includes}), which are used 7054prior to the expression under test. 7055 7056This macro now works even when cross-compiling. The @var{unused} 7057argument was used when cross-compiling. 7058 7059For example, the call 7060 7061@example 7062@c If you change this example, adjust tests/semantics.at:AC_CHECK_SIZEOF struct. 7063AC_CHECK_SIZEOF([int *]) 7064@end example 7065 7066@noindent 7067defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems. 7068 7069This macro caches its result in the @code{ac_cv_sizeof_@var{type-or-expr}} 7070variable, with @samp{*} mapped to @samp{p} and other characters not 7071suitable for a variable name mapped to underscores. 7072@end defmac 7073 7074@defmac AC_CHECK_ALIGNOF (@var{type}, @dvar{includes, AC_INCLUDES_DEFAULT}) 7075@acindex{CHECK_ALIGNOF} 7076@cvindex ALIGNOF_@var{type} 7077@caindex alignof_@var{type-or-expr} 7078Define @code{ALIGNOF_@var{type}} (@pxref{Standard Symbols}) to be the 7079alignment in bytes of @var{type}. @samp{@var{type} y;} must be valid as 7080a structure member declaration. If @samp{type} is unknown, the result 7081is 0. If no @var{includes} are specified, the default includes are used 7082(@pxref{Default Includes}). 7083 7084This macro caches its result in the @code{ac_cv_alignof_@var{type-or-expr}} 7085variable, with @samp{*} mapped to @samp{p} and other characters not 7086suitable for a variable name mapped to underscores. 7087@end defmac 7088 7089@defmac AC_COMPUTE_INT (@var{var}, @var{expression}, @ 7090 @dvar{includes, AC_INCLUDES_DEFAULT}, @ovar{action-if-fails}) 7091@acindex{COMPUTE_INT} 7092Store into the shell variable @var{var} the value of the integer 7093@var{expression}. The 7094value should fit in an initializer in a C variable of type @code{signed 7095long}. To support cross compilation (in which case, the macro only works on 7096hosts that use twos-complement arithmetic), it should be possible to evaluate 7097the expression at compile-time. If no @var{includes} are specified, the 7098default includes are used (@pxref{Default Includes}). 7099 7100Execute @var{action-if-fails} if the value cannot be determined correctly. 7101@end defmac 7102 7103@defmac AC_LANG_WERROR 7104@acindex{LANG_WERROR} 7105Normally Autoconf ignores warnings generated by the compiler, linker, and 7106preprocessor. If this macro is used, warnings count as fatal 7107errors for the current language. This macro is useful when the 7108results of configuration are used where warnings are unacceptable; for 7109instance, if parts of a program are built with the GCC 7110@option{-Werror} 7111option. If the whole program is built using @option{-Werror} it is 7112often simpler to put @option{-Werror} in the compiler flags (@code{CFLAGS}, 7113etc.). 7114@end defmac 7115 7116@defmac AC_OPENMP 7117@acindex{OPENMP} 7118@cvindex _OPENMP 7119@ovindex OPENMP_CFLAGS 7120@ovindex OPENMP_CXXFLAGS 7121@ovindex OPENMP_FFLAGS 7122@ovindex OPENMP_FCFLAGS 7123@caindex prog_c_openmp 7124@caindex prog_cxx_openmp 7125@caindex prog_f77_openmp 7126@caindex prog_fc_openmp 7127@uref{http://@/www.openmp.org/, OpenMP} specifies extensions of C, C++, 7128and Fortran that simplify optimization of shared memory parallelism, 7129which is a common problem on multicore CPUs. 7130 7131If the current language is C, the macro @code{AC_OPENMP} sets the 7132variable @code{OPENMP_CFLAGS} to the C compiler flags needed for 7133supporting OpenMP@. @code{OPENMP_CFLAGS} is set to empty if the 7134compiler already supports OpenMP, if it has no way to activate OpenMP 7135support, or if the user rejects OpenMP support by invoking 7136@samp{configure} with the @samp{--disable-openmp} option. 7137 7138@code{OPENMP_CFLAGS} needs to be used when compiling programs, when 7139preprocessing program source, and when linking programs. Therefore you 7140need to add @code{$(OPENMP_CFLAGS)} to the @code{CFLAGS} of C programs 7141that use OpenMP@. If you preprocess OpenMP-specific C code, you also 7142need to add @code{$(OPENMP_CFLAGS)} to @code{CPPFLAGS}. The presence of 7143OpenMP support is revealed at compile time by the preprocessor macro 7144@code{_OPENMP}. 7145 7146Linking a program with @code{OPENMP_CFLAGS} typically adds one more 7147shared library to the program's dependencies, so its use is recommended 7148only on programs that actually require OpenMP. 7149 7150If the current language is C++, @code{AC_OPENMP} sets the variable 7151@code{OPENMP_CXXFLAGS}, suitably for the C++ compiler. The same remarks 7152hold as for C. 7153 7154If the current language is Fortran 77 or Fortran, @code{AC_OPENMP} sets 7155the variable @code{OPENMP_FFLAGS} or @code{OPENMP_FCFLAGS}, 7156respectively. Similar remarks as for C hold, except that 7157@code{CPPFLAGS} is not used for Fortran, and no preprocessor macro 7158signals OpenMP support. 7159 7160For portability, it is best to avoid spaces between @samp{#} and 7161@samp{pragma omp}. That is, write @samp{#pragma omp}, not 7162@samp{# pragma omp}. The Sun WorkShop 6.2 C compiler chokes on the 7163latter. 7164 7165This macro caches its result in the @code{ac_cv_prog_c_openmp}, 7166@code{ac_cv_prog_cxx_openmp}, @code{ac_cv_prog_f77_openmp}, or 7167@code{ac_cv_prog_fc_openmp} variable, depending on the current language. 7168@end defmac 7169 7170@node C Compiler 7171@subsection C Compiler Characteristics 7172 7173The following macros provide ways to find and exercise a C Compiler. 7174There are a few constructs that ought to be avoided, but do not deserve 7175being checked for, since they can easily be worked around. 7176 7177@table @asis 7178@item Don't use lines containing solitary backslashes 7179They tickle a bug in the HP-UX C compiler (checked on 7180HP-UX 10.20, 718111.00, and 11i). When given the following source: 7182 7183@example 7184#ifdef __STDC__ 7185/\ 7186* A comment with backslash-newlines in it. %@{ %@} *\ 7187\ 7188/ 7189char str[] = "\\ 7190" A string with backslash-newlines in it %@{ %@} \\ 7191""; 7192char apostrophe = '\\ 7193\ 7194'\ 7195'; 7196#endif 7197@end example 7198 7199@noindent 7200the compiler incorrectly fails with the diagnostics ``Non-terminating 7201comment at end of file'' and ``Missing @samp{#endif} at end of file.'' 7202Removing the lines with solitary backslashes solves the problem. 7203 7204@item Don't compile several files at once if output matters to you 7205Some compilers, such as HP's, report names of files being 7206compiled when given more than one file operand. For instance: 7207 7208@example 7209$ @kbd{cc a.c b.c} 7210a.c: 7211b.c: 7212@end example 7213 7214@noindent 7215This can cause problems if you observe the output of the compiler to 7216detect failures. Invoking @samp{cc -c a.c && cc -c b.c && cc -o c a.o 7217b.o} solves the issue. 7218 7219@item Don't rely on @code{#error} failing 7220The IRIX C compiler does not fail when #error is preprocessed; it 7221simply emits a diagnostic and continues, exiting successfully. So, 7222instead of an error directive like @code{#error "Unsupported word size"} 7223it is more portable to use an invalid directive like @code{#Unsupported 7224word size} in Autoconf tests. In ordinary source code, @code{#error} is 7225OK, since installers with inadequate compilers like IRIX can simply 7226examine these compilers' diagnostic output. 7227 7228@item Don't rely on correct @code{#line} support 7229On Solaris, @command{c89} (at least Sun C 5.3 through 5.8) 7230diagnoses @code{#line} directives whose line 7231numbers are greater than 32767. Nothing in Posix 7232makes this invalid. That is why Autoconf stopped issuing 7233@code{#line} directives. 7234@end table 7235 7236@defmac AC_PROG_CC (@ovar{compiler-search-list}) 7237@acindex{PROG_CC} 7238@evindex CC 7239@evindex CFLAGS 7240@ovindex CC 7241@ovindex CFLAGS 7242@caindex prog_cc_c89 7243Determine a C compiler to use. If @code{CC} is not already set in the 7244environment, check for @code{gcc} and @code{cc}, then for other C 7245compilers. Set output variable @code{CC} to the name of the compiler 7246found. 7247 7248This macro may, however, be invoked with an optional first argument 7249which, if specified, must be a blank-separated list of C compilers to 7250search for. This just gives the user an opportunity to specify an 7251alternative search list for the C compiler. For example, if you didn't 7252like the default order, then you could invoke @code{AC_PROG_CC} like 7253this: 7254 7255@example 7256AC_PROG_CC([gcc cl cc]) 7257@end example 7258 7259If the C compiler does not handle function prototypes correctly by 7260default, try to add an option to output variable @code{CC} to make it 7261so. This macro tries various options that select standard-conformance 7262modes on various systems. 7263 7264After calling this macro you can check whether the C compiler has been 7265set to accept ANSI C89 (ISO C90); if not, the shell 7266variable 7267@code{ac_cv_prog_cc_c89} is set to @samp{no}. See also 7268@code{AC_C_PROTOTYPES} below. 7269 7270If using the GNU C compiler, set shell variable @code{GCC} to 7271@samp{yes}. If output variable @code{CFLAGS} was not already set, set 7272it to @option{-g -O2} for the GNU C compiler (@option{-O2} on systems 7273where GCC does not accept @option{-g}), or @option{-g} for 7274other compilers. If your package does not like this default, then it is 7275acceptable to insert the line @samp{: $@{CFLAGS=""@}} after @code{AC_INIT} 7276and before @code{AC_PROG_CC} to select an empty default instead. 7277 7278Many Autoconf macros use a compiler, and thus call 7279@samp{AC_REQUIRE([AC_PROG_CC])} to ensure that the compiler has been 7280determined before the body of the outermost @code{AC_DEFUN} macro. 7281Although @code{AC_PROG_CC} is safe to directly expand multiple times, it 7282performs certain checks (such as the proper value of @env{EXEEXT}) only 7283on the first invocation. Therefore, care must be used when invoking 7284this macro from within another macro rather than at the top level 7285(@pxref{Expanded Before Required}). 7286@end defmac 7287 7288@anchor{AC_PROG_CC_C_O} 7289@defmac AC_PROG_CC_C_O 7290@acindex{PROG_CC_C_O} 7291@cvindex NO_MINUS_C_MINUS_O 7292@caindex prog_cc_@var{compiler}_c_o 7293If the C compiler does not accept the @option{-c} and @option{-o} options 7294simultaneously, define @code{NO_MINUS_C_MINUS_O}. This macro actually 7295tests both the compiler found by @code{AC_PROG_CC}, and, if different, 7296the first @code{cc} in the path. The test fails if one fails. This 7297macro was created for GNU Make to choose the default C compilation 7298rule. 7299 7300For the compiler @var{compiler}, this macro caches its result in the 7301@code{ac_cv_prog_cc_@var{compiler}_c_o} variable. 7302@end defmac 7303 7304 7305@defmac AC_PROG_CPP 7306@acindex{PROG_CPP} 7307@evindex CPP 7308@ovindex CPP 7309Set output variable @code{CPP} to a command that runs the 7310C preprocessor. If @samp{$CC -E} doesn't work, @file{/lib/cpp} is used. 7311It is only portable to run @code{CPP} on files with a @file{.c} 7312extension. 7313 7314Some preprocessors don't indicate missing include files by the error 7315status. For such preprocessors an internal variable is set that causes 7316other macros to check the standard error from the preprocessor and 7317consider the test failed if any warnings have been reported. 7318For most preprocessors, though, warnings do not cause include-file 7319tests to fail unless @code{AC_PROG_CPP_WERROR} is also specified. 7320@end defmac 7321 7322@defmac AC_PROG_CPP_WERROR 7323@acindex{PROG_CPP_WERROR} 7324@ovindex CPP 7325This acts like @code{AC_PROG_CPP}, except it treats warnings from the 7326preprocessor as errors even if the preprocessor exit status indicates 7327success. This is useful for avoiding headers that generate mandatory 7328warnings, such as deprecation notices. 7329@end defmac 7330 7331 7332The following macros check for C compiler or machine architecture 7333features. To check for characteristics not listed here, use 7334@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or 7335@code{AC_RUN_IFELSE} (@pxref{Runtime}). 7336 7337@defmac AC_PROG_CC_STDC 7338@acindex{PROG_CC_STDC} 7339@caindex prog_cc_stdc 7340If the C compiler cannot compile ISO Standard C (currently 7341C99), try to add an option to output variable @code{CC} to make it work. 7342If the compiler does not support C99, fall back to supporting 7343ANSI C89 (ISO C90). 7344 7345After calling this macro you can check whether the C compiler has been 7346set to accept Standard C; if not, the shell variable 7347@code{ac_cv_prog_cc_stdc} is set to @samp{no}. 7348@end defmac 7349 7350@defmac AC_PROG_CC_C89 7351@acindex{PROG_CC_C89} 7352@caindex prog_cc_c89 7353If the C compiler is not in ANSI C89 (ISO C90) mode by 7354default, try to add an option to output variable @code{CC} to make it 7355so. This macro tries various options that select ANSI C89 on 7356some system or another, preferring extended functionality modes over 7357strict conformance modes. It considers the compiler to be in 7358ANSI C89 mode if it handles function prototypes correctly. 7359 7360After calling this macro you can check whether the C compiler has been 7361set to accept ANSI C89; if not, the shell variable 7362@code{ac_cv_prog_cc_c89} is set to @samp{no}. 7363 7364This macro is called automatically by @code{AC_PROG_CC}. 7365@end defmac 7366 7367@defmac AC_PROG_CC_C99 7368@acindex{PROG_CC_C99} 7369@caindex prog_cc_c99 7370If the C compiler is not in C99 mode by default, try to add an 7371option to output variable @code{CC} to make it so. This macro tries 7372various options that select C99 on some system or another, preferring 7373extended functionality modes over strict conformance modes. It 7374considers the compiler to be in C99 mode if it handles @code{_Bool}, 7375@code{//} comments, flexible array members, @code{inline}, signed and 7376unsigned @code{long long int}, mixed code and declarations, named 7377initialization of structs, 7378@code{restrict}, @code{va_copy}, varargs macros, variable declarations 7379in @code{for} loops, and variable length arrays. 7380 7381After calling this macro you can check whether the C compiler has been 7382set to accept C99; if not, the shell variable 7383@code{ac_cv_prog_cc_c99} is set to @samp{no}. 7384@end defmac 7385 7386@defmac AC_C_BACKSLASH_A 7387@acindex{C_BACKSLASH_A} 7388@cvindex HAVE_C_BACKSLASH_A 7389Define @samp{HAVE_C_BACKSLASH_A} to 1 if the C compiler understands 7390@samp{\a}. 7391 7392This macro is obsolescent, as current C compilers understand @samp{\a}. 7393New programs need not use this macro. 7394@end defmac 7395 7396@anchor{AC_C_BIGENDIAN} 7397@defmac AC_C_BIGENDIAN (@ovar{action-if-true}, @ovar{action-if-false}, @ 7398 @ovar{action-if-unknown}, @ovar{action-if-universal}) 7399@acindex{C_BIGENDIAN} 7400@cvindex WORDS_BIGENDIAN 7401@cindex Endianness 7402If words are stored with the most significant byte first (like Motorola 7403and SPARC CPUs), execute @var{action-if-true}. If words are stored with 7404the least significant byte first (like Intel and VAX CPUs), execute 7405@var{action-if-false}. 7406 7407This macro runs a test-case if endianness cannot be determined from the 7408system header files. When cross-compiling, the test-case is not run but 7409grep'ed for some magic values. @var{action-if-unknown} is executed if 7410the latter case fails to determine the byte sex of the host system. 7411 7412In some cases a single run of a compiler can generate code for multiple 7413architectures. This can happen, for example, when generating Mac OS X 7414universal binary files, which work on both PowerPC and Intel 7415architectures. In this case, the different variants might be for 7416different architectures whose endiannesses differ. If 7417@command{configure} detects this, it executes @var{action-if-universal} 7418instead of @var{action-if-unknown}. 7419 7420The default for @var{action-if-true} is to define 7421@samp{WORDS_BIGENDIAN}. The default for @var{action-if-false} is to do 7422nothing. The default for @var{action-if-unknown} is to 7423abort configure and tell the installer how to bypass this test. 7424And finally, the default for @var{action-if-universal} is to ensure that 7425@samp{WORDS_BIGENDIAN} is defined if and only if a universal build is 7426detected and the current code is big-endian; this default works only if 7427@command{autoheader} is used (@pxref{autoheader Invocation}). 7428 7429If you use this macro without specifying @var{action-if-universal}, you 7430should also use @code{AC_CONFIG_HEADERS}; otherwise 7431@samp{WORDS_BIGENDIAN} may be set incorrectly for Mac OS X universal 7432binary files. 7433@end defmac 7434 7435@anchor{AC_C_CONST} 7436@defmac AC_C_CONST 7437@acindex{C_CONST} 7438@cvindex const 7439@caindex c_const 7440If the C compiler does not fully support the @code{const} keyword, 7441define @code{const} to be empty. Some C compilers that do 7442not define @code{__STDC__} do support @code{const}; some compilers that 7443define @code{__STDC__} do not completely support @code{const}. Programs 7444can simply use @code{const} as if every C compiler supported it; for 7445those that don't, the makefile or configuration header file 7446defines it as empty. 7447 7448Occasionally installers use a C++ compiler to compile C code, typically 7449because they lack a C compiler. This causes problems with @code{const}, 7450because C and C++ treat @code{const} differently. For example: 7451 7452@example 7453const int foo; 7454@end example 7455 7456@noindent 7457is valid in C but not in C++. These differences unfortunately cannot be 7458papered over by defining @code{const} to be empty. 7459 7460If @command{autoconf} detects this situation, it leaves @code{const} alone, 7461as this generally yields better results in practice. However, using a 7462C++ compiler to compile C code is not recommended or supported, and 7463installers who run into trouble in this area should get a C compiler 7464like GCC to compile their C code. 7465 7466This macro caches its result in the @code{ac_cv_c_const} variable. 7467 7468This macro is obsolescent, as current C compilers support @code{const}. 7469New programs need not use this macro. 7470@end defmac 7471 7472@defmac AC_C_RESTRICT 7473@acindex{C_RESTRICT} 7474@cvindex restrict 7475@caindex c_restrict 7476If the C compiler recognizes a variant spelling for the @code{restrict} 7477keyword (@code{__restrict}, @code{__restrict__}, or @code{_Restrict}), 7478then define @code{restrict} to that; this is more likely to do the right 7479thing with compilers that support language variants where plain 7480@code{restrict} is not a keyword. Otherwise, if the C compiler 7481recognizes the @code{restrict} keyword, don't do anything. 7482Otherwise, define @code{restrict} to be empty. 7483Thus, programs may simply use @code{restrict} as if every C compiler 7484supported it; for those that do not, the makefile 7485or configuration header defines it away. 7486 7487Although support in C++ for the @code{restrict} keyword is not 7488required, several C++ compilers do accept the keyword. 7489This macro works for them, too. 7490 7491This macro caches @samp{no} in the @code{ac_cv_c_restrict} variable 7492if @code{restrict} is not supported, and a supported spelling otherwise. 7493@end defmac 7494 7495@defmac AC_C_VOLATILE 7496@acindex{C_VOLATILE} 7497@cvindex volatile 7498If the C compiler does not understand the keyword @code{volatile}, 7499define @code{volatile} to be empty. Programs can simply use 7500@code{volatile} as if every C compiler supported it; for those that do 7501not, the makefile or configuration header defines it as 7502empty. 7503 7504If the correctness of your program depends on the semantics of 7505@code{volatile}, simply defining it to be empty does, in a sense, break 7506your code. However, given that the compiler does not support 7507@code{volatile}, you are at its mercy anyway. At least your 7508program compiles, when it wouldn't before. 7509@xref{Volatile Objects}, for more about @code{volatile}. 7510 7511In general, the @code{volatile} keyword is a standard C feature, so 7512you might expect that @code{volatile} is available only when 7513@code{__STDC__} is defined. However, Ultrix 4.3's native compiler does 7514support volatile, but does not define @code{__STDC__}. 7515 7516This macro is obsolescent, as current C compilers support @code{volatile}. 7517New programs need not use this macro. 7518@end defmac 7519 7520@anchor{AC_C_INLINE} 7521@defmac AC_C_INLINE 7522@acindex{C_INLINE} 7523@cvindex inline 7524If the C compiler supports the keyword @code{inline}, do nothing. 7525Otherwise define @code{inline} to @code{__inline__} or @code{__inline} 7526if it accepts one of those, otherwise define @code{inline} to be empty. 7527@end defmac 7528 7529@anchor{AC_C_CHAR_UNSIGNED} 7530@defmac AC_C_CHAR_UNSIGNED 7531@acindex{C_CHAR_UNSIGNED} 7532@cvindex __CHAR_UNSIGNED__ 7533If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__}, 7534unless the C compiler predefines it. 7535 7536These days, using this macro is not necessary. The same information can 7537be determined by this portable alternative, thus avoiding the use of 7538preprocessor macros in the namespace reserved for the implementation. 7539 7540@example 7541#include <limits.h> 7542#if CHAR_MIN == 0 7543# define CHAR_UNSIGNED 1 7544#endif 7545@end example 7546@end defmac 7547 7548@defmac AC_C_STRINGIZE 7549@acindex{C_STRINGIZE} 7550@cvindex HAVE_STRINGIZE 7551If the C preprocessor supports the stringizing operator, define 7552@code{HAVE_STRINGIZE}. The stringizing operator is @samp{#} and is 7553found in macros such as this: 7554 7555@example 7556#define x(y) #y 7557@end example 7558 7559This macro is obsolescent, as current C compilers support the 7560stringizing operator. New programs need not use this macro. 7561@end defmac 7562 7563@defmac AC_C_FLEXIBLE_ARRAY_MEMBER 7564@acindex{C_FLEXIBLE_ARRAY_MEMBER} 7565@cvindex FLEXIBLE_ARRAY_MEMBER 7566If the C compiler supports flexible array members, define 7567@code{FLEXIBLE_ARRAY_MEMBER} to nothing; otherwise define it to 1. 7568That way, a declaration like this: 7569 7570@example 7571struct s 7572 @{ 7573 size_t n_vals; 7574 double val[FLEXIBLE_ARRAY_MEMBER]; 7575 @}; 7576@end example 7577 7578@noindent 7579will let applications use the ``struct hack'' even with compilers that 7580do not support flexible array members. To allocate and use such an 7581object, you can use code like this: 7582 7583@example 7584size_t i; 7585size_t n = compute_value_count (); 7586struct s *p = 7587 malloc (offsetof (struct s, val) 7588 + n * sizeof (double)); 7589p->n_vals = n; 7590for (i = 0; i < n; i++) 7591 p->val[i] = compute_value (i); 7592@end example 7593@end defmac 7594 7595@defmac AC_C_VARARRAYS 7596@acindex{C_VARARRAYS} 7597@cvindex HAVE_C_VARARRAYS 7598If the C compiler supports variable-length arrays, define 7599@code{HAVE_C_VARARRAYS}. A variable-length array is an array of automatic 7600storage duration whose length is determined at run time, when the array 7601is declared. 7602@end defmac 7603 7604@defmac AC_C_TYPEOF 7605@acindex{C_TYPEOF} 7606@cvindex HAVE_TYPEOF 7607@cvindex typeof 7608If the C compiler supports GCC's @code{typeof} syntax either 7609directly or 7610through a different spelling of the keyword (e.g., @code{__typeof__}), 7611define @code{HAVE_TYPEOF}. If the support is available only through a 7612different spelling, define @code{typeof} to that spelling. 7613@end defmac 7614 7615@defmac AC_C_PROTOTYPES 7616@acindex{C_PROTOTYPES} 7617@cvindex PROTOTYPES 7618@cvindex __PROTOTYPES 7619@cvindex PARAMS 7620If function prototypes are understood by the compiler (as determined by 7621@code{AC_PROG_CC}), define @code{PROTOTYPES} and @code{__PROTOTYPES}. 7622Defining @code{__PROTOTYPES} is for the benefit of 7623header files that cannot use macros that infringe on user name space. 7624 7625This macro is obsolescent, as current C compilers support prototypes. 7626New programs need not use this macro. 7627@end defmac 7628 7629@anchor{AC_PROG_GCC_TRADITIONAL} 7630@defmac AC_PROG_GCC_TRADITIONAL 7631@acindex{PROG_GCC_TRADITIONAL} 7632@ovindex CC 7633Add @option{-traditional} to output variable @code{CC} if using the 7634GNU C compiler and @code{ioctl} does not work properly without 7635@option{-traditional}. That usually happens when the fixed header files 7636have not been installed on an old system. 7637 7638This macro is obsolescent, since current versions of the GNU C 7639compiler fix the header files automatically when installed. 7640@end defmac 7641 7642 7643@node C++ Compiler 7644@subsection C++ Compiler Characteristics 7645 7646 7647@defmac AC_PROG_CXX (@ovar{compiler-search-list}) 7648@acindex{PROG_CXX} 7649@evindex CXX 7650@evindex CXXFLAGS 7651@ovindex CXX 7652@ovindex CXXFLAGS 7653Determine a C++ compiler to use. Check whether the environment variable 7654@code{CXX} or @code{CCC} (in that order) is set; if so, then set output 7655variable @code{CXX} to its value. 7656 7657Otherwise, if the macro is invoked without an argument, then search for 7658a C++ compiler under the likely names (first @code{g++} and @code{c++} 7659then other names). If none of those checks succeed, then as a last 7660resort set @code{CXX} to @code{g++}. 7661 7662This macro may, however, be invoked with an optional first argument 7663which, if specified, must be a blank-separated list of C++ compilers to 7664search for. This just gives the user an opportunity to specify an 7665alternative search list for the C++ compiler. For example, if you 7666didn't like the default order, then you could invoke @code{AC_PROG_CXX} 7667like this: 7668 7669@example 7670AC_PROG_CXX([gcc cl KCC CC cxx cc++ xlC aCC c++ g++]) 7671@end example 7672 7673If using the GNU C++ compiler, set shell variable @code{GXX} to 7674@samp{yes}. If output variable @code{CXXFLAGS} was not already set, set 7675it to @option{-g -O2} for the GNU C++ compiler (@option{-O2} on 7676systems where G++ does not accept @option{-g}), or @option{-g} for other 7677compilers. If your package does not like this default, then it is 7678acceptable to insert the line @samp{: $@{CXXFLAGS=""@}} after @code{AC_INIT} 7679and before @code{AC_PROG_CXX} to select an empty default instead. 7680 7681@end defmac 7682 7683@defmac AC_PROG_CXXCPP 7684@acindex{PROG_CXXCPP} 7685@evindex CXXCPP 7686@ovindex CXXCPP 7687Set output variable @code{CXXCPP} to a command that runs the C++ 7688preprocessor. If @samp{$CXX -E} doesn't work, @file{/lib/cpp} is used. 7689It is portable to run @code{CXXCPP} only on files with a @file{.c}, 7690@file{.C}, @file{.cc}, or @file{.cpp} extension. 7691 7692Some preprocessors don't indicate missing include files by the error 7693status. For such preprocessors an internal variable is set that causes 7694other macros to check the standard error from the preprocessor and 7695consider the test failed if any warnings have been reported. However, 7696it is not known whether such broken preprocessors exist for C++. 7697@end defmac 7698 7699@defmac AC_PROG_CXX_C_O 7700@acindex{PROG_CXX_C_O} 7701@cvindex CXX_NO_MINUS_C_MINUS_O 7702Test whether the C++ compiler accepts the options @option{-c} and 7703@option{-o} simultaneously, and define @code{CXX_NO_MINUS_C_MINUS_O}, 7704if it does not. 7705@end defmac 7706 7707 7708@node Objective C Compiler 7709@subsection Objective C Compiler Characteristics 7710 7711 7712@defmac AC_PROG_OBJC (@ovar{compiler-search-list}) 7713@acindex{PROG_OBJC} 7714@evindex OBJC 7715@evindex OBJCFLAGS 7716@ovindex OBJC 7717@ovindex OBJCFLAGS 7718Determine an Objective C compiler to use. If @code{OBJC} is not already 7719set in the environment, check for Objective C compilers. Set output 7720variable @code{OBJC} to the name of the compiler found. 7721 7722This macro may, however, be invoked with an optional first argument 7723which, if specified, must be a blank-separated list of Objective C compilers to 7724search for. This just gives the user an opportunity to specify an 7725alternative search list for the Objective C compiler. For example, if you 7726didn't like the default order, then you could invoke @code{AC_PROG_OBJC} 7727like this: 7728 7729@example 7730AC_PROG_OBJC([gcc objcc objc]) 7731@end example 7732 7733If using the GNU Objective C compiler, set shell variable 7734@code{GOBJC} to @samp{yes}. If output variable @code{OBJCFLAGS} was not 7735already set, set it to @option{-g -O2} for the GNU Objective C 7736compiler (@option{-O2} on systems where @command{gcc} does not accept 7737@option{-g}), or @option{-g} for other compilers. 7738@end defmac 7739 7740@defmac AC_PROG_OBJCPP 7741@acindex{PROG_OBJCPP} 7742@evindex OBJCPP 7743@ovindex OBJCPP 7744Set output variable @code{OBJCPP} to a command that runs the Objective C 7745preprocessor. If @samp{$OBJC -E} doesn't work, @file{/lib/cpp} is used. 7746@end defmac 7747 7748 7749@node Objective C++ Compiler 7750@subsection Objective C++ Compiler Characteristics 7751 7752 7753@defmac AC_PROG_OBJCXX (@ovar{compiler-search-list}) 7754@acindex{PROG_OBJCXX} 7755@evindex OBJCXX 7756@evindex OBJCXXFLAGS 7757@ovindex OBJCXX 7758@ovindex OBJCXXFLAGS 7759Determine an Objective C++ compiler to use. If @code{OBJCXX} is not already 7760set in the environment, check for Objective C++ compilers. Set output 7761variable @code{OBJCXX} to the name of the compiler found. 7762 7763This macro may, however, be invoked with an optional first argument 7764which, if specified, must be a blank-separated list of Objective C++ compilers 7765to search for. This just gives the user an opportunity to specify an 7766alternative search list for the Objective C++ compiler. For example, if you 7767didn't like the default order, then you could invoke @code{AC_PROG_OBJCXX} 7768like this: 7769 7770@example 7771AC_PROG_OBJCXX([gcc g++ objcc++ objcxx]) 7772@end example 7773 7774If using the GNU Objective C++ compiler, set shell variable 7775@code{GOBJCXX} to @samp{yes}. If output variable @code{OBJCXXFLAGS} was not 7776already set, set it to @option{-g -O2} for the GNU Objective C++ 7777compiler (@option{-O2} on systems where @command{gcc} does not accept 7778@option{-g}), or @option{-g} for other compilers. 7779@end defmac 7780 7781@defmac AC_PROG_OBJCXXCPP 7782@acindex{PROG_OBJCXXCPP} 7783@evindex OBJCXXCPP 7784@ovindex OBJCXXCPP 7785Set output variable @code{OBJCXXCPP} to a command that runs the Objective C++ 7786preprocessor. If @samp{$OBJCXX -E} doesn't work, @file{/lib/cpp} is used. 7787@end defmac 7788 7789 7790@node Erlang Compiler and Interpreter 7791@subsection Erlang Compiler and Interpreter Characteristics 7792@cindex Erlang 7793 7794Autoconf defines the following macros for determining paths to the essential 7795Erlang/OTP programs: 7796 7797@defmac AC_ERLANG_PATH_ERLC (@ovar{value-if-not-found}, @dvar{path, $PATH}) 7798@acindex{ERLANG_PATH_ERLC} 7799@evindex ERLC 7800@evindex ERLCFLAGS 7801@ovindex ERLC 7802@ovindex ERLCFLAGS 7803Determine an Erlang compiler to use. If @code{ERLC} is not already set in the 7804environment, check for @command{erlc}. Set output variable @code{ERLC} to the 7805complete path of the compiler command found. In addition, if @code{ERLCFLAGS} 7806is not set in the environment, set it to an empty value. 7807 7808The two optional arguments have the same meaning as the two last arguments of 7809macro @code{AC_PATH_PROG} for looking for the @command{erlc} program. For 7810example, to look for @command{erlc} only in the @file{/usr/lib/erlang/bin} 7811directory: 7812 7813@example 7814AC_ERLANG_PATH_ERLC([not found], [/usr/lib/erlang/bin]) 7815@end example 7816@end defmac 7817 7818@defmac AC_ERLANG_NEED_ERLC (@dvar{path, $PATH}) 7819@acindex{ERLANG_NEED_ERLC} 7820A simplified variant of the @code{AC_ERLANG_PATH_ERLC} macro, that prints an 7821error message and exits the @command{configure} script if the @command{erlc} 7822program is not found. 7823@end defmac 7824 7825@defmac AC_ERLANG_PATH_ERL (@ovar{value-if-not-found}, @dvar{path, $PATH}) 7826@acindex{ERLANG_PATH_ERL} 7827@evindex ERL 7828@ovindex ERL 7829Determine an Erlang interpreter to use. If @code{ERL} is not already 7830set in the 7831environment, check for @command{erl}. Set output variable @code{ERL} to the 7832complete path of the interpreter command found. 7833 7834The two optional arguments have the same meaning as the two last arguments of 7835macro @code{AC_PATH_PROG} for looking for the @command{erl} program. For 7836example, to look for @command{erl} only in the @file{/usr/lib/erlang/bin} 7837directory: 7838 7839@example 7840AC_ERLANG_PATH_ERL([not found], [/usr/lib/erlang/bin]) 7841@end example 7842@end defmac 7843 7844@defmac AC_ERLANG_NEED_ERL (@dvar{path, $PATH}) 7845@acindex{ERLANG_NEED_ERL} 7846A simplified variant of the @code{AC_ERLANG_PATH_ERL} macro, that prints an 7847error message and exits the @command{configure} script if the @command{erl} 7848program is not found. 7849@end defmac 7850 7851 7852@node Fortran Compiler 7853@subsection Fortran Compiler Characteristics 7854@cindex Fortran 7855@cindex F77 7856 7857The Autoconf Fortran support is divided into two categories: legacy 7858Fortran 77 macros (@code{F77}), and modern Fortran macros (@code{FC}). 7859The former are intended for traditional Fortran 77 code, and have output 7860variables like @code{F77}, @code{FFLAGS}, and @code{FLIBS}. The latter 7861are for newer programs that can (or must) compile under the newer 7862Fortran standards, and have output variables like @code{FC}, 7863@code{FCFLAGS}, and @code{FCLIBS}. 7864 7865Except for the macros @code{AC_FC_SRCEXT}, @code{AC_FC_FREEFORM}, 7866@code{AC_FC_FIXEDFORM}, and @code{AC_FC_LINE_LENGTH} (see below), the 7867@code{FC} and @code{F77} macros behave almost identically, and so they 7868are documented together in this section. 7869 7870 7871@defmac AC_PROG_F77 (@ovar{compiler-search-list}) 7872@acindex{PROG_F77} 7873@evindex F77 7874@evindex FFLAGS 7875@ovindex F77 7876@ovindex FFLAGS 7877@caindex f77_compiler_gnu 7878@caindex prog_f77_g 7879Determine a Fortran 77 compiler to use. If @code{F77} is not already 7880set in the environment, then check for @code{g77} and @code{f77}, and 7881then some other names. Set the output variable @code{F77} to the name 7882of the compiler found. 7883 7884This macro may, however, be invoked with an optional first argument 7885which, if specified, must be a blank-separated list of Fortran 77 7886compilers to search for. This just gives the user an opportunity to 7887specify an alternative search list for the Fortran 77 compiler. For 7888example, if you didn't like the default order, then you could invoke 7889@code{AC_PROG_F77} like this: 7890 7891@example 7892AC_PROG_F77([fl32 f77 fort77 xlf g77 f90 xlf90]) 7893@end example 7894 7895If using @code{g77} (the GNU Fortran 77 compiler), then 7896set the shell variable @code{G77} to @samp{yes}. 7897If the output variable @code{FFLAGS} was not already set in the 7898environment, then set it to @option{-g -02} for @code{g77} (or @option{-O2} 7899where @code{g77} does not accept @option{-g}). Otherwise, set 7900@code{FFLAGS} to @option{-g} for all other Fortran 77 compilers. 7901 7902The result of the GNU test is cached in the 7903@code{ac_cv_f77_compiler_gnu} variable, acceptance of @option{-g} in the 7904@code{ac_cv_prog_f77_g} variable. 7905@end defmac 7906 7907@defmac AC_PROG_FC (@ovar{compiler-search-list}, @ovar{dialect}) 7908@acindex{PROG_FC} 7909@evindex FC 7910@evindex FCFLAGS 7911@ovindex FC 7912@ovindex FCFLAGS 7913@caindex fc_compiler_gnu 7914@caindex prog_fc_g 7915Determine a Fortran compiler to use. If @code{FC} is not already set in 7916the environment, then @code{dialect} is a hint to indicate what Fortran 7917dialect to search for; the default is to search for the newest available 7918dialect. Set the output variable @code{FC} to the name of the compiler 7919found. 7920 7921By default, newer dialects are preferred over older dialects, but if 7922@code{dialect} is specified then older dialects are preferred starting 7923with the specified dialect. @code{dialect} can currently be one of 7924Fortran 77, Fortran 90, or Fortran 95. However, this is only a hint of 7925which compiler @emph{name} to prefer (e.g., @code{f90} or @code{f95}), 7926and no attempt is made to guarantee that a particular language standard 7927is actually supported. Thus, it is preferable that you avoid the 7928@code{dialect} option, and use AC_PROG_FC only for code compatible with 7929the latest Fortran standard. 7930 7931This macro may, alternatively, be invoked with an optional first argument 7932which, if specified, must be a blank-separated list of Fortran 7933compilers to search for, just as in @code{AC_PROG_F77}. 7934 7935If using @code{gfortran} or @code{g77} (the GNU Fortran compilers), then 7936set the shell variable @code{GFC} to @samp{yes}. 7937If the output variable @code{FCFLAGS} was not already set in the 7938environment, then set it to @option{-g -02} for GNU @code{g77} (or 7939@option{-O2} where @code{g77} does not accept @option{-g}). Otherwise, 7940set @code{FCFLAGS} to @option{-g} for all other Fortran compilers. 7941 7942The result of the GNU test is cached in the @code{ac_cv_fc_compiler_gnu} 7943variable, acceptance of @option{-g} in the @code{ac_cv_prog_fc_g} 7944variable. 7945@end defmac 7946 7947@defmac AC_PROG_F77_C_O 7948@defmacx AC_PROG_FC_C_O 7949@acindex{PROG_F77_C_O} 7950@acindex{PROG_FC_C_O} 7951@cvindex F77_NO_MINUS_C_MINUS_O 7952@cvindex FC_NO_MINUS_C_MINUS_O 7953@caindex prog_f77_c_o 7954@caindex prog_fc_c_o 7955Test whether the Fortran compiler accepts the options @option{-c} and 7956@option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} or 7957@code{FC_NO_MINUS_C_MINUS_O}, respectively, if it does not. 7958 7959The result of the test is cached in the @code{ac_cv_prog_f77_c_o} or 7960@code{ac_cv_prog_fc_c_o} variable, respectively. 7961@end defmac 7962 7963The following macros check for Fortran compiler characteristics. 7964To check for characteristics not listed here, use 7965@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or 7966@code{AC_RUN_IFELSE} (@pxref{Runtime}), making sure to first set the 7967current language to Fortran 77 or Fortran via @code{AC_LANG([Fortran 77])} 7968or @code{AC_LANG(Fortran)} (@pxref{Language Choice}). 7969 7970 7971@defmac AC_F77_LIBRARY_LDFLAGS 7972@defmacx AC_FC_LIBRARY_LDFLAGS 7973@acindex{F77_LIBRARY_LDFLAGS} 7974@ovindex FLIBS 7975@acindex{FC_LIBRARY_LDFLAGS} 7976@ovindex FCLIBS 7977@caindex prog_f77_v 7978@caindex prog_fc_v 7979@caindex f77_libs 7980@caindex fc_libs 7981Determine the linker flags (e.g., @option{-L} and @option{-l}) for the 7982@dfn{Fortran intrinsic and runtime libraries} that are required to 7983successfully link a Fortran program or shared library. The output 7984variable @code{FLIBS} or @code{FCLIBS} is set to these flags (which 7985should be included after @code{LIBS} when linking). 7986 7987This macro is intended to be used in those situations when it is 7988necessary to mix, e.g., C++ and Fortran source code in a single 7989program or shared library (@pxref{Mixing Fortran 77 With C and C++, , , 7990automake, GNU Automake}). 7991 7992For example, if object files from a C++ and Fortran compiler must be 7993linked together, then the C++ compiler/linker must be used for linking 7994(since special C++-ish things need to happen at link time like calling 7995global constructors, instantiating templates, enabling exception 7996support, etc.). 7997 7998However, the Fortran intrinsic and runtime libraries must be linked in 7999as well, but the C++ compiler/linker doesn't know by default how to add 8000these Fortran 77 libraries. Hence, this macro was created to determine 8001these Fortran libraries. 8002 8003The macros @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or 8004@code{AC_F77_MAIN} and @code{AC_FC_MAIN} are probably also necessary to 8005link C/C++ with Fortran; see below. Further, it is highly recommended 8006that you use @code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}) 8007because the complex defines that the function wrapper macros create 8008may not work with C/C++ compiler drivers. 8009 8010These macros internally compute the flag needed to verbose linking 8011output and cache it in @code{ac_cv_prog_f77_v} or @code{ac_cv_prog_fc_v} 8012variables, respectively. The computed linker flags are cached in 8013@code{ac_cv_f77_libs} or @code{ac_cv_fc_libs}, respectively. 8014@end defmac 8015 8016@defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @dvar{action-if-not-found, @ 8017 AC_MSG_FAILURE}) 8018@defmacx AC_FC_DUMMY_MAIN (@ovar{action-if-found}, @dvar{action-if-not-found, @ 8019 AC_MSG_FAILURE}) 8020@acindex{F77_DUMMY_MAIN} 8021@cvindex F77_DUMMY_MAIN 8022@acindex{FC_DUMMY_MAIN} 8023@cvindex FC_DUMMY_MAIN 8024@caindex f77_dummy_main 8025@caindex fc_dummy_main 8026With many compilers, the Fortran libraries detected by 8027@code{AC_F77_LIBRARY_LDFLAGS} or @code{AC_FC_LIBRARY_LDFLAGS} provide 8028their own @code{main} entry function that initializes things like 8029Fortran I/O, and which then calls a user-provided entry function named 8030(say) @code{MAIN__} to run the user's program. The 8031@code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or 8032@code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros figure out how to deal with 8033this interaction. 8034 8035When using Fortran for purely numerical functions (no I/O, etc.)@: often 8036one prefers to provide one's own @code{main} and skip the Fortran 8037library initializations. In this case, however, one may still need to 8038provide a dummy @code{MAIN__} routine in order to prevent linking errors 8039on some systems. @code{AC_F77_DUMMY_MAIN} or @code{AC_FC_DUMMY_MAIN} 8040detects whether any such routine is @emph{required} for linking, and 8041what its name is; the shell variable @code{F77_DUMMY_MAIN} or 8042@code{FC_DUMMY_MAIN} holds this name, @code{unknown} when no solution 8043was found, and @code{none} when no such dummy main is needed. 8044 8045By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} or 8046@code{FC_DUMMY_MAIN} to the name of this routine (e.g., @code{MAIN__}) 8047@emph{if} it is required. @var{action-if-not-found} defaults to 8048exiting with an error. 8049 8050In order to link with Fortran routines, the user's C/C++ program should 8051then include the following code to define the dummy main if it is 8052needed: 8053 8054@example 8055@c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage. 8056#ifdef F77_DUMMY_MAIN 8057# ifdef __cplusplus 8058 extern "C" 8059# endif 8060 int F77_DUMMY_MAIN () @{ return 1; @} 8061#endif 8062@end example 8063 8064(Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.) 8065 8066Note that this macro is called automatically from @code{AC_F77_WRAPPERS} 8067or @code{AC_FC_WRAPPERS}; there is generally no need to call it 8068explicitly unless one wants to change the default actions. 8069 8070The result of this macro is cached in the @code{ac_cv_f77_dummy_main} or 8071@code{ac_cv_fc_dummy_main} variable, respectively. 8072@end defmac 8073 8074@defmac AC_F77_MAIN 8075@defmacx AC_FC_MAIN 8076@acindex{F77_MAIN} 8077@cvindex F77_MAIN 8078@acindex{FC_MAIN} 8079@cvindex FC_MAIN 8080@caindex f77_main 8081@caindex fc_main 8082As discussed above, many Fortran libraries allow you to provide an entry 8083point called (say) @code{MAIN__} instead of the usual @code{main}, which 8084is then called by a @code{main} function in the Fortran libraries that 8085initializes things like Fortran I/O@. The 8086@code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros detect whether it is 8087@emph{possible} to utilize such an alternate main function, and defines 8088@code{F77_MAIN} and @code{FC_MAIN} to the name of the function. (If no 8089alternate main function name is found, @code{F77_MAIN} and @code{FC_MAIN} are 8090simply defined to @code{main}.) 8091 8092Thus, when calling Fortran routines from C that perform things like I/O, 8093one should use this macro and declare the "main" function like so: 8094 8095@example 8096@c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage. 8097#ifdef __cplusplus 8098 extern "C" 8099#endif 8100int F77_MAIN (int argc, char *argv[]); 8101@end example 8102 8103(Again, replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.) 8104 8105The result of this macro is cached in the @code{ac_cv_f77_main} or 8106@code{ac_cv_fc_main} variable, respectively. 8107@end defmac 8108 8109@defmac AC_F77_WRAPPERS 8110@defmacx AC_FC_WRAPPERS 8111@acindex{F77_WRAPPERS} 8112@cvindex F77_FUNC 8113@cvindex F77_FUNC_ 8114@acindex{FC_WRAPPERS} 8115@cvindex FC_FUNC 8116@cvindex FC_FUNC_ 8117@caindex f77_mangling 8118@caindex fc_mangling 8119Defines C macros @code{F77_FUNC (name, NAME)}, @code{FC_FUNC (name, NAME)}, 8120@code{F77_FUNC_(name, NAME)}, and @code{FC_FUNC_(name, NAME)} to properly 8121mangle the names of C/C++ identifiers, and identifiers with underscores, 8122respectively, so that they match the name-mangling scheme used by the 8123Fortran compiler. 8124 8125Fortran is case-insensitive, and in order to achieve this the Fortran 8126compiler converts all identifiers into a canonical case and format. To 8127call a Fortran subroutine from C or to write a C function that is 8128callable from Fortran, the C program must explicitly use identifiers in 8129the format expected by the Fortran compiler. In order to do this, one 8130simply wraps all C identifiers in one of the macros provided by 8131@code{AC_F77_WRAPPERS} or @code{AC_FC_WRAPPERS}. For example, suppose 8132you have the following Fortran 77 subroutine: 8133 8134@example 8135@c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage. 8136 subroutine foobar (x, y) 8137 double precision x, y 8138 y = 3.14159 * x 8139 return 8140 end 8141@end example 8142 8143You would then declare its prototype in C or C++ as: 8144 8145@example 8146@c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage. 8147#define FOOBAR_F77 F77_FUNC (foobar, FOOBAR) 8148#ifdef __cplusplus 8149extern "C" /* prevent C++ name mangling */ 8150#endif 8151void FOOBAR_F77 (double *x, double *y); 8152@end example 8153 8154Note that we pass both the lowercase and uppercase versions of the 8155function name to @code{F77_FUNC} so that it can select the right one. 8156Note also that all parameters to Fortran 77 routines are passed as 8157pointers (@pxref{Mixing Fortran 77 With C and C++, , , automake, GNU 8158Automake}). 8159 8160(Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.) 8161 8162Although Autoconf tries to be intelligent about detecting the 8163name-mangling scheme of the Fortran compiler, there may be Fortran 8164compilers that it doesn't support yet. In this case, the above code 8165generates a compile-time error, but some other behavior 8166(e.g., disabling Fortran-related features) can be induced by checking 8167whether @code{F77_FUNC} or @code{FC_FUNC} is defined. 8168 8169Now, to call that routine from a C program, we would do something like: 8170 8171@example 8172@c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage. 8173@{ 8174 double x = 2.7183, y; 8175 FOOBAR_F77 (&x, &y); 8176@} 8177@end example 8178 8179If the Fortran identifier contains an underscore (e.g., @code{foo_bar}), 8180you should use @code{F77_FUNC_} or @code{FC_FUNC_} instead of 8181@code{F77_FUNC} or @code{FC_FUNC} (with the same arguments). This is 8182because some Fortran compilers mangle names differently if they contain 8183an underscore. 8184 8185The name mangling scheme is encoded in the @code{ac_cv_f77_mangling} or 8186@code{ac_cv_fc_mangling} cache variable, respectively, and also used for 8187the @code{AC_F77_FUNC} and @code{AC_FC_FUNC} macros described below. 8188@end defmac 8189 8190@defmac AC_F77_FUNC (@var{name}, @ovar{shellvar}) 8191@defmacx AC_FC_FUNC (@var{name}, @ovar{shellvar}) 8192@acindex{F77_FUNC} 8193@acindex{FC_FUNC} 8194Given an identifier @var{name}, set the shell variable @var{shellvar} to 8195hold the mangled version @var{name} according to the rules of the 8196Fortran linker (see also @code{AC_F77_WRAPPERS} or 8197@code{AC_FC_WRAPPERS}). @var{shellvar} is optional; if it is not 8198supplied, the shell variable is simply @var{name}. The purpose of 8199this macro is to give the caller a way to access the name-mangling 8200information other than through the C preprocessor as above, for example, 8201to call Fortran routines from some language other than C/C++. 8202@end defmac 8203 8204@defmac AC_FC_SRCEXT (@var{ext}, @ovar{action-if-success}, @ 8205 @dvar{action-if-failure, AC_MSG_FAILURE}) 8206@defmacx AC_FC_PP_SRCEXT (@var{ext}, @ovar{action-if-success}, @ 8207 @dvar{action-if-failure, AC_MSG_FAILURE}) 8208@acindex{FC_SRCEXT} 8209@acindex{FC_PP_SRCEXT} 8210@caindex fc_srcext_@var{ext} 8211@caindex fc_pp_srcext_@var{ext} 8212By default, the @code{FC} macros perform their tests using a @file{.f} 8213extension for source-code files. Some compilers, however, only enable 8214newer language features for appropriately named files, e.g., Fortran 90 8215features only for @file{.f90} files, or preprocessing only with 8216@file{.F} files or maybe other upper-case extensions. On the other 8217hand, some other compilers expect all source files to end in @file{.f} 8218and require special flags to support other file name extensions. The 8219@code{AC_FC_SRCEXT} and @code{AC_FC_PP_SRCEXT} macros deal with these 8220issues. 8221 8222The @code{AC_FC_SRCEXT} macro tries to get the @code{FC} compiler to 8223accept files ending with the extension @file{.@var{ext}} (i.e., 8224@var{ext} does @emph{not} contain the dot). If any special compiler 8225flags are needed for this, it stores them in the output variable 8226@code{FCFLAGS_@var{ext}}. This extension and these flags are then used 8227for all subsequent @code{FC} tests (until @code{AC_FC_SRCEXT} or 8228@code{AC_FC_PP_SRCEXT} is called another time). 8229 8230For example, you would use @code{AC_FC_SRCEXT(f90)} to employ the 8231@file{.f90} extension in future tests, and it would set the 8232@code{FCFLAGS_f90} output variable with any extra flags that are needed 8233to compile such files. 8234 8235Similarly, the @code{AC_FC_PP_SRCEXT} macro tries to get the @code{FC} 8236compiler to preprocess and compile files with the extension 8237@file{.@var{ext}}. When both @command{fpp} and @command{cpp} style 8238preprocessing are provided, the former is preferred, as the latter may 8239treat continuation lines, @code{//} tokens, and white space differently 8240from what some Fortran dialects expect. Conversely, if you do not want 8241files to be preprocessed, use only lower-case characters in the file 8242name extension. Like with @code{AC_FC_SRCEXT(f90)}, any needed flags 8243are stored in the @code{FCFLAGS_@var{ext}} variable. 8244 8245The @code{FCFLAGS_@var{ext}} flags can @emph{not} be simply absorbed 8246into @code{FCFLAGS}, for two reasons based on the limitations of some 8247compilers. First, only one @code{FCFLAGS_@var{ext}} can be used at a 8248time, so files with different extensions must be compiled separately. 8249Second, @code{FCFLAGS_@var{ext}} must appear @emph{immediately} before 8250the source-code file name when compiling. So, continuing the example 8251above, you might compile a @file{foo.f90} file in your makefile with the 8252command: 8253 8254@example 8255foo.o: foo.f90 8256 $(FC) -c $(FCFLAGS) $(FCFLAGS_f90) '$(srcdir)/foo.f90' 8257@end example 8258 8259If @code{AC_FC_SRCEXT} or @code{AC_FC_PP_SRCEXT} succeeds in compiling 8260files with the @var{ext} extension, it calls @var{action-if-success} 8261(defaults to nothing). If it fails, and cannot find a way to make the 8262@code{FC} compiler accept such files, it calls @var{action-if-failure} 8263(defaults to exiting with an error message). 8264 8265The @code{AC_FC_SRCEXT} and @code{AC_FC_PP_SRCEXT} macros cache their 8266results in @code{ac_cv_fc_srcext_@var{ext}} and 8267@code{ac_cv_fc_pp_srcext_@var{ext}} variables, respectively. 8268@end defmac 8269 8270@defmac AC_FC_PP_DEFINE (@ovar{action-if-success}, @dvar{action-if-failure, @ 8271 AC_MSG_FAILURE}) 8272@acindex{FC_PP_DEFINE} 8273@caindex fc_pp_define 8274 8275Find a flag to specify defines for preprocessed Fortran. Not all 8276Fortran compilers use @option{-D}. Substitute @code{FC_DEFINE} with 8277the result and call @var{action-if-success} (defaults to nothing) if 8278successful, and @var{action-if-failure} (defaults to failing with an 8279error message) if not. 8280 8281This macro calls @code{AC_FC_PP_SRCEXT([F])} in order to learn how to 8282preprocess a @file{conftest.F} file, but restores a previously used 8283Fortran source file extension afterwards again. 8284 8285The result of this test is cached in the @code{ac_cv_fc_pp_define} 8286variable. 8287@end defmac 8288 8289@defmac AC_FC_FREEFORM (@ovar{action-if-success}, @dvar{action-if-failure, @ 8290 AC_MSG_FAILURE}) 8291@acindex{FC_FREEFORM} 8292@caindex fc_freeform 8293 8294Try to ensure that the Fortran compiler (@code{$FC}) allows free-format 8295source code (as opposed to the older fixed-format style from Fortran 829677). If necessary, it may add some additional flags to @code{FCFLAGS}. 8297 8298This macro is most important if you are using the default @file{.f} 8299extension, since many compilers interpret this extension as indicating 8300fixed-format source unless an additional flag is supplied. If you 8301specify a different extension with @code{AC_FC_SRCEXT}, such as 8302@file{.f90}, then @code{AC_FC_FREEFORM} ordinarily succeeds without 8303modifying @code{FCFLAGS}. For extensions which the compiler does not 8304know about, the flag set by the @code{AC_FC_SRCEXT} macro might let 8305the compiler assume Fortran 77 by default, however. 8306 8307If @code{AC_FC_FREEFORM} succeeds in compiling free-form source, it 8308calls @var{action-if-success} (defaults to nothing). If it fails, it 8309calls @var{action-if-failure} (defaults to exiting with an error 8310message). 8311 8312The result of this test, or @samp{none} or @samp{unknown}, is cached in 8313the @code{ac_cv_fc_freeform} variable. 8314@end defmac 8315 8316@defmac AC_FC_FIXEDFORM (@ovar{action-if-success}, @dvar{action-if-failure, @ 8317 AC_MSG_FAILURE}) 8318@acindex{FC_FIXEDFORM} 8319@caindex fc_fixedform 8320 8321Try to ensure that the Fortran compiler (@code{$FC}) allows the old 8322fixed-format source code (as opposed to free-format style). If 8323necessary, it may add some additional flags to @code{FCFLAGS}. 8324 8325This macro is needed for some compilers alias names like @command{xlf95} 8326which assume free-form source code by default, and in case you want to 8327use fixed-form source with an extension like @file{.f90} which many 8328compilers interpret as free-form by default. If you specify a different 8329extension with @code{AC_FC_SRCEXT}, such as @file{.f}, then 8330@code{AC_FC_FIXEDFORM} ordinarily succeeds without modifying 8331@code{FCFLAGS}. 8332 8333If @code{AC_FC_FIXEDFORM} succeeds in compiling fixed-form source, it 8334calls @var{action-if-success} (defaults to nothing). If it fails, it 8335calls @var{action-if-failure} (defaults to exiting with an error 8336message). 8337 8338The result of this test, or @samp{none} or @samp{unknown}, is cached in 8339the @code{ac_cv_fc_fixedform} variable. 8340@end defmac 8341 8342@defmac AC_FC_LINE_LENGTH (@ovar{length}, @ovar{action-if-success}, @ 8343 @dvar{action-if-failure, AC_MSG_FAILURE}) 8344@acindex{FC_LINE_LENGTH} 8345@caindex fc_line_length 8346 8347Try to ensure that the Fortran compiler (@code{$FC}) accepts long source 8348code lines. The @var{length} argument may be given as 80, 132, or 8349unlimited, and defaults to 132. Note that line lengths above 254 8350columns are not portable, and some compilers do not accept more than 132 8351columns at least for fixed format source. If necessary, it may add some 8352additional flags to @code{FCFLAGS}. 8353 8354If @code{AC_FC_LINE_LENGTH} succeeds in compiling fixed-form source, it 8355calls @var{action-if-success} (defaults to nothing). If it fails, it 8356calls @var{action-if-failure} (defaults to exiting with an error 8357message). 8358 8359The result of this test, or @samp{none} or @samp{unknown}, is cached in 8360the @code{ac_cv_fc_line_length} variable. 8361@end defmac 8362 8363@defmac AC_FC_CHECK_BOUNDS (@ovar{action-if-success}, @ 8364 @dvar{action-if-failure, AC_MSG_FAILURE}) 8365@acindex{FC_CHECK_BOUNDS} 8366@caindex fc_check_bounds 8367 8368The @code{AC_FC_CHECK_BOUNDS} macro tries to enable array bounds checking 8369in the Fortran compiler. If successful, the @var{action-if-success} 8370is called and any needed flags are added to @code{FCFLAGS}. Otherwise, 8371@var{action-if-failure} is called, which defaults to failing with an error 8372message. The macro currently requires Fortran 90 or a newer dialect. 8373 8374The result of the macro is cached in the @code{ac_cv_fc_check_bounds} 8375variable. 8376@end defmac 8377 8378@defmac AC_F77_IMPLICIT_NONE (@ovar{action-if-success}, @ 8379 @dvar{action-if-failure, AC_MSG_FAILURE}) 8380@defmacx AC_FC_IMPLICIT_NONE (@ovar{action-if-success}, @ 8381 @dvar{action-if-failure, AC_MSG_FAILURE}) 8382@acindex{F77_IMPLICIT_NONE} 8383@acindex{FC_IMPLICIT_NONE} 8384@caindex f77_implicit_none 8385@caindex fc_implicit_none 8386 8387Try to disallow implicit declarations in the Fortran compiler. If 8388successful, @var{action-if-success} is called and any needed flags 8389are added to @code{FFLAGS} or @code{FCFLAGS}, respectively. Otherwise, 8390@var{action-if-failure} is called, which defaults to failing with an error 8391message. 8392 8393The result of these macros are cached in the 8394@code{ac_cv_f77_implicit_none} and @code{ac_cv_fc_implicit_none} 8395variables, respectively. 8396@end defmac 8397 8398@defmac AC_FC_MODULE_EXTENSION 8399@acindex{FC_MODULE_EXTENSION} 8400@caindex fc_module_ext 8401@ovindex FC_MODEXT 8402 8403Find the Fortran 90 module file name extension. Most Fortran 90 8404compilers store module information in files separate from the object 8405files. The module files are usually named after the name of the module 8406rather than the source file name, with characters possibly turned to 8407upper case, plus an extension, often @file{.mod}. 8408 8409Not all compilers use module files at all, or by default. The Cray 8410Fortran compiler requires @option{-e m} in order to store and search 8411module information in @file{.mod} files rather than in object files. 8412Likewise, the Fujitsu Fortran compilers uses the @option{-Am} option to 8413indicate how module information is stored. 8414 8415The @code{AC_FC_MODULE_EXTENSION} macro computes the module extension 8416without the leading dot, and stores that in the @code{FC_MODEXT} 8417variable. If the compiler does not produce module files, or the 8418extension cannot be determined, @code{FC_MODEXT} is empty. Typically, 8419the result of this macro may be used in cleanup @command{make} rules as 8420follows: 8421 8422@example 8423clean-modules: 8424 -test -z "$(FC_MODEXT)" || rm -f *.$(FC_MODEXT) 8425@end example 8426 8427The extension, or @samp{unknown}, is cached in the 8428@code{ac_cv_fc_module_ext} variable. 8429@end defmac 8430 8431@defmac AC_FC_MODULE_FLAG (@ovar{action-if-success}, @ 8432 @dvar{action-if-failure, AC_MSG_FAILURE}) 8433@acindex{FC_MODULE_FLAG} 8434@caindex fc_module_flag 8435@ovindex FC_MODINC 8436@ovindex ac_empty 8437 8438Find the compiler flag to include Fortran 90 module information from 8439another directory, and store that in the @code{FC_MODINC} variable. 8440Call @var{action-if-success} (defaults to nothing) if successful, and 8441set @code{FC_MODINC} to empty and call @var{action-if-failure} (defaults 8442to exiting with an error message) if not. 8443 8444Most Fortran 90 compilers provide a way to specify module directories. 8445Some have separate flags for the directory to write module files to, 8446and directories to search them in, whereas others only allow writing to 8447the current directory or to the first directory specified in the include 8448path. Further, with some compilers, the module search path and the 8449preprocessor search path can only be modified with the same flag. Thus, 8450for portability, write module files to the current directory only and 8451list that as first directory in the search path. 8452 8453There may be no whitespace between @code{FC_MODINC} and the following 8454directory name, but @code{FC_MODINC} may contain trailing white space. 8455For example, if you use Automake and would like to search @file{../lib} 8456for module files, you can use the following: 8457 8458@example 8459AM_FCFLAGS = $(FC_MODINC). $(FC_MODINC)../lib 8460@end example 8461 8462Inside @command{configure} tests, you can use: 8463 8464@example 8465if test -n "$FC_MODINC"; then 8466 FCFLAGS="$FCFLAGS $FC_MODINC. $FC_MODINC../lib" 8467fi 8468@end example 8469 8470The flag is cached in the @code{ac_cv_fc_module_flag} variable. 8471The substituted value of @code{FC_MODINC} may refer to the 8472@code{ac_empty} dummy placeholder empty variable, to avoid losing 8473the significant trailing whitespace in a @file{Makefile}. 8474@end defmac 8475 8476@defmac AC_FC_MODULE_OUTPUT_FLAG (@ovar{action-if-success}, @ 8477 @dvar{action-if-failure, AC_MSG_FAILURE}) 8478@acindex{FC_MODULE_OUTPUT_FLAG} 8479@caindex fc_module_output_flag 8480@ovindex FC_MODOUT 8481 8482Find the compiler flag to write Fortran 90 module information to 8483another directory, and store that in the @code{FC_MODOUT} variable. 8484Call @var{action-if-success} (defaults to nothing) if successful, and 8485set @code{FC_MODOUT} to empty and call @var{action-if-failure} (defaults 8486to exiting with an error message) if not. 8487 8488Not all Fortran 90 compilers write module files, and of those that do, 8489not all allow writing to a directory other than the current one, nor 8490do all have separate flags for writing and reading; see the description 8491of @code{AC_FC_MODULE_FLAG} above. If you need to be able to write to 8492another directory, for maximum portability use @code{FC_MODOUT} before 8493any @code{FC_MODINC} and include both the current directory and the one 8494you write to in the search path: 8495 8496@example 8497AM_FCFLAGS = $(FC_MODOUT)../mod $(FC_MODINC)../mod $(FC_MODINC). @dots{} 8498@end example 8499 8500The flag is cached in the @code{ac_cv_fc_module_output_flag} variable. 8501The substituted value of @code{FC_MODOUT} may refer to the 8502@code{ac_empty} dummy placeholder empty variable, to avoid losing 8503the significant trailing whitespace in a @file{Makefile}. 8504@end defmac 8505 8506 8507@node Go Compiler 8508@subsection Go Compiler Characteristics 8509@cindex Go 8510 8511Autoconf provides basic support for the Go programming language when 8512using the @code{gccgo} compiler (there is currently no support for the 8513@code{6g} and @code{8g} compilers). 8514 8515@defmac AC_PROG_GO (@ovar{compiler-search-list}) 8516Find the Go compiler to use. Check whether the environment variable 8517@code{GOC} is set; if so, then set output variable @code{GOC} to its 8518value. 8519 8520Otherwise, if the macro is invoked without an argument, then search for 8521a Go compiler named @code{gccgo}. If it is not found, then as a last 8522resort set @code{GOC} to @code{gccgo}. 8523 8524This macro may be invoked with an optional first argument which, if 8525specified, must be a blank-separated list of Go compilers to search for. 8526 8527If output variable @code{GOFLAGS} was not already set, set it to 8528@option{-g -O2}. If your package does not like this default, 8529@code{GOFLAGS} may be set before @code{AC_PROG_GO}. 8530@end defmac 8531 8532 8533@node System Services 8534@section System Services 8535 8536The following macros check for operating system services or capabilities. 8537 8538@anchor{AC_PATH_X} 8539@defmac AC_PATH_X 8540@acindex{PATH_X} 8541@evindex XMKMF 8542@cindex X Window System 8543Try to locate the X Window System include files and libraries. If the 8544user gave the command line options @option{--x-includes=@var{dir}} and 8545@option{--x-libraries=@var{dir}}, use those directories. 8546 8547If either or both were not given, get the missing values by running 8548@code{xmkmf} (or an executable pointed to by the @code{XMKMF} 8549environment variable) on a trivial @file{Imakefile} and examining the 8550makefile that it produces. Setting @code{XMKMF} to @samp{false} 8551disables this method. 8552 8553If this method fails to find the X Window System, @command{configure} 8554looks for the files in several directories where they often reside. 8555If either method is successful, set the shell variables 8556@code{x_includes} and @code{x_libraries} to their locations, unless they 8557are in directories the compiler searches by default. 8558 8559If both methods fail, or the user gave the command line option 8560@option{--without-x}, set the shell variable @code{no_x} to @samp{yes}; 8561otherwise set it to the empty string. 8562@end defmac 8563 8564@anchor{AC_PATH_XTRA} 8565@defmac AC_PATH_XTRA 8566@acindex{PATH_XTRA} 8567@ovindex X_CFLAGS 8568@ovindex X_LIBS 8569@ovindex X_EXTRA_LIBS 8570@ovindex X_PRE_LIBS 8571@cvindex X_DISPLAY_MISSING 8572An enhanced version of @code{AC_PATH_X}. It adds the C compiler flags 8573that X needs to output variable @code{X_CFLAGS}, and the X linker flags 8574to @code{X_LIBS}. Define @code{X_DISPLAY_MISSING} if X is not 8575available. 8576 8577This macro also checks for special libraries that some systems need in 8578order to compile X programs. It adds any that the system needs to 8579output variable @code{X_EXTRA_LIBS}. And it checks for special X11R6 8580libraries that need to be linked with before @option{-lX11}, and adds 8581any found to the output variable @code{X_PRE_LIBS}. 8582 8583@c This is an incomplete kludge. Make a real way to do it. 8584@c If you need to check for other X functions or libraries yourself, then 8585@c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to 8586@c @code{LIBS} temporarily, like this: (FIXME - add example) 8587@end defmac 8588 8589@anchor{AC_SYS_INTERPRETER} 8590@defmac AC_SYS_INTERPRETER 8591@acindex{SYS_INTERPRETER} 8592Check whether the system supports starting scripts with a line of the 8593form @samp{#!/bin/sh} to select the interpreter to use for the script. 8594After running this macro, shell code in @file{configure.ac} can check 8595the shell variable @code{interpval}; it is set to @samp{yes} 8596if the system supports @samp{#!}, @samp{no} if not. 8597@end defmac 8598 8599@defmac AC_SYS_LARGEFILE 8600@acindex{SYS_LARGEFILE} 8601@cvindex _FILE_OFFSET_BITS 8602@cvindex _LARGE_FILES 8603@ovindex CC 8604@cindex Large file support 8605@cindex LFS 8606Arrange for 64-bit file offsets, known as 8607@uref{http://@/www.unix-systems@/.org/@/version2/@/whatsnew/@/lfs20mar.html, 8608large-file support}. On some hosts, one must use special compiler 8609options to build programs that can access large files. Append any such 8610options to the output variable @code{CC}. Define 8611@code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary. 8612 8613Large-file support can be disabled by configuring with the 8614@option{--disable-largefile} option. 8615 8616If you use this macro, check that your program works even when 8617@code{off_t} is wider than @code{long int}, since this is common when 8618large-file support is enabled. For example, it is not correct to print 8619an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld", 8620(long int) X)}. 8621 8622The LFS introduced the @code{fseeko} and @code{ftello} functions to 8623replace their C counterparts @code{fseek} and @code{ftell} that do not 8624use @code{off_t}. Take care to use @code{AC_FUNC_FSEEKO} to make their 8625prototypes available when using them and large-file support is 8626enabled. 8627@end defmac 8628 8629@anchor{AC_SYS_LONG_FILE_NAMES} 8630@defmac AC_SYS_LONG_FILE_NAMES 8631@acindex{SYS_LONG_FILE_NAMES} 8632@cvindex HAVE_LONG_FILE_NAMES 8633If the system supports file names longer than 14 characters, define 8634@code{HAVE_LONG_FILE_NAMES}. 8635@end defmac 8636 8637@defmac AC_SYS_POSIX_TERMIOS 8638@acindex{SYS_POSIX_TERMIOS} 8639@cindex Posix termios headers 8640@cindex termios Posix headers 8641@caindex sys_posix_termios 8642Check to see if the Posix termios headers and functions are available on the 8643system. If so, set the shell variable @code{ac_cv_sys_posix_termios} to 8644@samp{yes}. If not, set the variable to @samp{no}. 8645@end defmac 8646 8647@node Posix Variants 8648@section Posix Variants 8649 8650The following macro makes it possible to use features of Posix that are 8651extensions to C, as well as platform extensions not defined by Posix. 8652 8653@anchor{AC_USE_SYSTEM_EXTENSIONS} 8654@defmac AC_USE_SYSTEM_EXTENSIONS 8655@acindex{USE_SYSTEM_EXTENSIONS} 8656@cvindex _ALL_SOURCE 8657@cvindex _GNU_SOURCE 8658@cvindex _MINIX 8659@cvindex _POSIX_1_SOURCE 8660@cvindex _POSIX_PTHREAD_SEMANTICS 8661@cvindex _POSIX_SOURCE 8662@cvindex _TANDEM_SOURCE 8663@cvindex __EXTENSIONS__ 8664This macro was introduced in Autoconf 2.60. If possible, enable 8665extensions to C or Posix on hosts that normally disable the extensions, 8666typically due to standards-conformance namespace issues. This should be 8667called before any macros that run the C compiler. The following 8668preprocessor macros are defined where appropriate: 8669 8670@table @code 8671@item _GNU_SOURCE 8672Enable extensions on GNU/Linux. 8673@item __EXTENSIONS__ 8674Enable general extensions on Solaris. 8675@item _POSIX_PTHREAD_SEMANTICS 8676Enable threading extensions on Solaris. 8677@item _TANDEM_SOURCE 8678Enable extensions for the HP NonStop platform. 8679@item _ALL_SOURCE 8680Enable extensions for AIX 3, and for Interix. 8681@item _POSIX_SOURCE 8682Enable Posix functions for Minix. 8683@item _POSIX_1_SOURCE 8684Enable additional Posix functions for Minix. 8685@item _MINIX 8686Identify Minix platform. This particular preprocessor macro is 8687obsolescent, and may be removed in a future release of Autoconf. 8688@end table 8689@end defmac 8690 8691 8692@node Erlang Libraries 8693@section Erlang Libraries 8694@cindex Erlang, Library, checking 8695 8696The following macros check for an installation of Erlang/OTP, and for the 8697presence of certain Erlang libraries. All those macros require the 8698configuration of an Erlang interpreter and an Erlang compiler 8699(@pxref{Erlang Compiler and Interpreter}). 8700 8701@defmac AC_ERLANG_SUBST_ERTS_VER 8702@acindex{ERLANG_SUBST_ERTS_VER} 8703@ovindex ERLANG_ERTS_VER 8704Set the output variable @code{ERLANG_ERTS_VER} to the version of the 8705Erlang runtime system (as returned by Erlang's 8706@code{erlang:system_info(version)} function). The result of this test 8707is cached if caching is enabled when running @command{configure}. The 8708@code{ERLANG_ERTS_VER} variable is not intended to be used for testing 8709for features of specific ERTS versions, but to be used for substituting 8710the ERTS version in Erlang/OTP release resource files (@code{.rel} 8711files), as shown below. 8712@end defmac 8713 8714@defmac AC_ERLANG_SUBST_ROOT_DIR 8715@acindex{ERLANG_SUBST_ROOT_DIR} 8716@ovindex ERLANG_ROOT_DIR 8717Set the output variable @code{ERLANG_ROOT_DIR} to the path to the base 8718directory in which Erlang/OTP is installed (as returned by Erlang's 8719@code{code:root_dir/0} function). The result of this test is cached if 8720caching is enabled when running @command{configure}. 8721@end defmac 8722 8723@defmac AC_ERLANG_SUBST_LIB_DIR 8724@acindex{ERLANG_SUBST_LIB_DIR} 8725@ovindex ERLANG_LIB_DIR 8726Set the output variable @code{ERLANG_LIB_DIR} to the path of the library 8727directory of Erlang/OTP (as returned by Erlang's 8728@code{code:lib_dir/0} function), which subdirectories each contain an installed 8729Erlang/OTP library. The result of this test is cached if caching is enabled 8730when running @command{configure}. 8731@end defmac 8732 8733@defmac AC_ERLANG_CHECK_LIB (@var{library}, @ovar{action-if-found}, @ 8734 @ovar{action-if-not-found}) 8735@acindex{ERLANG_CHECK_LIB} 8736@ovindex ERLANG_LIB_DIR_@var{library} 8737@ovindex ERLANG_LIB_VER_@var{library} 8738Test whether the Erlang/OTP library @var{library} is installed by 8739calling Erlang's @code{code:lib_dir/1} function. The result of this 8740test is cached if caching is enabled when running @command{configure}. 8741@var{action-if-found} is a list of shell commands to run if the library 8742is installed; @var{action-if-not-found} is a list of shell commands to 8743run if it is not. Additionally, if the library is installed, the output 8744variable @samp{ERLANG_LIB_DIR_@var{library}} is set to the path to the 8745library installation directory, and the output variable 8746@samp{ERLANG_LIB_VER_@var{library}} is set to the version number that is 8747part of the subdirectory name, if it is in the standard form 8748(@code{@var{library}-@var{version}}). If the directory name does not 8749have a version part, @samp{ERLANG_LIB_VER_@var{library}} is set to the 8750empty string. If the library is not installed, 8751@samp{ERLANG_LIB_DIR_@var{library}} and 8752@samp{ERLANG_LIB_VER_@var{library}} are set to @code{"not found"}. For 8753example, to check if library @code{stdlib} is installed: 8754 8755@example 8756AC_ERLANG_CHECK_LIB([stdlib], 8757 [echo "stdlib version \"$ERLANG_LIB_VER_stdlib\"" 8758 echo "is installed in \"$ERLANG_LIB_DIR_stdlib\""], 8759 [AC_MSG_ERROR([stdlib was not found!])]) 8760@end example 8761 8762The @samp{ERLANG_LIB_VER_@var{library}} variables (set by 8763@code{AC_ERLANG_CHECK_LIB}) and the @code{ERLANG_ERTS_VER} variable (set 8764by @code{AC_ERLANG_SUBST_ERTS_VER}) are not intended to be used for 8765testing for features of specific versions of libraries or of the Erlang 8766runtime system. Those variables are intended to be substituted in 8767Erlang release resource files (@code{.rel} files). For instance, to 8768generate a @file{example.rel} file for an application depending on the 8769@code{stdlib} library, @file{configure.ac} could contain: 8770 8771@example 8772AC_ERLANG_SUBST_ERTS_VER 8773AC_ERLANG_CHECK_LIB([stdlib], 8774 [], 8775 [AC_MSG_ERROR([stdlib was not found!])]) 8776AC_CONFIG_FILES([example.rel]) 8777@end example 8778 8779@noindent 8780The @file{example.rel.in} file used to generate @file{example.rel} 8781should contain: 8782 8783@example 8784@{release, 8785 @{"@@PACKAGE@@", "@@VERSION@@"@}, 8786 @{erts, "@@ERLANG_ERTS_VER@@"@}, 8787 [@{stdlib, "@@ERLANG_LIB_VER_stdlib@@"@}, 8788 @{@@PACKAGE@@, "@@VERSION@@"@}]@}. 8789@end example 8790@end defmac 8791 8792In addition to the above macros, which test installed Erlang libraries, the 8793following macros determine the paths to the directories into which newly built 8794Erlang libraries are to be installed: 8795 8796@defmac AC_ERLANG_SUBST_INSTALL_LIB_DIR 8797@acindex{ERLANG_SUBST_INSTALL_LIB_DIR} 8798@ovindex ERLANG_INSTALL_LIB_DIR 8799 8800Set the @code{ERLANG_INSTALL_LIB_DIR} output variable to the directory into 8801which every built Erlang library should be installed in a separate 8802subdirectory. 8803If this variable is not set in the environment when @command{configure} runs, 8804its default value is @code{$@{libdir@}/erlang/lib}. 8805@end defmac 8806 8807@defmac AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR (@var{library}, @var{version}) 8808@acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR} 8809@ovindex ERLANG_INSTALL_LIB_DIR_@var{library} 8810 8811Set the @samp{ERLANG_INSTALL_LIB_DIR_@var{library}} output variable to the 8812directory into which the built Erlang library @var{library} version 8813@var{version} should be installed. If this variable is not set in the 8814environment when @command{configure} runs, its default value is 8815@samp{$ERLANG_INSTALL_LIB_DIR/@var{library}-@var{version}}, the value of the 8816@code{ERLANG_INSTALL_LIB_DIR} variable being set by the 8817@code{AC_ERLANG_SUBST_INSTALL_LIB_DIR} macro. 8818@end defmac 8819 8820 8821 8822 8823 8824@c ========================================================= Writing Tests 8825 8826@node Writing Tests 8827@chapter Writing Tests 8828 8829If the existing feature tests don't do something you need, you have to 8830write new ones. These macros are the building blocks. They provide 8831ways for other macros to check whether various kinds of features are 8832available and report the results. 8833 8834This chapter contains some suggestions and some of the reasons why the 8835existing tests are written the way they are. You can also learn a lot 8836about how to write Autoconf tests by looking at the existing ones. If 8837something goes wrong in one or more of the Autoconf tests, this 8838information can help you understand the assumptions behind them, which 8839might help you figure out how to best solve the problem. 8840 8841These macros check the output of the compiler system of the current 8842language (@pxref{Language Choice}). They do not cache the results of 8843their tests for future use (@pxref{Caching Results}), because they don't 8844know enough about the information they are checking for to generate a 8845cache variable name. They also do not print any messages, for the same 8846reason. The checks for particular kinds of features call these macros 8847and do cache their results and print messages about what they're 8848checking for. 8849 8850When you write a feature test that could be applicable to more than one 8851software package, the best thing to do is encapsulate it in a new macro. 8852@xref{Writing Autoconf Macros}, for how to do that. 8853 8854@menu 8855* Language Choice:: Selecting which language to use for testing 8856* Writing Test Programs:: Forging source files for compilers 8857* Running the Preprocessor:: Detecting preprocessor symbols 8858* Running the Compiler:: Detecting language or header features 8859* Running the Linker:: Detecting library features 8860* Runtime:: Testing for runtime features 8861* Systemology:: A zoology of operating systems 8862* Multiple Cases:: Tests for several possible values 8863@end menu 8864 8865@node Language Choice 8866@section Language Choice 8867@cindex Language 8868 8869Autoconf-generated @command{configure} scripts check for the C compiler and 8870its features by default. Packages that use other programming languages 8871(maybe more than one, e.g., C and C++) need to test features of the 8872compilers for the respective languages. The following macros determine 8873which programming language is used in the subsequent tests in 8874@file{configure.ac}. 8875 8876@anchor{AC_LANG} 8877@defmac AC_LANG (@var{language}) 8878@acindex{LANG} 8879Do compilation tests using the compiler, preprocessor, and file 8880extensions for the specified @var{language}. 8881 8882Supported languages are: 8883 8884@table @samp 8885@item C 8886Do compilation tests using @code{CC} and @code{CPP} and use extension 8887@file{.c} for test programs. Use compilation flags: @code{CPPFLAGS} with 8888@code{CPP}, and both @code{CPPFLAGS} and @code{CFLAGS} with @code{CC}. 8889 8890@item C++ 8891Do compilation tests using @code{CXX} and @code{CXXCPP} and use 8892extension @file{.C} for test programs. Use compilation flags: 8893@code{CPPFLAGS} with @code{CXXCPP}, and both @code{CPPFLAGS} and 8894@code{CXXFLAGS} with @code{CXX}. 8895 8896@item Fortran 77 8897Do compilation tests using @code{F77} and use extension @file{.f} for 8898test programs. Use compilation flags: @code{FFLAGS}. 8899 8900@item Fortran 8901Do compilation tests using @code{FC} and use extension @file{.f} (or 8902whatever has been set by @code{AC_FC_SRCEXT}) for test programs. Use 8903compilation flags: @code{FCFLAGS}. 8904 8905@item Erlang 8906@ovindex ERLC 8907@ovindex ERL 8908@ovindex ERLCFLAGS 8909Compile and execute tests using @code{ERLC} and @code{ERL} and use extension 8910@file{.erl} for test Erlang modules. Use compilation flags: @code{ERLCFLAGS}. 8911 8912@item Objective C 8913Do compilation tests using @code{OBJC} and @code{OBJCPP} and use 8914extension @file{.m} for test programs. Use compilation flags: 8915@code{CPPFLAGS} with @code{OBJCPP}, and both @code{CPPFLAGS} and 8916@code{OBJCFLAGS} with @code{OBJC}. 8917 8918@item Objective C++ 8919Do compilation tests using @code{OBJCXX} and @code{OBJCXXCPP} and use 8920extension @file{.mm} for test programs. Use compilation flags: 8921@code{CPPFLAGS} with @code{OBJCXXCPP}, and both @code{CPPFLAGS} and 8922@code{OBJCXXFLAGS} with @code{OBJCXX}. 8923 8924@item Go 8925Do compilation tests using @code{GOC} and use extension @file{.go} for 8926test programs. Use compilation flags @code{GOFLAGS}. 8927@end table 8928@end defmac 8929 8930@anchor{AC_LANG_PUSH} 8931@defmac AC_LANG_PUSH (@var{language}) 8932@acindex{LANG_PUSH} 8933Remember the current language (as set by @code{AC_LANG}) on a stack, and 8934then select the @var{language}. Use this macro and @code{AC_LANG_POP} 8935in macros that need to temporarily switch to a particular language. 8936@end defmac 8937 8938@defmac AC_LANG_POP (@ovar{language}) 8939@acindex{LANG_POP} 8940Select the language that is saved on the top of the stack, as set by 8941@code{AC_LANG_PUSH}, and remove it from the stack. 8942 8943If given, @var{language} specifies the language we just @emph{quit}. It 8944is a good idea to specify it when it's known (which should be the 8945case@dots{}), since Autoconf detects inconsistencies. 8946 8947@example 8948AC_LANG_PUSH([Fortran 77]) 8949# Perform some tests on Fortran 77. 8950# @dots{} 8951AC_LANG_POP([Fortran 77]) 8952@end example 8953@end defmac 8954 8955@defmac AC_LANG_ASSERT (@var{language}) 8956@acindex{LANG_ASSERT} 8957Check statically that the current language is @var{language}. 8958You should use this in your language specific macros 8959to avoid that they be called with an inappropriate language. 8960 8961This macro runs only at @command{autoconf} time, and incurs no cost at 8962@command{configure} time. Sadly enough and because Autoconf is a two 8963layer language @footnote{Because M4 is not aware of Sh code, 8964especially conditionals, some optimizations that look nice statically 8965may produce incorrect results at runtime.}, the macros 8966@code{AC_LANG_PUSH} and @code{AC_LANG_POP} cannot be ``optimizing'', 8967therefore as much as possible you ought to avoid using them to wrap 8968your code, rather, require from the user to run the macro with a 8969correct current language, and check it with @code{AC_LANG_ASSERT}. 8970And anyway, that may help the user understand she is running a Fortran 8971macro while expecting a result about her Fortran 77 compiler@enddots{} 8972@end defmac 8973 8974 8975@defmac AC_REQUIRE_CPP 8976@acindex{REQUIRE_CPP} 8977Ensure that whichever preprocessor would currently be used for tests has 8978been found. Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an 8979argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP}, 8980depending on which language is current. 8981@end defmac 8982 8983 8984@node Writing Test Programs 8985@section Writing Test Programs 8986 8987Autoconf tests follow a common scheme: feed some program with some 8988input, and most of the time, feed a compiler with some source file. 8989This section is dedicated to these source samples. 8990 8991@menu 8992* Guidelines:: General rules for writing test programs 8993* Test Functions:: Avoiding pitfalls in test programs 8994* Generating Sources:: Source program boilerplate 8995@end menu 8996 8997@node Guidelines 8998@subsection Guidelines for Test Programs 8999 9000The most important rule to follow when writing testing samples is: 9001 9002@center @emph{Look for realism.} 9003 9004This motto means that testing samples must be written with the same 9005strictness as real programs are written. In particular, you should 9006avoid ``shortcuts'' and simplifications. 9007 9008Don't just play with the preprocessor if you want to prepare a 9009compilation. For instance, using @command{cpp} to check whether a header is 9010functional might let your @command{configure} accept a header which 9011causes some @emph{compiler} error. Do not hesitate to check a header with 9012other headers included before, especially required headers. 9013 9014Make sure the symbols you use are properly defined, i.e., refrain from 9015simply declaring a function yourself instead of including the proper 9016header. 9017 9018Test programs should not write to standard output. They 9019should exit with status 0 if the test succeeds, and with status 1 9020otherwise, so that success 9021can be distinguished easily from a core dump or other failure; 9022segmentation violations and other failures produce a nonzero exit 9023status. Unless you arrange for @code{exit} to be declared, test 9024programs should @code{return}, not @code{exit}, from @code{main}, 9025because on many systems @code{exit} is not declared by default. 9026 9027Test programs can use @code{#if} or @code{#ifdef} to check the values of 9028preprocessor macros defined by tests that have already run. For 9029example, if you call @code{AC_HEADER_STDBOOL}, then later on in 9030@file{configure.ac} you can have a test program that includes 9031@file{stdbool.h} conditionally: 9032 9033@example 9034@group 9035#ifdef HAVE_STDBOOL_H 9036# include <stdbool.h> 9037#endif 9038@end group 9039@end example 9040 9041Both @code{#if HAVE_STDBOOL_H} and @code{#ifdef HAVE_STDBOOL_H} will 9042work with any standard C compiler. Some developers prefer @code{#if} 9043because it is easier to read, while others prefer @code{#ifdef} because 9044it avoids diagnostics with picky compilers like GCC with the 9045@option{-Wundef} option. 9046 9047If a test program needs to use or create a data file, give it a name 9048that starts with @file{conftest}, such as @file{conftest.data}. The 9049@command{configure} script cleans up by running @samp{rm -f -r conftest*} 9050after running test programs and if the script is interrupted. 9051 9052@node Test Functions 9053@subsection Test Functions 9054 9055These days it's safe to assume support for function prototypes 9056(introduced in C89). 9057 9058Functions that test programs declare should also be conditionalized for 9059C++, which requires @samp{extern "C"} prototypes. Make sure to not 9060include any header files containing clashing prototypes. 9061 9062@example 9063#ifdef __cplusplus 9064extern "C" 9065#endif 9066void *valloc (size_t); 9067@end example 9068 9069If a test program calls a function with invalid parameters (just to see 9070whether it exists), organize the program to ensure that it never invokes 9071that function. You can do this by calling it in another function that is 9072never invoked. You can't do it by putting it after a call to 9073@code{exit}, because GCC version 2 knows that @code{exit} 9074never returns 9075and optimizes out any code that follows it in the same block. 9076 9077If you include any header files, be sure to call the functions 9078relevant to them with the correct number of arguments, even if they are 9079just 0, to avoid compilation errors due to prototypes. GCC 9080version 2 9081has internal prototypes for several functions that it automatically 9082inlines; for example, @code{memcpy}. To avoid errors when checking for 9083them, either pass them the correct number of arguments or redeclare them 9084with a different return type (such as @code{char}). 9085 9086 9087@node Generating Sources 9088@subsection Generating Sources 9089 9090Autoconf provides a set of macros that can be used to generate test 9091source files. They are written to be language generic, i.e., they 9092actually depend on the current language (@pxref{Language Choice}) to 9093``format'' the output properly. 9094 9095 9096@defmac AC_LANG_CONFTEST (@var{source}) 9097@acindex{LANG_CONFTEST} 9098Save the @var{source} text in the current test source file: 9099@file{conftest.@var{extension}} where the @var{extension} depends on the 9100current language. As of Autoconf 2.63b, the source file also contains 9101the results of all of the @code{AC_DEFINE} performed so far. 9102 9103Note that the @var{source} is evaluated exactly once, like regular 9104Autoconf macro arguments, and therefore (i) you may pass a macro 9105invocation, (ii) if not, be sure to double quote if needed. 9106 9107This macro issues a warning during @command{autoconf} processing if 9108@var{source} does not include an expansion of the macro 9109@code{AC_LANG_DEFINES_PROVIDED} (note that both @code{AC_LANG_SOURCE} and 9110@code{AC_LANG_PROGRAM} call this macro, and thus avoid the warning). 9111 9112This macro is seldom called directly, but is used under the hood by more 9113common macros such as @code{AC_COMPILE_IFELSE} and @code{AC_RUN_IFELSE}. 9114@end defmac 9115 9116@defmac AC_LANG_DEFINES_PROVIDED 9117@acindex{LANG_DEFINES_PROVIDED} 9118This macro is called as a witness that the file 9119@file{conftest.@var{extension}} appropriate for the current language is 9120complete, including all previously determined results from 9121@code{AC_DEFINE}. This macro is seldom called directly, but exists if 9122you have a compelling reason to write a conftest file without using 9123@code{AC_LANG_SOURCE}, yet still want to avoid a syntax warning from 9124@code{AC_LANG_CONFTEST}. 9125@end defmac 9126 9127@defmac AC_LANG_SOURCE (@var{source}) 9128@acindex{LANG_SOURCE} 9129Expands into the @var{source}, with the definition of 9130all the @code{AC_DEFINE} performed so far. This macro includes an 9131expansion of @code{AC_LANG_DEFINES_PROVIDED}. 9132 9133In many cases, you may find it more convenient to use the wrapper 9134@code{AC_LANG_PROGRAM}. 9135@end defmac 9136 9137For instance, executing (observe the double quotation!): 9138 9139@example 9140@c If you change this example, adjust tests/compile.at:AC_LANG_SOURCE example. 9141AC_INIT([Hello], [1.0], [bug-hello@@example.org], [], 9142 [http://www.example.org/]) 9143AC_DEFINE([HELLO_WORLD], ["Hello, World\n"], 9144 [Greetings string.]) 9145AC_LANG([C]) 9146AC_LANG_CONFTEST( 9147 [AC_LANG_SOURCE([[const char hw[] = "Hello, World\n";]])]) 9148gcc -E -dD conftest.c 9149@end example 9150 9151@noindent 9152on a system with @command{gcc} installed, results in: 9153 9154@example 9155@c If you change this example, adjust tests/compile.at:AC_LANG_SOURCE example. 9156@dots{} 9157# 1 "conftest.c" 9158 9159#define PACKAGE_NAME "Hello" 9160#define PACKAGE_TARNAME "hello" 9161#define PACKAGE_VERSION "1.0" 9162#define PACKAGE_STRING "Hello 1.0" 9163#define PACKAGE_BUGREPORT "bug-hello@@example.org" 9164#define PACKAGE_URL "http://www.example.org/" 9165#define HELLO_WORLD "Hello, World\n" 9166 9167const char hw[] = "Hello, World\n"; 9168@end example 9169 9170When the test language is Fortran, Erlang, or Go, the @code{AC_DEFINE} 9171definitions are not automatically translated into constants in the 9172source code by this macro. 9173 9174@defmac AC_LANG_PROGRAM (@var{prologue}, @var{body}) 9175@acindex{LANG_PROGRAM} 9176Expands into a source file which consists of the @var{prologue}, and 9177then @var{body} as body of the main function (e.g., @code{main} in 9178C). Since it uses @code{AC_LANG_SOURCE}, the features of the latter are 9179available. 9180@end defmac 9181 9182For instance: 9183 9184@example 9185@c If you change this example, adjust tests/compile.at:AC_LANG_PROGRAM example. 9186AC_INIT([Hello], [1.0], [bug-hello@@example.org], [], 9187 [http://www.example.org/]) 9188AC_DEFINE([HELLO_WORLD], ["Hello, World\n"], 9189 [Greetings string.]) 9190AC_LANG_CONFTEST( 9191[AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]], 9192 [[fputs (hw, stdout);]])]) 9193gcc -E -dD conftest.c 9194@end example 9195 9196@noindent 9197on a system with @command{gcc} installed, results in: 9198 9199@example 9200@c If you change this example, adjust tests/compile.at:AC_LANG_PROGRAM example. 9201@dots{} 9202# 1 "conftest.c" 9203 9204#define PACKAGE_NAME "Hello" 9205#define PACKAGE_TARNAME "hello" 9206#define PACKAGE_VERSION "1.0" 9207#define PACKAGE_STRING "Hello 1.0" 9208#define PACKAGE_BUGREPORT "bug-hello@@example.org" 9209#define PACKAGE_URL "http://www.example.org/" 9210#define HELLO_WORLD "Hello, World\n" 9211 9212const char hw[] = "Hello, World\n"; 9213int 9214main () 9215@{ 9216fputs (hw, stdout); 9217 ; 9218 return 0; 9219@} 9220@end example 9221 9222In Erlang tests, the created source file is that of an Erlang module called 9223@code{conftest} (@file{conftest.erl}). This module defines and exports 9224at least 9225one @code{start/0} function, which is called to perform the test. The 9226@var{prologue} is optional code that is inserted between the module header and 9227the @code{start/0} function definition. @var{body} is the body of the 9228@code{start/0} function without the final period (@pxref{Runtime}, about 9229constraints on this function's behavior). 9230 9231For instance: 9232 9233@example 9234AC_INIT([Hello], [1.0], [bug-hello@@example.org]) 9235AC_LANG(Erlang) 9236AC_LANG_CONFTEST( 9237[AC_LANG_PROGRAM([[-define(HELLO_WORLD, "Hello, world!").]], 9238 [[io:format("~s~n", [?HELLO_WORLD])]])]) 9239cat conftest.erl 9240@end example 9241 9242@noindent 9243results in: 9244 9245@example 9246-module(conftest). 9247-export([start/0]). 9248-define(HELLO_WORLD, "Hello, world!"). 9249start() -> 9250io:format("~s~n", [?HELLO_WORLD]) 9251. 9252@end example 9253 9254@defmac AC_LANG_CALL (@var{prologue}, @var{function}) 9255@acindex{LANG_CALL} 9256Expands into a source file which consists of the @var{prologue}, and 9257then a call to the @var{function} as body of the main function (e.g., 9258@code{main} in C). Since it uses @code{AC_LANG_PROGRAM}, the feature 9259of the latter are available. 9260 9261This function will probably be replaced in the future by a version 9262which would enable specifying the arguments. The use of this macro is 9263not encouraged, as it violates strongly the typing system. 9264 9265This macro cannot be used for Erlang tests. 9266@end defmac 9267 9268@defmac AC_LANG_FUNC_LINK_TRY (@var{function}) 9269@acindex{LANG_FUNC_LINK_TRY} 9270Expands into a source file which uses the @var{function} in the body of 9271the main function (e.g., @code{main} in C). Since it uses 9272@code{AC_LANG_PROGRAM}, the features of the latter are available. 9273 9274As @code{AC_LANG_CALL}, this macro is documented only for completeness. 9275It is considered to be severely broken, and in the future will be 9276removed in favor of actual function calls (with properly typed 9277arguments). 9278 9279This macro cannot be used for Erlang tests. 9280@end defmac 9281 9282@node Running the Preprocessor 9283@section Running the Preprocessor 9284 9285Sometimes one might need to run the preprocessor on some source file. 9286@emph{Usually it is a bad idea}, as you typically need to @emph{compile} 9287your project, not merely run the preprocessor on it; therefore you 9288certainly want to run the compiler, not the preprocessor. Resist the 9289temptation of following the easiest path. 9290 9291Nevertheless, if you need to run the preprocessor, then use 9292@code{AC_PREPROC_IFELSE}. 9293 9294The macros described in this section cannot be used for tests in Erlang, 9295Fortran, or Go, since those languages require no preprocessor. 9296 9297@anchor{AC_PREPROC_IFELSE} 9298@defmac AC_PREPROC_IFELSE (@var{input}, @ovar{action-if-true}, @ 9299 @ovar{action-if-false}) 9300@acindex{PREPROC_IFELSE} 9301Run the preprocessor of the current language (@pxref{Language Choice}) 9302on the @var{input}, run the shell commands @var{action-if-true} on 9303success, @var{action-if-false} otherwise. The @var{input} can be made 9304by @code{AC_LANG_PROGRAM} and friends. 9305 9306This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because 9307@option{-g}, @option{-O}, etc.@: are not valid options to many C 9308preprocessors. 9309 9310It is customary to report unexpected failures with 9311@code{AC_MSG_FAILURE}. If needed, @var{action-if-true} can further access 9312the preprocessed output in the file @file{conftest.i}. 9313@end defmac 9314 9315For instance: 9316 9317@example 9318AC_INIT([Hello], [1.0], [bug-hello@@example.org]) 9319AC_DEFINE([HELLO_WORLD], ["Hello, World\n"], 9320 [Greetings string.]) 9321AC_PREPROC_IFELSE( 9322 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]], 9323 [[fputs (hw, stdout);]])], 9324 [AC_MSG_RESULT([OK])], 9325 [AC_MSG_FAILURE([unexpected preprocessor failure])]) 9326@end example 9327 9328@noindent 9329results in: 9330 9331@example 9332checking for gcc... gcc 9333checking for C compiler default output file name... a.out 9334checking whether the C compiler works... yes 9335checking whether we are cross compiling... no 9336checking for suffix of executables... 9337checking for suffix of object files... o 9338checking whether we are using the GNU C compiler... yes 9339checking whether gcc accepts -g... yes 9340checking for gcc option to accept ISO C89... none needed 9341checking how to run the C preprocessor... gcc -E 9342OK 9343@end example 9344 9345@sp 1 9346 9347The macro @code{AC_TRY_CPP} (@pxref{Obsolete Macros}) used to play the 9348role of @code{AC_PREPROC_IFELSE}, but double quotes its argument, making 9349it impossible to use it to elaborate sources. You are encouraged to 9350get rid of your old use of the macro @code{AC_TRY_CPP} in favor of 9351@code{AC_PREPROC_IFELSE}, but, in the first place, are you sure you need 9352to run the @emph{preprocessor} and not the compiler? 9353 9354@anchor{AC_EGREP_HEADER} 9355@defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @ 9356 @var{action-if-found}, @ovar{action-if-not-found}) 9357@acindex{EGREP_HEADER} 9358If the output of running the preprocessor on the system header file 9359@var{header-file} matches the extended regular expression 9360@var{pattern}, execute shell commands @var{action-if-found}, otherwise 9361execute @var{action-if-not-found}. 9362@end defmac 9363 9364@anchor{AC_EGREP_CPP} 9365@defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @ 9366 @ovar{action-if-found}, @ovar{action-if-not-found}) 9367@acindex{EGREP_CPP} 9368@var{program} is the text of a C or C++ program, on which shell 9369variable, back quote, and backslash substitutions are performed. If the 9370output of running the preprocessor on @var{program} matches the 9371extended regular expression @var{pattern}, execute shell commands 9372@var{action-if-found}, otherwise execute @var{action-if-not-found}. 9373@end defmac 9374 9375 9376 9377@node Running the Compiler 9378@section Running the Compiler 9379 9380To check for a syntax feature of the current language's (@pxref{Language 9381Choice}) compiler, such as whether it recognizes a certain keyword, or 9382simply to try some library feature, use @code{AC_COMPILE_IFELSE} to try 9383to compile a small program that uses that feature. 9384 9385@defmac AC_COMPILE_IFELSE (@var{input}, @ovar{action-if-true}, @ 9386 @ovar{action-if-false}) 9387@acindex{COMPILE_IFELSE} 9388Run the compiler and compilation flags of the current language 9389(@pxref{Language Choice}) on the @var{input}, run the shell commands 9390@var{action-if-true} on success, @var{action-if-false} otherwise. The 9391@var{input} can be made by @code{AC_LANG_PROGRAM} and friends. 9392 9393It is customary to report unexpected failures with 9394@code{AC_MSG_FAILURE}. This macro does not try to link; use 9395@code{AC_LINK_IFELSE} if you need to do that (@pxref{Running the 9396Linker}). If needed, @var{action-if-true} can further access the 9397just-compiled object file @file{conftest.$OBJEXT}. 9398 9399This macro uses @code{AC_REQUIRE} for the compiler associated with the 9400current language, which means that if the compiler has not yet been 9401determined, the compiler determination will be made prior to the body of 9402the outermost @code{AC_DEFUN} macro that triggered this macro to 9403expand (@pxref{Expanded Before Required}). 9404@end defmac 9405 9406@ovindex ERL 9407For tests in Erlang, the @var{input} must be the source code of a module named 9408@code{conftest}. @code{AC_COMPILE_IFELSE} generates a @file{conftest.beam} 9409file that can be interpreted by the Erlang virtual machine (@code{ERL}). It is 9410recommended to use @code{AC_LANG_PROGRAM} to specify the test program, 9411to ensure that the Erlang module has the right name. 9412 9413@node Running the Linker 9414@section Running the Linker 9415 9416To check for a library, a function, or a global variable, Autoconf 9417@command{configure} scripts try to compile and link a small program that 9418uses it. This is unlike Metaconfig, which by default uses @code{nm} or 9419@code{ar} on the C library to try to figure out which functions are 9420available. Trying to link with the function is usually a more reliable 9421approach because it avoids dealing with the variations in the options 9422and output formats of @code{nm} and @code{ar} and in the location of the 9423standard libraries. It also allows configuring for cross-compilation or 9424checking a function's runtime behavior if needed. On the other hand, 9425it can be slower than scanning the libraries once, but accuracy is more 9426important than speed. 9427 9428@code{AC_LINK_IFELSE} is used to compile test programs to test for 9429functions and global variables. It is also used by @code{AC_CHECK_LIB} 9430to check for libraries (@pxref{Libraries}), by adding the library being 9431checked for to @code{LIBS} temporarily and trying to link a small 9432program. 9433 9434@anchor{AC_LINK_IFELSE} 9435@defmac AC_LINK_IFELSE (@var{input}, @ovar{action-if-true}, @ 9436 @ovar{action-if-false}) 9437@acindex{LINK_IFELSE} 9438Run the compiler (and compilation flags) and the linker of the current 9439language (@pxref{Language Choice}) on the @var{input}, run the shell 9440commands @var{action-if-true} on success, @var{action-if-false} 9441otherwise. The @var{input} can be made by @code{AC_LANG_PROGRAM} and 9442friends. If needed, @var{action-if-true} can further access the 9443just-linked program file @file{conftest$EXEEXT}. 9444 9445@code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the 9446current compilation flags. 9447 9448It is customary to report unexpected failures with 9449@code{AC_MSG_FAILURE}. This macro does not try to execute the program; 9450use @code{AC_RUN_IFELSE} if you need to do that (@pxref{Runtime}). 9451@end defmac 9452 9453The @code{AC_LINK_IFELSE} macro cannot be used for Erlang tests, since Erlang 9454programs are interpreted and do not require linking. 9455 9456 9457 9458@node Runtime 9459@section Checking Runtime Behavior 9460 9461Sometimes you need to find out how a system performs at runtime, such 9462as whether a given function has a certain capability or bug. If you 9463can, make such checks when your program runs instead of when it is 9464configured. You can check for things like the machine's endianness when 9465your program initializes itself. 9466 9467If you really need to test for a runtime behavior while configuring, 9468you can write a test program to determine the result, and compile and 9469run it using @code{AC_RUN_IFELSE}. Avoid running test programs if 9470possible, because this prevents people from configuring your package for 9471cross-compiling. 9472 9473@anchor{AC_RUN_IFELSE} 9474@defmac AC_RUN_IFELSE (@var{input}, @ovar{action-if-true}, @ 9475 @ovar{action-if-false}, @dvar{action-if-cross-compiling, AC_MSG_FAILURE}) 9476@acindex{RUN_IFELSE} 9477Run the compiler (and compilation flags) and the linker of the current 9478language (@pxref{Language Choice}) on the @var{input}, then execute the 9479resulting program. If the program returns an exit 9480status of 0 when executed, run shell commands @var{action-if-true}. 9481Otherwise, run shell commands @var{action-if-false}. 9482 9483The @var{input} can be made by @code{AC_LANG_PROGRAM} and friends. 9484@code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the 9485compilation flags of the current language (@pxref{Language Choice}). 9486Additionally, @var{action-if-true} can run @command{./conftest$EXEEXT} 9487for further testing. 9488 9489In the @var{action-if-false} section, the failing exit status is 9490available in the shell variable @samp{$?}. This exit status might be 9491that of a failed compilation, or it might be that of a failed program 9492execution. 9493 9494If cross-compilation mode is enabled (this is the case if either the 9495compiler being used does not produce executables that run on the system 9496where @command{configure} is being run, or if the options @code{--build} 9497and @code{--host} were both specified and their values are different), 9498then the test program is 9499not run. If the optional shell commands @var{action-if-cross-compiling} 9500are given, those commands are run instead; typically these commands 9501provide pessimistic defaults that allow cross-compilation to work even 9502if the guess was wrong. If the fourth argument is empty or omitted, but 9503cross-compilation is detected, then @command{configure} prints an error 9504message and exits. If you want your package to be useful in a 9505cross-compilation scenario, you @emph{should} provide a non-empty 9506@var{action-if-cross-compiling} clause, as well as wrap the 9507@code{AC_RUN_IFELSE} compilation inside an @code{AC_CACHE_CHECK} 9508(@pxref{Caching Results}) which allows the user to override the 9509pessimistic default if needed. 9510 9511It is customary to report unexpected failures with 9512@code{AC_MSG_FAILURE}. 9513@end defmac 9514 9515@command{autoconf} prints a warning message when creating 9516@command{configure} each time it encounters a call to 9517@code{AC_RUN_IFELSE} with no @var{action-if-cross-compiling} argument 9518given. If you are not concerned about users configuring your package 9519for cross-compilation, you may ignore the warning. A few of the macros 9520distributed with Autoconf produce this warning message; but if this is a 9521problem for you, please report it as a bug, along with an appropriate 9522pessimistic guess to use instead. 9523 9524To configure for cross-compiling you can also choose a value for those 9525parameters based on the canonical system name (@pxref{Manual 9526Configuration}). Alternatively, set up a test results cache file with 9527the correct values for the host system (@pxref{Caching Results}). 9528 9529@ovindex cross_compiling 9530To provide a default for calls of @code{AC_RUN_IFELSE} that are embedded 9531in other macros, including a few of the ones that come with Autoconf, 9532you can test whether the shell variable @code{cross_compiling} is set to 9533@samp{yes}, and then use an alternate method to get the results instead 9534of calling the macros. 9535 9536It is also permissible to temporarily assign to @code{cross_compiling} 9537in order to force tests to behave as though they are in a 9538cross-compilation environment, particularly since this provides a way to 9539test your @var{action-if-cross-compiling} even when you are not using a 9540cross-compiler. 9541 9542@example 9543# We temporarily set cross-compile mode to force AC_COMPUTE_INT 9544# to use the slow link-only method 9545save_cross_compiling=$cross_compiling 9546cross_compiling=yes 9547AC_COMPUTE_INT([@dots{}]) 9548cross_compiling=$save_cross_compiling 9549@end example 9550 9551A C or C++ runtime test should be portable. 9552@xref{Portable C and C++}. 9553 9554Erlang tests must exit themselves the Erlang VM by calling the @code{halt/1} 9555function: the given status code is used to determine the success of the test 9556(status is @code{0}) or its failure (status is different than @code{0}), as 9557explained above. It must be noted that data output through the standard output 9558(e.g., using @code{io:format/2}) may be truncated when halting the VM. 9559Therefore, if a test must output configuration information, it is recommended 9560to create and to output data into the temporary file named @file{conftest.out}, 9561using the functions of module @code{file}. The @code{conftest.out} file is 9562automatically deleted by the @code{AC_RUN_IFELSE} macro. For instance, a 9563simplified implementation of Autoconf's @code{AC_ERLANG_SUBST_LIB_DIR} 9564macro is: 9565 9566@example 9567AC_INIT([LibdirTest], [1.0], [bug-libdirtest@@example.org]) 9568AC_ERLANG_NEED_ERL 9569AC_LANG(Erlang) 9570AC_RUN_IFELSE( 9571 [AC_LANG_PROGRAM([], [dnl 9572 file:write_file("conftest.out", code:lib_dir()), 9573 halt(0)])], 9574 [echo "code:lib_dir() returned: `cat conftest.out`"], 9575 [AC_MSG_FAILURE([test Erlang program execution failed])]) 9576@end example 9577 9578 9579@node Systemology 9580@section Systemology 9581@cindex Systemology 9582 9583This section aims at presenting some systems and pointers to 9584documentation. It may help you addressing particular problems reported 9585by users. 9586 9587@uref{http://@/www.opengroup.org/@/susv3, Posix-conforming systems} are 9588derived from the @uref{http://@/www.bell-labs.com/@/history/@/unix/, Unix 9589operating system}. 9590 9591The @uref{http://@/bhami.com/@/rosetta.html, Rosetta Stone for Unix} 9592contains a table correlating the features of various Posix-conforming 9593systems. @uref{http://@/www.levenez.com/@/unix/, Unix History} is a 9594simplified diagram of how many Unix systems were derived from each 9595other. 9596 9597@uref{http://@/heirloom.sourceforge.net/, The Heirloom Project} 9598provides some variants of traditional implementations of Unix utilities. 9599 9600@table @asis 9601@item Darwin 9602@cindex Darwin 9603Darwin is also known as Mac OS X@. Beware that the file system @emph{can} be 9604case-preserving, but case insensitive. This can cause nasty problems, 9605since for instance the installation attempt for a package having an 9606@file{INSTALL} file can result in @samp{make install} report that 9607nothing was to be done! 9608 9609That's all dependent on whether the file system is a UFS (case 9610sensitive) or HFS+ (case preserving). By default Apple wants you to 9611install the OS on HFS+. Unfortunately, there are some pieces of 9612software which really need to be built on UFS@. We may want to rebuild 9613Darwin to have both UFS and HFS+ available (and put the /local/build 9614tree on the UFS). 9615 9616@item QNX 4.25 9617@cindex QNX 4.25 9618@c FIXME: Please, if you feel like writing something more precise, 9619@c it'd be great. In particular, I can't understand the difference with 9620@c QNX Neutrino. 9621QNX is a realtime operating system running on Intel architecture 9622meant to be scalable from the small embedded systems to the hundred 9623processor super-computer. It claims to be Posix certified. More 9624information is available on the 9625@uref{http://@/www.qnx.com/, QNX home page}. 9626 9627@item Tru64 9628@cindex Tru64 9629@uref{http://@/h30097.www3.hp.com/@/docs/, 9630Documentation of several versions of Tru64} is available in different 9631formats. 9632 9633@item Unix version 7 9634@cindex Unix version 7 9635@cindex V7 9636Officially this was called the ``Seventh Edition'' of ``the UNIX 9637time-sharing system'' but we use the more-common name ``Unix version 7''. 9638Documentation is available in the 9639@uref{http://@/plan9.bell-labs.com/@/7thEdMan/, Unix Seventh Edition Manual}. 9640Previous versions of Unix are called ``Unix version 6'', etc., but 9641they were not as widely used. 9642@end table 9643 9644 9645@node Multiple Cases 9646@section Multiple Cases 9647 9648Some operations are accomplished in several possible ways, depending on 9649the OS variant. Checking for them essentially requires a ``case 9650statement''. Autoconf does not directly provide one; however, it is 9651easy to simulate by using a shell variable to keep track of whether a 9652way to perform the operation has been found yet. 9653 9654Here is an example that uses the shell variable @code{fstype} to keep 9655track of whether the remaining cases need to be checked. Note that 9656since the value of @code{fstype} is under our control, we don't have to 9657use the longer @samp{test "x$fstype" = xno}. 9658 9659@example 9660@group 9661AC_MSG_CHECKING([how to get file system type]) 9662fstype=no 9663# The order of these tests is important. 9664AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statvfs.h> 9665#include <sys/fstyp.h>]])], 9666 [AC_DEFINE([FSTYPE_STATVFS], [1], 9667 [Define if statvfs exists.]) 9668 fstype=SVR4]) 9669if test $fstype = no; then 9670 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h> 9671#include <sys/fstyp.h>]])], 9672 [AC_DEFINE([FSTYPE_USG_STATFS], [1], 9673 [Define if USG statfs.]) 9674 fstype=SVR3]) 9675fi 9676if test $fstype = no; then 9677 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h> 9678#include <sys/vmount.h>]])]), 9679 [AC_DEFINE([FSTYPE_AIX_STATFS], [1], 9680 [Define if AIX statfs.]) 9681 fstype=AIX]) 9682fi 9683# (more cases omitted here) 9684AC_MSG_RESULT([$fstype]) 9685@end group 9686@end example 9687 9688@c ====================================================== Results of Tests. 9689 9690@node Results 9691@chapter Results of Tests 9692 9693Once @command{configure} has determined whether a feature exists, what can 9694it do to record that information? There are four sorts of things it can 9695do: define a C preprocessor symbol, set a variable in the output files, 9696save the result in a cache file for future @command{configure} runs, and 9697print a message letting the user know the result of the test. 9698 9699@menu 9700* Defining Symbols:: Defining C preprocessor symbols 9701* Setting Output Variables:: Replacing variables in output files 9702* Special Chars in Variables:: Characters to beware of in variables 9703* Caching Results:: Speeding up subsequent @command{configure} runs 9704* Printing Messages:: Notifying @command{configure} users 9705@end menu 9706 9707@node Defining Symbols 9708@section Defining C Preprocessor Symbols 9709 9710A common action to take in response to a feature test is to define a C 9711preprocessor symbol indicating the results of the test. That is done by 9712calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}. 9713 9714By default, @code{AC_OUTPUT} places the symbols defined by these macros 9715into the output variable @code{DEFS}, which contains an option 9716@option{-D@var{symbol}=@var{value}} for each symbol defined. Unlike in 9717Autoconf version 1, there is no variable @code{DEFS} defined while 9718@command{configure} is running. To check whether Autoconf macros have 9719already defined a certain C preprocessor symbol, test the value of the 9720appropriate cache variable, as in this example: 9721 9722@example 9723AC_CHECK_FUNC([vprintf], [AC_DEFINE([HAVE_VPRINTF], [1], 9724 [Define if vprintf exists.])]) 9725if test "x$ac_cv_func_vprintf" != xyes; then 9726 AC_CHECK_FUNC([_doprnt], [AC_DEFINE([HAVE_DOPRNT], [1], 9727 [Define if _doprnt exists.])]) 9728fi 9729@end example 9730 9731If @code{AC_CONFIG_HEADERS} has been called, then instead of creating 9732@code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the 9733correct values into @code{#define} statements in a template file. 9734@xref{Configuration Headers}, for more information about this kind of 9735output. 9736 9737@defmac AC_DEFINE (@var{variable}, @var{value}, @ovar{description}) 9738@defmacx AC_DEFINE (@var{variable}) 9739@cvindex @var{variable} 9740@acindex{DEFINE} 9741Define @var{variable} to @var{value} (verbatim), by defining a C 9742preprocessor macro for @var{variable}. @var{variable} should be a C 9743identifier, optionally suffixed by a parenthesized argument list to 9744define a C preprocessor macro with arguments. The macro argument list, 9745if present, should be a comma-separated list of C identifiers, possibly 9746terminated by an ellipsis @samp{...} if C99 syntax is employed. 9747@var{variable} should not contain comments, white space, trigraphs, 9748backslash-newlines, universal character names, or non-ASCII 9749characters. 9750 9751@var{value} may contain backslash-escaped newlines, which will be 9752preserved if you use @code{AC_CONFIG_HEADERS} but flattened if passed 9753via @code{@@DEFS@@} (with no effect on the compilation, since the 9754preprocessor sees only one line in the first place). @var{value} should 9755not contain raw newlines. If you are not using 9756@code{AC_CONFIG_HEADERS}, @var{value} should not contain any @samp{#} 9757characters, as @command{make} tends to eat them. To use a shell 9758variable, use @code{AC_DEFINE_UNQUOTED} instead. 9759 9760@var{description} is only useful if you are using 9761@code{AC_CONFIG_HEADERS}. In this case, @var{description} is put into 9762the generated @file{config.h.in} as the comment before the macro define. 9763The following example defines the C preprocessor variable 9764@code{EQUATION} to be the string constant @samp{"$a > $b"}: 9765 9766@example 9767AC_DEFINE([EQUATION], ["$a > $b"], 9768 [Equation string.]) 9769@end example 9770 9771If neither @var{value} nor @var{description} are given, then 9772@var{value} defaults to 1 instead of to the empty string. This is for 9773backwards compatibility with older versions of Autoconf, but this usage 9774is obsolescent and may be withdrawn in future versions of Autoconf. 9775 9776If the @var{variable} is a literal string, it is passed to 9777@code{m4_pattern_allow} (@pxref{Forbidden Patterns}). 9778 9779If multiple @code{AC_DEFINE} statements are executed for the same 9780@var{variable} name (not counting any parenthesized argument list), 9781the last one wins. 9782@end defmac 9783 9784@defmac AC_DEFINE_UNQUOTED (@var{variable}, @var{value}, @ovar{description}) 9785@defmacx AC_DEFINE_UNQUOTED (@var{variable}) 9786@acindex{DEFINE_UNQUOTED} 9787@cvindex @var{variable} 9788Like @code{AC_DEFINE}, but three shell expansions are 9789performed---once---on @var{variable} and @var{value}: variable expansion 9790(@samp{$}), command substitution (@samp{`}), and backslash escaping 9791(@samp{\}), as if in an unquoted here-document. Single and double quote 9792characters in the value have no 9793special meaning. Use this macro instead of @code{AC_DEFINE} when 9794@var{variable} or @var{value} is a shell variable. Examples: 9795 9796@example 9797AC_DEFINE_UNQUOTED([config_machfile], ["$machfile"], 9798 [Configuration machine file.]) 9799AC_DEFINE_UNQUOTED([GETGROUPS_T], [$ac_cv_type_getgroups], 9800 [getgroups return type.]) 9801AC_DEFINE_UNQUOTED([$ac_tr_hdr], [1], 9802 [Translated header name.]) 9803@end example 9804@end defmac 9805 9806Due to a syntactical bizarreness of the Bourne shell, do not use 9807semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED} 9808calls from other macro calls or shell code; that can cause syntax errors 9809in the resulting @command{configure} script. Use either blanks or 9810newlines. That is, do this: 9811 9812@example 9813AC_CHECK_HEADER([elf.h], 9814 [AC_DEFINE([SVR4], [1], [System V Release 4]) LIBS="-lelf $LIBS"]) 9815@end example 9816 9817@noindent 9818or this: 9819 9820@example 9821AC_CHECK_HEADER([elf.h], 9822 [AC_DEFINE([SVR4], [1], [System V Release 4]) 9823 LIBS="-lelf $LIBS"]) 9824@end example 9825 9826@noindent 9827instead of this: 9828 9829@example 9830AC_CHECK_HEADER([elf.h], 9831 [AC_DEFINE([SVR4], [1], [System V Release 4]); LIBS="-lelf $LIBS"]) 9832@end example 9833 9834@node Setting Output Variables 9835@section Setting Output Variables 9836@cindex Output variables 9837 9838Another way to record the results of tests is to set @dfn{output 9839variables}, which are shell variables whose values are substituted into 9840files that @command{configure} outputs. The two macros below create new 9841output variables. @xref{Preset Output Variables}, for a list of output 9842variables that are always available. 9843 9844@defmac AC_SUBST (@var{variable}, @ovar{value}) 9845@acindex{SUBST} 9846Create an output variable from a shell variable. Make @code{AC_OUTPUT} 9847substitute the variable @var{variable} into output files (typically one 9848or more makefiles). This means that @code{AC_OUTPUT} 9849replaces instances of @samp{@@@var{variable}@@} in input files with the 9850value that the shell variable @var{variable} has when @code{AC_OUTPUT} 9851is called. The value can contain any non-@code{NUL} character, including 9852newline. If you are using Automake 1.11 or newer, for newlines in values 9853you might want to consider using @code{AM_SUBST_NOTMAKE} to prevent 9854@command{automake} from adding a line @code{@var{variable} = 9855@@@var{variable}@@} to the @file{Makefile.in} files (@pxref{Optional, , 9856Automake, automake, Other things Automake recognizes}). 9857 9858Variable occurrences should not overlap: e.g., an input file should 9859not contain @samp{@@@var{var1}@@@var{var2}@@} if @var{var1} and @var{var2} 9860are variable names. 9861The substituted value is not rescanned for more output variables; 9862occurrences of @samp{@@@var{variable}@@} in the value are inserted 9863literally into the output file. (The algorithm uses the special marker 9864@code{|#_!!_#|} internally, so neither the substituted value nor the 9865output file may contain @code{|#_!!_#|}.) 9866 9867If @var{value} is given, in addition assign it to @var{variable}. 9868 9869The string @var{variable} is passed to @code{m4_pattern_allow} 9870(@pxref{Forbidden Patterns}). 9871@end defmac 9872 9873@defmac AC_SUBST_FILE (@var{variable}) 9874@acindex{SUBST_FILE} 9875Another way to create an output variable from a shell variable. Make 9876@code{AC_OUTPUT} insert (without substitutions) the contents of the file 9877named by shell variable @var{variable} into output files. This means 9878that @code{AC_OUTPUT} replaces instances of 9879@samp{@@@var{variable}@@} in output files (such as @file{Makefile.in}) 9880with the contents of the file that the shell variable @var{variable} 9881names when @code{AC_OUTPUT} is called. Set the variable to 9882@file{/dev/null} for cases that do not have a file to insert. 9883This substitution occurs only when the @samp{@@@var{variable}@@} is on a 9884line by itself, optionally surrounded by spaces and tabs. The 9885substitution replaces the whole line, including the spaces, tabs, and 9886the terminating newline. 9887 9888This macro is useful for inserting makefile fragments containing 9889special dependencies or other @command{make} directives for particular host 9890or target types into makefiles. For example, @file{configure.ac} 9891could contain: 9892 9893@example 9894AC_SUBST_FILE([host_frag]) 9895host_frag=$srcdir/conf/sun4.mh 9896@end example 9897 9898@noindent 9899and then a @file{Makefile.in} could contain: 9900 9901@example 9902@@host_frag@@ 9903@end example 9904 9905The string @var{variable} is passed to @code{m4_pattern_allow} 9906(@pxref{Forbidden Patterns}). 9907@end defmac 9908 9909@cindex Precious Variable 9910@cindex Variable, Precious 9911Running @command{configure} in varying environments can be extremely 9912dangerous. If for instance the user runs @samp{CC=bizarre-cc 9913./configure}, then the cache, @file{config.h}, and many other output 9914files depend upon @command{bizarre-cc} being the C compiler. If 9915for some reason the user runs @command{./configure} again, or if it is 9916run via @samp{./config.status --recheck}, (@xref{Automatic Remaking}, 9917and @pxref{config.status Invocation}), then the configuration can be 9918inconsistent, composed of results depending upon two different 9919compilers. 9920 9921Environment variables that affect this situation, such as @samp{CC} 9922above, are called @dfn{precious variables}, and can be declared as such 9923by @code{AC_ARG_VAR}. 9924 9925@defmac AC_ARG_VAR (@var{variable}, @var{description}) 9926@acindex{ARG_VAR} 9927Declare @var{variable} is a precious variable, and include its 9928@var{description} in the variable section of @samp{./configure --help}. 9929 9930Being precious means that 9931@itemize @minus 9932@item 9933@var{variable} is substituted via @code{AC_SUBST}. 9934 9935@item 9936The value of @var{variable} when @command{configure} was launched is 9937saved in the cache, including if it was not specified on the command 9938line but via the environment. Indeed, while @command{configure} can 9939notice the definition of @code{CC} in @samp{./configure CC=bizarre-cc}, 9940it is impossible to notice it in @samp{CC=bizarre-cc ./configure}, 9941which, unfortunately, is what most users do. 9942 9943We emphasize that it is the @emph{initial} value of @var{variable} which 9944is saved, not that found during the execution of @command{configure}. 9945Indeed, specifying @samp{./configure FOO=foo} and letting 9946@samp{./configure} guess that @code{FOO} is @code{foo} can be two 9947different things. 9948 9949@item 9950@var{variable} is checked for consistency between two 9951@command{configure} runs. For instance: 9952 9953@example 9954$ @kbd{./configure --silent --config-cache} 9955$ @kbd{CC=cc ./configure --silent --config-cache} 9956configure: error: `CC' was not set in the previous run 9957configure: error: changes in the environment can compromise \ 9958the build 9959configure: error: run `make distclean' and/or \ 9960`rm config.cache' and start over 9961@end example 9962 9963@noindent 9964and similarly if the variable is unset, or if its content is changed. 9965If the content has white space changes only, then the error is degraded 9966to a warning only, but the old value is reused. 9967 9968@item 9969@var{variable} is kept during automatic reconfiguration 9970(@pxref{config.status Invocation}) as if it had been passed as a command 9971line argument, including when no cache is used: 9972 9973@example 9974$ @kbd{CC=/usr/bin/cc ./configure var=raboof --silent} 9975$ @kbd{./config.status --recheck} 9976running CONFIG_SHELL=/bin/sh /bin/sh ./configure var=raboof \ 9977 CC=/usr/bin/cc --no-create --no-recursion 9978@end example 9979@end itemize 9980@end defmac 9981 9982@node Special Chars in Variables 9983@section Special Characters in Output Variables 9984@cindex Output variables, special characters in 9985 9986Many output variables are intended to be evaluated both by 9987@command{make} and by the shell. Some characters are expanded 9988differently in these two contexts, so to avoid confusion these 9989variables' values should not contain any of the following characters: 9990 9991@example 9992" # $ & ' ( ) * ; < > ? [ \ ^ ` | 9993@end example 9994 9995Also, these variables' values should neither contain newlines, nor start 9996with @samp{~}, nor contain white space or @samp{:} immediately followed 9997by @samp{~}. The values can contain nonempty sequences of white space 9998characters like tabs and spaces, but each such sequence might 9999arbitrarily be replaced by a single space during substitution. 10000 10001These restrictions apply both to the values that @command{configure} 10002computes, and to the values set directly by the user. For example, the 10003following invocations of @command{configure} are problematic, since they 10004attempt to use special characters within @code{CPPFLAGS} and white space 10005within @code{$(srcdir)}: 10006 10007@example 10008CPPFLAGS='-DOUCH="&\"#$*?"' '../My Source/ouch-1.0/configure' 10009 10010'../My Source/ouch-1.0/configure' CPPFLAGS='-DOUCH="&\"#$*?"' 10011@end example 10012 10013@node Caching Results 10014@section Caching Results 10015@cindex Cache 10016 10017To avoid checking for the same features repeatedly in various 10018@command{configure} scripts (or in repeated runs of one script), 10019@command{configure} can optionally save the results of many checks in a 10020@dfn{cache file} (@pxref{Cache Files}). If a @command{configure} script 10021runs with caching enabled and finds a cache file, it reads the results 10022of previous runs from the cache and avoids rerunning those checks. As a 10023result, @command{configure} can then run much faster than if it had to 10024perform all of the checks every time. 10025 10026@defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it}) 10027@acindex{CACHE_VAL} 10028Ensure that the results of the check identified by @var{cache-id} are 10029available. If the results of the check were in the cache file that was 10030read, and @command{configure} was not given the @option{--quiet} or 10031@option{--silent} option, print a message saying that the result was 10032cached; otherwise, run the shell commands @var{commands-to-set-it}. If 10033the shell commands are run to determine the value, the value is 10034saved in the cache file just before @command{configure} creates its output 10035files. @xref{Cache Variable Names}, for how to choose the name of the 10036@var{cache-id} variable. 10037 10038The @var{commands-to-set-it} @emph{must have no side effects} except for 10039setting the variable @var{cache-id}, see below. 10040@end defmac 10041 10042@defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @ 10043 @var{commands-to-set-it}) 10044@acindex{CACHE_CHECK} 10045A wrapper for @code{AC_CACHE_VAL} that takes care of printing the 10046messages. This macro provides a convenient shorthand for the most 10047common way to use these macros. It calls @code{AC_MSG_CHECKING} for 10048@var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and 10049@var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}. 10050 10051The @var{commands-to-set-it} @emph{must have no side effects} except for 10052setting the variable @var{cache-id}, see below. 10053@end defmac 10054 10055It is common to find buggy macros using @code{AC_CACHE_VAL} or 10056@code{AC_CACHE_CHECK}, because people are tempted to call 10057@code{AC_DEFINE} in the @var{commands-to-set-it}. Instead, the code that 10058@emph{follows} the call to @code{AC_CACHE_VAL} should call 10059@code{AC_DEFINE}, by examining the value of the cache variable. For 10060instance, the following macro is broken: 10061 10062@example 10063@c If you change this example, adjust tests/base.at:AC_CACHE_CHECK. 10064@group 10065AC_DEFUN([AC_SHELL_TRUE], 10066[AC_CACHE_CHECK([whether true(1) works], [my_cv_shell_true_works], 10067 [my_cv_shell_true_works=no 10068 (true) 2>/dev/null && my_cv_shell_true_works=yes 10069 if test "x$my_cv_shell_true_works" = xyes; then 10070 AC_DEFINE([TRUE_WORKS], [1], 10071 [Define if `true(1)' works properly.]) 10072 fi]) 10073]) 10074@end group 10075@end example 10076 10077@noindent 10078This fails if the cache is enabled: the second time this macro is run, 10079@code{TRUE_WORKS} @emph{will not be defined}. The proper implementation 10080is: 10081 10082@example 10083@c If you change this example, adjust tests/base.at:AC_CACHE_CHECK. 10084@group 10085AC_DEFUN([AC_SHELL_TRUE], 10086[AC_CACHE_CHECK([whether true(1) works], [my_cv_shell_true_works], 10087 [my_cv_shell_true_works=no 10088 (true) 2>/dev/null && my_cv_shell_true_works=yes]) 10089 if test "x$my_cv_shell_true_works" = xyes; then 10090 AC_DEFINE([TRUE_WORKS], [1], 10091 [Define if `true(1)' works properly.]) 10092 fi 10093]) 10094@end group 10095@end example 10096 10097Also, @var{commands-to-set-it} should not print any messages, for 10098example with @code{AC_MSG_CHECKING}; do that before calling 10099@code{AC_CACHE_VAL}, so the messages are printed regardless of whether 10100the results of the check are retrieved from the cache or determined by 10101running the shell commands. 10102 10103@menu 10104* Cache Variable Names:: Shell variables used in caches 10105* Cache Files:: Files @command{configure} uses for caching 10106* Cache Checkpointing:: Loading and saving the cache file 10107@end menu 10108 10109@node Cache Variable Names 10110@subsection Cache Variable Names 10111@cindex Cache variable 10112 10113The names of cache variables should have the following format: 10114 10115@example 10116@var{package-prefix}_cv_@var{value-type}_@var{specific-value}_@ovar{additional-options} 10117@end example 10118 10119@noindent 10120for example, @samp{ac_cv_header_stat_broken} or 10121@samp{ac_cv_prog_gcc_traditional}. The parts of the variable name are: 10122 10123@table @asis 10124@item @var{package-prefix} 10125An abbreviation for your package or organization; the same prefix you 10126begin local Autoconf macros with, except lowercase by convention. 10127For cache values used by the distributed Autoconf macros, this value is 10128@samp{ac}. 10129 10130@item @code{_cv_} 10131Indicates that this shell variable is a cache value. This string 10132@emph{must} be present in the variable name, including the leading 10133underscore. 10134 10135@item @var{value-type} 10136A convention for classifying cache values, to produce a rational naming 10137system. The values used in Autoconf are listed in @ref{Macro Names}. 10138 10139@item @var{specific-value} 10140Which member of the class of cache values this test applies to. 10141For example, which function (@samp{alloca}), program (@samp{gcc}), or 10142output variable (@samp{INSTALL}). 10143 10144@item @var{additional-options} 10145Any particular behavior of the specific member that this test applies to. 10146For example, @samp{broken} or @samp{set}. This part of the name may 10147be omitted if it does not apply. 10148@end table 10149 10150The values assigned to cache variables may not contain newlines. 10151Usually, their values are Boolean (@samp{yes} or @samp{no}) or the 10152names of files or functions; so this is not an important restriction. 10153@ref{Cache Variable Index} for an index of cache variables with 10154documented semantics. 10155 10156 10157@node Cache Files 10158@subsection Cache Files 10159 10160A cache file is a shell script that caches the results of configure 10161tests run on one system so they can be shared between configure scripts 10162and configure runs. It is not useful on other systems. If its contents 10163are invalid for some reason, the user may delete or edit it, or override 10164documented cache variables on the @command{configure} command line. 10165 10166By default, @command{configure} uses no cache file, 10167to avoid problems caused by accidental 10168use of stale cache files. 10169 10170To enable caching, @command{configure} accepts @option{--config-cache} (or 10171@option{-C}) to cache results in the file @file{config.cache}. 10172Alternatively, @option{--cache-file=@var{file}} specifies that 10173@var{file} be the cache file. The cache file is created if it does not 10174exist already. When @command{configure} calls @command{configure} scripts in 10175subdirectories, it uses the @option{--cache-file} argument so that they 10176share the same cache. @xref{Subdirectories}, for information on 10177configuring subdirectories with the @code{AC_CONFIG_SUBDIRS} macro. 10178 10179@file{config.status} only pays attention to the cache file if it is 10180given the @option{--recheck} option, which makes it rerun 10181@command{configure}. 10182 10183It is wrong to try to distribute cache files for particular system types. 10184There is too much room for error in doing that, and too much 10185administrative overhead in maintaining them. For any features that 10186can't be guessed automatically, use the standard method of the canonical 10187system type and linking files (@pxref{Manual Configuration}). 10188 10189The site initialization script can specify a site-wide cache file to 10190use, instead of the usual per-program cache. In this case, the cache 10191file gradually accumulates information whenever someone runs a new 10192@command{configure} script. (Running @command{configure} merges the new cache 10193results with the existing cache file.) This may cause problems, 10194however, if the system configuration (e.g., the installed libraries or 10195compilers) changes and the stale cache file is not deleted. 10196 10197If @command{configure} is interrupted at the right time when it updates 10198a cache file outside of the build directory where the @command{configure} 10199script is run, it may leave behind a temporary file named after the 10200cache file with digits following it. You may safely delete such a file. 10201 10202 10203@node Cache Checkpointing 10204@subsection Cache Checkpointing 10205 10206If your configure script, or a macro called from @file{configure.ac}, happens 10207to abort the configure process, it may be useful to checkpoint the cache 10208a few times at key points using @code{AC_CACHE_SAVE}. Doing so 10209reduces the amount of time it takes to rerun the configure script with 10210(hopefully) the error that caused the previous abort corrected. 10211 10212@c FIXME: Do we really want to document this guy? 10213@defmac AC_CACHE_LOAD 10214@acindex{CACHE_LOAD} 10215Loads values from existing cache file, or creates a new cache file if a 10216cache file is not found. Called automatically from @code{AC_INIT}. 10217@end defmac 10218 10219@defmac AC_CACHE_SAVE 10220@acindex{CACHE_SAVE} 10221Flushes all cached values to the cache file. Called automatically from 10222@code{AC_OUTPUT}, but it can be quite useful to call 10223@code{AC_CACHE_SAVE} at key points in @file{configure.ac}. 10224@end defmac 10225 10226For instance: 10227 10228@example 10229@r{ @dots{} AC_INIT, etc. @dots{}} 10230@group 10231# Checks for programs. 10232AC_PROG_CC 10233AC_PROG_AWK 10234@r{ @dots{} more program checks @dots{}} 10235AC_CACHE_SAVE 10236@end group 10237 10238@group 10239# Checks for libraries. 10240AC_CHECK_LIB([nsl], [gethostbyname]) 10241AC_CHECK_LIB([socket], [connect]) 10242@r{ @dots{} more lib checks @dots{}} 10243AC_CACHE_SAVE 10244@end group 10245 10246@group 10247# Might abort@dots{} 10248AM_PATH_GTK([1.0.2], [], [AC_MSG_ERROR([GTK not in path])]) 10249AM_PATH_GTKMM([0.9.5], [], [AC_MSG_ERROR([GTK not in path])]) 10250@end group 10251@r{ @dots{} AC_OUTPUT, etc. @dots{}} 10252@end example 10253 10254@node Printing Messages 10255@section Printing Messages 10256@cindex Messages, from @command{configure} 10257 10258@command{configure} scripts need to give users running them several kinds 10259of information. The following macros print messages in ways appropriate 10260for each kind. The arguments to all of them get enclosed in shell 10261double quotes, so the shell performs variable and back-quote 10262substitution on them. 10263 10264These macros are all wrappers around the @command{echo} shell command. 10265They direct output to the appropriate file descriptor (@pxref{File 10266Descriptor Macros}). 10267@command{configure} scripts should rarely need to run @command{echo} directly 10268to print messages for the user. Using these macros makes it easy to 10269change how and when each kind of message is printed; such changes need 10270only be made to the macro definitions and all the callers change 10271automatically. 10272 10273To diagnose static issues, i.e., when @command{autoconf} is run, see 10274@ref{Diagnostic Macros}. 10275 10276@defmac AC_MSG_CHECKING (@var{feature-description}) 10277@acindex{MSG_CHECKING} 10278Notify the user that @command{configure} is checking for a particular 10279feature. This macro prints a message that starts with @samp{checking } 10280and ends with @samp{...} and no newline. It must be followed by a call 10281to @code{AC_MSG_RESULT} to print the result of the check and the 10282newline. The @var{feature-description} should be something like 10283@samp{whether the Fortran compiler accepts C++ comments} or @samp{for 10284c89}. 10285 10286This macro prints nothing if @command{configure} is run with the 10287@option{--quiet} or @option{--silent} option. 10288@end defmac 10289 10290@anchor{AC_MSG_RESULT} 10291@defmac AC_MSG_RESULT (@var{result-description}) 10292@acindex{MSG_RESULT} 10293Notify the user of the results of a check. @var{result-description} is 10294almost always the value of the cache variable for the check, typically 10295@samp{yes}, @samp{no}, or a file name. This macro should follow a call 10296to @code{AC_MSG_CHECKING}, and the @var{result-description} should be 10297the completion of the message printed by the call to 10298@code{AC_MSG_CHECKING}. 10299 10300This macro prints nothing if @command{configure} is run with the 10301@option{--quiet} or @option{--silent} option. 10302@end defmac 10303 10304@anchor{AC_MSG_NOTICE} 10305@defmac AC_MSG_NOTICE (@var{message}) 10306@acindex{MSG_NOTICE} 10307Deliver the @var{message} to the user. It is useful mainly to print a 10308general description of the overall purpose of a group of feature checks, 10309e.g., 10310 10311@example 10312AC_MSG_NOTICE([checking if stack overflow is detectable]) 10313@end example 10314 10315This macro prints nothing if @command{configure} is run with the 10316@option{--quiet} or @option{--silent} option. 10317@end defmac 10318 10319@anchor{AC_MSG_ERROR} 10320@defmac AC_MSG_ERROR (@var{error-description}, @dvar{exit-status, $?/1}) 10321@acindex{MSG_ERROR} 10322Notify the user of an error that prevents @command{configure} from 10323completing. This macro prints an error message to the standard error 10324output and exits @command{configure} with @var{exit-status} (@samp{$?} 10325by default, except that @samp{0} is converted to @samp{1}). 10326@var{error-description} should be something like @samp{invalid value 10327$HOME for \$HOME}. 10328 10329The @var{error-description} should start with a lower-case letter, and 10330``cannot'' is preferred to ``can't''. 10331@end defmac 10332 10333@defmac AC_MSG_FAILURE (@var{error-description}, @ovar{exit-status}) 10334@acindex{MSG_FAILURE} 10335This @code{AC_MSG_ERROR} wrapper notifies the user of an error that 10336prevents @command{configure} from completing @emph{and} that additional 10337details are provided in @file{config.log}. This is typically used when 10338abnormal results are found during a compilation. 10339@end defmac 10340 10341@anchor{AC_MSG_WARN} 10342@defmac AC_MSG_WARN (@var{problem-description}) 10343@acindex{MSG_WARN} 10344Notify the @command{configure} user of a possible problem. This macro 10345prints the message to the standard error output; @command{configure} 10346continues running afterward, so macros that call @code{AC_MSG_WARN} should 10347provide a default (back-up) behavior for the situations they warn about. 10348@var{problem-description} should be something like @samp{ln -s seems to 10349make hard links}. 10350@end defmac 10351 10352 10353 10354@c ====================================================== Programming in M4. 10355 10356@node Programming in M4 10357@chapter Programming in M4 10358@cindex M4 10359 10360Autoconf is written on top of two layers: @dfn{M4sugar}, which provides 10361convenient macros for pure M4 programming, and @dfn{M4sh}, which 10362provides macros dedicated to shell script generation. 10363 10364As of this version of Autoconf, these two layers still contain 10365experimental macros, whose interface might change in the future. As a 10366matter of fact, @emph{anything that is not documented must not be used}. 10367 10368@menu 10369* M4 Quotation:: Protecting macros from unwanted expansion 10370* Using autom4te:: The Autoconf executables backbone 10371* Programming in M4sugar:: Convenient pure M4 macros 10372* Debugging via autom4te:: Figuring out what M4 was doing 10373@end menu 10374 10375@node M4 Quotation 10376@section M4 Quotation 10377@cindex M4 quotation 10378@cindex quotation 10379 10380The most common problem with existing macros is an improper quotation. 10381This section, which users of Autoconf can skip, but which macro writers 10382@emph{must} read, first justifies the quotation scheme that was chosen 10383for Autoconf and then ends with a rule of thumb. Understanding the 10384former helps one to follow the latter. 10385 10386@menu 10387* Active Characters:: Characters that change the behavior of M4 10388* One Macro Call:: Quotation and one macro call 10389* Quoting and Parameters:: M4 vs. shell parameters 10390* Quotation and Nested Macros:: Macros calling macros 10391* Changequote is Evil:: Worse than INTERCAL: M4 + changequote 10392* Quadrigraphs:: Another way to escape special characters 10393* Balancing Parentheses:: Dealing with unbalanced parentheses 10394* Quotation Rule Of Thumb:: One parenthesis, one quote 10395@end menu 10396 10397@node Active Characters 10398@subsection Active Characters 10399 10400To fully understand where proper quotation is important, you first need 10401to know what the special characters are in Autoconf: @samp{#} introduces 10402a comment inside which no macro expansion is performed, @samp{,} 10403separates arguments, @samp{[} and @samp{]} are the quotes 10404themselves@footnote{By itself, M4 uses @samp{`} and @samp{'}; it is the 10405M4sugar layer that sets up the preferred quotes of @samp{[} and @samp{]}.}, 10406@samp{(} and @samp{)} (which M4 tries to match by pairs), and finally 10407@samp{$} inside a macro definition. 10408 10409In order to understand the delicate case of macro calls, we first have 10410to present some obvious failures. Below they are ``obvious-ified'', 10411but when you find them in real life, they are usually in disguise. 10412 10413Comments, introduced by a hash and running up to the newline, are opaque 10414tokens to the top level: active characters are turned off, and there is 10415no macro expansion: 10416 10417@example 10418# define([def], ine) 10419@result{}# define([def], ine) 10420@end example 10421 10422Each time there can be a macro expansion, there is a quotation 10423expansion, i.e., one level of quotes is stripped: 10424 10425@example 10426int tab[10]; 10427@result{}int tab10; 10428[int tab[10];] 10429@result{}int tab[10]; 10430@end example 10431 10432Without this in mind, the reader might try hopelessly to use her macro 10433@code{array}: 10434 10435@example 10436define([array], [int tab[10];]) 10437array 10438@result{}int tab10; 10439[array] 10440@result{}array 10441@end example 10442 10443@noindent 10444How can you correctly output the intended results@footnote{Using 10445@code{defn}.}? 10446 10447 10448@node One Macro Call 10449@subsection One Macro Call 10450 10451Let's proceed on the interaction between active characters and macros 10452with this small macro, which just returns its first argument: 10453 10454@example 10455define([car], [$1]) 10456@end example 10457 10458@noindent 10459The two pairs of quotes above are not part of the arguments of 10460@code{define}; rather, they are understood by the top level when it 10461tries to find the arguments of @code{define}. Therefore, assuming 10462@code{car} is not already defined, it is equivalent to write: 10463 10464@example 10465define(car, $1) 10466@end example 10467 10468@noindent 10469But, while it is acceptable for a @file{configure.ac} to avoid unnecessary 10470quotes, it is bad practice for Autoconf macros which must both be more 10471robust and also advocate perfect style. 10472 10473At the top level, there are only two possibilities: either you 10474quote or you don't: 10475 10476@example 10477car(foo, bar, baz) 10478@result{}foo 10479[car(foo, bar, baz)] 10480@result{}car(foo, bar, baz) 10481@end example 10482 10483Let's pay attention to the special characters: 10484 10485@example 10486car(#) 10487@error{}EOF in argument list 10488@end example 10489 10490The closing parenthesis is hidden in the comment; with a hypothetical 10491quoting, the top level understood it this way: 10492 10493@example 10494car([#)] 10495@end example 10496 10497@noindent 10498Proper quotation, of course, fixes the problem: 10499 10500@example 10501car([#]) 10502@result{}# 10503@end example 10504 10505Here are more examples: 10506 10507@example 10508car(foo, bar) 10509@result{}foo 10510car([foo, bar]) 10511@result{}foo, bar 10512car((foo, bar)) 10513@result{}(foo, bar) 10514car([(foo], [bar)]) 10515@result{}(foo 10516define([a], [b]) 10517@result{} 10518car(a) 10519@result{}b 10520car([a]) 10521@result{}b 10522car([[a]]) 10523@result{}a 10524car([[[a]]]) 10525@result{}[a] 10526@end example 10527 10528@node Quoting and Parameters 10529@subsection Quoting and Parameters 10530 10531When M4 encounters @samp{$} within a macro definition, followed 10532immediately by a character it recognizes (@samp{0}@dots{}@samp{9}, 10533@samp{#}, @samp{@@}, or @samp{*}), it will perform M4 parameter 10534expansion. This happens regardless of how many layers of quotes the 10535parameter expansion is nested within, or even if it occurs in text that 10536will be rescanned as a comment. 10537 10538@example 10539define([none], [$1]) 10540@result{} 10541define([one], [[$1]]) 10542@result{} 10543define([two], [[[$1]]]) 10544@result{} 10545define([comment], [# $1]) 10546@result{} 10547define([active], [ACTIVE]) 10548@result{} 10549none([active]) 10550@result{}ACTIVE 10551one([active]) 10552@result{}active 10553two([active]) 10554@result{}[active] 10555comment([active]) 10556@result{}# active 10557@end example 10558 10559On the other hand, since autoconf generates shell code, you often want 10560to output shell variable expansion, rather than performing M4 parameter 10561expansion. To do this, you must use M4 quoting to separate the @samp{$} 10562from the next character in the definition of your macro. If the macro 10563definition occurs in single-quoted text, then insert another level of 10564quoting; if the usage is already inside a double-quoted string, then 10565split it into concatenated strings. 10566 10567@example 10568define([single], [a single-quoted $[]1 definition]) 10569@result{} 10570define([double], [[a double-quoted $][1 definition]]) 10571@result{} 10572single 10573@result{}a single-quoted $1 definition 10574double 10575@result{}a double-quoted $1 definition 10576@end example 10577 10578Posix states that M4 implementations are free to provide implementation 10579extensions when @samp{$@{} is encountered in a macro definition. 10580Autoconf reserves the longer sequence @samp{$@{@{} for use with planned 10581extensions that will be available in the future GNU M4 2.0, 10582but guarantees that all other instances of @samp{$@{} will be output 10583literally. Therefore, this idiom can also be used to output shell code 10584parameter references: 10585 10586@example 10587define([first], [$@{1@}])first 10588@result{}$@{1@} 10589@end example 10590 10591Posix also states that @samp{$11} should expand to the first parameter 10592concatenated with a literal @samp{1}, although some versions of 10593GNU M4 expand the eleventh parameter instead. For 10594portability, you should only use single-digit M4 parameter expansion. 10595 10596With this in mind, we can explore the cases where macros invoke 10597macros@enddots{} 10598 10599@node Quotation and Nested Macros 10600@subsection Quotation and Nested Macros 10601 10602The examples below use the following macros: 10603 10604@example 10605define([car], [$1]) 10606define([active], [ACT, IVE]) 10607define([array], [int tab[10]]) 10608@end example 10609 10610Each additional embedded macro call introduces other possible 10611interesting quotations: 10612 10613@example 10614car(active) 10615@result{}ACT 10616car([active]) 10617@result{}ACT, IVE 10618car([[active]]) 10619@result{}active 10620@end example 10621 10622In the first case, the top level looks for the arguments of @code{car}, 10623and finds @samp{active}. Because M4 evaluates its arguments 10624before applying the macro, @samp{active} is expanded, which results in: 10625 10626@example 10627car(ACT, IVE) 10628@result{}ACT 10629@end example 10630 10631@noindent 10632In the second case, the top level gives @samp{active} as first and only 10633argument of @code{car}, which results in: 10634 10635@example 10636active 10637@result{}ACT, IVE 10638@end example 10639 10640@noindent 10641i.e., the argument is evaluated @emph{after} the macro that invokes it. 10642In the third case, @code{car} receives @samp{[active]}, which results in: 10643 10644@example 10645[active] 10646@result{}active 10647@end example 10648 10649@noindent 10650exactly as we already saw above. 10651 10652The example above, applied to a more realistic example, gives: 10653 10654@example 10655car(int tab[10];) 10656@result{}int tab10; 10657car([int tab[10];]) 10658@result{}int tab10; 10659car([[int tab[10];]]) 10660@result{}int tab[10]; 10661@end example 10662 10663@noindent 10664Huh? The first case is easily understood, but why is the second wrong, 10665and the third right? To understand that, you must know that after 10666M4 expands a macro, the resulting text is immediately subjected 10667to macro expansion and quote removal. This means that the quote removal 10668occurs twice---first before the argument is passed to the @code{car} 10669macro, and second after the @code{car} macro expands to the first 10670argument. 10671 10672As the author of the Autoconf macro @code{car}, you then consider it to 10673be incorrect that your users have to double-quote the arguments of 10674@code{car}, so you ``fix'' your macro. Let's call it @code{qar} for 10675quoted car: 10676 10677@example 10678define([qar], [[$1]]) 10679@end example 10680 10681@noindent 10682and check that @code{qar} is properly fixed: 10683 10684@example 10685qar([int tab[10];]) 10686@result{}int tab[10]; 10687@end example 10688 10689@noindent 10690Ahhh! That's much better. 10691 10692But note what you've done: now that the result of @code{qar} is always 10693a literal string, the only time a user can use nested macros is if she 10694relies on an @emph{unquoted} macro call: 10695 10696@example 10697qar(active) 10698@result{}ACT 10699qar([active]) 10700@result{}active 10701@end example 10702 10703@noindent 10704leaving no way for her to reproduce what she used to do with @code{car}: 10705 10706@example 10707car([active]) 10708@result{}ACT, IVE 10709@end example 10710 10711@noindent 10712Worse yet: she wants to use a macro that produces a set of @code{cpp} 10713macros: 10714 10715@example 10716define([my_includes], [#include <stdio.h>]) 10717car([my_includes]) 10718@result{}#include <stdio.h> 10719qar(my_includes) 10720@error{}EOF in argument list 10721@end example 10722 10723This macro, @code{qar}, because it double quotes its arguments, forces 10724its users to leave their macro calls unquoted, which is dangerous. 10725Commas and other active symbols are interpreted by M4 before 10726they are given to the macro, often not in the way the users expect. 10727Also, because @code{qar} behaves differently from the other macros, 10728it's an exception that should be avoided in Autoconf. 10729 10730@node Changequote is Evil 10731@subsection @code{changequote} is Evil 10732@cindex @code{changequote} 10733 10734The temptation is often high to bypass proper quotation, in particular 10735when it's late at night. Then, many experienced Autoconf hackers 10736finally surrender to the dark side of the force and use the ultimate 10737weapon: @code{changequote}. 10738 10739The M4 builtin @code{changequote} belongs to a set of primitives that 10740allow one to adjust the syntax of the language to adjust it to one's 10741needs. For instance, by default M4 uses @samp{`} and @samp{'} as 10742quotes, but in the context of shell programming (and actually of most 10743programming languages), that's about the worst choice one can make: 10744because of strings and back-quoted expressions in shell code (such as 10745@samp{'this'} and @samp{`that`}), and because of literal characters in usual 10746programming languages (as in @samp{'0'}), there are many unbalanced 10747@samp{`} and @samp{'}. Proper M4 quotation then becomes a nightmare, if 10748not impossible. In order to make M4 useful in such a context, its 10749designers have equipped it with @code{changequote}, which makes it 10750possible to choose another pair of quotes. M4sugar, M4sh, Autoconf, and 10751Autotest all have chosen to use @samp{[} and @samp{]}. Not especially 10752because they are unlikely characters, but @emph{because they are 10753characters unlikely to be unbalanced}. 10754 10755There are other magic primitives, such as @code{changecom} to specify 10756what syntactic forms are comments (it is common to see 10757@samp{changecom(<!--, -->)} when M4 is used to produce HTML pages), 10758@code{changeword} and @code{changesyntax} to change other syntactic 10759details (such as the character to denote the @var{n}th argument, @samp{$} by 10760default, the parentheses around arguments, etc.). 10761 10762These primitives are really meant to make M4 more useful for specific 10763domains: they should be considered like command line options: 10764@option{--quotes}, @option{--comments}, @option{--words}, and 10765@option{--syntax}. Nevertheless, they are implemented as M4 builtins, as 10766it makes M4 libraries self contained (no need for additional options). 10767 10768There lies the problem@enddots{} 10769 10770@sp 1 10771 10772The problem is that it is then tempting to use them in the middle of an 10773M4 script, as opposed to its initialization. This, if not carefully 10774thought out, can lead to disastrous effects: @emph{you are changing the 10775language in the middle of the execution}. Changing and restoring the 10776syntax is often not enough: if you happened to invoke macros in between, 10777these macros are lost, as the current syntax is probably not 10778the one they were implemented with. 10779 10780@c FIXME: I've been looking for a short, real case example, but I 10781@c lost them all :( 10782 10783 10784@node Quadrigraphs 10785@subsection Quadrigraphs 10786@cindex quadrigraphs 10787@cindex @samp{@@S|@@} 10788@cindex @samp{@@&t@@} 10789@c Info cannot handle `:' in index entries. 10790@ifnotinfo 10791@cindex @samp{@@<:@@} 10792@cindex @samp{@@:>@@} 10793@cindex @samp{@@%:@@} 10794@cindex @samp{@@@{:@@} 10795@cindex @samp{@@:@}@@} 10796@end ifnotinfo 10797 10798When writing an Autoconf macro you may occasionally need to generate 10799special characters that are difficult to express with the standard 10800Autoconf quoting rules. For example, you may need to output the regular 10801expression @samp{[^[]}, which matches any character other than @samp{[}. 10802This expression contains unbalanced brackets so it cannot be put easily 10803into an M4 macro. 10804 10805Additionally, there are a few m4sugar macros (such as @code{m4_split} 10806and @code{m4_expand}) which internally use special markers in addition 10807to the regular quoting characters. If the arguments to these macros 10808contain the literal strings @samp{-=<@{(} or @samp{)@}>=-}, the macros 10809might behave incorrectly. 10810 10811You can work around these problems by using one of the following 10812@dfn{quadrigraphs}: 10813 10814@table @samp 10815@item @@<:@@ 10816@samp{[} 10817@item @@:>@@ 10818@samp{]} 10819@item @@S|@@ 10820@samp{$} 10821@item @@%:@@ 10822@samp{#} 10823@item @@@{:@@ 10824@samp{(} 10825@item @@:@}@@ 10826@samp{)} 10827@item @@&t@@ 10828Expands to nothing. 10829@end table 10830 10831Quadrigraphs are replaced at a late stage of the translation process, 10832after @command{m4} is run, so they do not get in the way of M4 quoting. 10833For example, the string @samp{^@@<:@@}, independently of its quotation, 10834appears as @samp{^[} in the output. 10835 10836The empty quadrigraph can be used: 10837 10838@itemize @minus 10839@item to mark trailing spaces explicitly 10840 10841Trailing spaces are smashed by @command{autom4te}. This is a feature. 10842 10843@item to produce quadrigraphs and other strings reserved by m4sugar 10844 10845For instance @samp{@@<@@&t@@:@@} produces @samp{@@<:@@}. For a more 10846contrived example: 10847 10848@example 10849m4_define([a], [A])m4_define([b], [B])m4_define([c], [C])dnl 10850m4_split([a )@}>=- b -=<@{( c]) 10851@result{}[a], [], [B], [], [c] 10852m4_split([a )@}@@&t@@>=- b -=<@@&t@@@{( c]) 10853@result{}[a], [)@}>=-], [b], [-=<@{(], [c] 10854@end example 10855 10856@item to escape @emph{occurrences} of forbidden patterns 10857 10858For instance you might want to mention @code{AC_FOO} in a comment, while 10859still being sure that @command{autom4te} still catches unexpanded 10860@samp{AC_*}. Then write @samp{AC@@&t@@_FOO}. 10861@end itemize 10862 10863The name @samp{@@&t@@} was suggested by Paul Eggert: 10864 10865@quotation 10866I should give some credit to the @samp{@@&t@@} pun. The @samp{&} is my 10867own invention, but the @samp{t} came from the source code of the 10868ALGOL68C compiler, written by Steve Bourne (of Bourne shell fame), 10869and which used @samp{mt} to denote the empty string. In C, it would 10870have looked like something like: 10871 10872@example 10873char const mt[] = ""; 10874@end example 10875 10876@noindent 10877but of course the source code was written in Algol 68. 10878 10879I don't know where he got @samp{mt} from: it could have been his own 10880invention, and I suppose it could have been a common pun around the 10881Cambridge University computer lab at the time. 10882@end quotation 10883 10884 10885@node Balancing Parentheses 10886@subsection Dealing with unbalanced parentheses 10887@cindex balancing parentheses 10888@cindex parentheses, balancing 10889@cindex unbalanced parentheses, managing 10890 10891One of the pitfalls of portable shell programming is that @command{case} 10892statements require unbalanced parentheses (@pxref{case, , Limitations of 10893Shell Builtins}). With syntax highlighting 10894editors, the presence of unbalanced @samp{)} can interfere with editors 10895that perform syntax highlighting of macro contents based on finding the 10896matching @samp{(}. Another concern is how much editing must be done 10897when transferring code snippets between shell scripts and macro 10898definitions. But most importantly, the presence of unbalanced 10899parentheses can introduce expansion bugs. 10900 10901For an example, here is an underquoted attempt to use the macro 10902@code{my_case}, which happens to expand to a portable @command{case} 10903statement: 10904 10905@example 10906AC_DEFUN([my_case], 10907[case $file_name in 10908 *.c) echo "C source code";; 10909esac]) 10910AS_IF(:, my_case) 10911@end example 10912 10913@noindent 10914In the above example, the @code{AS_IF} call underquotes its arguments. 10915As a result, the unbalanced @samp{)} generated by the premature 10916expansion of @code{my_case} results in expanding @code{AS_IF} with a 10917truncated parameter, and the expansion is syntactically invalid: 10918 10919@example 10920if :; then 10921 case $file_name in 10922 *.c 10923fi echo "C source code";; 10924esac) 10925@end example 10926 10927If nothing else, this should emphasize the importance of the quoting 10928arguments to macro calls. On the other hand, there are several 10929variations for defining @code{my_case} to be more robust, even when used 10930without proper quoting, each with some benefits and some drawbacks. 10931 10932@itemize @w{} 10933@item Creative literal shell comment 10934@example 10935AC_DEFUN([my_case], 10936[case $file_name in #( 10937 *.c) echo "C source code";; 10938esac]) 10939@end example 10940@noindent 10941This version provides balanced parentheses to several editors, and can 10942be copied and pasted into a terminal as is. Unfortunately, it is still 10943unbalanced as an Autoconf argument, since @samp{#(} is an M4 comment 10944that masks the normal properties of @samp{(}. 10945 10946@item Quadrigraph shell comment 10947@example 10948AC_DEFUN([my_case], 10949[case $file_name in @@%:@@( 10950 *.c) echo "C source code";; 10951esac]) 10952@end example 10953@noindent 10954This version provides balanced parentheses to even more editors, and can 10955be used as a balanced Autoconf argument. Unfortunately, it requires 10956some editing before it can be copied and pasted into a terminal, and the 10957use of the quadrigraph @samp{@@%:@@} for @samp{#} reduces readability. 10958 10959@item Quoting just the parenthesis 10960@example 10961AC_DEFUN([my_case], 10962[case $file_name in 10963 *.c[)] echo "C source code";; 10964esac]) 10965@end example 10966@noindent 10967This version quotes the @samp{)}, so that it can be used as a balanced 10968Autoconf argument. As written, this is not balanced to an editor, but 10969it can be coupled with @samp{[#(]} to meet that need, too. However, it 10970still requires some edits before it can be copied and pasted into a 10971terminal. 10972 10973@item Double-quoting the entire statement 10974@example 10975AC_DEFUN([my_case], 10976[[case $file_name in #( 10977 *.c) echo "C source code";; 10978esac]]) 10979@end example 10980@noindent 10981Since the entire macro is double-quoted, there is no problem with using 10982this as an Autoconf argument; and since the double-quoting is over the 10983entire statement, this code can be easily copied and pasted into a 10984terminal. However, the double quoting prevents the expansion of any 10985macros inside the case statement, which may cause its own set of 10986problems. 10987 10988@item Using @code{AS_CASE} 10989@example 10990AC_DEFUN([my_case], 10991[AS_CASE([$file_name], 10992 [*.c], [echo "C source code"])]) 10993@end example 10994@noindent 10995This version avoids the balancing issue altogether, by relying on 10996@code{AS_CASE} (@pxref{Common Shell Constructs}); it also allows for the 10997expansion of @code{AC_REQUIRE} to occur prior to the entire case 10998statement, rather than within a branch of the case statement that might 10999not be taken. However, the abstraction comes with a penalty that it is 11000no longer a quick copy, paste, and edit to get back to shell code. 11001@end itemize 11002 11003 11004@node Quotation Rule Of Thumb 11005@subsection Quotation Rule Of Thumb 11006 11007To conclude, the quotation rule of thumb is: 11008 11009@center @emph{One pair of quotes per pair of parentheses.} 11010 11011Never over-quote, never under-quote, in particular in the definition of 11012macros. In the few places where the macros need to use brackets 11013(usually in C program text or regular expressions), properly quote 11014@emph{the arguments}! 11015 11016It is common to read Autoconf programs with snippets like: 11017 11018@example 11019AC_TRY_LINK( 11020changequote(<<, >>)dnl 11021<<#include <time.h> 11022#ifndef tzname /* For SGI. */ 11023extern char *tzname[]; /* RS6000 and others reject char **tzname. */ 11024#endif>>, 11025changequote([, ])dnl 11026[atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no) 11027@end example 11028 11029@noindent 11030which is incredibly useless since @code{AC_TRY_LINK} is @emph{already} 11031double quoting, so you just need: 11032 11033@example 11034AC_TRY_LINK( 11035[#include <time.h> 11036#ifndef tzname /* For SGI. */ 11037extern char *tzname[]; /* RS6000 and others reject char **tzname. */ 11038#endif], 11039 [atoi (*tzname);], 11040 [ac_cv_var_tzname=yes], 11041 [ac_cv_var_tzname=no]) 11042@end example 11043 11044@noindent 11045The M4-fluent reader might note that these two examples are rigorously 11046equivalent, since M4 swallows both the @samp{changequote(<<, >>)} 11047and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these 11048quotes are not part of the arguments! 11049 11050Simplified, the example above is just doing this: 11051 11052@example 11053changequote(<<, >>)dnl 11054<<[]>> 11055changequote([, ])dnl 11056@end example 11057 11058@noindent 11059instead of simply: 11060 11061@example 11062[[]] 11063@end example 11064 11065With macros that do not double quote their arguments (which is the 11066rule), double-quote the (risky) literals: 11067 11068@example 11069AC_LINK_IFELSE([AC_LANG_PROGRAM( 11070[[#include <time.h> 11071#ifndef tzname /* For SGI. */ 11072extern char *tzname[]; /* RS6000 and others reject char **tzname. */ 11073#endif]], 11074 [atoi (*tzname);])], 11075 [ac_cv_var_tzname=yes], 11076 [ac_cv_var_tzname=no]) 11077@end example 11078 11079Please note that the macro @code{AC_TRY_LINK} is obsolete, so you really 11080should be using @code{AC_LINK_IFELSE} instead. 11081 11082@xref{Quadrigraphs}, for what to do if you run into a hopeless case 11083where quoting does not suffice. 11084 11085When you create a @command{configure} script using newly written macros, 11086examine it carefully to check whether you need to add more quotes in 11087your macros. If one or more words have disappeared in the M4 11088output, you need more quotes. When in doubt, quote. 11089 11090However, it's also possible to put on too many layers of quotes. If 11091this happens, the resulting @command{configure} script may contain 11092unexpanded macros. The @command{autoconf} program checks for this problem 11093by looking for the string @samp{AC_} in @file{configure}. However, this 11094heuristic does not work in general: for example, it does not catch 11095overquoting in @code{AC_DEFINE} descriptions. 11096 11097 11098@c ---------------------------------------- Using autom4te 11099 11100@node Using autom4te 11101@section Using @command{autom4te} 11102 11103The Autoconf suite, including M4sugar, M4sh, and Autotest, in addition 11104to Autoconf per se, heavily rely on M4. All these different uses 11105revealed common needs factored into a layer over M4: 11106@command{autom4te}@footnote{ 11107@c 11108Yet another great name from Lars J. Aas. 11109@c 11110}. 11111 11112@command{autom4te} is a preprocessor that is like @command{m4}. 11113It supports M4 extensions designed for use in tools like Autoconf. 11114 11115@menu 11116* autom4te Invocation:: A GNU M4 wrapper 11117* Customizing autom4te:: Customizing the Autoconf package 11118@end menu 11119 11120@node autom4te Invocation 11121@subsection Invoking @command{autom4te} 11122 11123The command line arguments are modeled after M4's: 11124 11125@example 11126autom4te @var{options} @var{files} 11127@end example 11128 11129@noindent 11130@evindex M4 11131where the @var{files} are directly passed to @command{m4}. By default, 11132GNU M4 is found during configuration, but the environment 11133variable 11134@env{M4} can be set to tell @command{autom4te} where to look. In addition 11135to the regular expansion, it handles the replacement of the quadrigraphs 11136(@pxref{Quadrigraphs}), and of @samp{__oline__}, the current line in the 11137output. It supports an extended syntax for the @var{files}: 11138 11139@table @file 11140@item @var{file}.m4f 11141This file is an M4 frozen file. Note that @emph{all the previous files 11142are ignored}. See the option @option{--melt} for the rationale. 11143 11144@item @var{file}? 11145If found in the library path, the @var{file} is included for expansion, 11146otherwise it is ignored instead of triggering a failure. 11147@end table 11148 11149@sp 1 11150 11151Of course, it supports the Autoconf common subset of options: 11152 11153@table @option 11154@item --help 11155@itemx -h 11156Print a summary of the command line options and exit. 11157 11158@item --version 11159@itemx -V 11160Print the version number of Autoconf and exit. 11161 11162@item --verbose 11163@itemx -v 11164Report processing steps. 11165 11166@item --debug 11167@itemx -d 11168Don't remove the temporary files and be even more verbose. 11169 11170@item --include=@var{dir} 11171@itemx -I @var{dir} 11172Also look for input files in @var{dir}. Multiple invocations 11173accumulate. 11174 11175@item --output=@var{file} 11176@itemx -o @var{file} 11177Save output (script or trace) to @var{file}. The file @option{-} stands 11178for the standard output. 11179@end table 11180 11181@sp 1 11182 11183As an extension of @command{m4}, it includes the following options: 11184 11185@table @option 11186@item --warnings=@var{category} 11187@itemx -W @var{category} 11188@evindex WARNINGS 11189@c FIXME: Point to the M4sugar macros, not Autoconf's. 11190Report the warnings related to @var{category} (which can actually be a 11191comma separated list). @xref{Reporting Messages}, macro 11192@code{AC_DIAGNOSE}, for a comprehensive list of categories. Special 11193values include: 11194 11195@table @samp 11196@item all 11197report all the warnings 11198 11199@item none 11200report none 11201 11202@item error 11203treats warnings as errors 11204 11205@item no-@var{category} 11206disable warnings falling into @var{category} 11207@end table 11208 11209Warnings about @samp{syntax} are enabled by default, and the environment 11210variable @env{WARNINGS}, a comma separated list of categories, is 11211honored. @samp{autom4te -W @var{category}} actually 11212behaves as if you had run: 11213 11214@example 11215autom4te --warnings=syntax,$WARNINGS,@var{category} 11216@end example 11217 11218@noindent 11219For example, if you want to disable defaults and @env{WARNINGS} 11220of @command{autom4te}, but enable the warnings about obsolete 11221constructs, you would use @option{-W none,obsolete}. 11222 11223@cindex Back trace 11224@cindex Macro invocation stack 11225@command{autom4te} displays a back trace for errors, but not for 11226warnings; if you want them, just pass @option{-W error}. 11227 11228@item --melt 11229@itemx -M 11230Do not use frozen files. Any argument @code{@var{file}.m4f} is 11231replaced by @code{@var{file}.m4}. This helps tracing the macros which 11232are executed only when the files are frozen, typically 11233@code{m4_define}. For instance, running: 11234 11235@example 11236autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4 11237@end example 11238 11239@noindent 11240is roughly equivalent to running: 11241 11242@example 11243m4 1.m4 2.m4 3.m4 4.m4 input.m4 11244@end example 11245 11246@noindent 11247while 11248 11249@example 11250autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4 11251@end example 11252 11253@noindent 11254is equivalent to: 11255 11256@example 11257m4 --reload-state=4.m4f input.m4 11258@end example 11259 11260@item --freeze 11261@itemx -F 11262Produce a frozen state file. @command{autom4te} freezing is stricter 11263than M4's: it must produce no warnings, and no output other than empty 11264lines (a line with white space is @emph{not} empty) and comments 11265(starting with @samp{#}). Unlike @command{m4}'s similarly-named option, 11266this option takes no argument: 11267 11268@example 11269autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f 11270@end example 11271 11272@noindent 11273corresponds to 11274 11275@example 11276m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f 11277@end example 11278 11279@item --mode=@var{octal-mode} 11280@itemx -m @var{octal-mode} 11281Set the mode of the non-traces output to @var{octal-mode}; by default 11282@samp{0666}. 11283@end table 11284 11285@sp 1 11286 11287@cindex @file{autom4te.cache} 11288As another additional feature over @command{m4}, @command{autom4te} 11289caches its results. GNU M4 is able to produce a regular 11290output and traces at the same time. Traces are heavily used in the 11291GNU Build System: @command{autoheader} uses them to build 11292@file{config.h.in}, @command{autoreconf} to determine what 11293GNU Build System components are used, @command{automake} to 11294``parse'' @file{configure.ac} etc. To avoid recomputation, 11295traces are cached while performing regular expansion, 11296and conversely. This cache is (actually, the caches are) stored in 11297the directory @file{autom4te.cache}. @emph{It can safely be removed} 11298at any moment (especially if for some reason @command{autom4te} 11299considers it trashed). 11300 11301@table @option 11302@item --cache=@var{directory} 11303@itemx -C @var{directory} 11304Specify the name of the directory where the result should be cached. 11305Passing an empty value disables caching. Be sure to pass a relative 11306file name, as for the time being, global caches are not supported. 11307 11308@item --no-cache 11309Don't cache the results. 11310 11311@item --force 11312@itemx -f 11313If a cache is used, consider it obsolete (but update it anyway). 11314@end table 11315 11316@sp 1 11317 11318Because traces are so important to the GNU Build System, 11319@command{autom4te} provides high level tracing features as compared to 11320M4, and helps exploiting the cache: 11321 11322@table @option 11323@item --trace=@var{macro}[:@var{format}] 11324@itemx -t @var{macro}[:@var{format}] 11325Trace the invocations of @var{macro} according to the @var{format}. 11326Multiple @option{--trace} arguments can be used to list several macros. 11327Multiple @option{--trace} arguments for a single macro are not 11328cumulative; instead, you should just make @var{format} as long as 11329needed. 11330 11331The @var{format} is a regular string, with newlines if desired, and 11332several special escape codes. It defaults to @samp{$f:$l:$n:$%}. It can 11333use the following special escapes: 11334 11335@table @samp 11336@item $$ 11337@c $$ restore font-lock 11338The character @samp{$}. 11339 11340@item $f 11341The file name from which @var{macro} is called. 11342 11343@item $l 11344The line number from which @var{macro} is called. 11345 11346@item $d 11347The depth of the @var{macro} call. This is an M4 technical detail that 11348you probably don't want to know about. 11349 11350@item $n 11351The name of the @var{macro}. 11352 11353@item $@var{num} 11354The @var{num}th argument of the call to @var{macro}. 11355 11356@item $@@ 11357@itemx $@var{sep}@@ 11358@itemx $@{@var{separator}@}@@ 11359All the arguments passed to @var{macro}, separated by the character 11360@var{sep} or the string @var{separator} (@samp{,} by default). Each 11361argument is quoted, i.e., enclosed in a pair of square brackets. 11362 11363@item $* 11364@itemx $@var{sep}* 11365@itemx $@{@var{separator}@}* 11366As above, but the arguments are not quoted. 11367 11368@item $% 11369@itemx $@var{sep}% 11370@itemx $@{@var{separator}@}% 11371As above, but the arguments are not quoted, all new line characters in 11372the arguments are smashed, and the default separator is @samp{:}. 11373 11374The escape @samp{$%} produces single-line trace outputs (unless you put 11375newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do 11376not. 11377@end table 11378 11379@xref{autoconf Invocation}, for examples of trace uses. 11380 11381@item --preselect=@var{macro} 11382@itemx -p @var{macro} 11383Cache the traces of @var{macro}, but do not enable traces. This is 11384especially important to save CPU cycles in the future. For instance, 11385when invoked, @command{autoconf} preselects all the macros that 11386@command{autoheader}, @command{automake}, @command{autoreconf}, etc., 11387trace, so that running @command{m4} is not needed to trace them: the 11388cache suffices. This results in a huge speed-up. 11389@end table 11390 11391@sp 1 11392 11393@cindex Autom4te Library 11394Finally, @command{autom4te} introduces the concept of @dfn{Autom4te 11395libraries}. They consists in a powerful yet extremely simple feature: 11396sets of combined command line arguments: 11397 11398@table @option 11399@item --language=@var{language} 11400@itemx -l @var{language} 11401Use the @var{language} Autom4te library. Current languages include: 11402 11403@table @code 11404@item M4sugar 11405create M4sugar output. 11406 11407@item M4sh 11408create M4sh executable shell scripts. 11409 11410@item Autotest 11411create Autotest executable test suites. 11412 11413@item Autoconf-without-aclocal-m4 11414create Autoconf executable configure scripts without 11415reading @file{aclocal.m4}. 11416 11417@item Autoconf 11418create Autoconf executable configure scripts. This language inherits 11419all the characteristics of @code{Autoconf-without-aclocal-m4} and 11420additionally reads @file{aclocal.m4}. 11421@end table 11422 11423@item --prepend-include=@var{dir} 11424@itemx -B @var{dir} 11425Prepend directory @var{dir} to the search path. This is used to include 11426the language-specific files before any third-party macros. 11427 11428@end table 11429 11430@cindex @file{autom4te.cfg} 11431As an example, if Autoconf is installed in its default location, 11432@file{/usr/local}, the command @samp{autom4te -l m4sugar foo.m4} is 11433strictly equivalent to the command: 11434 11435@example 11436autom4te --prepend-include /usr/local/share/autoconf \ 11437 m4sugar/m4sugar.m4f --warnings syntax foo.m4 11438@end example 11439 11440@noindent 11441Recursive expansion applies here: the command @samp{autom4te -l m4sh foo.m4} 11442is the same as @samp{autom4te --language M4sugar m4sugar/m4sh.m4f 11443foo.m4}, i.e.: 11444 11445@example 11446autom4te --prepend-include /usr/local/share/autoconf \ 11447 m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4 11448@end example 11449 11450@noindent 11451The definition of the languages is stored in @file{autom4te.cfg}. 11452 11453@node Customizing autom4te 11454@subsection Customizing @command{autom4te} 11455 11456One can customize @command{autom4te} via @file{~/.autom4te.cfg} (i.e., 11457as found in the user home directory), and @file{./.autom4te.cfg} (i.e., 11458as found in the directory from which @command{autom4te} is run). The 11459order is first reading @file{autom4te.cfg}, then @file{~/.autom4te.cfg}, 11460then @file{./.autom4te.cfg}, and finally the command line arguments. 11461 11462In these text files, comments are introduced with @code{#}, and empty 11463lines are ignored. Customization is performed on a per-language basis, 11464wrapped in between a @samp{begin-language: "@var{language}"}, 11465@samp{end-language: "@var{language}"} pair. 11466 11467Customizing a language stands for appending options (@pxref{autom4te 11468Invocation}) to the current definition of the language. Options, and 11469more generally arguments, are introduced by @samp{args: 11470@var{arguments}}. You may use the traditional shell syntax to quote the 11471@var{arguments}. 11472 11473As an example, to disable Autoconf caches (@file{autom4te.cache}) 11474globally, include the following lines in @file{~/.autom4te.cfg}: 11475 11476@verbatim 11477## ------------------ ## 11478## User Preferences. ## 11479## ------------------ ## 11480 11481begin-language: "Autoconf-without-aclocal-m4" 11482args: --no-cache 11483end-language: "Autoconf-without-aclocal-m4" 11484@end verbatim 11485 11486 11487@node Programming in M4sugar 11488@section Programming in M4sugar 11489 11490@cindex M4sugar 11491M4 by itself provides only a small, but sufficient, set of all-purpose 11492macros. M4sugar introduces additional generic macros. Its name was 11493coined by Lars J. Aas: ``Readability And Greater Understanding Stands 4 11494M4sugar''. 11495 11496M4sugar reserves the macro namespace @samp{^_m4_} for internal use, and 11497the macro namespace @samp{^m4_} for M4sugar macros. You should not 11498define your own macros into these namespaces. 11499 11500@menu 11501* Redefined M4 Macros:: M4 builtins changed in M4sugar 11502* Diagnostic Macros:: Diagnostic messages from M4sugar 11503* Diversion support:: Diversions in M4sugar 11504* Conditional constructs:: Conditions in M4 11505* Looping constructs:: Iteration in M4 11506* Evaluation Macros:: More quotation and evaluation control 11507* Text processing Macros:: String manipulation in M4 11508* Number processing Macros:: Arithmetic computation in M4 11509* Set manipulation Macros:: Set manipulation in M4 11510* Forbidden Patterns:: Catching unexpanded macros 11511@end menu 11512 11513@node Redefined M4 Macros 11514@subsection Redefined M4 Macros 11515 11516@msindex{builtin} 11517@msindex{changecom} 11518@msindex{changequote} 11519@msindex{debugfile} 11520@msindex{debugmode} 11521@msindex{decr} 11522@msindex{define} 11523@msindex{divnum} 11524@msindex{errprint} 11525@msindex{esyscmd} 11526@msindex{eval} 11527@msindex{format} 11528@msindex{ifdef} 11529@msindex{incr} 11530@msindex{index} 11531@msindex{indir} 11532@msindex{len} 11533@msindex{pushdef} 11534@msindex{shift} 11535@msindex{substr} 11536@msindex{syscmd} 11537@msindex{sysval} 11538@msindex{traceoff} 11539@msindex{traceon} 11540@msindex{translit} 11541With a few exceptions, all the M4 native macros are moved in the 11542@samp{m4_} pseudo-namespace, e.g., M4sugar renames @code{define} as 11543@code{m4_define} etc. 11544 11545The list of macros unchanged from M4, except for their name, is: 11546@itemize @minus 11547@item m4_builtin 11548@item m4_changecom 11549@item m4_changequote 11550@item m4_debugfile 11551@item m4_debugmode 11552@item m4_decr 11553@item m4_define 11554@item m4_divnum 11555@item m4_errprint 11556@item m4_esyscmd 11557@item m4_eval 11558@item m4_format 11559@item m4_ifdef 11560@item m4_incr 11561@item m4_index 11562@item m4_indir 11563@item m4_len 11564@item m4_pushdef 11565@item m4_shift 11566@item m4_substr 11567@item m4_syscmd 11568@item m4_sysval 11569@item m4_traceoff 11570@item m4_traceon 11571@item m4_translit 11572@end itemize 11573 11574Some M4 macros are redefined, and are slightly incompatible with their 11575native equivalent. 11576 11577@defmac __file__ 11578@defmacx __line__ 11579@MSindex __file__ 11580@MSindex __line__ 11581All M4 macros starting with @samp{__} retain their original name: for 11582example, no @code{m4__file__} is defined. 11583@end defmac 11584 11585@defmac __oline__ 11586@MSindex __oline__ 11587This is not technically a macro, but a feature of Autom4te. The 11588sequence @code{__oline__} can be used similarly to the other m4sugar 11589location macros, but rather than expanding to the location of the input 11590file, it is translated to the line number where it appears in the output 11591file after all other M4 expansions. 11592@end defmac 11593 11594@defmac dnl 11595@MSindex dnl 11596This macro kept its original name: no @code{m4_dnl} is defined. 11597@end defmac 11598 11599@defmac m4_bpatsubst (@var{string}, @var{regexp}, @ovar{replacement}) 11600@msindex{bpatsubst} 11601This macro corresponds to @code{patsubst}. The name @code{m4_patsubst} 11602is kept for future versions of M4sugar, once GNU M4 2.0 is 11603released and supports extended regular expression syntax. 11604@end defmac 11605 11606@defmac m4_bregexp (@var{string}, @var{regexp}, @ovar{replacement}) 11607@msindex{bregexp} 11608This macro corresponds to @code{regexp}. The name @code{m4_regexp} 11609is kept for future versions of M4sugar, once GNU M4 2.0 is 11610released and supports extended regular expression syntax. 11611@end defmac 11612 11613@defmac m4_copy (@var{source}, @var{dest}) 11614@defmacx m4_copy_force (@var{source}, @var{dest}) 11615@defmacx m4_rename (@var{source}, @var{dest}) 11616@defmacx m4_rename_force (@var{source}, @var{dest}) 11617@msindex{copy} 11618@msindex{copy_force} 11619@msindex{rename} 11620@msindex{rename_force} 11621These macros aren't directly builtins, but are closely related to 11622@code{m4_pushdef} and @code{m4_defn}. @code{m4_copy} and 11623@code{m4_rename} ensure that @var{dest} is undefined, while 11624@code{m4_copy_force} and @code{m4_rename_force} overwrite any existing 11625definition. All four macros then proceed to copy the entire pushdef 11626stack of definitions of @var{source} over to @var{dest}. @code{m4_copy} 11627and @code{m4_copy_force} preserve the source (including in the special 11628case where @var{source} is undefined), while @code{m4_rename} and 11629@code{m4_rename_force} undefine the original macro name (making it an 11630error to rename an undefined @var{source}). 11631 11632Note that attempting to invoke a renamed macro might not work, since the 11633macro may have a dependence on helper macros accessed via composition of 11634@samp{$0} but that were not also renamed; likewise, other macros may 11635have a hard-coded dependence on @var{source} and could break if 11636@var{source} has been deleted. On the other hand, it is always safe to 11637rename a macro to temporarily move it out of the way, then rename it 11638back later to restore original semantics. 11639@end defmac 11640 11641@defmac m4_defn (@var{macro}@dots{}) 11642@msindex{defn} 11643This macro fails if @var{macro} is not defined, even when using older 11644versions of M4 that did not warn. See @code{m4_undefine}. 11645Unfortunately, in order to support these older versions of M4, there are 11646some situations involving unbalanced quotes where concatenating multiple 11647macros together will work in newer M4 but not in m4sugar; use 11648quadrigraphs to work around this. 11649@end defmac 11650 11651@defmac m4_divert (@var{diversion}) 11652@msindex{divert} 11653M4sugar relies heavily on diversions, so rather than behaving as a 11654primitive, @code{m4_divert} behaves like: 11655@example 11656m4_divert_pop()m4_divert_push([@var{diversion}]) 11657@end example 11658@noindent 11659@xref{Diversion support}, for more details about the use of the 11660diversion stack. In particular, this implies that @var{diversion} 11661should be a named diversion rather than a raw number. But be aware that 11662it is seldom necessary to explicitly change the diversion stack, and 11663that when done incorrectly, it can lead to syntactically invalid 11664scripts. 11665@end defmac 11666 11667@defmac m4_dumpdef (@var{name}@dots{}) 11668@defmacx m4_dumpdefs (@var{name}@dots{}) 11669@msindex{dumpdef} 11670@msindex{dumpdefs} 11671@code{m4_dumpdef} is like the M4 builtin, except that this version 11672requires at least one argument, output always goes to standard error 11673rather than the current debug file, no sorting is done on multiple 11674arguments, and an error is issued if any 11675@var{name} is undefined. @code{m4_dumpdefs} is a convenience macro that 11676calls @code{m4_dumpdef} for all of the 11677@code{m4_pushdef} stack of definitions, starting with the current, and 11678silently does nothing if @var{name} is undefined. 11679 11680Unfortunately, due to a limitation in M4 1.4.x, any macro defined as a 11681builtin is output as the empty string. This behavior is rectified by 11682using M4 1.6 or newer. However, this behavior difference means that 11683@code{m4_dumpdef} should only be used while developing m4sugar macros, 11684and never in the final published form of a macro. 11685@end defmac 11686 11687@defmac m4_esyscmd_s (@var{command}) 11688@msindex{esyscmd_s} 11689Like @code{m4_esyscmd}, this macro expands to the result of running 11690@var{command} in a shell. The difference is that any trailing newlines 11691are removed, so that the output behaves more like shell command 11692substitution. 11693@end defmac 11694 11695@defmac m4_exit (@var{exit-status}) 11696@msindex{exit} 11697This macro corresponds to @code{m4exit}. 11698@end defmac 11699 11700@defmac m4_if (@var{comment}) 11701@defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @ovar{not-equal}) 11702@defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal-1}, @ 11703 @var{string-3}, @var{string-4}, @var{equal-2}, @dots{}, @ovar{not-equal}) 11704@msindex{if} 11705This macro corresponds to @code{ifelse}. @var{string-1} and 11706@var{string-2} are compared literally, so usually one of the two 11707arguments is passed unquoted. @xref{Conditional constructs}, for more 11708conditional idioms. 11709@end defmac 11710 11711@defmac m4_include (@var{file}) 11712@defmacx m4_sinclude (@var{file}) 11713@msindex{include} 11714@msindex{sinclude} 11715Like the M4 builtins, but warn against multiple inclusions of @var{file}. 11716@end defmac 11717 11718@defmac m4_mkstemp (@var{template}) 11719@defmacx m4_maketemp (@var{template}) 11720@msindex{maketemp} 11721@msindex{mkstemp} 11722Posix requires @code{maketemp} to replace the trailing @samp{X} 11723characters in @var{template} with the process id, without regards to the 11724existence of a file by that name, but this a security hole. When this 11725was pointed out to the Posix folks, they agreed to invent a new macro 11726@code{mkstemp} that always creates a uniquely named file, but not all 11727versions of GNU M4 support the new macro. In M4sugar, 11728@code{m4_maketemp} and @code{m4_mkstemp} are synonyms for each other, 11729and both have the secure semantics regardless of which macro the 11730underlying M4 provides. 11731@end defmac 11732 11733@defmac m4_popdef (@var{macro}@dots{}) 11734@msindex{popdef} 11735This macro fails if @var{macro} is not defined, even when using older 11736versions of M4 that did not warn. See @code{m4_undefine}. 11737@end defmac 11738 11739@defmac m4_undefine (@var{macro}@dots{}) 11740@msindex{undefine} 11741This macro fails if @var{macro} is not defined, even when using older 11742versions of M4 that did not warn. Use 11743 11744@example 11745m4_ifdef([@var{macro}], [m4_undefine([@var{macro}])]) 11746@end example 11747 11748@noindent 11749if you are not sure whether @var{macro} is defined. 11750@end defmac 11751 11752@defmac m4_undivert (@var{diversion}@dots{}) 11753@msindex{undivert} 11754Unlike the M4 builtin, at least one @var{diversion} must be specified. 11755Also, since the M4sugar diversion stack prefers named 11756diversions, the use of @code{m4_undivert} to include files is risky. 11757@xref{Diversion support}, for more details about the use of the 11758diversion stack. But be aware that it is seldom necessary to explicitly 11759change the diversion stack, and that when done incorrectly, it can lead 11760to syntactically invalid scripts. 11761@end defmac 11762 11763@defmac m4_wrap (@var{text}) 11764@defmacx m4_wrap_lifo (@var{text}) 11765@msindex{wrap} 11766@msindex{wrap_lifo} 11767These macros correspond to @code{m4wrap}. Posix requires arguments of 11768multiple wrap calls to be reprocessed at EOF in the same order 11769as the original calls (first-in, first-out). GNU M4 versions 11770through 1.4.10, however, reprocess them in reverse order (last-in, 11771first-out). Both orders are useful, therefore, you can rely on 11772@code{m4_wrap} to provide FIFO semantics and @code{m4_wrap_lifo} for 11773LIFO semantics, regardless of the underlying GNU M4 version. 11774 11775Unlike the GNU M4 builtin, these macros only recognize one 11776argument, and avoid token pasting between consecutive invocations. On 11777the other hand, nested calls to @code{m4_wrap} from within wrapped text 11778work just as in the builtin. 11779@end defmac 11780 11781 11782@node Diagnostic Macros 11783@subsection Diagnostic messages from M4sugar 11784@cindex Messages, from @command{M4sugar} 11785 11786When macros statically diagnose abnormal situations, benign or fatal, 11787they should report them using these macros. For issuing dynamic issues, 11788i.e., when @command{configure} is run, see @ref{Printing Messages}. 11789 11790@defmac m4_assert (@var{expression}, @dvar{exit-status, 1}) 11791@msindex{assert} 11792Assert that the arithmetic @var{expression} evaluates to non-zero. 11793Otherwise, issue a fatal error, and exit @command{autom4te} with 11794@var{exit-status}. 11795@end defmac 11796 11797@defmac m4_errprintn (@var{message}) 11798@msindex{errprintn} 11799Similar to the builtin @code{m4_errprint}, except that a newline is 11800guaranteed after @var{message}. 11801@end defmac 11802 11803@anchor{m4_fatal} 11804@defmac m4_fatal (@var{message}) 11805@msindex{fatal} 11806Report a severe error @var{message} prefixed with the current location, 11807and have @command{autom4te} die. 11808@end defmac 11809 11810@defmac m4_location 11811@msindex{location} 11812Useful as a prefix in a message line. Short for: 11813@example 11814__file__:__line__ 11815@end example 11816@end defmac 11817 11818@anchor{m4_warn} 11819@defmac m4_warn (@var{category}, @var{message}) 11820@msindex{warn} 11821Report @var{message} as a warning (or as an error if requested by the 11822user) if warnings of the @var{category} are turned on. If the message 11823is emitted, it is prefixed with the current location, and followed by a 11824call trace of all macros defined via @code{AC_DEFUN} used to get to the 11825current expansion. You are encouraged to use standard categories, which 11826currently include: 11827 11828@table @samp 11829@item all 11830messages that don't fall into one of the following categories. Use of an 11831empty @var{category} is equivalent. 11832 11833@item cross 11834related to cross compilation issues. 11835 11836@item obsolete 11837use of an obsolete construct. 11838 11839@item syntax 11840dubious syntactic constructs, incorrectly ordered macro calls. 11841@end table 11842@end defmac 11843 11844 11845@node Diversion support 11846@subsection Diversion support 11847 11848M4sugar makes heavy use of diversions under the hood, because it is 11849often the case that 11850text that must appear early in the output is not discovered until late 11851in the input. Additionally, some of the topological sorting algorithms 11852used in resolving macro dependencies use diversions. However, most 11853macros should not need to change diversions directly, but rather rely on 11854higher-level M4sugar macros to manage diversions transparently. If you 11855change diversions improperly, you risk generating a syntactically 11856invalid script, because an incorrect diversion will violate assumptions 11857made by many macros about whether prerequisite text has been previously 11858output. In short, if you manually change the diversion, you should not 11859expect any macros provided by the Autoconf package to work until you 11860have restored the diversion stack back to its original state. 11861 11862In the rare case that it is necessary to write a macro that explicitly 11863outputs text to a different diversion, it is important to be aware of an 11864M4 limitation regarding diversions: text only goes to a diversion if it 11865is not part of argument collection. Therefore, any macro that changes 11866the current diversion cannot be used as an unquoted argument to another 11867macro, but must be expanded at the top level. The macro 11868@code{m4_expand} will diagnose any attempt to change diversions, since 11869it is generally useful only as an argument to another macro. The 11870following example shows what happens when diversion manipulation is 11871attempted within macro arguments: 11872 11873@example 11874m4_do([normal text] 11875m4_divert_push([KILL])unwanted[]m4_divert_pop([KILL]) 11876[m4_divert_push([KILL])discarded[]m4_divert_pop([KILL])])dnl 11877@result{}normal text 11878@result{}unwanted 11879@end example 11880 11881@noindent 11882Notice that the unquoted text @code{unwanted} is output, even though it 11883was processed while the current diversion was @code{KILL}, because it 11884was collected as part of the argument to @code{m4_do}. However, the 11885text @code{discarded} disappeared as desired, because the diversion 11886changes were single-quoted, and were not expanded until the top-level 11887rescan of the output of @code{m4_do}. 11888 11889To make diversion management easier, M4sugar uses the concept of named 11890diversions. Rather than using diversion numbers directly, it is nicer 11891to associate a name with each diversion. The diversion number associated 11892with a particular diversion name is an implementation detail, and a 11893syntax warning is issued if a diversion number is used instead of a 11894name. In general, you should not output text 11895to a named diversion until after calling the appropriate initialization 11896routine for your language (@code{m4_init}, @code{AS_INIT}, 11897@code{AT_INIT}, @dots{}), although there are some exceptions documented 11898below. 11899 11900M4sugar defines two named diversions. 11901@table @code 11902@item KILL 11903Text written to this diversion is discarded. This is the default 11904diversion once M4sugar is initialized. 11905@item GROW 11906This diversion is used behind the scenes by topological sorting macros, 11907such as @code{AC_REQUIRE}. 11908@end table 11909 11910M4sh adds several more named diversions. 11911@table @code 11912@item BINSH 11913This diversion is reserved for the @samp{#!} interpreter line. 11914@item HEADER-REVISION 11915This diversion holds text from @code{AC_REVISION}. 11916@item HEADER-COMMENT 11917This diversion holds comments about the purpose of a file. 11918@item HEADER-COPYRIGHT 11919This diversion is managed by @code{AC_COPYRIGHT}. 11920@item M4SH-SANITIZE 11921This diversion contains M4sh sanitization code, used to ensure M4sh is 11922executing in a reasonable shell environment. 11923@item M4SH-INIT 11924This diversion contains M4sh initialization code, initializing variables 11925that are required by other M4sh macros. 11926@item BODY 11927This diversion contains the body of the shell code, and is the default 11928diversion once M4sh is initialized. 11929@end table 11930 11931Autotest inherits diversions from M4sh, and changes the default 11932diversion from @code{BODY} back to @code{KILL}. It also adds several 11933more named diversions, with the following subset designed for developer 11934use. 11935@table @code 11936@item PREPARE_TESTS 11937This diversion contains initialization sequences which are executed 11938after @file{atconfig} and @file{atlocal}, and after all command line 11939arguments have been parsed, but prior to running any tests. It can be 11940used to set up state that is required across all tests. This diversion 11941will work even before @code{AT_INIT}. 11942@end table 11943 11944Autoconf inherits diversions from M4sh, and adds the following named 11945diversions which developers can utilize. 11946@table @code 11947@item DEFAULTS 11948This diversion contains shell variable assignments to set defaults that 11949must be in place before arguments are parsed. This diversion is placed 11950early enough in @file{configure} that it is unsafe to expand any 11951autoconf macros into this diversion. 11952@item HELP_ENABLE 11953If @code{AC_PRESERVE_HELP_ORDER} was used, then text placed in this 11954diversion will be included as part of a quoted here-doc providing all of 11955the @option{--help} output of @file{configure} related to options 11956created by @code{AC_ARG_WITH} and @code{AC_ARG_ENABLE}. 11957@item INIT_PREPARE 11958This diversion occurs after all command line options have been parsed, 11959but prior to the main body of the @file{configure} script. This 11960diversion is the last chance to insert shell code such as variable 11961assignments or shell function declarations that will used by the 11962expansion of other macros. 11963@end table 11964 11965For now, the remaining named diversions of Autoconf, Autoheader, and 11966Autotest are not documented. In other words, 11967intentionally outputting text into an undocumented diversion is subject 11968to breakage in a future release of Autoconf. 11969 11970@defmac m4_cleardivert (@var{diversion}@dots{}) 11971@msindex{cleardivert} 11972Permanently discard any text that has been diverted into 11973@var{diversion}. 11974@end defmac 11975 11976@defmac m4_divert_once (@var{diversion}, @ovar{content}) 11977@msindex{divert_once} 11978Similar to @code{m4_divert_text}, except that @var{content} is only 11979output to @var{diversion} if this is the first time that 11980@code{m4_divert_once} has been called with its particular arguments. 11981@end defmac 11982 11983@defmac m4_divert_pop (@ovar{diversion}) 11984@msindex{divert_pop} 11985If provided, check that the current diversion is indeed @var{diversion}. 11986Then change to the diversion located earlier on the stack, giving an 11987error if an attempt is made to pop beyond the initial m4sugar diversion 11988of @code{KILL}. 11989@end defmac 11990 11991@defmac m4_divert_push (@var{diversion}) 11992@msindex{divert_push} 11993Remember the former diversion on the diversion stack, and output 11994subsequent text into @var{diversion}. M4sugar maintains a diversion 11995stack, and issues an error if there is not a matching pop for every 11996push. 11997@end defmac 11998 11999@defmac m4_divert_text (@var{diversion}, @ovar{content}) 12000@msindex{divert_text} 12001Output @var{content} and a newline into @var{diversion}, without 12002affecting the current diversion. Shorthand for: 12003@example 12004m4_divert_push([@var{diversion}])@var{content} 12005m4_divert_pop([@var{diversion}])dnl 12006@end example 12007 12008One use of @code{m4_divert_text} is to develop two related macros, where 12009macro @samp{MY_A} does the work, but adjusts what work is performed 12010based on whether the optional macro @samp{MY_B} has also been expanded. 12011Of course, it is possible to use @code{AC_BEFORE} within @code{MY_A} to 12012require that @samp{MY_B} occurs first, if it occurs at all. But this 12013imposes an ordering restriction on the user; it would be nicer if macros 12014@samp{MY_A} and @samp{MY_B} can be invoked in either order. The trick 12015is to let @samp{MY_B} leave a breadcrumb in an early diversion, which 12016@samp{MY_A} can then use to determine whether @samp{MY_B} has been 12017expanded. 12018 12019@example 12020AC_DEFUN([MY_A], 12021[# various actions 12022if test -n "$b_was_used"; then 12023 # extra action 12024fi]) 12025AC_DEFUN([MY_B], 12026[AC_REQUIRE([MY_A])dnl 12027m4_divert_text([INIT_PREPARE], [b_was_used=true])]) 12028@end example 12029 12030@end defmac 12031 12032@defmac m4_init 12033@msindex{init} 12034Initialize the M4sugar environment, setting up the default named 12035diversion to be @code{KILL}. 12036@end defmac 12037 12038@node Conditional constructs 12039@subsection Conditional constructs 12040 12041The following macros provide additional conditional constructs as 12042convenience wrappers around @code{m4_if}. 12043 12044@defmac m4_bmatch (@var{string}, @var{regex-1}, @var{value-1}, @ 12045 @ovar{regex-2}, @ovar{value-2}, @dots{}, @ovar{default}) 12046@msindex{bmatch} 12047The string @var{string} is repeatedly compared against a series of 12048@var{regex} arguments; if a match is found, the expansion is the 12049corresponding @var{value}, otherwise, the macro moves on to the next 12050@var{regex}. If no @var{regex} match, then the result is the optional 12051@var{default}, or nothing. 12052@end defmac 12053 12054@defmac m4_bpatsubsts (@var{string}, @var{regex-1}, @var{subst-1}, @ 12055 @ovar{regex-2}, @ovar{subst-2}, @dots{}) 12056@msindex{bpatsubsts} 12057The string @var{string} is altered by @var{regex-1} and @var{subst-1}, 12058as if by: 12059@example 12060m4_bpatsubst([[@var{string}]], [@var{regex}], [@var{subst}]) 12061@end example 12062 12063@noindent 12064The result of the substitution is then passed through the next set of 12065@var{regex} and @var{subst}, and so forth. An empty @var{subst} implies 12066deletion of any matched portions in the current string. Note that this 12067macro over-quotes @var{string}; this behavior is intentional, so that 12068the result of each step of the recursion remains as a quoted string. 12069However, it means that anchors (@samp{^} and @samp{$} in the @var{regex} 12070will line up with the extra quotations, and not the characters of the 12071original string. The overquoting is removed after the final 12072substitution. 12073@end defmac 12074 12075@defmac m4_case (@var{string}, @var{value-1}, @var{if-value-1}, @ 12076 @ovar{value-2}, @ovar{if-value-2}, @dots{}, @ovar{default}) 12077@msindex{case} 12078Test @var{string} against multiple @var{value} possibilities, resulting 12079in the first @var{if-value} for a match, or in the optional 12080@var{default}. This is shorthand for: 12081@example 12082m4_if([@var{string}], [@var{value-1}], [@var{if-value-1}], 12083 [@var{string}], [@var{value-2}], [@var{if-value-2}], @dots{}, 12084 [@var{default}]) 12085@end example 12086@end defmac 12087 12088@defmac m4_cond (@var{test-1}, @var{value-1}, @var{if-value-1}, @ 12089 @ovar{test-2}, @ovar{value-2}, @ovar{if-value-2}, @dots{}, @ovar{default}) 12090@msindex{cond} 12091This macro was introduced in Autoconf 2.62. Similar to @code{m4_if}, 12092except that each @var{test} is expanded only when it is encountered. 12093This is useful for short-circuiting expensive tests; while @code{m4_if} 12094requires all its strings to be expanded up front before doing 12095comparisons, @code{m4_cond} only expands a @var{test} when all earlier 12096tests have failed. 12097 12098For an example, these two sequences give the same result, but in the 12099case where @samp{$1} does not contain a backslash, the @code{m4_cond} 12100version only expands @code{m4_index} once, instead of five times, for 12101faster computation if this is a common case for @samp{$1}. Notice that 12102every third argument is unquoted for @code{m4_if}, and quoted for 12103@code{m4_cond}: 12104 12105@example 12106m4_if(m4_index([$1], [\]), [-1], [$2], 12107 m4_eval(m4_index([$1], [\\]) >= 0), [1], [$2], 12108 m4_eval(m4_index([$1], [\$]) >= 0), [1], [$2], 12109 m4_eval(m4_index([$1], [\`]) >= 0), [1], [$3], 12110 m4_eval(m4_index([$1], [\"]) >= 0), [1], [$3], 12111 [$2]) 12112m4_cond([m4_index([$1], [\])], [-1], [$2], 12113 [m4_eval(m4_index([$1], [\\]) >= 0)], [1], [$2], 12114 [m4_eval(m4_index([$1], [\$]) >= 0)], [1], [$2], 12115 [m4_eval(m4_index([$1], [\`]) >= 0)], [1], [$3], 12116 [m4_eval(m4_index([$1], [\"]) >= 0)], [1], [$3], 12117 [$2]) 12118@end example 12119@end defmac 12120 12121@defmac m4_default (@var{expr-1}, @var{expr-2}) 12122@defmacx m4_default_quoted (@var{expr-1}, @var{expr-2}) 12123@defmacx m4_default_nblank (@var{expr-1}, @ovar{expr-2}) 12124@defmacx m4_default_nblank_quoted (@var{expr-1}, @ovar{expr-2}) 12125@msindex{default} 12126@msindex{default_quoted} 12127@msindex{default_nblank} 12128@msindex{default_nblank_quoted} 12129If @var{expr-1} contains text, use it. Otherwise, select @var{expr-2}. 12130@code{m4_default} expands the result, while @code{m4_default_quoted} 12131does not. Useful for providing a fixed default if the expression that 12132results in @var{expr-1} would otherwise be empty. The difference 12133between @code{m4_default} and @code{m4_default_nblank} is whether an 12134argument consisting of just blanks (space, tab, newline) is 12135significant. When using the expanding versions, note that an argument 12136may contain text but still expand to an empty string. 12137 12138@example 12139m4_define([active], [ACTIVE])dnl 12140m4_define([empty], [])dnl 12141m4_define([demo1], [m4_default([$1], [$2])])dnl 12142m4_define([demo2], [m4_default_quoted([$1], [$2])])dnl 12143m4_define([demo3], [m4_default_nblank([$1], [$2])])dnl 12144m4_define([demo4], [m4_default_nblank_quoted([$1], [$2])])dnl 12145demo1([active], [default]) 12146@result{}ACTIVE 12147demo1([], [active]) 12148@result{}ACTIVE 12149demo1([empty], [text]) 12150@result{} 12151-demo1([ ], [active])- 12152@result{}- - 12153demo2([active], [default]) 12154@result{}active 12155demo2([], [active]) 12156@result{}active 12157demo2([empty], [text]) 12158@result{}empty 12159-demo2([ ], [active])- 12160@result{}- - 12161demo3([active], [default]) 12162@result{}ACTIVE 12163demo3([], [active]) 12164@result{}ACTIVE 12165demo3([empty], [text]) 12166@result{} 12167-demo3([ ], [active])- 12168@result{}-ACTIVE- 12169demo4([active], [default]) 12170@result{}active 12171demo4([], [active]) 12172@result{}active 12173demo4([empty], [text]) 12174@result{}empty 12175-demo4([ ], [active])- 12176@result{}-active- 12177@end example 12178@end defmac 12179 12180@defmac m4_define_default (@var{macro}, @ovar{default-definition}) 12181@msindex{define_default} 12182If @var{macro} does not already have a definition, then define it to 12183@var{default-definition}. 12184@end defmac 12185 12186@defmac m4_ifblank (@var{cond}, @ovar{if-blank}, @ovar{if-text}) 12187@defmacx m4_ifnblank (@var{cond}, @ovar{if-text}, @ovar{if-blank}) 12188@msindex{ifblank} 12189@msindex{ifnblank} 12190If @var{cond} is empty or consists only of blanks (space, tab, newline), 12191then expand @var{if-blank}; otherwise, expand @var{if-text}. Two 12192variants exist, in order to make it easier to select the correct logical 12193sense when using only two parameters. Note that this is more efficient 12194than the equivalent behavior of: 12195@example 12196m4_ifval(m4_normalize([@var{cond}]), @var{if-text}, @var{if-blank}) 12197@end example 12198@end defmac 12199 12200@defmac m4_ifndef (@var{macro}, @var{if-not-defined}, @ovar{if-defined}) 12201@msindex{ifndef} 12202This is shorthand for: 12203@example 12204m4_ifdef([@var{macro}], [@var{if-defined}], [@var{if-not-defined}]) 12205@end example 12206@end defmac 12207 12208@defmac m4_ifset (@var{macro}, @ovar{if-true}, @ovar{if-false}) 12209@msindex{ifset} 12210If @var{macro} is undefined, or is defined as the empty string, expand 12211to @var{if-false}. Otherwise, expands to @var{if-true}. Similar to: 12212@example 12213m4_ifval(m4_defn([@var{macro}]), [@var{if-true}], [@var{if-false}]) 12214@end example 12215@noindent 12216except that it is not an error if @var{macro} is undefined. 12217@end defmac 12218 12219@defmac m4_ifval (@var{cond}, @ovar{if-true}, @ovar{if-false}) 12220@msindex{ifval} 12221Expands to @var{if-true} if @var{cond} is not empty, otherwise to 12222@var{if-false}. This is shorthand for: 12223@example 12224m4_if([@var{cond}], [], [@var{if-false}], [@var{if-true}]) 12225@end example 12226@end defmac 12227 12228@defmac m4_ifvaln (@var{cond}, @ovar{if-true}, @ovar{if-false}) 12229@msindex{ifvaln} 12230Similar to @code{m4_ifval}, except guarantee that a newline is present 12231after any non-empty expansion. Often followed by @code{dnl}. 12232@end defmac 12233 12234@defmac m4_n (@var{text}) 12235@msindex{n} 12236Expand to @var{text}, and add a newline if @var{text} is not empty. 12237Often followed by @code{dnl}. 12238@end defmac 12239 12240 12241@node Looping constructs 12242@subsection Looping constructs 12243 12244The following macros are useful in implementing recursive algorithms in 12245M4, including loop operations. An M4 list is formed by quoting a list 12246of quoted elements; generally the lists are comma-separated, although 12247@code{m4_foreach_w} is whitespace-separated. For example, the list 12248@samp{[[a], [b,c]]} contains two elements: @samp{[a]} and @samp{[b,c]}. 12249It is common to see lists with unquoted elements when those elements are 12250not likely to be macro names, as in @samp{[fputc_unlocked, 12251fgetc_unlocked]}. 12252 12253Although not generally recommended, it is possible for quoted lists to 12254have side effects; all side effects are expanded only once, and prior to 12255visiting any list element. On the other hand, the fact that unquoted 12256macros are expanded exactly once means that macros without side effects 12257can be used to generate lists. For example, 12258 12259@example 12260m4_foreach([i], [[1], [2], [3]m4_errprintn([hi])], [i]) 12261@error{}hi 12262@result{}123 12263m4_define([list], [[1], [2], [3]]) 12264@result{} 12265m4_foreach([i], [list], [i]) 12266@result{}123 12267@end example 12268 12269@defmac m4_argn (@var{n}, @ovar{arg}@dots{}) 12270@msindex{argn} 12271Extracts argument @var{n} (larger than 0) from the remaining arguments. 12272If there are too few arguments, the empty string is used. For any 12273@var{n} besides 1, this is more efficient than the similar 12274@samp{m4_car(m4_shiftn([@var{n}], [], [@var{arg}@dots{}]))}. 12275@end defmac 12276 12277@defmac m4_car (@var{arg}@dots{}) 12278@msindex{car} 12279Expands to the quoted first @var{arg}. Can be used with @code{m4_cdr} 12280to recursively iterate 12281through a list. Generally, when using quoted lists of quoted elements, 12282@code{m4_car} should be called without any extra quotes. 12283@end defmac 12284 12285@defmac m4_cdr (@var{arg}@dots{}) 12286@msindex{cdr} 12287Expands to a quoted list of all but the first @var{arg}, or the empty 12288string if there was only one argument. Generally, when using quoted 12289lists of quoted elements, @code{m4_cdr} should be called without any 12290extra quotes. 12291 12292For example, this is a simple implementation of @code{m4_map}; note how 12293each iteration checks for the end of recursion, then merely applies the 12294first argument to the first element of the list, then repeats with the 12295rest of the list. (The actual implementation in M4sugar is a bit more 12296involved, to gain some speed and share code with @code{m4_map_sep}, and 12297also to avoid expanding side effects in @samp{$2} twice). 12298@example 12299m4_define([m4_map], [m4_ifval([$2], 12300 [m4_apply([$1], m4_car($2))[]$0([$1], m4_cdr($2))])])dnl 12301m4_map([ m4_eval], [[[1]], [[1+1]], [[10],[16]]]) 12302@result{} 1 2 a 12303@end example 12304@end defmac 12305 12306@defmac m4_for (@var{var}, @var{first}, @var{last}, @ovar{step}, @ 12307 @var{expression}) 12308@msindex{for} 12309Loop over the numeric values between @var{first} and @var{last} 12310including bounds by increments of @var{step}. For each iteration, 12311expand @var{expression} with the numeric value assigned to @var{var}. 12312If @var{step} is omitted, it defaults to @samp{1} or @samp{-1} depending 12313on the order of the limits. If given, @var{step} has to match this 12314order. The number of iterations is determined independently from 12315definition of @var{var}; iteration cannot be short-circuited or 12316lengthened by modifying @var{var} from within @var{expression}. 12317@end defmac 12318 12319@defmac m4_foreach (@var{var}, @var{list}, @var{expression}) 12320@msindex{foreach} 12321Loop over the comma-separated M4 list @var{list}, assigning each value 12322to @var{var}, and expand @var{expression}. The following example 12323outputs two lines: 12324 12325@example 12326m4_foreach([myvar], [[foo], [bar, baz]], 12327 [echo myvar 12328])dnl 12329@result{}echo foo 12330@result{}echo bar, baz 12331@end example 12332 12333Note that for some forms of @var{expression}, it may be faster to use 12334@code{m4_map_args}. 12335@end defmac 12336 12337@anchor{m4_foreach_w} 12338@defmac m4_foreach_w (@var{var}, @var{list}, @var{expression}) 12339@msindex{foreach_w} 12340Loop over the white-space-separated list @var{list}, assigning each value 12341to @var{var}, and expand @var{expression}. If @var{var} is only 12342referenced once in @var{expression}, it is more efficient to use 12343@code{m4_map_args_w}. 12344 12345The deprecated macro @code{AC_FOREACH} is an alias of 12346@code{m4_foreach_w}. 12347@end defmac 12348 12349@defmac m4_map (@var{macro}, @var{list}) 12350@defmacx m4_mapall (@var{macro}, @var{list}) 12351@defmacx m4_map_sep (@var{macro}, @var{separator}, @var{list}) 12352@defmacx m4_mapall_sep (@var{macro}, @var{separator}, @var{list}) 12353@msindex{map} 12354@msindex{mapall} 12355@msindex{map_sep} 12356@msindex{mapall_sep} 12357Loop over the comma separated quoted list of argument descriptions in 12358@var{list}, and invoke @var{macro} with the arguments. An argument 12359description is in turn a comma-separated quoted list of quoted elements, 12360suitable for @code{m4_apply}. The macros @code{m4_map} and 12361@code{m4_map_sep} ignore empty argument descriptions, while 12362@code{m4_mapall} and @code{m4_mapall_sep} invoke @var{macro} with no 12363arguments. The macros @code{m4_map_sep} and @code{m4_mapall_sep} 12364additionally expand @var{separator} between invocations of @var{macro}. 12365 12366Note that @var{separator} is expanded, unlike in @code{m4_join}. When 12367separating output with commas, this means that the map result can be 12368used as a series of arguments, by using a single-quoted comma as 12369@var{separator}, or as a single string, by using a double-quoted comma. 12370 12371@example 12372m4_map([m4_count], []) 12373@result{} 12374m4_map([ m4_count], [[], 12375 [[1]], 12376 [[1], [2]]]) 12377@result{} 1 2 12378m4_mapall([ m4_count], [[], 12379 [[1]], 12380 [[1], [2]]]) 12381@result{} 0 1 2 12382m4_map_sep([m4_eval], [,], [[[1+2]], 12383 [[10], [16]]]) 12384@result{}3,a 12385m4_map_sep([m4_echo], [,], [[[a]], [[b]]]) 12386@result{}a,b 12387m4_count(m4_map_sep([m4_echo], [,], [[[a]], [[b]]])) 12388@result{}2 12389m4_map_sep([m4_echo], [[,]], [[[a]], [[b]]]) 12390@result{}a,b 12391m4_count(m4_map_sep([m4_echo], [[,]], [[[a]], [[b]]])) 12392@result{}1 12393@end example 12394@end defmac 12395 12396@defmac m4_map_args (@var{macro}, @var{arg}@dots{}) 12397@msindex{map_args} 12398Repeatedly invoke @var{macro} with each successive @var{arg} as its only 12399argument. In the following example, three solutions are presented with 12400the same expansion; the solution using @code{m4_map_args} is the most 12401efficient. 12402@example 12403m4_define([active], [ACTIVE])dnl 12404m4_foreach([var], [[plain], [active]], [ m4_echo(m4_defn([var]))]) 12405@result{} plain active 12406m4_map([ m4_echo], [[[plain]], [[active]]]) 12407@result{} plain active 12408m4_map_args([ m4_echo], [plain], [active]) 12409@result{} plain active 12410@end example 12411 12412In cases where it is useful to operate on additional parameters besides 12413the list elements, the macro @code{m4_curry} can be used in @var{macro} 12414to supply the argument currying necessary to generate the desired 12415argument list. In the following example, @code{list_add_n} is more 12416efficient than @code{list_add_x}. On the other hand, using 12417@code{m4_map_args_sep} can be even more efficient. 12418 12419@example 12420m4_define([list], [[1], [2], [3]])dnl 12421m4_define([add], [m4_eval(([$1]) + ([$2]))])dnl 12422dnl list_add_n(N, ARG...) 12423dnl Output a list consisting of each ARG added to N 12424m4_define([list_add_n], 12425[m4_shift(m4_map_args([,m4_curry([add], [$1])], m4_shift($@@)))])dnl 12426list_add_n([1], list) 12427@result{}2,3,4 12428list_add_n([2], list) 12429@result{}3,4,5 12430m4_define([list_add_x], 12431[m4_shift(m4_foreach([var], m4_dquote(m4_shift($@@)), 12432 [,add([$1],m4_defn([var]))]))])dnl 12433list_add_x([1], list) 12434@result{}2,3,4 12435@end example 12436@end defmac 12437 12438@defmac m4_map_args_pair (@var{macro}, @dvar{macro-end, macro}, @ 12439 @var{arg}@dots{}) 12440@msindex{map_args_pair} 12441For every pair of arguments @var{arg}, invoke @var{macro} with two 12442arguments. If there is an odd number of arguments, invoke 12443@var{macro-end}, which defaults to @var{macro}, with the remaining 12444argument. 12445 12446@example 12447m4_map_args_pair([, m4_reverse], [], [1], [2], [3]) 12448@result{}, 2, 1, 3 12449m4_map_args_pair([, m4_reverse], [, m4_dquote], [1], [2], [3]) 12450@result{}, 2, 1, [3] 12451m4_map_args_pair([, m4_reverse], [, m4_dquote], [1], [2], [3], [4]) 12452@result{}, 2, 1, 4, 3 12453@end example 12454@end defmac 12455 12456@defmac m4_map_args_sep (@ovar{pre}, @ovar{post}, @ovar{sep}, @var{arg}@dots{}) 12457@msindex{map_args_sep} 12458Expand the sequence @code{@var{pre}[@var{arg}]@var{post}} for each 12459argument, additionally expanding @var{sep} between arguments. One 12460common use of this macro is constructing a macro call, where the opening 12461and closing parentheses are split between @var{pre} and @var{post}; in 12462particular, @code{m4_map_args([@var{macro}], [@var{arg}])} is equivalent 12463to @code{m4_map_args_sep([@var{macro}(], [)], [], [@var{arg}])}. This 12464macro provides the most efficient means for iterating over an arbitrary 12465list of arguments, particularly when repeatedly constructing a macro 12466call with more arguments than @var{arg}. 12467@end defmac 12468 12469@defmac m4_map_args_w (@var{string}, @ovar{pre}, @ovar{post}, @ovar{sep}) 12470@msindex{map_args_w} 12471Expand the sequence @code{@var{pre}[word]@var{post}} for each word in 12472the whitespace-separated @var{string}, additionally expanding @var{sep} 12473between words. This macro provides the most efficient means for 12474iterating over a whitespace-separated string. In particular, 12475@code{m4_map_args_w([@var{string}], [@var{action}(], [)])} is more 12476efficient than @code{m4_foreach_w([var], [@var{string}], 12477[@var{action}(m4_defn([var]))])}. 12478@end defmac 12479 12480@defmac m4_shiftn (@var{count}, @dots{}) 12481@defmacx m4_shift2 (@dots{}) 12482@defmacx m4_shift3 (@dots{}) 12483@msindex{shift2} 12484@msindex{shift3} 12485@msindex{shiftn} 12486@code{m4_shiftn} performs @var{count} iterations of @code{m4_shift}, 12487along with validation that enough arguments were passed in to match the 12488shift count, and that the count is positive. @code{m4_shift2} and 12489@code{m4_shift3} are specializations 12490of @code{m4_shiftn}, introduced in Autoconf 2.62, and are more efficient 12491for two and three shifts, respectively. 12492@end defmac 12493 12494@defmac m4_stack_foreach (@var{macro}, @var{action}) 12495@defmacx m4_stack_foreach_lifo (@var{macro}, @var{action}) 12496@msindex{stack_foreach} 12497@msindex{stack_foreach_lifo} 12498For each of the @code{m4_pushdef} definitions of @var{macro}, expand 12499@var{action} with the single argument of a definition of @var{macro}. 12500@code{m4_stack_foreach} starts with the oldest definition, while 12501@code{m4_stack_foreach_lifo} starts with the current definition. 12502@var{action} should not push or pop definitions of @var{macro}, nor is 12503there any guarantee that the current definition of @var{macro} matches 12504the argument that was passed to @var{action}. The macro @code{m4_curry} 12505can be used if @var{action} needs more than one argument, although in 12506that case it is more efficient to use @var{m4_stack_foreach_sep}. 12507 12508Due to technical limitations, there are a few low-level m4sugar 12509functions, such as @code{m4_pushdef}, that cannot be used as the 12510@var{macro} argument. 12511 12512@example 12513m4_pushdef([a], [1])m4_pushdef([a], [2])dnl 12514m4_stack_foreach([a], [ m4_incr]) 12515@result{} 2 3 12516m4_stack_foreach_lifo([a], [ m4_curry([m4_substr], [abcd])]) 12517@result{} cd bcd 12518@end example 12519@end defmac 12520 12521@defmac m4_stack_foreach_sep (@var{macro}, @ovar{pre}, @ovar{post}, @ovar{sep}) 12522@defmacx m4_stack_foreach_sep_lifo (@var{macro}, @ovar{pre}, @ovar{post}, @ 12523 @ovar{sep}) 12524@msindex{stack_foreach_sep} 12525@msindex{stack_foreach_sep_lifo} 12526Expand the sequence @code{@var{pre}[definition]@var{post}} for each 12527@code{m4_pushdef} definition of @var{macro}, additionally expanding 12528@var{sep} between definitions. @code{m4_stack_foreach_sep} visits the 12529oldest definition first, while @code{m4_stack_foreach_sep_lifo} visits 12530the current definition first. This macro provides the most efficient 12531means for iterating over a pushdef stack. In particular, 12532@code{m4_stack_foreach([@var{macro}], [@var{action}])} is short for 12533@code{m4_stack_foreach_sep([@var{macro}], [@var{action}(], [)])}. 12534@end defmac 12535 12536@node Evaluation Macros 12537@subsection Evaluation Macros 12538 12539The following macros give some control over the order of the evaluation 12540by adding or removing levels of quotes. 12541 12542@defmac m4_apply (@var{macro}, @var{list}) 12543@msindex{apply} 12544Apply the elements of the quoted, comma-separated @var{list} as the 12545arguments to @var{macro}. If @var{list} is empty, invoke @var{macro} 12546without arguments. Note the difference between @code{m4_indir}, which 12547expects its first argument to be a macro name but can use names that are 12548otherwise invalid, and @code{m4_apply}, where @var{macro} can contain 12549other text, but must end in a valid macro name. 12550@example 12551m4_apply([m4_count], []) 12552@result{}0 12553m4_apply([m4_count], [[]]) 12554@result{}1 12555m4_apply([m4_count], [[1], [2]]) 12556@result{}2 12557m4_apply([m4_join], [[|], [1], [2]]) 12558@result{}1|2 12559@end example 12560@end defmac 12561 12562@defmac m4_count (@var{arg}, @dots{}) 12563@msindex{count} 12564This macro returns the decimal count of the number of arguments it was 12565passed. 12566@end defmac 12567 12568@defmac m4_curry (@var{macro}, @var{arg}@dots{}) 12569@msindex{curry} 12570This macro performs argument currying. The expansion of this macro is 12571another macro name that expects exactly one argument; that argument is 12572then appended to the @var{arg} list, and then @var{macro} is expanded 12573with the resulting argument list. 12574 12575@example 12576m4_curry([m4_curry], [m4_reverse], [1])([2])([3]) 12577@result{}3, 2, 1 12578@end example 12579 12580Unfortunately, due to a limitation in M4 1.4.x, it is not possible to 12581pass the definition of a builtin macro as the argument to the output of 12582@code{m4_curry}; the empty string is used instead of the builtin token. 12583This behavior is rectified by using M4 1.6 or newer. 12584@end defmac 12585 12586@defmac m4_do (@var{arg}, @dots{}) 12587@msindex{do} 12588This macro loops over its arguments and expands each @var{arg} in 12589sequence. Its main use is for readability; it allows the use of 12590indentation and fewer @code{dnl} to result in the same expansion. This 12591macro guarantees that no expansion will be concatenated with subsequent 12592text; to achieve full concatenation, use @code{m4_unquote(m4_join([], 12593@var{arg@dots{}}))}. 12594 12595@example 12596m4_define([ab],[1])m4_define([bc],[2])m4_define([abc],[3])dnl 12597m4_do([a],[b])c 12598@result{}abc 12599m4_unquote(m4_join([],[a],[b]))c 12600@result{}3 12601m4_define([a],[A])m4_define([b],[B])m4_define([c],[C])dnl 12602m4_define([AB],[4])m4_define([BC],[5])m4_define([ABC],[6])dnl 12603m4_do([a],[b])c 12604@result{}ABC 12605m4_unquote(m4_join([],[a],[b]))c 12606@result{}3 12607@end example 12608@end defmac 12609 12610@defmac m4_dquote (@var{arg}, @dots{}) 12611@msindex{dquote} 12612Return the arguments as a quoted list of quoted arguments. 12613Conveniently, if there is just one @var{arg}, this effectively adds a 12614level of quoting. 12615@end defmac 12616 12617@defmac m4_dquote_elt (@var{arg}, @dots{}) 12618@msindex{dquote_elt} 12619Return the arguments as a series of double-quoted arguments. Whereas 12620@code{m4_dquote} returns a single argument, @code{m4_dquote_elt} returns 12621as many arguments as it was passed. 12622@end defmac 12623 12624@defmac m4_echo (@var{arg}, @dots{}) 12625@msindex{echo} 12626Return the arguments, with the same level of quoting. Other than 12627discarding whitespace after unquoted commas, this macro is a no-op. 12628@end defmac 12629 12630@defmac m4_expand (@var{arg}) 12631@msindex{expand} 12632Return the expansion of @var{arg} as a quoted string. Whereas 12633@code{m4_quote} is designed to collect expanded text into a single 12634argument, @code{m4_expand} is designed to perform one level of expansion 12635on quoted text. One distinction is in the treatment of whitespace 12636following a comma in the original @var{arg}. Any time multiple 12637arguments are collected into one with @code{m4_quote}, the M4 argument 12638collection rules discard the whitespace. However, with @code{m4_expand}, 12639whitespace is preserved, even after the expansion of macros contained in 12640@var{arg}. Additionally, @code{m4_expand} is able to expand text that 12641would involve an unterminated comment, whereas expanding that same text 12642as the argument to @code{m4_quote} runs into difficulty in finding the 12643end of the argument. Since manipulating diversions during argument 12644collection is inherently unsafe, @code{m4_expand} issues an error if 12645@var{arg} attempts to change the current diversion (@pxref{Diversion 12646support}). 12647 12648@example 12649m4_define([active], [ACT, IVE])dnl 12650m4_define([active2], [[ACT, IVE]])dnl 12651m4_quote(active, active) 12652@result{}ACT,IVE,ACT,IVE 12653m4_expand([active, active]) 12654@result{}ACT, IVE, ACT, IVE 12655m4_quote(active2, active2) 12656@result{}ACT, IVE,ACT, IVE 12657m4_expand([active2, active2]) 12658@result{}ACT, IVE, ACT, IVE 12659m4_expand([# m4_echo]) 12660@result{}# m4_echo 12661m4_quote(# m4_echo) 12662) 12663@result{}# m4_echo) 12664@result{} 12665@end example 12666 12667Note that @code{m4_expand} cannot handle an @var{arg} that expands to 12668literal unbalanced quotes, but that quadrigraphs can be used when 12669unbalanced output is necessary. Likewise, unbalanced parentheses should 12670be supplied with double quoting or a quadrigraph. 12671 12672@example 12673m4_define([pattern], [[!@@<:@@]])dnl 12674m4_define([bar], [BAR])dnl 12675m4_expand([case $foo in 12676 m4_defn([pattern])@@:@}@@ bar ;; 12677 *[)] blah ;; 12678esac]) 12679@result{}case $foo in 12680@result{} [![]) BAR ;; 12681@result{} *) blah ;; 12682@result{}esac 12683@end example 12684@end defmac 12685 12686@defmac m4_ignore (@dots{}) 12687@msindex{ignore} 12688This macro was introduced in Autoconf 2.62. Expands to nothing, 12689ignoring all of its arguments. By itself, this isn't very useful. 12690However, it can be used to conditionally ignore an arbitrary number of 12691arguments, by deciding which macro name to apply to a list of arguments. 12692@example 12693dnl foo outputs a message only if [debug] is defined. 12694m4_define([foo], 12695[m4_ifdef([debug],[AC_MSG_NOTICE],[m4_ignore])([debug message])]) 12696@end example 12697 12698Note that for earlier versions of Autoconf, the macro @code{__gnu__} can 12699serve the same purpose, although it is less readable. 12700@end defmac 12701 12702@defmac m4_make_list (@var{arg}, @dots{}) 12703@msindex{make_list} 12704This macro exists to aid debugging of M4sugar algorithms. Its net 12705effect is similar to @code{m4_dquote}---it produces a quoted list of 12706quoted arguments, for each @var{arg}. The difference is that this 12707version uses a comma-newline separator instead of just comma, to improve 12708readability of the list; with the result that it is less efficient than 12709@code{m4_dquote}. 12710@example 12711m4_define([zero],[0])m4_define([one],[1])m4_define([two],[2])dnl 12712m4_dquote(zero, [one], [[two]]) 12713@result{}[0],[one],[[two]] 12714m4_make_list(zero, [one], [[two]]) 12715@result{}[0], 12716@result{}[one], 12717@result{}[[two]] 12718m4_foreach([number], m4_dquote(zero, [one], [[two]]), [ number]) 12719@result{} 0 1 two 12720m4_foreach([number], m4_make_list(zero, [one], [[two]]), [ number]) 12721@result{} 0 1 two 12722@end example 12723@end defmac 12724 12725@c m4_noquote is too dangerous to document - it invokes macros that 12726@c probably rely on @samp{[]} nested quoting for proper operation. The 12727@c user should generally prefer m4_unquote instead. 12728 12729@defmac m4_quote (@var{arg}, @dots{}) 12730@msindex{quote} 12731Return the arguments as a single entity, i.e., wrap them into a pair of 12732quotes. This effectively collapses multiple arguments into one, 12733although it loses whitespace after unquoted commas in the process. 12734@end defmac 12735 12736@defmac m4_reverse (@var{arg}, @dots{}) 12737@msindex{reverse} 12738Outputs each argument with the same level of quoting, but in reverse 12739order, and with space following each comma for readability. 12740 12741@example 12742m4_define([active], [ACT,IVE]) 12743@result{} 12744m4_reverse(active, [active]) 12745@result{}active, IVE, ACT 12746@end example 12747@end defmac 12748 12749@defmac m4_unquote (@var{arg}, @dots{}) 12750@msindex{unquote} 12751This macro was introduced in Autoconf 2.62. Expand each argument, 12752separated by commas. For a single @var{arg}, this effectively removes a 12753layer of quoting, and @code{m4_unquote([@var{arg}])} is more efficient 12754than the equivalent @code{m4_do([@var{arg}])}. For multiple arguments, 12755this results in an unquoted list of expansions. This is commonly used 12756with @code{m4_split}, in order to convert a single quoted list into a 12757series of quoted elements. 12758@end defmac 12759 12760The following example aims at emphasizing the difference between several 12761scenarios: not using these macros, using @code{m4_defn}, using 12762@code{m4_quote}, using @code{m4_dquote}, and using @code{m4_expand}. 12763 12764@example 12765$ @kbd{cat example.m4} 12766dnl Overquote, so that quotes are visible. 12767m4_define([show], [$[]1 = [$1], $[]@@ = [$@@]]) 12768m4_define([a], [A]) 12769m4_define([mkargs], [1, 2[,] 3]) 12770m4_define([arg1], [[$1]]) 12771m4_divert([0])dnl 12772show(a, b) 12773show([a, b]) 12774show(m4_quote(a, b)) 12775show(m4_dquote(a, b)) 12776show(m4_expand([a, b])) 12777 12778arg1(mkargs) 12779arg1([mkargs]) 12780arg1(m4_defn([mkargs])) 12781arg1(m4_quote(mkargs)) 12782arg1(m4_dquote(mkargs)) 12783arg1(m4_expand([mkargs])) 12784$ @kbd{autom4te -l m4sugar example.m4} 12785$1 = A, $@@ = [A],[b] 12786$1 = a, b, $@@ = [a, b] 12787$1 = A,b, $@@ = [A,b] 12788$1 = [A],[b], $@@ = [[A],[b]] 12789$1 = A, b, $@@ = [A, b] 12790 127911 12792mkargs 127931, 2[,] 3 127941,2, 3 12795[1],[2, 3] 127961, 2, 3 12797@end example 12798 12799 12800@node Text processing Macros 12801@subsection String manipulation in M4 12802 12803The following macros may be used to manipulate strings in M4. Many of 12804the macros in this section intentionally result in quoted strings as 12805output, rather than subjecting the arguments to further expansions. As 12806a result, if you are manipulating text that contains active M4 12807characters, the arguments are passed with single quoting rather than 12808double. 12809 12810@defmac m4_append (@var{macro-name}, @var{string}, @ovar{separator}) 12811@defmacx m4_append_uniq (@var{macro-name}, @var{string}, @ovar{separator} @ 12812 @ovar{if-uniq}, @ovar{if-duplicate}) 12813@msindex{append} 12814@msindex{append_uniq} 12815Redefine @var{macro-name} to its former contents with @var{separator} 12816and @var{string} added at the end. If @var{macro-name} was undefined 12817before (but not if it was defined but empty), then no @var{separator} is 12818added. As of Autoconf 2.62, neither @var{string} nor @var{separator} 12819are expanded during this macro; instead, they are expanded when 12820@var{macro-name} is invoked. 12821 12822@code{m4_append} can be used to grow strings, and @code{m4_append_uniq} 12823to grow strings without duplicating substrings. Additionally, 12824@code{m4_append_uniq} takes two optional parameters as of Autoconf 2.62; 12825@var{if-uniq} is expanded if @var{string} was appended, and 12826@var{if-duplicate} is expanded if @var{string} was already present. 12827Also, @code{m4_append_uniq} warns if @var{separator} is not empty, but 12828occurs within @var{string}, since that can lead to duplicates. 12829 12830Note that @code{m4_append} can scale linearly in the length of the final 12831string, depending on the quality of the underlying M4 implementation, 12832while @code{m4_append_uniq} has an inherent quadratic scaling factor. 12833If an algorithm can tolerate duplicates in the final string, use the 12834former for speed. If duplicates must be avoided, consider using 12835@code{m4_set_add} instead (@pxref{Set manipulation Macros}). 12836 12837@example 12838m4_define([active], [ACTIVE])dnl 12839m4_append([sentence], [This is an])dnl 12840m4_append([sentence], [ active ])dnl 12841m4_append([sentence], [symbol.])dnl 12842sentence 12843@result{}This is an ACTIVE symbol. 12844m4_undefine([active])dnl 12845@result{}This is an active symbol. 12846m4_append_uniq([list], [one], [, ], [new], [existing]) 12847@result{}new 12848m4_append_uniq([list], [one], [, ], [new], [existing]) 12849@result{}existing 12850m4_append_uniq([list], [two], [, ], [new], [existing]) 12851@result{}new 12852m4_append_uniq([list], [three], [, ], [new], [existing]) 12853@result{}new 12854m4_append_uniq([list], [two], [, ], [new], [existing]) 12855@result{}existing 12856list 12857@result{}one, two, three 12858m4_dquote(list) 12859@result{}[one],[two],[three] 12860m4_append([list2], [one], [[, ]])dnl 12861m4_append_uniq([list2], [two], [[, ]])dnl 12862m4_append([list2], [three], [[, ]])dnl 12863list2 12864@result{}one, two, three 12865m4_dquote(list2) 12866@result{}[one, two, three] 12867@end example 12868@end defmac 12869 12870@defmac m4_append_uniq_w (@var{macro-name}, @var{strings}) 12871@msindex{append_uniq_w} 12872This macro was introduced in Autoconf 2.62. It is similar to 12873@code{m4_append_uniq}, but treats @var{strings} as a whitespace 12874separated list of words to append, and only appends unique words. 12875@var{macro-name} is updated with a single space between new words. 12876@example 12877m4_append_uniq_w([numbers], [1 1 2])dnl 12878m4_append_uniq_w([numbers], [ 2 3 ])dnl 12879numbers 12880@result{}1 2 3 12881@end example 12882@end defmac 12883 12884@defmac m4_chomp (@var{string}) 12885@defmacx m4_chomp_all (@var{string}) 12886@msindex{chomp} 12887@msindex{chomp_all} 12888Output @var{string} in quotes, but without a trailing newline. The 12889macro @code{m4_chomp} is slightly faster, and removes at most one 12890newline; the macro @code{m4_chomp_all} removes all consecutive trailing 12891newlines. Unlike @code{m4_flatten}, embedded newlines are left intact, 12892and backslash does not influence the result. 12893@end defmac 12894 12895@defmac m4_combine (@ovar{separator}, @var{prefix-list}, @ovar{infix}, @ 12896 @var{suffix-1}, @ovar{suffix-2}, @dots{}) 12897@msindex{combine} 12898This macro produces a quoted string containing the pairwise combination 12899of every element of the quoted, comma-separated @var{prefix-list}, and 12900every element from the @var{suffix} arguments. Each pairwise 12901combination is joined with @var{infix} in the middle, and successive 12902pairs are joined by @var{separator}. No expansion occurs on any of the 12903arguments. No output occurs if either the @var{prefix} or @var{suffix} 12904list is empty, but the lists can contain empty elements. 12905@example 12906m4_define([a], [oops])dnl 12907m4_combine([, ], [[a], [b], [c]], [-], [1], [2], [3]) 12908@result{}a-1, a-2, a-3, b-1, b-2, b-3, c-1, c-2, c-3 12909m4_combine([, ], [[a], [b]], [-]) 12910@result{} 12911m4_combine([, ], [[a], [b]], [-], []) 12912@result{}a-, b- 12913m4_combine([, ], [], [-], [1], [2]) 12914@result{} 12915m4_combine([, ], [[]], [-], [1], [2]) 12916@result{}-1, -2 12917@end example 12918@end defmac 12919 12920@defmac m4_escape (@var{string}) 12921@msindex{escape} 12922Convert all instances of @samp{[}, @samp{]}, @samp{#}, and @samp{$} 12923within @var{string} into their respective quadrigraphs. The result is 12924still a quoted string. 12925@end defmac 12926 12927@defmac m4_flatten (@var{string}) 12928@msindex{flatten} 12929Flatten @var{string} into a single line. Delete all backslash-newline 12930pairs, and replace all remaining newlines with a space. The result is 12931still a quoted string. 12932@end defmac 12933 12934@defmac m4_join (@ovar{separator}, @var{args}@dots{}) 12935@defmacx m4_joinall (@ovar{separator}, @var{args}@dots{}) 12936@msindex{join} 12937@msindex{joinall} 12938Concatenate each @var{arg}, separated by @var{separator}. 12939@code{joinall} uses every argument, while @code{join} omits empty 12940arguments so that there are no back-to-back separators in the output. 12941The result is a quoted string. 12942@example 12943m4_define([active], [ACTIVE])dnl 12944m4_join([|], [one], [], [active], [two]) 12945@result{}one|active|two 12946m4_joinall([|], [one], [], [active], [two]) 12947@result{}one||active|two 12948@end example 12949 12950Note that if all you intend to do is join @var{args} with commas between 12951them, to form a quoted list suitable for @code{m4_foreach}, it is more 12952efficient to use @code{m4_dquote}. 12953@end defmac 12954 12955@defmac m4_newline (@ovar{text}) 12956@msindex{newline} 12957This macro was introduced in Autoconf 2.62, and expands to a newline, 12958followed by any @var{text}. 12959It is primarily useful for maintaining macro formatting, and ensuring 12960that M4 does not discard leading whitespace during argument collection. 12961@end defmac 12962 12963@defmac m4_normalize (@var{string}) 12964@msindex{normalize} 12965Remove leading and trailing spaces and tabs, sequences of 12966backslash-then-newline, and replace multiple spaces, tabs, and newlines 12967with a single space. This is a combination of @code{m4_flatten} and 12968@code{m4_strip}. To determine if @var{string} consists only of bytes 12969that would be removed by @code{m4_normalize}, you can use 12970@code{m4_ifblank}. 12971@end defmac 12972 12973@defmac m4_re_escape (@var{string}) 12974@msindex{re_escape} 12975Backslash-escape all characters in @var{string} that are active in 12976regexps. 12977@end defmac 12978 12979@c We cannot use @dvar because the macro expansion mistreats backslashes. 12980@defmac m4_split (@var{string}, @r{[}@var{regexp} = @samp{[\t ]+}@r{]}) 12981@msindex{split} 12982Split @var{string} into an M4 list of elements quoted by @samp{[} and 12983@samp{]}, while keeping white space at the beginning and at the end. 12984If @var{regexp} is given, use it instead of @samp{[\t ]+} for splitting. 12985If @var{string} is empty, the result is an empty list. 12986@end defmac 12987 12988@defmac m4_strip (@var{string}) 12989@msindex{strip} 12990Strip whitespace from @var{string}. Sequences of spaces and tabs are 12991reduced to a single space, then leading and trailing spaces are removed. 12992The result is still a quoted string. Note that this does not interfere 12993with newlines; if you want newlines stripped as well, consider 12994@code{m4_flatten}, or do it all at once with @code{m4_normalize}. To 12995quickly test if @var{string} has only whitespace, use @code{m4_ifblank}. 12996@end defmac 12997 12998@defmac m4_text_box (@var{message}, @dvar{frame, -}) 12999@msindex{text_box} 13000Add a text box around @var{message}, using @var{frame} as the border 13001character above and below the message. The @var{frame} argument must be 13002a single byte, and does not support quadrigraphs. 13003The frame correctly accounts for 13004the subsequent expansion of @var{message}. For example: 13005@example 13006m4_define([macro], [abc])dnl 13007m4_text_box([macro]) 13008@result{}## --- ## 13009@result{}## abc ## 13010@result{}## --- ## 13011@end example 13012 13013The @var{message} must contain balanced quotes and parentheses, although 13014quadrigraphs can be used to work around this. 13015@end defmac 13016 13017@defmac m4_text_wrap (@var{string}, @ovar{prefix}, @ 13018 @dvar{prefix1, @var{prefix}}, @dvar{width, 79}) 13019@msindex{text_wrap} 13020Break @var{string} into a series of whitespace-separated words, then 13021output those words separated by spaces, and wrapping lines any time the 13022output would exceed @var{width} columns. If given, @var{prefix1} begins 13023the first line, and @var{prefix} begins all wrapped lines. If 13024@var{prefix1} is longer than @var{prefix}, then the first line consists 13025of just @var{prefix1}. If @var{prefix} is longer than @var{prefix1}, 13026padding is inserted so that the first word of @var{string} begins at the 13027same indentation as all wrapped lines. Note that using literal tab 13028characters in any of the arguments will interfere with the calculation 13029of width. No expansions occur on @var{prefix}, @var{prefix1}, or the 13030words of @var{string}, although quadrigraphs are recognized. 13031 13032For some examples: 13033@example 13034m4_text_wrap([Short string */], [ ], [/* ], [20]) 13035@result{}/* Short string */ 13036m4_text_wrap([Much longer string */], [ ], [/* ], [20]) 13037@result{}/* Much longer 13038@result{} string */ 13039m4_text_wrap([Short doc.], [ ], [ --short ], [30]) 13040@result{} --short Short doc. 13041m4_text_wrap([Short doc.], [ ], [ --too-wide ], [30]) 13042@result{} --too-wide 13043@result{} Short doc. 13044m4_text_wrap([Super long documentation.], [ ], 13045 [ --too-wide ], 30) 13046@result{} --too-wide 13047@result{} Super long 13048@result{} documentation. 13049@end example 13050@end defmac 13051 13052@defmac m4_tolower (@var{string}) 13053@defmacx m4_toupper (@var{string}) 13054@msindex{tolower} 13055@msindex{toupper} 13056Return @var{string} with letters converted to upper or lower case, 13057respectively. 13058@end defmac 13059 13060@node Number processing Macros 13061@subsection Arithmetic computation in M4 13062 13063The following macros facilitate integer arithmetic operations. 13064Where a parameter is documented as taking an arithmetic expression, you 13065can use anything that can be parsed by @code{m4_eval}. 13066 13067@defmac m4_cmp (@var{expr-1}, @var{expr-2}) 13068@msindex{cmp} 13069Compare the arithmetic expressions @var{expr-1} and @var{expr-2}, and 13070expand to @samp{-1} if @var{expr-1} is smaller, @samp{0} if they are 13071equal, and @samp{1} if @var{expr-1} is larger. 13072@end defmac 13073 13074@defmac m4_list_cmp (@var{list-1}, @var{list-2}) 13075@msindex{list_cmp} 13076Compare the two M4 lists consisting of comma-separated arithmetic 13077expressions, left to right. Expand to @samp{-1} for the first element 13078pairing where the value from @var{list-1} is smaller, @samp{1} where the 13079value from @var{list-2} is smaller, or @samp{0} if both lists have the 13080same values. If one list is shorter than the other, the remaining 13081elements of the longer list are compared against zero. 13082@example 13083m4_list_cmp([1, 0], [1]) 13084@result{}0 13085m4_list_cmp([1, [1 * 0]], [1, 0]) 13086@result{}0 13087m4_list_cmp([1, 2], [1, 0]) 13088@result{}1 13089m4_list_cmp([1, [1+1], 3],[1, 2]) 13090@result{}1 13091m4_list_cmp([1, 2, -3], [1, 2]) 13092@result{}-1 13093m4_list_cmp([1, 0], [1, 2]) 13094@result{}-1 13095m4_list_cmp([1], [1, 2]) 13096@result{}-1 13097@end example 13098@end defmac 13099 13100@defmac m4_max (@var{arg}, @dots{}) 13101@msindex{max} 13102This macro was introduced in Autoconf 2.62. Expand to the decimal value 13103of the maximum arithmetic expression among all the arguments. 13104@end defmac 13105 13106@defmac m4_min (@var{arg}, @dots{}) 13107@msindex{min} 13108This macro was introduced in Autoconf 2.62. Expand to the decimal value 13109of the minimum arithmetic expression among all the arguments. 13110@end defmac 13111 13112@defmac m4_sign (@var{expr}) 13113@msindex{sign} 13114Expand to @samp{-1} if the arithmetic expression @var{expr} is negative, 13115@samp{1} if it is positive, and @samp{0} if it is zero. 13116@end defmac 13117 13118@anchor{m4_version_compare} 13119@defmac m4_version_compare (@var{version-1}, @var{version-2}) 13120@msindex{version_compare} 13121This macro was introduced in Autoconf 2.53, but had a number of 13122usability limitations that were not lifted until Autoconf 2.62. Compare 13123the version strings @var{version-1} and @var{version-2}, and expand to 13124@samp{-1} if @var{version-1} is smaller, @samp{0} if they are the same, 13125or @samp{1} @var{version-2} is smaller. Version strings must be a list 13126of elements separated by @samp{.}, @samp{,} or @samp{-}, where each 13127element is a number along with optional case-insensitive letters 13128designating beta releases. The comparison stops at the leftmost element 13129that contains a difference, although a 0 element compares equal to a 13130missing element. 13131 13132It is permissible to include commit identifiers in @var{version}, such 13133as an abbreviated SHA1 of the commit, provided there is still a 13134monotonically increasing prefix to allow for accurate version-based 13135comparisons. For example, this paragraph was written when the 13136development snapshot of autoconf claimed to be at version 13137@samp{2.61a-248-dc51}, or 248 commits after the 2.61a release, with an 13138abbreviated commit identification of @samp{dc51}. 13139 13140@example 13141m4_version_compare([1.1], [2.0]) 13142@result{}-1 13143m4_version_compare([2.0b], [2.0a]) 13144@result{}1 13145m4_version_compare([1.1.1], [1.1.1a]) 13146@result{}-1 13147m4_version_compare([1.2], [1.1.1a]) 13148@result{}1 13149m4_version_compare([1.0], [1]) 13150@result{}0 13151m4_version_compare([1.1pre], [1.1PRE]) 13152@result{}0 13153m4_version_compare([1.1a], [1,10]) 13154@result{}-1 13155m4_version_compare([2.61a], [2.61a-248-dc51]) 13156@result{}-1 13157m4_version_compare([2.61b], [2.61a-248-dc51]) 13158@result{}1 13159@end example 13160@end defmac 13161 13162@defmac m4_version_prereq (@var{version}, @ovar{if-new-enough}, @ 13163 @dvar{if-old, m4_fatal}) 13164@msindex{version_prereq} 13165Compares @var{version} against the version of Autoconf currently 13166running. If the running version is at @var{version} or newer, expand 13167@var{if-new-enough}, but if @var{version} is larger than the version 13168currently executing, expand @var{if-old}, which defaults to printing an 13169error message and exiting m4sugar with status 63. When given only one 13170argument, this behaves like @code{AC_PREREQ} (@pxref{Versioning}). 13171Remember that the autoconf philosophy favors feature checks over version 13172checks. 13173@end defmac 13174 13175@node Set manipulation Macros 13176@subsection Set manipulation in M4 13177@cindex Set manipulation 13178@cindex Data structure, set 13179@cindex Unordered set manipulation 13180 13181Sometimes, it is necessary to track a set of data, where the order does 13182not matter and where there are no duplicates in the set. The following 13183macros facilitate set manipulations. Each set is an opaque object, 13184which can only be accessed via these basic operations. The underlying 13185implementation guarantees linear scaling for set creation, which is more 13186efficient than using the quadratic @code{m4_append_uniq}. Both set 13187names and values can be arbitrary strings, except for unbalanced quotes. 13188This implementation ties up memory for removed elements until the next 13189operation that must traverse all the elements of a set; and although 13190that may slow down some operations until the memory for removed elements 13191is pruned, it still guarantees linear performance. 13192 13193@defmac m4_set_add (@var{set}, @var{value}, @ovar{if-uniq}, @ovar{if-dup}) 13194@msindex{set_add} 13195Adds the string @var{value} as a member of set @var{set}. Expand 13196@var{if-uniq} if the element was added, or @var{if-dup} if it was 13197previously in the set. Operates in amortized constant time, so that set 13198creation scales linearly. 13199@end defmac 13200 13201@defmac m4_set_add_all (@var{set}, @var{value}@dots{}) 13202@msindex{set_add_all} 13203Adds each @var{value} to the set @var{set}. This is slightly more 13204efficient than repeatedly invoking @code{m4_set_add}. 13205@end defmac 13206 13207@defmac m4_set_contains (@var{set}, @var{value}, @ovar{if-present}, @ 13208 @ovar{if-absent}) 13209@msindex{set_contains} 13210Expands @var{if-present} if the string @var{value} is a member of 13211@var{set}, otherwise @var{if-absent}. 13212 13213@example 13214m4_set_contains([a], [1], [yes], [no]) 13215@result{}no 13216m4_set_add([a], [1], [added], [dup]) 13217@result{}added 13218m4_set_add([a], [1], [added], [dup]) 13219@result{}dup 13220m4_set_contains([a], [1], [yes], [no]) 13221@result{}yes 13222m4_set_remove([a], [1], [removed], [missing]) 13223@result{}removed 13224m4_set_contains([a], [1], [yes], [no]) 13225@result{}no 13226m4_set_remove([a], [1], [removed], [missing]) 13227@result{}missing 13228@end example 13229@end defmac 13230 13231@defmac m4_set_contents (@var{set}, @ovar{sep}) 13232@defmacx m4_set_dump (@var{set}, @ovar{sep}) 13233@msindex{set_contents} 13234@msindex{set_dump} 13235Expands to a single string consisting of all the members of the set 13236@var{set}, each separated by @var{sep}, which is not expanded. 13237@code{m4_set_contents} leaves the elements in @var{set} but reclaims any 13238memory occupied by removed elements, while @code{m4_set_dump} is a 13239faster one-shot action that also deletes the set. No provision is made 13240for disambiguating members that contain a non-empty @var{sep} as a 13241substring; use @code{m4_set_empty} to distinguish between an empty set 13242and the set containing only the empty string. The order of the output 13243is unspecified; in the current implementation, part of the speed of 13244@code{m4_set_dump} results from using a different output order than 13245@code{m4_set_contents}. These macros scale linearly in the size of the 13246set before memory pruning, and @code{m4_set_contents([@var{set}], 13247[@var{sep}])} is faster than 13248@code{m4_joinall([@var{sep}]m4_set_listc([@var{set}]))}. 13249 13250@example 13251m4_set_add_all([a], [1], [2], [3]) 13252@result{} 13253m4_set_contents([a], [-]) 13254@result{}1-2-3 13255m4_joinall([-]m4_set_listc([a])) 13256@result{}1-2-3 13257m4_set_dump([a], [-]) 13258@result{}3-2-1 13259m4_set_contents([a]) 13260@result{} 13261m4_set_add([a], []) 13262@result{} 13263m4_set_contents([a], [-]) 13264@result{} 13265@end example 13266@end defmac 13267 13268@defmac m4_set_delete (@var{set}) 13269@msindex{set_delete} 13270Delete all elements and memory associated with @var{set}. This is 13271linear in the set size, and faster than removing one element at a time. 13272@end defmac 13273 13274@defmac m4_set_difference (@var{seta}, @var{setb}) 13275@defmacx m4_set_intersection (@var{seta}, @var{setb}) 13276@defmacx m4_set_union (@var{seta}, @var{setb}) 13277@msindex{set_difference} 13278@msindex{set_intersection} 13279@msindex{set_union} 13280Compute the relation between @var{seta} and @var{setb}, and output the 13281result as a list of quoted arguments without duplicates and with a 13282leading comma. Set difference selects the elements in @var{seta} but 13283not @var{setb}, intersection selects only elements in both sets, and 13284union selects elements in either set. These actions are linear in the 13285sum of the set sizes. The leading comma is necessary to distinguish 13286between no elements and the empty string as the only element. 13287 13288@example 13289m4_set_add_all([a], [1], [2], [3]) 13290@result{} 13291m4_set_add_all([b], [3], [], [4]) 13292@result{} 13293m4_set_difference([a], [b]) 13294@result{},1,2 13295m4_set_difference([b], [a]) 13296@result{},,4 13297m4_set_intersection([a], [b]) 13298@result{},3 13299m4_set_union([a], [b]) 13300@result{},1,2,3,,4 13301@end example 13302@end defmac 13303 13304@defmac m4_set_empty (@var{set}, @ovar{if-empty}, @ovar{if-elements}) 13305@msindex{set_empty} 13306Expand @var{if-empty} if the set @var{set} has no elements, otherwise 13307expand @var{if-elements}. This macro operates in constant time. Using 13308this macro can help disambiguate output from @code{m4_set_contents} or 13309@code{m4_set_list}. 13310@end defmac 13311 13312@defmac m4_set_foreach (@var{set}, @var{variable}, @var{action}) 13313@msindex{set_foreach} 13314For each element in the set @var{set}, expand @var{action} with the 13315macro @var{variable} defined as the set element. Behavior is 13316unspecified if @var{action} recursively lists the contents of @var{set} 13317(although listing other sets is acceptable), or if it modifies the set 13318in any way other than removing the element currently contained in 13319@var{variable}. This macro is faster than the corresponding 13320@code{m4_foreach([@var{variable}], 13321m4_indir([m4_dquote]m4_set_listc([@var{set}])), [@var{action}])}, 13322although @code{m4_set_map} might be faster still. 13323 13324@example 13325m4_set_add_all([a]m4_for([i], [1], [5], [], [,i])) 13326@result{} 13327m4_set_contents([a]) 13328@result{}12345 13329m4_set_foreach([a], [i], 13330 [m4_if(m4_eval(i&1), [0], [m4_set_remove([a], i, [i])])]) 13331@result{}24 13332m4_set_contents([a]) 13333@result{}135 13334@end example 13335@end defmac 13336 13337@defmac m4_set_list (@var{set}) 13338@defmacx m4_set_listc (@var{set}) 13339@msindex{set_list} 13340@msindex{set_listc} 13341Produce a list of arguments, where each argument is a quoted element 13342from the set @var{set}. The variant @code{m4_set_listc} is unambiguous, 13343by adding a leading comma if there are any set elements, whereas the 13344variant @code{m4_set_list} cannot distinguish between an empty set and a 13345set containing only the empty string. These can be directly used in 13346macros that take multiple arguments, such as @code{m4_join} or 13347@code{m4_set_add_all}, or wrapped by @code{m4_dquote} for macros that 13348take a quoted list, such as @code{m4_map} or @code{m4_foreach}. Any 13349memory occupied by removed elements is reclaimed during these macros. 13350 13351@example 13352m4_set_add_all([a], [1], [2], [3]) 13353@result{} 13354m4_set_list([a]) 13355@result{}1,2,3 13356m4_set_list([b]) 13357@result{} 13358m4_set_listc([b]) 13359@result{} 13360m4_count(m4_set_list([b])) 13361@result{}1 13362m4_set_empty([b], [0], [m4_count(m4_set_list([b]))]) 13363@result{}0 13364m4_set_add([b], []) 13365@result{} 13366m4_set_list([b]) 13367@result{} 13368m4_set_listc([b]) 13369@result{}, 13370m4_count(m4_set_list([b])) 13371@result{}1 13372m4_set_empty([b], [0], [m4_count(m4_set_list([b]))]) 13373@result{}1 13374@end example 13375@end defmac 13376 13377@defmac m4_set_map (@var{set}, @var{action}) 13378@msindex{set_map} 13379For each element in the set @var{set}, expand @var{action} with a single 13380argument of the set element. Behavior is unspecified if @var{action} 13381recursively lists the contents of @var{set} (although listing other sets 13382is acceptable), or if it modifies the set in any way other than removing 13383the element passed as an argument. This macro is faster than either 13384corresponding counterpart of 13385@code{m4_map_args([@var{action}]m4_set_listc([@var{set}]))} or 13386@code{m4_set_foreach([@var{set}], [var], 13387[@var{action}(m4_defn([var]))])}. It is possible to use @code{m4_curry} 13388if more than one argument is needed for @var{action}, although it is 13389more efficient to use @code{m4_set_map_sep} in that case. 13390@end defmac 13391 13392@defmac m4_set_map_sep (@var{set}, @ovar{pre}, @ovar{post}, @ovar{sep}) 13393@msindex{set_map_sep} 13394For each element in the set @var{set}, expand 13395@code{@var{pre}[element]@var{post}}, additionally expanding @var{sep} 13396between elements. Behavior is unspecified if the expansion recursively 13397lists the contents of @var{set} (although listing other sets 13398is acceptable), or if it modifies the set in any way other than removing 13399the element visited by the expansion. This macro provides the most 13400efficient means for non-destructively visiting the elements of a set; in 13401particular, @code{m4_set_map([@var{set}], [@var{action}])} is equivalent 13402to @code{m4_set_map_sep([@var{set}], [@var{action}(], [)])}. 13403@end defmac 13404 13405@defmac m4_set_remove (@var{set}, @var{value}, @ovar{if-present}, @ 13406 @ovar{if-absent}) 13407@msindex{set_remove} 13408If @var{value} is an element in the set @var{set}, then remove it and 13409expand @var{if-present}. Otherwise expand @var{if-absent}. This macro 13410operates in constant time so that multiple removals will scale linearly 13411rather than quadratically; but when used outside of 13412@code{m4_set_foreach} or @code{m4_set_map}, it leaves memory occupied 13413until the set is later 13414compacted by @code{m4_set_contents} or @code{m4_set_list}. Several 13415other set operations are then less efficient between the time of element 13416removal and subsequent memory compaction, but still maintain their 13417guaranteed scaling performance. 13418@end defmac 13419 13420@defmac m4_set_size (@var{set}) 13421@msindex{set_size} 13422Expand to the size of the set @var{set}. This implementation operates 13423in constant time, and is thus more efficient than 13424@code{m4_eval(m4_count(m4_set_listc([set])) - 1)}. 13425@end defmac 13426 13427 13428@node Forbidden Patterns 13429@subsection Forbidden Patterns 13430@cindex Forbidden patterns 13431@cindex Patterns, forbidden 13432 13433M4sugar provides a means to define suspicious patterns, patterns 13434describing tokens which should not be found in the output. For 13435instance, if an Autoconf @file{configure} script includes tokens such as 13436@samp{AC_DEFINE}, or @samp{dnl}, then most probably something went 13437wrong (typically a macro was not evaluated because of overquotation). 13438 13439M4sugar forbids all the tokens matching @samp{^_?m4_} and @samp{^dnl$}. 13440Additional layers, such as M4sh and Autoconf, add additional forbidden 13441patterns to the list. 13442 13443@defmac m4_pattern_forbid (@var{pattern}) 13444@msindex{pattern_forbid} 13445Declare that no token matching @var{pattern} must be found in the output. 13446Comments are not checked; this can be a problem if, for instance, you 13447have some macro left unexpanded after an @samp{#include}. No consensus 13448is currently found in the Autoconf community, as some people consider it 13449should be valid to name macros in comments (which doesn't make sense to 13450the authors of this documentation: input, such as macros, should be 13451documented by @samp{dnl} comments; reserving @samp{#}-comments to 13452document the output). 13453@end defmac 13454 13455Of course, you might encounter exceptions to these generic rules, for 13456instance you might have to refer to @samp{$m4_flags}. 13457 13458@defmac m4_pattern_allow (@var{pattern}) 13459@msindex{pattern_allow} 13460Any token matching @var{pattern} is allowed, including if it matches an 13461@code{m4_pattern_forbid} pattern. 13462@end defmac 13463 13464@node Debugging via autom4te 13465@section Debugging via autom4te 13466@cindex debugging tips 13467@cindex autom4te debugging tips 13468@cindex m4sugar debugging tips 13469At times, it is desirable to see what was happening inside m4, to see 13470why output was not matching expectations. However, post-processing done 13471by @command{autom4te} means that directly using the m4 builtin 13472@code{m4_traceon} is likely to interfere with operation. Also, frequent 13473diversion changes and the concept of forbidden tokens make it difficult 13474to use @code{m4_defn} to generate inline comments in the final output. 13475 13476There are a couple of tools to help with this. One is the use of the 13477@option{--trace} option provided by @command{autom4te} (as well as each 13478of the programs that wrap @command{autom4te}, such as 13479@command{autoconf}), in order to inspect when a macro is called and with 13480which arguments. For example, when this paragraph was written, the 13481autoconf version could be found by: 13482 13483@example 13484$ @kbd{autoconf --trace=AC_INIT} 13485configure.ac:23:AC_INIT:GNU Autoconf:2.63b.95-3963:bug-autoconf@@gnu.org 13486$ @kbd{autoconf --trace='AC_INIT:version is $2'} 13487version is 2.63b.95-3963 13488@end example 13489 13490Another trick is to print out the expansion of various m4 expressions to 13491standard error or to an independent file, with no further m4 expansion, 13492and without interfering with diversion changes or the post-processing 13493done to standard output. @code{m4_errprintn} shows a given expression 13494on standard error. For example, if you want to see the expansion of an 13495autoconf primitive or of one of your autoconf macros, you can do it like 13496this: 13497 13498@example 13499$ @kbd{cat <<\EOF > configure.ac} 13500AC_INIT 13501m4_errprintn([The definition of AC_DEFINE_UNQUOTED:]) 13502m4_errprintn(m4_defn([AC_DEFINE_UNQUOTED])) 13503AC_OUTPUT 13504EOF 13505$ @kbd{autoconf} 13506@error{}The definition of AC_DEFINE_UNQUOTED: 13507@error{}_AC_DEFINE_Q([], $@@) 13508@end example 13509 13510@node Programming in M4sh 13511@chapter Programming in M4sh 13512 13513M4sh, pronounced ``mash'', is aiming at producing portable Bourne shell 13514scripts. This name was coined by Lars J. Aas, who notes that, 13515according to the Webster's Revised Unabridged Dictionary (1913): 13516 13517@quotation 13518Mash \Mash\, n. [Akin to G. meisch, maisch, meische, maische, mash, 13519wash, and prob.@: to AS. miscian to mix. See ``Mix''.] 13520 13521@enumerate 1 13522@item 13523A mass of mixed ingredients reduced to a soft pulpy state by beating or 13524pressure@enddots{} 13525 13526@item 13527A mixture of meal or bran and water fed to animals. 13528 13529@item 13530A mess; trouble. [Obs.] --Beau.@: & Fl. 13531@end enumerate 13532@end quotation 13533 13534M4sh reserves the M4 macro namespace @samp{^_AS_} for internal use, and 13535the namespace @samp{^AS_} for M4sh macros. It also reserves the shell 13536and environment variable namespace @samp{^as_}, and the here-document 13537delimiter namespace @samp{^_AS[A-Z]} in the output file. You should not 13538define your own macros or output shell code that conflicts with these 13539namespaces. 13540 13541@menu 13542* Common Shell Constructs:: Portability layer for common shell constructs 13543* Polymorphic Variables:: Support for indirect variable names 13544* Initialization Macros:: Macros to establish a sane shell environment 13545* File Descriptor Macros:: File descriptor macros for input and output 13546@end menu 13547 13548@node Common Shell Constructs 13549@section Common Shell Constructs 13550 13551M4sh provides portable alternatives for some common shell constructs 13552that unfortunately are not portable in practice. 13553 13554@c Deprecated, to be replaced by a better API 13555@ignore 13556@defmac AS_BASENAME (@var{file-name}) 13557@asindex{BASENAME} 13558Output the non-directory portion of @var{file-name}. For example, 13559if @code{$file} is @samp{/one/two/three}, the command 13560@code{base=`AS_BASENAME(["$file"])`} sets @code{base} to @samp{three}. 13561@end defmac 13562@end ignore 13563 13564@defmac AS_BOX (@var{text}, @dvar{char, -}) 13565@asindex{BOX} 13566Expand into shell code that will output @var{text} surrounded by a box 13567with @var{char} in the top and bottom border. @var{text} should not 13568contain a newline, but may contain shell expansions valid for unquoted 13569here-documents. @var{char} defaults to @samp{-}, but can be any 13570character except @samp{/}, @samp{'}, @samp{"}, @samp{\}, 13571@samp{&}, or @samp{`}. This is useful for outputting a comment box into 13572log files to separate distinct phases of script operation. 13573@end defmac 13574 13575@defmac AS_CASE (@var{word}, @ovar{pattern1}, @ovar{if-matched1}, @ 13576 @dots{}, @ovar{default}) 13577@asindex{CASE} 13578Expand into a shell @samp{case} statement, where @var{word} is matched 13579against one or more patterns. @var{if-matched} is run if the 13580corresponding pattern matched @var{word}, else @var{default} is run. 13581Avoids several portability issues (@pxref{case, , Limitations of Shell 13582Builtins}). 13583@end defmac 13584 13585@c Deprecated, to be replaced by a better API 13586@defmac AS_DIRNAME (@var{file-name}) 13587@asindex{DIRNAME} 13588Output the directory portion of @var{file-name}. For example, 13589if @code{$file} is @samp{/one/two/three}, the command 13590@code{dir=`AS_DIRNAME(["$file"])`} sets @code{dir} to @samp{/one/two}. 13591 13592This interface may be improved in the future to avoid forks and losing 13593trailing newlines. 13594@end defmac 13595 13596@defmac AS_ECHO (@var{word}) 13597@asindex{ECHO} 13598Emits @var{word} to the standard output, followed by a newline. @var{word} 13599must be a single shell word (typically a quoted string). The bytes of 13600@var{word} are output as-is, even if it starts with "-" or contains "\". 13601Redirections can be placed outside the macro invocation. This is much 13602more portable than using @command{echo} (@pxref{echo, , Limitations of 13603Shell Builtins}). 13604@end defmac 13605 13606@defmac AS_ECHO_N (@var{word}) 13607@asindex{ECHO_N} 13608Emits @var{word} to the standard output, without a following newline. 13609@var{word} must be a single shell word (typically a quoted string) and, 13610for portability, should not include more than one newline. The bytes of 13611@var{word} are output as-is, even if it starts with "-" or contains "\". 13612Redirections can be placed outside the macro invocation. 13613@end defmac 13614 13615@c We cannot use @dvar because the macro expansion mistreats backslashes. 13616@defmac AS_ESCAPE (@var{string}, @r{[}@var{chars} = @samp{`\"$}@r{]}) 13617@asindex{ESCAPE} 13618Expands to @var{string}, with any characters in @var{chars} escaped with 13619a backslash (@samp{\}). @var{chars} should be at most four bytes long, 13620and only contain characters from the set @samp{`\"$}; however, 13621characters may be safely listed more than once in @var{chars} for the 13622sake of syntax highlighting editors. The current implementation expands 13623@var{string} after adding escapes; if @var{string} contains macro calls 13624that in turn expand to text needing shell quoting, you can use 13625@code{AS_ESCAPE(m4_dquote(m4_expand([string])))}. 13626 13627The default for @var{chars} (@samp{\"$`}) is the set of characters 13628needing escapes when @var{string} will be used literally within double 13629quotes. One common variant is the set of characters to protect when 13630@var{string} will be used literally within back-ticks or an unquoted 13631here-document (@samp{\$`}). Another common variant is @samp{""}, which can 13632be used to form a double-quoted string containing the same expansions 13633that would have occurred if @var{string} were expanded in an unquoted 13634here-document; however, when using this variant, care must be taken that 13635@var{string} does not use double quotes within complex variable 13636expansions (such as @samp{$@{foo-`echo "hi"`@}}) that would be broken 13637with improper escapes. 13638 13639This macro is often used with @code{AS_ECHO}. For an example, observe 13640the output generated by the shell code generated from this snippet: 13641 13642@example 13643foo=bar 13644AS_ECHO(["AS_ESCAPE(["$foo" = ])AS_ESCAPE(["$foo"], [""])"]) 13645@result{}"$foo" = "bar" 13646m4_define([macro], [a, [\b]]) 13647AS_ECHO(["AS_ESCAPE([[macro]])"]) 13648@result{}macro 13649AS_ECHO(["AS_ESCAPE([macro])"]) 13650@result{}a, b 13651AS_ECHO(["AS_ESCAPE(m4_dquote(m4_expand([macro])))"]) 13652@result{}a, \b 13653@end example 13654 13655@comment Should we add AS_ESCAPE_SINGLE? If we do, we can optimize in 13656@comment the case of @var{string} that does not contain '. 13657To escape a string that will be placed within single quotes, use: 13658 13659@example 13660m4_bpatsubst([[@var{string}]], ['], ['\\'']) 13661@end example 13662@end defmac 13663 13664@defmac AS_EXECUTABLE_P (@var{file}) 13665@asindex{EXECUTABLE_P} 13666Emit code to probe whether @var{file} is a regular file with executable 13667permissions (and not a directory with search permissions). The caller 13668is responsible for quoting @var{file}. 13669@end defmac 13670 13671@defmac AS_EXIT (@dvar{status, $?}) 13672@asindex{EXIT} 13673Emit code to exit the shell with @var{status}, defaulting to @samp{$?}. 13674This macro 13675works around shells that see the exit status of the command prior to 13676@code{exit} inside a @samp{trap 0} handler (@pxref{trap, , Limitations 13677of Shell Builtins}). 13678@end defmac 13679 13680@defmac AS_IF (@var{test1}, @ovar{run-if-true1}, @dots{}, @ovar{run-if-false}) 13681@asindex{IF} 13682Run shell code @var{test1}. If @var{test1} exits with a zero status then 13683run shell code @var{run-if-true1}, else examine further tests. If no test 13684exits with a zero status, run shell code @var{run-if-false}, with 13685simplifications if either @var{run-if-true1} or @var{run-if-false} 13686is empty. For example, 13687 13688@example 13689AS_IF([test "x$foo" = xyes], [HANDLE_FOO([yes])], 13690 [test "x$foo" != xno], [HANDLE_FOO([maybe])], 13691 [echo foo not specified]) 13692@end example 13693 13694@noindent 13695ensures any required macros of @code{HANDLE_FOO} 13696are expanded before the first test. 13697@end defmac 13698 13699@defmac AS_MKDIR_P (@var{file-name}) 13700@asindex{MKDIR_P} 13701Make the directory @var{file-name}, including intervening directories 13702as necessary. This is equivalent to @samp{mkdir -p -- @var{file-name}}, 13703except that it is portable to older versions of @command{mkdir} that 13704lack support for the @option{-p} option or for the @option{--} 13705delimiter (@pxref{mkdir, , Limitations of Usual Tools}). Also, 13706@code{AS_MKDIR_P} 13707succeeds if @var{file-name} is a symbolic link to an existing directory, 13708even though Posix is unclear whether @samp{mkdir -p} should 13709succeed in that case. If creation of @var{file-name} fails, exit the 13710script. 13711 13712Also see the @code{AC_PROG_MKDIR_P} macro (@pxref{Particular Programs}). 13713@end defmac 13714 13715@defmac AS_SET_STATUS (@var{status}) 13716@asindex{SET_STATUS} 13717Emit shell code to set the value of @samp{$?} to @var{status}, as 13718efficiently as possible. However, this is not guaranteed to abort a 13719shell running with @code{set -e} (@pxref{set, , Limitations of Shell 13720Builtins}). This should also be used at the end of a complex shell 13721function instead of @samp{return} (@pxref{Shell Functions}) to avoid 13722a DJGPP shell bug. 13723@end defmac 13724 13725@defmac AS_TR_CPP (@var{expression}) 13726@asindex{TR_CPP} 13727Transform @var{expression} into a valid right-hand side for a C @code{#define}. 13728For example: 13729 13730@example 13731# This outputs "#define HAVE_CHAR_P 1". 13732# Notice the m4 quoting around #, to prevent an m4 comment 13733type="char *" 13734echo "[#]define AS_TR_CPP([HAVE_$type]) 1" 13735@end example 13736@end defmac 13737 13738@defmac AS_TR_SH (@var{expression}) 13739@asindex{TR_SH} 13740Transform @var{expression} into shell code that generates a valid shell 13741variable name. The result is literal when possible at m4 time, but must 13742be used with @code{eval} if @var{expression} causes shell indirections. 13743For example: 13744 13745@example 13746# This outputs "Have it!". 13747header="sys/some file.h" 13748eval AS_TR_SH([HAVE_$header])=yes 13749if test "x$HAVE_sys_some_file_h" = xyes; then echo "Have it!"; fi 13750@end example 13751@end defmac 13752 13753@defmac AS_SET_CATFILE (@var{var}, @var{dir}, @var{file}) 13754@asindex{SET_CATFILE} 13755Set the polymorphic shell variable @var{var} to @var{dir}/@var{file}, 13756but optimizing the common cases (@var{dir} or @var{file} is @samp{.}, 13757@var{file} is absolute, etc.). 13758@end defmac 13759 13760@defmac AS_UNSET (@var{var}) 13761@asindex{UNSET} 13762Unsets the shell variable @var{var}, working around bugs in older 13763shells (@pxref{unset, , Limitations of Shell 13764Builtins}). @var{var} can be a literal or indirect variable name. 13765@end defmac 13766 13767@defmac AS_VERSION_COMPARE (@var{version-1}, @var{version-2}, @ 13768 @ovar{action-if-less}, @ovar{action-if-equal}, @ovar{action-if-greater}) 13769@asindex{VERSION_COMPARE} 13770Compare two strings @var{version-1} and @var{version-2}, possibly 13771containing shell variables, as version strings, and expand 13772@var{action-if-less}, @var{action-if-equal}, or @var{action-if-greater} 13773depending upon the result. 13774The algorithm to compare is similar to the one used by strverscmp in 13775glibc (@pxref{String/Array Comparison, , String/Array Comparison, libc, 13776The GNU C Library}). 13777@end defmac 13778 13779@node Polymorphic Variables 13780@section Support for indirect variable names 13781@cindex variable name indirection 13782@cindex polymorphic variable name 13783@cindex indirection, variable name 13784 13785Often, it is convenient to write a macro that will emit shell code 13786operating on a shell variable. The simplest case is when the variable 13787name is known. But a more powerful idiom is writing shell code that can 13788work through an indirection, where another variable or command 13789substitution produces the name of the variable to actually manipulate. 13790M4sh supports the notion of polymorphic shell variables, making it easy 13791to write a macro that can deal with either literal or indirect variable 13792names and output shell code appropriate for both use cases. Behavior is 13793undefined if expansion of an indirect variable does not result in a 13794literal variable name. 13795 13796@defmac AS_LITERAL_IF (@var{expression}, @ovar{if-literal}, @ovar{if-not}, @ 13797 @dvar{if-simple-ref, @var{if-not}}) 13798@defmacx AS_LITERAL_WORD_IF (@var{expression}, @ovar{if-literal}, @ 13799 @ovar{if-not}, @dvar{if-simple-ref, @var{if-not}}) 13800@asindex{LITERAL_IF} 13801@asindex{LITERAL_WORD_IF} 13802If the expansion of @var{expression} is definitely a shell literal, 13803expand @var{if-literal}. If the expansion of @var{expression} looks 13804like it might contain shell indirections (such as @code{$var} or 13805@code{`expr`}), then @var{if-not} is expanded. Sometimes, it is 13806possible to output optimized code if @var{expression} consists only of 13807shell variable expansions (such as @code{$@{var@}}), in which case 13808@var{if-simple-ref} can be provided; but defaulting to @var{if-not} 13809should always be safe. @code{AS_LITERAL_WORD_IF} only expands 13810@var{if-literal} if @var{expression} looks like a single shell word, 13811containing no whitespace; while @code{AS_LITERAL_IF} allows whitespace 13812in @var{expression}. 13813 13814In order to reduce the time spent recognizing whether an 13815@var{expression} qualifies as a literal or a simple indirection, the 13816implementation is somewhat conservative: @var{expression} must be a 13817single shell word (possibly after stripping whitespace), consisting only 13818of bytes that would have the same meaning whether unquoted or enclosed 13819in double quotes (for example, @samp{a.b} results in @var{if-literal}, 13820even though it is not a valid shell variable name; while both @samp{'a'} 13821and @samp{[$]} result in @var{if-not}, because they behave differently 13822than @samp{"'a'"} and @samp{"[$]"}). This macro can be used in contexts 13823for recognizing portable file names (such as in the implementation of 13824@code{AC_LIBSOURCE}), or coupled with some transliterations for forming 13825valid variable names (such as in the implementation of @code{AS_TR_SH}, 13826which uses an additional @code{m4_translit} to convert @samp{.} to 13827@samp{_}). 13828 13829This example shows how to read the contents of the shell variable 13830@code{bar}, exercising all three arguments to @code{AS_LITERAL_IF}. It 13831results in a script that will output the line @samp{hello} three times. 13832 13833@example 13834AC_DEFUN([MY_ACTION], 13835[AS_LITERAL_IF([$1], 13836 [echo "$$1"], 13837@c $$ 13838 [AS_VAR_COPY([var], [$1]) 13839 echo "$var"], 13840 [eval 'echo "$'"$1"\"])]) 13841foo=bar bar=hello 13842MY_ACTION([bar]) 13843MY_ACTION([`echo bar`]) 13844MY_ACTION([$foo]) 13845@end example 13846@end defmac 13847 13848@defmac AS_VAR_APPEND (@var{var}, @var{text}) 13849@asindex{VAR_APPEND} 13850Emit shell code to append the shell expansion of @var{text} to the end 13851of the current contents of the polymorphic shell variable @var{var}, 13852taking advantage of shells that provide the @samp{+=} extension for more 13853efficient scaling. 13854 13855For situations where the final contents of @var{var} are relatively 13856short (less than 256 bytes), it is more efficient to use the simpler 13857code sequence of @code{@var{var}=$@{@var{var}@}@var{text}} (or its 13858polymorphic equivalent of @code{AS_VAR_COPY([t], [@var{var}])} and 13859@code{AS_VAR_SET([@var{var}], ["$t"@var{text}])}). But in the case 13860when the script will be repeatedly appending text into @code{var}, 13861issues of scaling start to become apparent. A naive implementation 13862requires execution time linear to the length of the current contents of 13863@var{var} as well as the length of @var{text} for a single append, for 13864an overall quadratic scaling with multiple appends. This macro takes 13865advantage of shells which provide the extension 13866@code{@var{var}+=@var{text}}, which can provide amortized constant time 13867for a single append, for an overall linear scaling with multiple 13868appends. Note that unlike @code{AS_VAR_SET}, this macro requires that 13869@var{text} be quoted properly to avoid field splitting and file name 13870expansion. 13871@end defmac 13872 13873@defmac AS_VAR_ARITH (@var{var}, @var{expression}) 13874@asindex{VAR_ARITH} 13875Emit shell code to compute the arithmetic expansion of @var{expression}, 13876assigning the result as the contents of the polymorphic shell variable 13877@var{var}. The code takes advantage of shells that provide @samp{$(())} 13878for fewer forks, but uses @command{expr} as a fallback. Therefore, the 13879syntax for a valid @var{expression} is rather limited: all operators 13880must occur as separate shell arguments and with proper quoting, there is 13881no portable equality operator, all variables containing numeric values 13882must be expanded prior to the computation, all numeric values must be 13883provided in decimal without leading zeroes, and the first shell argument 13884should not be a negative number. In the following example, this snippet 13885will print @samp{(2+3)*4 == 20}. 13886 13887@example 13888bar=3 13889AS_VAR_ARITH([foo], [\( 2 + $bar \) \* 4]) 13890echo "(2+$bar)*4 == $foo" 13891@end example 13892@end defmac 13893 13894@defmac AS_VAR_COPY (@var{dest}, @var{source}) 13895@asindex{VAR_COPY} 13896Emit shell code to assign the contents of the polymorphic shell variable 13897@var{source} to the polymorphic shell variable @var{dest}. For example, 13898executing this M4sh snippet will output @samp{bar hi}: 13899 13900@example 13901foo=bar bar=hi 13902AS_VAR_COPY([a], [foo]) 13903AS_VAR_COPY([b], [$foo]) 13904echo "$a $b" 13905@end example 13906 13907When it is necessary to access the contents of an indirect variable 13908inside a shell double-quoted context, the recommended idiom is to first 13909copy the contents into a temporary literal shell variable. 13910 13911@smallexample 13912for header in stdint_h inttypes_h ; do 13913 AS_VAR_COPY([var], [ac_cv_header_$header]) 13914 echo "$header detected: $var" 13915done 13916@end smallexample 13917@end defmac 13918 13919@comment AS_VAR_GET is intentionally undocumented; it can't handle 13920@comment trailing newlines uniformly, and forks too much. 13921 13922@defmac AS_VAR_IF (@var{var}, @ovar{word}, @ovar{if-equal}, @ 13923 @ovar{if-not-equal}) 13924@asindex{VAR_IF} 13925Output a shell conditional statement. If the contents of the 13926polymorphic shell variable @var{var} match the string @var{word}, 13927execute @var{if-equal}; otherwise execute @var{if-not-equal}. @var{word} 13928must be a single shell word (typically a quoted string). Avoids 13929shell bugs if an interrupt signal arrives while a command substitution 13930in @var{var} is being expanded. 13931@end defmac 13932 13933@defmac AS_VAR_PUSHDEF (@var{m4-name}, @var{value}) 13934@defmacx AS_VAR_POPDEF (@var{m4-name}) 13935@asindex{VAR_PUSHDEF} 13936@asindex{VAR_POPDEF} 13937@cindex composing variable names 13938@cindex variable names, composing 13939A common M4sh idiom involves composing shell variable names from an m4 13940argument (for example, writing a macro that uses a cache variable). 13941@var{value} can be an arbitrary string, which will be transliterated 13942into a valid shell name by @code{AS_TR_SH}. In order to access the 13943composed variable name based on @var{value}, it is easier to declare a 13944temporary m4 macro @var{m4-name} with @code{AS_VAR_PUSHDEF}, then use 13945that macro as the argument to subsequent @code{AS_VAR} macros as a 13946polymorphic variable name, and finally free the temporary macro with 13947@code{AS_VAR_POPDEF}. These macros are often followed with @code{dnl}, 13948to avoid excess newlines in the output. 13949 13950Here is an involved example, that shows the power of writing macros that 13951can handle composed shell variable names: 13952 13953@example 13954m4_define([MY_CHECK_HEADER], 13955[AS_VAR_PUSHDEF([my_Header], [ac_cv_header_$1])dnl 13956AS_VAR_IF([my_Header], [yes], [echo "header $1 detected"])dnl 13957AS_VAR_POPDEF([my_Header])dnl 13958]) 13959MY_CHECK_HEADER([stdint.h]) 13960for header in inttypes.h stdlib.h ; do 13961 MY_CHECK_HEADER([$header]) 13962done 13963@end example 13964 13965@noindent 13966In the above example, @code{MY_CHECK_HEADER} can operate on polymorphic 13967variable names. In the first invocation, the m4 argument is 13968@code{stdint.h}, which transliterates into a literal @code{stdint_h}. 13969As a result, the temporary macro @code{my_Header} expands to the literal 13970shell name @samp{ac_cv_header_stdint_h}. In the second invocation, the 13971m4 argument to @code{MY_CHECK_HEADER} is @code{$header}, and the 13972temporary macro @code{my_Header} expands to the indirect shell name 13973@samp{$as_my_Header}. During the shell execution of the for loop, when 13974@samp{$header} contains @samp{inttypes.h}, then @samp{$as_my_Header} 13975contains @samp{ac_cv_header_inttypes_h}. If this script is then run on a 13976platform where all three headers have been previously detected, the 13977output of the script will include: 13978 13979@smallexample 13980header stdint.h detected 13981header inttypes.h detected 13982header stdlib.h detected 13983@end smallexample 13984@end defmac 13985 13986@defmac AS_VAR_SET (@var{var}, @ovar{value}) 13987@asindex{VAR_SET} 13988Emit shell code to assign the contents of the polymorphic shell variable 13989@var{var} to the shell expansion of @var{value}. @var{value} is not 13990subject to field splitting or file name expansion, so if command 13991substitution is used, it may be done with @samp{`""`} rather than using 13992an intermediate variable (@pxref{Shell Substitutions}). However, 13993@var{value} does undergo rescanning for additional macro names; behavior 13994is unspecified if late expansion results in any shell meta-characters. 13995@end defmac 13996 13997@defmac AS_VAR_SET_IF (@var{var}, @ovar{if-set}, @ovar{if-undef}) 13998@asindex{VAR_SET_IF} 13999Emit a shell conditional statement, which executes @var{if-set} if the 14000polymorphic shell variable @code{var} is set to any value, and 14001@var{if-undef} otherwise. 14002@end defmac 14003 14004@defmac AS_VAR_TEST_SET (@var{var}) 14005@asindex{VAR_TEST_SET} 14006Emit a shell statement that results in a successful exit status only if 14007the polymorphic shell variable @code{var} is set. 14008@end defmac 14009 14010@node Initialization Macros 14011@section Initialization Macros 14012 14013@defmac AS_BOURNE_COMPATIBLE 14014@asindex{BOURNE_COMPATIBLE} 14015Set up the shell to be more compatible with the Bourne shell as 14016standardized by Posix, if possible. This may involve setting 14017environment variables, or setting options, or similar 14018implementation-specific actions. This macro is deprecated, since 14019@code{AS_INIT} already invokes it. 14020@end defmac 14021 14022@defmac AS_INIT 14023@asindex{INIT} 14024@evindex LC_ALL 14025@evindex SHELL 14026Initialize the M4sh environment. This macro calls @code{m4_init}, then 14027outputs the @code{#! /bin/sh} line, a notice about where the output was 14028generated from, and code to sanitize the environment for the rest of the 14029script. Among other initializations, this sets @env{SHELL} to the shell 14030chosen to run the script (@pxref{CONFIG_SHELL}), and @env{LC_ALL} to 14031ensure the C locale. Finally, it changes the current diversion to 14032@code{BODY}. @code{AS_INIT} is called automatically by @code{AC_INIT} 14033and @code{AT_INIT}, so shell code in @file{configure}, 14034@file{config.status}, and @file{testsuite} all benefit from a sanitized 14035shell environment. 14036@end defmac 14037 14038@defmac AS_INIT_GENERATED (@var{file}, @ovar{comment}) 14039@asindex{INIT_GENERATED} 14040Emit shell code to start the creation of a subsidiary shell script in 14041@var{file}, including changing @var{file} to be executable. This macro 14042populates the child script with information learned from the parent 14043(thus, the emitted code is equivalent in effect, but more efficient, 14044than the code output by @code{AS_INIT}, @code{AS_BOURNE_COMPATIBLE}, and 14045@code{AS_SHELL_SANITIZE}). If present, @var{comment} is output near the 14046beginning of the child, prior to the shell initialization code, and is 14047subject to parameter expansion, command substitution, and backslash 14048quote removal. The 14049parent script should check the exit status after this macro, in case 14050@var{file} could not be properly created (for example, if the disk was 14051full). If successfully created, the parent script can then proceed to 14052append additional M4sh constructs into the child script. 14053 14054Note that the child script starts life without a log file open, so if 14055the parent script uses logging (@pxref{AS_MESSAGE_LOG_FD}), you 14056must temporarily disable any attempts to use the log file until after 14057emitting code to open a log within the child. On the other hand, if the 14058parent script has @code{AS_MESSAGE_FD} redirected somewhere besides 14059@samp{1}, then the child script already has code that copies stdout to 14060that descriptor. Currently, the suggested 14061idiom for writing a M4sh shell script from within another script is: 14062 14063@example 14064AS_INIT_GENERATED([@var{file}], [[# My child script. 14065]]) || @{ AS_ECHO(["Failed to create child script"]); AS_EXIT; @} 14066m4_pushdef([AS_MESSAGE_LOG_FD])dnl 14067cat >> "@var{file}" <<\__EOF__ 14068# Code to initialize AS_MESSAGE_LOG_FD 14069m4_popdef([AS_MESSAGE_LOG_FD])dnl 14070# Additional code 14071__EOF__ 14072@end example 14073 14074This, however, may change in the future as the M4sh interface is 14075stabilized further. 14076 14077Also, be aware that use of @env{LINENO} within the child script may 14078report line numbers relative to their location in the parent script, 14079even when using @code{AS_LINENO_PREPARE}, if the parent script was 14080unable to locate a shell with working @env{LINENO} support. 14081@end defmac 14082 14083@defmac AS_LINENO_PREPARE 14084@asindex{LINENO_PREPARE} 14085@evindex LINENO 14086Find a shell that supports the special variable @env{LINENO}, which 14087contains the number of the currently executing line. This macro is 14088automatically invoked by @code{AC_INIT} in configure scripts. 14089@end defmac 14090 14091@defmac AS_ME_PREPARE 14092@asindex{ME_PREPARE} 14093Set up variable @env{as_me} to be the basename of the currently executing 14094script. This macro is automatically invoked by @code{AC_INIT} in 14095configure scripts. 14096@end defmac 14097 14098@defmac AS_TMPDIR (@var{prefix}, @dvar{dir, $@{TMPDIR:=/tmp@}}) 14099@asindex{TMPDIR} 14100@evindex TMPDIR 14101@ovindex tmp 14102Create, as safely as possible, a temporary sub-directory within 14103@var{dir} with a name starting with @var{prefix}. @var{prefix} should 14104be 2-4 characters, to make it slightly easier to identify the owner of 14105the directory. If @var{dir} is omitted, then the value of @env{TMPDIR} 14106will be used (defaulting to @samp{/tmp}). On success, the name of the 14107newly created directory is stored in the shell variable @code{tmp}. On 14108error, the script is aborted. 14109 14110Typically, this macro is coupled with some exit traps to delete the created 14111directory and its contents on exit or interrupt. However, there is a 14112slight window between when the directory is created and when the name is 14113actually known to the shell, so an interrupt at the right moment might 14114leave the temporary directory behind. Hence it is important to use a 14115@var{prefix} that makes it easier to determine if a leftover temporary 14116directory from an interrupted script is safe to delete. 14117 14118The use of the output variable @samp{$tmp} rather than something in the 14119@samp{as_} namespace is historical; it has the unfortunate consequence 14120that reusing this otherwise common name for any other purpose inside 14121your script has the potential to break any cleanup traps designed to 14122remove the temporary directory. 14123@end defmac 14124 14125@defmac AS_SHELL_SANITIZE 14126@asindex{SHELL_SANITIZE} 14127Initialize the shell suitably for @command{configure} scripts. This has 14128the effect of @code{AS_BOURNE_COMPATIBLE}, and sets some other 14129environment variables for predictable results from configuration tests. 14130For example, it sets @env{LC_ALL} to change to the default C locale. 14131@xref{Special Shell Variables}. This macro is deprecated, since 14132@code{AS_INIT} already invokes it. 14133@end defmac 14134 14135 14136@node File Descriptor Macros 14137@section File Descriptor Macros 14138@cindex input 14139@cindex standard input 14140@cindex file descriptors 14141@cindex descriptors 14142@cindex low-level output 14143@cindex output, low-level 14144 14145The following macros define file descriptors used to output messages 14146(or input values) from @file{configure} scripts. 14147For example: 14148 14149@example 14150echo "$wombats found" >&AS_MESSAGE_LOG_FD 14151echo 'Enter desired kangaroo count:' >&AS_MESSAGE_FD 14152read kangaroos <&AS_ORIGINAL_STDIN_FD` 14153@end example 14154 14155@noindent 14156However doing so is seldom needed, because Autoconf provides higher 14157level macros as described below. 14158 14159@defmac AS_MESSAGE_FD 14160@asindex{MESSAGE_FD} 14161The file descriptor for @samp{checking for...} messages and results. 14162By default, @code{AS_INIT} sets this to @samp{1} for standalone M4sh 14163clients. However, @code{AC_INIT} shuffles things around to another file 14164descriptor, in order to allow the @option{-q} option of 14165@command{configure} to choose whether messages should go to the script's 14166standard output or be discarded. 14167 14168If you want to display some messages, consider using one of the printing 14169macros (@pxref{Printing Messages}) instead. Copies of messages output 14170via these macros are also recorded in @file{config.log}. 14171@end defmac 14172 14173@anchor{AS_MESSAGE_LOG_FD} 14174@defmac AS_MESSAGE_LOG_FD 14175@asindex{MESSAGE_LOG_FD} 14176This must either be empty, or expand to a file descriptor for log 14177messages. By default, @code{AS_INIT} sets this macro to the empty 14178string for standalone M4sh clients, thus disabling logging. However, 14179@code{AC_INIT} shuffles things around so that both @command{configure} 14180and @command{config.status} use @file{config.log} for log messages. 14181Macros that run tools, like @code{AC_COMPILE_IFELSE} (@pxref{Running the 14182Compiler}), redirect all output to this descriptor. You may want to do 14183so if you develop such a low-level macro. 14184@end defmac 14185 14186@defmac AS_ORIGINAL_STDIN_FD 14187@asindex{ORIGINAL_STDIN_FD} 14188This must expand to a file descriptor for the original standard input. 14189By default, @code{AS_INIT} sets this macro to @samp{0} for standalone 14190M4sh clients. However, @code{AC_INIT} shuffles things around for 14191safety. 14192 14193When @command{configure} runs, it may accidentally execute an 14194interactive command that has the same name as the non-interactive meant 14195to be used or checked. If the standard input was the terminal, such 14196interactive programs would cause @command{configure} to stop, pending 14197some user input. Therefore @command{configure} redirects its standard 14198input from @file{/dev/null} during its initialization. This is not 14199normally a problem, since @command{configure} normally does not need 14200user input. 14201 14202In the extreme case where your @file{configure} script really needs to 14203obtain some values from the original standard input, you can read them 14204explicitly from @code{AS_ORIGINAL_STDIN_FD}. 14205@end defmac 14206 14207 14208@c =================================================== Writing Autoconf Macros. 14209 14210@node Writing Autoconf Macros 14211@chapter Writing Autoconf Macros 14212 14213When you write a feature test that could be applicable to more than one 14214software package, the best thing to do is encapsulate it in a new macro. 14215Here are some instructions and guidelines for writing Autoconf macros. 14216 14217@menu 14218* Macro Definitions:: Basic format of an Autoconf macro 14219* Macro Names:: What to call your new macros 14220* Reporting Messages:: Notifying @command{autoconf} users 14221* Dependencies Between Macros:: What to do when macros depend on other macros 14222* Obsoleting Macros:: Warning about old ways of doing things 14223* Coding Style:: Writing Autoconf macros @`a la Autoconf 14224@end menu 14225 14226@node Macro Definitions 14227@section Macro Definitions 14228 14229@defmac AC_DEFUN (@var{name}, @ovar{body}) 14230@acindex{DEFUN} 14231Autoconf macros are defined using the @code{AC_DEFUN} macro, which is 14232similar to the M4 builtin @code{m4_define} macro; this creates a macro 14233named @var{name} and with @var{body} as its expansion. In addition to 14234defining a macro, @code{AC_DEFUN} adds to it some code that is used to 14235constrain the order in which macros are called, while avoiding redundant 14236output (@pxref{Prerequisite Macros}). 14237@end defmac 14238 14239An Autoconf macro definition looks like this: 14240 14241@example 14242AC_DEFUN(@var{macro-name}, @var{macro-body}) 14243@end example 14244 14245You can refer to any arguments passed to the macro as @samp{$1}, 14246@samp{$2}, etc. @xref{Definitions, , How to define new macros, m4.info, 14247GNU M4}, for more complete information on writing M4 macros. 14248 14249Most macros fall in one of two general categories. The first category 14250includes macros which take arguments, in order to generate output 14251parameterized by those arguments. Macros in this category are designed 14252to be directly expanded, often multiple times, and should not be used as 14253the argument to @code{AC_REQUIRE}. The other category includes macros 14254which are shorthand for a fixed block of text, and therefore do not take 14255arguments. For this category of macros, directly expanding the macro 14256multiple times results in redundant output, so it is more common to use 14257the macro as the argument to @code{AC_REQUIRE}, or to declare the macro 14258with @code{AC_DEFUN_ONCE} (@pxref{One-Shot Macros}). 14259 14260Be sure to properly quote both the @var{macro-body} @emph{and} the 14261@var{macro-name} to avoid any problems if the macro happens to have 14262been previously defined. 14263 14264Each macro should have a header comment that gives its prototype, and a 14265brief description. When arguments have default values, display them in 14266the prototype. For example: 14267 14268@example 14269# AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1]) 14270# -------------------------------------- 14271m4_define([AC_MSG_ERROR], 14272 [@{ AS_MESSAGE([error: $1], [2]) 14273 exit m4_default([$2], [1]); @}]) 14274@end example 14275 14276Comments about the macro should be left in the header comment. Most 14277other comments make their way into @file{configure}, so just keep 14278using @samp{#} to introduce comments. 14279 14280@cindex @code{dnl} 14281If you have some special comments about pure M4 code, comments 14282that make no sense in @file{configure} and in the header comment, then 14283use the builtin @code{dnl}: it causes M4 to discard the text 14284through the next newline. 14285 14286Keep in mind that @code{dnl} is rarely needed to introduce comments; 14287@code{dnl} is more useful to get rid of the newlines following macros 14288that produce no output, such as @code{AC_REQUIRE}. 14289 14290Public third-party macros need to use @code{AC_DEFUN}, and not 14291@code{m4_define}, in order to be found by @command{aclocal} 14292(@pxref{Extending aclocal,,, automake, GNU Automake}). 14293Additionally, if it is ever determined that a macro should be made 14294obsolete, it is easy to convert from @code{AC_DEFUN} to @code{AU_DEFUN} 14295in order to have @command{autoupdate} assist the user in choosing a 14296better alternative, but there is no corresponding way to make 14297@code{m4_define} issue an upgrade notice (@pxref{AU_DEFUN}). 14298 14299There is another subtle, but important, difference between using 14300@code{m4_define} and @code{AC_DEFUN}: only the former is unaffected by 14301@code{AC_REQUIRE}. When writing a file, it is always safe to replace a 14302block of text with a @code{m4_define} macro that will expand to the same 14303text. But replacing a block of text with an @code{AC_DEFUN} macro with 14304the same content does not necessarily give the same results, because it 14305changes the location where any embedded but unsatisfied 14306@code{AC_REQUIRE} invocations within the block will be expanded. For an 14307example of this, see @ref{Expanded Before Required}. 14308 14309@node Macro Names 14310@section Macro Names 14311 14312All of the public Autoconf macros have all-uppercase names in the 14313namespace @samp{^AC_} to prevent them from accidentally conflicting with 14314other text; Autoconf also reserves the namespace @samp{^_AC_} for 14315internal macros. All shell variables that they use for internal 14316purposes have mostly-lowercase names starting with @samp{ac_}. Autoconf 14317also uses here-document delimiters in the namespace @samp{^_AC[A-Z]}. During 14318@command{configure}, files produced by Autoconf make heavy use of the 14319file system namespace @samp{^conf}. 14320 14321Since Autoconf is built on top of M4sugar (@pxref{Programming in 14322M4sugar}) and M4sh (@pxref{Programming in M4sh}), you must also be aware 14323of those namespaces (@samp{^_?\(m4\|AS\)_}). And since 14324@file{configure.ac} is also designed to be scanned by Autoheader, 14325Autoscan, Autoupdate, and Automake, you should be aware of the 14326@samp{^_?A[HNUM]_} namespaces. In general, you @emph{should not use} 14327the namespace of a package that does not own the macro or shell code you 14328are writing. 14329 14330To ensure that your macros don't conflict with present or future 14331Autoconf macros, you should prefix your own macro names and any shell 14332variables they use with some other sequence. Possibilities include your 14333initials, or an abbreviation for the name of your organization or 14334software package. Historically, people have not always followed the 14335rule of using a namespace appropriate for their package, and this has 14336made it difficult for determining the origin of a macro (and where to 14337report bugs about that macro), as well as difficult for the true 14338namespace owner to add new macros without interference from pre-existing 14339uses of third-party macros. Perhaps the best example of this confusion 14340is the @code{AM_GNU_GETTEXT} macro, which belongs, not to Automake, but 14341to Gettext. 14342 14343Most of the Autoconf macros' names follow a structured naming convention 14344that indicates the kind of feature check by the name. The macro names 14345consist of several words, separated by underscores, going from most 14346general to most specific. The names of their cache variables use the 14347same convention (@pxref{Cache Variable Names}, for more information on 14348them). 14349 14350The first word of the name after the namespace initials (such as 14351@samp{AC_}) usually tells the category 14352of the feature being tested. Here are the categories used in Autoconf for 14353specific test macros, the kind of macro that you are more likely to 14354write. They are also used for cache variables, in all-lowercase. Use 14355them where applicable; where they're not, invent your own categories. 14356 14357@table @code 14358@item C 14359C language builtin features. 14360@item DECL 14361Declarations of C variables in header files. 14362@item FUNC 14363Functions in libraries. 14364@item GROUP 14365Posix group owners of files. 14366@item HEADER 14367Header files. 14368@item LIB 14369C libraries. 14370@item PROG 14371The base names of programs. 14372@item MEMBER 14373Members of aggregates. 14374@item SYS 14375Operating system features. 14376@item TYPE 14377C builtin or declared types. 14378@item VAR 14379C variables in libraries. 14380@end table 14381 14382After the category comes the name of the particular feature being 14383tested. Any further words in the macro name indicate particular aspects 14384of the feature. For example, @code{AC_PROG_CC_STDC} checks whether the 14385C compiler supports ISO Standard C. 14386 14387An internal macro should have a name that starts with an underscore; 14388Autoconf internals should therefore start with @samp{_AC_}. 14389Additionally, a macro that is an internal subroutine of another macro 14390should have a name that starts with an underscore and the name of that 14391other macro, followed by one or more words saying what the internal 14392macro does. For example, @code{AC_PATH_X} has internal macros 14393@code{_AC_PATH_X_XMKMF} and @code{_AC_PATH_X_DIRECT}. 14394 14395@node Reporting Messages 14396@section Reporting Messages 14397@cindex Messages, from @command{autoconf} 14398 14399When macros statically diagnose abnormal situations, benign or fatal, it 14400is possible to make @command{autoconf} detect the problem, and refuse to 14401create @file{configure} in the case of an error. The macros in this 14402section are considered obsolescent, and new code should use M4sugar 14403macros for this purpose, see @ref{Diagnostic Macros}. 14404 14405On the other hand, it is possible to want to detect errors when 14406@command{configure} is run, which are dependent on the environment of 14407the user rather than the maintainer. For dynamic diagnostics, see 14408@ref{Printing Messages}. 14409 14410@defmac AC_DIAGNOSE (@var{category}, @var{message}) 14411@acindex{DIAGNOSE} 14412Report @var{message} as a warning (or as an error if requested by the 14413user) if warnings of the @var{category} are turned on. This macro is 14414obsolescent; you are encouraged to use: 14415@example 14416m4_warn([@var{category}], [@var{message}]) 14417@end example 14418@noindent 14419instead. @xref{m4_warn}, for more details, including valid 14420@var{category} names. 14421@end defmac 14422 14423@defmac AC_WARNING (@var{message}) 14424@acindex{WARNING} 14425Report @var{message} as a syntax warning. This macro is obsolescent; 14426you are encouraged to use: 14427@example 14428m4_warn([syntax], [@var{message}]) 14429@end example 14430@noindent 14431instead. @xref{m4_warn}, for more details, as well as better 14432finer-grained categories of warnings (not all problems have to do with 14433syntax). 14434@end defmac 14435 14436@defmac AC_FATAL (@var{message}) 14437@acindex{FATAL} 14438Report a severe error @var{message}, and have @command{autoconf} die. 14439This macro is obsolescent; you are encouraged to use: 14440@example 14441m4_fatal([@var{message}]) 14442@end example 14443@noindent 14444instead. @xref{m4_fatal}, for more details. 14445@end defmac 14446 14447When the user runs @samp{autoconf -W error}, warnings from 14448@code{m4_warn} (including those issued through @code{AC_DIAGNOSE} and 14449@code{AC_WARNING}) are reported as errors, see @ref{autoconf Invocation}. 14450 14451@node Dependencies Between Macros 14452@section Dependencies Between Macros 14453@cindex Dependencies between macros 14454 14455Some Autoconf macros depend on other macros having been called first in 14456order to work correctly. Autoconf provides a way to ensure that certain 14457macros are called if needed and a way to warn the user if macros are 14458called in an order that might cause incorrect operation. 14459 14460@menu 14461* Prerequisite Macros:: Ensuring required information 14462* Suggested Ordering:: Warning about possible ordering problems 14463* One-Shot Macros:: Ensuring a macro is called only once 14464@end menu 14465 14466@node Prerequisite Macros 14467@subsection Prerequisite Macros 14468@cindex Prerequisite macros 14469@cindex Macros, prerequisites 14470 14471A macro that you write might need to use values that have previously 14472been computed by other macros. For example, @code{AC_DECL_YYTEXT} 14473examines the output of @code{flex} or @code{lex}, so it depends on 14474@code{AC_PROG_LEX} having been called first to set the shell variable 14475@code{LEX}. 14476 14477Rather than forcing the user of the macros to keep track of the 14478dependencies between them, you can use the @code{AC_REQUIRE} macro to do 14479it automatically. @code{AC_REQUIRE} can ensure that a macro is only 14480called if it is needed, and only called once. 14481 14482@defmac AC_REQUIRE (@var{macro-name}) 14483@acindex{REQUIRE} 14484If the M4 macro @var{macro-name} has not already been called, call it 14485(without any arguments). Make sure to quote @var{macro-name} with 14486square brackets. @var{macro-name} must have been defined using 14487@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate 14488that it has been called. 14489 14490@code{AC_REQUIRE} must be used inside a macro defined by @code{AC_DEFUN}; it 14491must not be called from the top level. Also, it does not make sense to 14492require a macro that takes parameters. 14493@end defmac 14494 14495@code{AC_REQUIRE} is often misunderstood. It really implements 14496dependencies between macros in the sense that if one macro depends upon 14497another, the latter is expanded @emph{before} the body of the 14498former. To be more precise, the required macro is expanded before 14499the outermost defined macro in the current expansion stack. 14500In particular, @samp{AC_REQUIRE([FOO])} is not replaced with the body of 14501@code{FOO}. For instance, this definition of macros: 14502 14503@example 14504@group 14505AC_DEFUN([TRAVOLTA], 14506[test "$body_temperature_in_celsius" -gt "38" && 14507 dance_floor=occupied]) 14508AC_DEFUN([NEWTON_JOHN], 14509[test "x$hair_style" = xcurly && 14510 dance_floor=occupied]) 14511@end group 14512 14513@group 14514AC_DEFUN([RESERVE_DANCE_FLOOR], 14515[if date | grep '^Sat.*pm' >/dev/null 2>&1; then 14516 AC_REQUIRE([TRAVOLTA]) 14517 AC_REQUIRE([NEWTON_JOHN]) 14518fi]) 14519@end group 14520@end example 14521 14522@noindent 14523with this @file{configure.ac} 14524 14525@example 14526AC_INIT([Dance Manager], [1.0], [bug-dance@@example.org]) 14527RESERVE_DANCE_FLOOR 14528if test "x$dance_floor" = xoccupied; then 14529 AC_MSG_ERROR([cannot pick up here, let's move]) 14530fi 14531@end example 14532 14533@noindent 14534does not leave you with a better chance to meet a kindred soul at 14535other times than Saturday night since it expands into: 14536 14537@example 14538@group 14539test "$body_temperature_in_Celsius" -gt "38" && 14540 dance_floor=occupied 14541test "x$hair_style" = xcurly && 14542 dance_floor=occupied 14543fi 14544if date | grep '^Sat.*pm' >/dev/null 2>&1; then 14545 14546 14547fi 14548@end group 14549@end example 14550 14551This behavior was chosen on purpose: (i) it prevents messages in 14552required macros from interrupting the messages in the requiring macros; 14553(ii) it avoids bad surprises when shell conditionals are used, as in: 14554 14555@example 14556@group 14557if @dots{}; then 14558 AC_REQUIRE([SOME_CHECK]) 14559fi 14560@dots{} 14561SOME_CHECK 14562@end group 14563@end example 14564 14565However, this implementation can lead to another class of problems. 14566Consider the case where an outer macro first expands, then indirectly 14567requires, an inner macro: 14568 14569@example 14570AC_DEFUN([TESTA], [[echo in A 14571if test -n "$SEEN_A" ; then echo duplicate ; fi 14572SEEN_A=:]]) 14573AC_DEFUN([TESTB], [AC_REQUIRE([TESTA])[echo in B 14574if test -z "$SEEN_A" ; then echo bug ; fi]]) 14575AC_DEFUN([TESTC], [AC_REQUIRE([TESTB])[echo in C]]) 14576AC_DEFUN([OUTER], [[echo in OUTER] 14577TESTA 14578TESTC]) 14579OUTER 14580@end example 14581 14582@noindent 14583Prior to Autoconf 2.64, the implementation of @code{AC_REQUIRE} 14584recognized that @code{TESTB} needed to be hoisted prior to the expansion 14585of @code{OUTER}, but because @code{TESTA} had already been directly 14586expanded, it failed to hoist @code{TESTA}. Therefore, the expansion of 14587@code{TESTB} occurs prior to its prerequisites, leading to the following 14588output: 14589 14590@example 14591in B 14592bug 14593in OUTER 14594in A 14595in C 14596@end example 14597 14598@noindent 14599Newer Autoconf is smart enough to recognize this situation, and hoists 14600@code{TESTA} even though it has already been expanded, but issues a 14601syntax warning in the process. This is because the hoisted expansion of 14602@code{TESTA} defeats the purpose of using @code{AC_REQUIRE} to avoid 14603redundant code, and causes its own set of problems if the hoisted macro 14604is not idempotent: 14605 14606@example 14607in A 14608in B 14609in OUTER 14610in A 14611duplicate 14612in C 14613@end example 14614 14615The bug is not in Autoconf, but in the macro definitions. If you ever 14616pass a particular macro name to @code{AC_REQUIRE}, then you are implying 14617that the macro only needs to be expanded once. But to enforce this, 14618either the macro must be declared with @code{AC_DEFUN_ONCE} (although 14619this only helps in Autoconf 2.64 or newer), or all 14620uses of that macro should be through @code{AC_REQUIRE}; directly 14621expanding the macro defeats the point of using @code{AC_REQUIRE} to 14622eliminate redundant expansion. In the example, this rule of thumb was 14623violated because @code{TESTB} requires @code{TESTA} while @code{OUTER} 14624directly expands it. One way of fixing the bug is to factor 14625@code{TESTA} into two macros, the portion designed for direct and 14626repeated use (here, named @code{TESTA}), and the portion designed for 14627one-shot output and used only inside @code{AC_REQUIRE} (here, named 14628@code{TESTA_PREREQ}). Then, by fixing all clients to use the correct 14629calling convention according to their needs: 14630 14631@example 14632AC_DEFUN([TESTA], [AC_REQUIRE([TESTA_PREREQ])[echo in A]]) 14633AC_DEFUN([TESTA_PREREQ], [[echo in A_PREREQ 14634if test -n "$SEEN_A" ; then echo duplicate ; fi 14635SEEN_A=:]]) 14636AC_DEFUN([TESTB], [AC_REQUIRE([TESTA_PREREQ])[echo in B 14637if test -z "$SEEN_A" ; then echo bug ; fi]]) 14638AC_DEFUN([TESTC], [AC_REQUIRE([TESTB])[echo in C]]) 14639AC_DEFUN([OUTER], [[echo in OUTER] 14640TESTA 14641TESTC]) 14642OUTER 14643@end example 14644 14645@noindent 14646the resulting output will then obey all dependency rules and avoid any 14647syntax warnings, whether the script is built with old or new Autoconf 14648versions: 14649 14650@example 14651in A_PREREQ 14652in B 14653in OUTER 14654in A 14655in C 14656@end example 14657 14658The helper macros @code{AS_IF} and @code{AS_CASE} may be used to 14659enforce expansion of required macros outside of shell conditional 14660constructs. You are furthermore encouraged, although not required, to 14661put all @code{AC_REQUIRE} calls 14662at the beginning of a macro. You can use @code{dnl} to avoid the empty 14663lines they leave. 14664 14665@node Suggested Ordering 14666@subsection Suggested Ordering 14667@cindex Macros, ordering 14668@cindex Ordering macros 14669 14670Some macros should be run before another macro if both are called, but 14671neither @emph{requires} that the other be called. For example, a macro 14672that changes the behavior of the C compiler should be called before any 14673macros that run the C compiler. Many of these dependencies are noted in 14674the documentation. 14675 14676Autoconf provides the @code{AC_BEFORE} macro to warn users when macros 14677with this kind of dependency appear out of order in a 14678@file{configure.ac} file. The warning occurs when creating 14679@command{configure} from @file{configure.ac}, not when running 14680@command{configure}. 14681 14682For example, @code{AC_PROG_CPP} checks whether the C compiler 14683can run the C preprocessor when given the @option{-E} option. It should 14684therefore be called after any macros that change which C compiler is 14685being used, such as @code{AC_PROG_CC}. So @code{AC_PROG_CC} contains: 14686 14687@example 14688AC_BEFORE([$0], [AC_PROG_CPP])dnl 14689@end example 14690 14691@noindent 14692This warns the user if a call to @code{AC_PROG_CPP} has already occurred 14693when @code{AC_PROG_CC} is called. 14694 14695@defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name}) 14696@acindex{BEFORE} 14697Make M4 print a warning message to the standard error output if 14698@var{called-macro-name} has already been called. @var{this-macro-name} 14699should be the name of the macro that is calling @code{AC_BEFORE}. The 14700macro @var{called-macro-name} must have been defined using 14701@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate 14702that it has been called. 14703@end defmac 14704 14705@node One-Shot Macros 14706@subsection One-Shot Macros 14707@cindex One-shot macros 14708@cindex Macros, called once 14709 14710Some macros should be called only once, either because calling them 14711multiple time is unsafe, or because it is bad style. For instance 14712Autoconf ensures that @code{AC_CANONICAL_BUILD} and cousins 14713(@pxref{Canonicalizing}) are evaluated only once, because it makes no 14714sense to run these expensive checks more than once. Such one-shot 14715macros can be defined using @code{AC_DEFUN_ONCE}. 14716 14717@defmac AC_DEFUN_ONCE (@var{macro-name}, @var{macro-body}) 14718@acindex{DEFUN_ONCE} 14719Declare macro @var{macro-name} like @code{AC_DEFUN} would (@pxref{Macro 14720Definitions}), but add additional logic that guarantees that only the 14721first use of the macro (whether by direct expansion or 14722@code{AC_REQUIRE}) causes an expansion of @var{macro-body}; the 14723expansion will occur before the start of any enclosing macro defined by 14724@code{AC_DEFUN}. Subsequent expansions are silently ignored. 14725Generally, it does not make sense for @var{macro-body} to use parameters 14726such as @code{$1}. 14727@end defmac 14728 14729Prior to Autoconf 2.64, a macro defined by @code{AC_DEFUN_ONCE} would 14730emit a warning if it was directly expanded a second time, so for 14731portability, it is better to use @code{AC_REQUIRE} than direct 14732invocation of @var{macro-name} inside a macro defined by @code{AC_DEFUN} 14733(@pxref{Prerequisite Macros}). 14734 14735@node Obsoleting Macros 14736@section Obsoleting Macros 14737@cindex Obsoleting macros 14738@cindex Macros, obsoleting 14739 14740Configuration and portability technology has evolved over the years. 14741Often better ways of solving a particular problem are developed, or 14742ad-hoc approaches are systematized. This process has occurred in many 14743parts of Autoconf. One result is that some of the macros are now 14744considered @dfn{obsolete}; they still work, but are no longer considered 14745the best thing to do, hence they should be replaced with more modern 14746macros. Ideally, @command{autoupdate} should replace the old macro calls 14747with their modern implementation. 14748 14749Autoconf provides a simple means to obsolete a macro. 14750 14751@anchor{AU_DEFUN} 14752@defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message}) 14753@auindex{DEFUN} 14754Define @var{old-macro} as @var{implementation}. The only difference 14755with @code{AC_DEFUN} is that the user is warned that 14756@var{old-macro} is now obsolete. 14757 14758If she then uses @command{autoupdate}, the call to @var{old-macro} is 14759replaced by the modern @var{implementation}. @var{message} should 14760include information on what to do after running @command{autoupdate}; 14761@command{autoupdate} prints it as a warning, and includes it 14762in the updated @file{configure.ac} file. 14763 14764The details of this macro are hairy: if @command{autoconf} encounters an 14765@code{AU_DEFUN}ed macro, all macros inside its second argument are expanded 14766as usual. However, when @command{autoupdate} is run, only M4 and M4sugar 14767macros are expanded here, while all other macros are disabled and 14768appear literally in the updated @file{configure.ac}. 14769@end defmac 14770 14771@defmac AU_ALIAS (@var{old-name}, @var{new-name}) 14772@auindex{ALIAS} 14773Used if the @var{old-name} is to be replaced by a call to @var{new-macro} 14774with the same parameters. This happens for example if the macro was renamed. 14775@end defmac 14776 14777@node Coding Style 14778@section Coding Style 14779@cindex Coding style 14780 14781The Autoconf macros follow a strict coding style. You are encouraged to 14782follow this style, especially if you intend to distribute your macro, 14783either by contributing it to Autoconf itself or the 14784@uref{http://@/www.gnu.org/@/software/@/autoconf-archive/, Autoconf Macro 14785Archive}, or by other means. 14786 14787The first requirement is to pay great attention to the quotation. For 14788more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}. 14789 14790Do not try to invent new interfaces. It is likely that there is a macro 14791in Autoconf that resembles the macro you are defining: try to stick to 14792this existing interface (order of arguments, default values, etc.). We 14793@emph{are} conscious that some of these interfaces are not perfect; 14794nevertheless, when harmless, homogeneity should be preferred over 14795creativity. 14796 14797Be careful about clashes both between M4 symbols and between shell 14798variables. 14799 14800If you stick to the suggested M4 naming scheme (@pxref{Macro Names}), 14801you are unlikely to generate conflicts. Nevertheless, when you need to 14802set a special value, @emph{avoid using a regular macro name}; rather, 14803use an ``impossible'' name. For instance, up to version 2.13, the macro 14804@code{AC_SUBST} used to remember what @var{symbol} macros were already defined 14805by setting @code{AC_SUBST_@var{symbol}}, which is a regular macro name. 14806But since there is a macro named @code{AC_SUBST_FILE}, it was just 14807impossible to @samp{AC_SUBST(FILE)}! In this case, 14808@code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should 14809have been used (yes, with the parentheses). 14810@c or better yet, high-level macros such as @code{m4_expand_once} 14811 14812No Autoconf macro should ever enter the user-variable name space; i.e., 14813except for the variables that are the actual result of running the 14814macro, all shell variables should start with @code{ac_}. In 14815addition, small macros or any macro that is likely to be embedded in 14816other macros should be careful not to use obvious names. 14817 14818@cindex @code{dnl} 14819Do not use @code{dnl} to introduce comments: most of the comments you 14820are likely to write are either header comments which are not output 14821anyway, or comments that should make their way into @file{configure}. 14822There are exceptional cases where you do want to comment special M4 14823constructs, in which case @code{dnl} is right, but keep in mind that it 14824is unlikely. 14825 14826M4 ignores the leading blanks and newlines before each argument. 14827Use this feature to 14828indent in such a way that arguments are (more or less) aligned with the 14829opening parenthesis of the macro being called. For instance, instead of 14830 14831@example 14832AC_CACHE_CHECK(for EMX OS/2 environment, 14833ac_cv_emxos2, 14834[AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])], 14835[ac_cv_emxos2=yes], [ac_cv_emxos2=no])]) 14836@end example 14837 14838@noindent 14839write 14840 14841@example 14842AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2], 14843[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])], 14844 [ac_cv_emxos2=yes], 14845 [ac_cv_emxos2=no])]) 14846@end example 14847 14848@noindent 14849or even 14850 14851@example 14852AC_CACHE_CHECK([for EMX OS/2 environment], 14853 [ac_cv_emxos2], 14854 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], 14855 [return __EMX__;])], 14856 [ac_cv_emxos2=yes], 14857 [ac_cv_emxos2=no])]) 14858@end example 14859 14860When using @code{AC_RUN_IFELSE} or any macro that cannot work when 14861cross-compiling, provide a pessimistic value (typically @samp{no}). 14862 14863Feel free to use various tricks to prevent auxiliary tools, such as 14864syntax-highlighting editors, from behaving improperly. For instance, 14865instead of: 14866 14867@example 14868m4_bpatsubst([$1], [$"]) 14869@end example 14870 14871@noindent 14872use 14873 14874@example 14875m4_bpatsubst([$1], [$""]) 14876@end example 14877 14878@noindent 14879so that Emacsen do not open an endless ``string'' at the first quote. 14880For the same reasons, avoid: 14881 14882@example 14883test $[#] != 0 14884@end example 14885 14886@noindent 14887and use: 14888 14889@example 14890test $[@@%:@@] != 0 14891@end example 14892 14893@noindent 14894Otherwise, the closing bracket would be hidden inside a @samp{#}-comment, 14895breaking the bracket-matching highlighting from Emacsen. Note the 14896preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]}, etc. Do 14897not escape when it is unnecessary. Common examples of useless quotation 14898are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}), 14899etc. If you add portability issues to the picture, you'll prefer 14900@samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something 14901better than hacking Autoconf @code{:-)}. 14902 14903When using @command{sed}, don't use @option{-e} except for indenting 14904purposes. With the @code{s} and @code{y} commands, the preferred 14905separator is @samp{/} unless @samp{/} itself might appear in the pattern 14906or replacement, in which case you should use @samp{|}, or optionally 14907@samp{,} if you know the pattern and replacement cannot contain a file 14908name. If none of these characters will do, choose a printable character 14909that cannot appear in the pattern or replacement. Characters from the 14910set @samp{"#$&'()*;<=>?`|~} are good choices if the pattern or 14911replacement might contain a file name, since they have special meaning 14912to the shell and are less likely to occur in file names. 14913 14914@xref{Macro Definitions}, for details on how to define a macro. If a 14915macro doesn't use @code{AC_REQUIRE}, is expected to never be the object 14916of an @code{AC_REQUIRE} directive, and macros required by other macros 14917inside arguments do not need to be expanded before this macro, then 14918use @code{m4_define}. In case of doubt, use @code{AC_DEFUN}. 14919Also take into account that public third-party macros need to use 14920@code{AC_DEFUN} in order to be found by @command{aclocal} 14921(@pxref{Extending aclocal,,, automake, GNU Automake}). 14922All the @code{AC_REQUIRE} statements should be at the beginning of the 14923macro, and each statement should be followed by @code{dnl}. 14924 14925You should not rely on the number of arguments: instead of checking 14926whether an argument is missing, test that it is not empty. It provides 14927both a simpler and a more predictable interface to the user, and saves 14928room for further arguments. 14929 14930Unless the macro is short, try to leave the closing @samp{])} at the 14931beginning of a line, followed by a comment that repeats the name of the 14932macro being defined. This introduces an additional newline in 14933@command{configure}; normally, that is not a problem, but if you want to 14934remove it you can use @samp{[]dnl} on the last line. You can similarly 14935use @samp{[]dnl} after a macro call to remove its newline. @samp{[]dnl} 14936is recommended instead of @samp{dnl} to ensure that M4 does not 14937interpret the @samp{dnl} as being attached to the preceding text or 14938macro output. For example, instead of: 14939 14940@example 14941AC_DEFUN([AC_PATH_X], 14942[AC_MSG_CHECKING([for X]) 14943AC_REQUIRE_CPP() 14944@r{# @dots{}omitted@dots{}} 14945 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes]) 14946fi]) 14947@end example 14948 14949@noindent 14950you would write: 14951 14952@example 14953AC_DEFUN([AC_PATH_X], 14954[AC_REQUIRE_CPP()[]dnl 14955AC_MSG_CHECKING([for X]) 14956@r{# @dots{}omitted@dots{}} 14957 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes]) 14958fi[]dnl 14959])# AC_PATH_X 14960@end example 14961 14962If the macro is long, try to split it into logical chunks. Typically, 14963macros that check for a bug in a function and prepare its 14964@code{AC_LIBOBJ} replacement should have an auxiliary macro to perform 14965this setup. Do not hesitate to introduce auxiliary macros to factor 14966your code. 14967 14968In order to highlight the recommended coding style, here is a macro 14969written the old way: 14970 14971@example 14972dnl Check for EMX on OS/2. 14973dnl _AC_EMXOS2 14974AC_DEFUN(_AC_EMXOS2, 14975[AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2, 14976[AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)], 14977ac_cv_emxos2=yes, ac_cv_emxos2=no)]) 14978test "x$ac_cv_emxos2" = xyes && EMXOS2=yes]) 14979@end example 14980 14981@noindent 14982and the new way: 14983 14984@example 14985# _AC_EMXOS2 14986# ---------- 14987# Check for EMX on OS/2. 14988m4_define([_AC_EMXOS2], 14989[AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2], 14990[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])], 14991 [ac_cv_emxos2=yes], 14992 [ac_cv_emxos2=no])]) 14993test "x$ac_cv_emxos2" = xyes && EMXOS2=yes[]dnl 14994])# _AC_EMXOS2 14995@end example 14996 14997 14998 14999 15000@c ============================================= Portable Shell Programming 15001 15002@node Portable Shell 15003@chapter Portable Shell Programming 15004@cindex Portable shell programming 15005 15006When writing your own checks, there are some shell-script programming 15007techniques you should avoid in order to make your code portable. The 15008Bourne shell and upward-compatible shells like the Korn shell and Bash 15009have evolved over the years, and many features added to the original 15010System7 shell are now supported on all interesting porting targets. 15011However, the following discussion between Russ Allbery and Robert Lipe 15012is worth reading: 15013 15014@noindent 15015Russ Allbery: 15016 15017@quotation 15018The GNU assumption that @command{/bin/sh} is the one and only shell 15019leads to a permanent deadlock. Vendors don't want to break users' 15020existing shell scripts, and there are some corner cases in the Bourne 15021shell that are not completely compatible with a Posix shell. Thus, 15022vendors who have taken this route will @emph{never} (OK@dots{}``never say 15023never'') replace the Bourne shell (as @command{/bin/sh}) with a 15024Posix shell. 15025@end quotation 15026 15027@noindent 15028Robert Lipe: 15029 15030@quotation 15031This is exactly the problem. While most (at least most System V's) do 15032have a Bourne shell that accepts shell functions most vendor 15033@command{/bin/sh} programs are not the Posix shell. 15034 15035So while most modern systems do have a shell @emph{somewhere} that meets the 15036Posix standard, the challenge is to find it. 15037@end quotation 15038 15039For this reason, part of the job of M4sh (@pxref{Programming in M4sh}) 15040is to find such a shell. But to prevent trouble, if you're not using 15041M4sh you should not take advantage of features that were added after Unix 15042version 7, circa 1977 (@pxref{Systemology}); you should not use aliases, 15043negated character classes, or even @command{unset}. @code{#} comments, 15044while not in Unix version 7, were retrofitted in the original Bourne 15045shell and can be assumed to be part of the least common denominator. 15046 15047On the other hand, if you're using M4sh you can assume that the shell 15048has the features that were added in SVR2 (circa 1984), including shell 15049functions, 15050@command{return}, @command{unset}, and I/O redirection for builtins. For 15051more information, refer to @uref{http://@/www.in-ulm.de/@/~mascheck/@/bourne/}. 15052However, some pitfalls have to be avoided for portable use of these 15053constructs; these will be documented in the rest of this chapter. 15054See in particular @ref{Shell Functions} and @ref{Limitations of 15055Builtins, , Limitations of Shell Builtins}. 15056 15057Some ancient systems have quite 15058small limits on the length of the @samp{#!} line; for instance, 32 15059bytes (not including the newline) on SunOS 4. 15060However, these ancient systems are no longer of practical concern. 15061 15062The set of external programs you should run in a @command{configure} script 15063is fairly small. @xref{Utilities in Makefiles, , Utilities in 15064Makefiles, standards, The GNU Coding Standards}, for the list. This 15065restriction allows users to start out with a fairly small set of 15066programs and build the rest, avoiding too many interdependencies between 15067packages. 15068 15069Some of these external utilities have a portable subset of features; see 15070@ref{Limitations of Usual Tools}. 15071 15072There are other sources of documentation about shells. The 15073specification for the Posix 15074@uref{http://@/www.opengroup.org/@/susv3/@/utilities/@/xcu_chap02@/.html, Shell 15075Command Language}, though more generous than the restrictive shell 15076subset described above, is fairly portable nowadays. Also please see 15077@uref{http://@/www.faqs.org/@/faqs/@/unix-faq/@/shell/, the Shell FAQs}. 15078 15079@menu 15080* Shellology:: A zoology of shells 15081* Invoking the Shell:: Invoking the shell as a command 15082* Here-Documents:: Quirks and tricks 15083* File Descriptors:: FDs and redirections 15084* Signal Handling:: Shells, signals, and headaches 15085* File System Conventions:: File names 15086* Shell Pattern Matching:: Pattern matching 15087* Shell Substitutions:: Variable and command expansions 15088* Assignments:: Varying side effects of assignments 15089* Parentheses:: Parentheses in shell scripts 15090* Slashes:: Slashes in shell scripts 15091* Special Shell Variables:: Variables you should not change 15092* Shell Functions:: What to look out for if you use them 15093* Limitations of Builtins:: Portable use of not so portable /bin/sh 15094* Limitations of Usual Tools:: Portable use of portable tools 15095@end menu 15096 15097@node Shellology 15098@section Shellology 15099@cindex Shellology 15100 15101There are several families of shells, most prominently the Bourne family 15102and the C shell family which are deeply incompatible. If you want to 15103write portable shell scripts, avoid members of the C shell family. The 15104@uref{http://@/www.faqs.org/@/faqs/@/unix-faq/@/shell/@/shell-differences/, the 15105Shell difference FAQ} includes a small history of Posix shells, and a 15106comparison between several of them. 15107 15108Below we describe some of the members of the Bourne shell family. 15109 15110@table @asis 15111@item Ash 15112@cindex Ash 15113Ash is often used on GNU/Linux and BSD 15114systems as a light-weight Bourne-compatible shell. Ash 0.2 has some 15115bugs that are fixed in the 0.3.x series, but portable shell scripts 15116should work around them, since version 0.2 is still shipped with many 15117GNU/Linux distributions. 15118 15119To be compatible with Ash 0.2: 15120 15121@itemize @minus 15122@item 15123don't use @samp{$?} after expanding empty or unset variables, 15124or at the start of an @command{eval}: 15125 15126@example 15127foo= 15128false 15129$foo 15130echo "Do not use it: $?" 15131false 15132eval 'echo "Do not use it: $?"' 15133@end example 15134 15135@item 15136don't use command substitution within variable expansion: 15137 15138@example 15139cat $@{FOO=`bar`@} 15140@end example 15141 15142@item 15143beware that single builtin substitutions are not performed by a 15144subshell, hence their effect applies to the current shell! @xref{Shell 15145Substitutions}, item ``Command Substitution''. 15146@end itemize 15147 15148@item Bash 15149@cindex Bash 15150To detect whether you are running Bash, test whether 15151@code{BASH_VERSION} is set. To require 15152Posix compatibility, run @samp{set -o posix}. @xref{Bash POSIX 15153Mode, , Bash Posix Mode, bash, The GNU Bash Reference 15154Manual}, for details. 15155 15156@item Bash 2.05 and later 15157@cindex Bash 2.05 and later 15158Versions 2.05 and later of Bash use a different format for the 15159output of the @command{set} builtin, designed to make evaluating its 15160output easier. However, this output is not compatible with earlier 15161versions of Bash (or with many other shells, probably). So if 15162you use Bash 2.05 or higher to execute @command{configure}, 15163you'll need to use Bash 2.05 for all other build tasks as well. 15164 15165@item Ksh 15166@cindex Ksh 15167@cindex Korn shell 15168@prindex @samp{ksh} 15169@prindex @samp{ksh88} 15170@prindex @samp{ksh93} 15171The Korn shell is compatible with the Bourne family and it mostly 15172conforms to Posix. It has two major variants commonly 15173called @samp{ksh88} and @samp{ksh93}, named after the years of initial 15174release. It is usually called @command{ksh}, but is called @command{sh} 15175on some hosts if you set your path appropriately. 15176 15177Solaris systems have three variants: 15178@prindex @command{/usr/bin/ksh} on Solaris 15179@command{/usr/bin/ksh} is @samp{ksh88}; it is 15180standard on Solaris 2.0 and later. 15181@prindex @command{/usr/xpg4/bin/sh} on Solaris 15182@command{/usr/xpg4/bin/sh} is a Posix-compliant variant of 15183@samp{ksh88}; it is standard on Solaris 9 and later. 15184@prindex @command{/usr/dt/bin/dtksh} on Solaris 15185@command{/usr/dt/bin/dtksh} is @samp{ksh93}. 15186Variants that are not standard may be parts of optional 15187packages. There is no extra charge for these packages, but they are 15188not part of a minimal OS install and therefore some installations may 15189not have it. 15190 15191Starting with Tru64 Version 4.0, the Korn shell @command{/usr/bin/ksh} 15192is also available as @command{/usr/bin/posix/sh}. If the environment 15193variable @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of 15194the standard shell conform to Posix. 15195 15196@item Pdksh 15197@prindex @samp{pdksh} 15198A public-domain clone of the Korn shell called @command{pdksh} is widely 15199available: it has most of the @samp{ksh88} features along with a few of 15200its own. It usually sets @code{KSH_VERSION}, except if invoked as 15201@command{/bin/sh} on OpenBSD, and similarly to Bash you can require 15202Posix compatibility by running @samp{set -o posix}. Unfortunately, with 15203@command{pdksh} 5.2.14 (the latest stable version as of January 2007) 15204Posix mode is buggy and causes @command{pdksh} to depart from Posix in 15205at least one respect, see @ref{Shell Substitutions}. 15206 15207@item Zsh 15208@cindex Zsh 15209To detect whether you are running @command{zsh}, test whether 15210@code{ZSH_VERSION} is set. By default @command{zsh} is @emph{not} 15211compatible with the Bourne shell: you must execute @samp{emulate sh}, 15212and for @command{zsh} versions before 3.1.6-dev-18 you must also 15213set @code{NULLCMD} to @samp{:}. @xref{Compatibility, , Compatibility, 15214zsh, The Z Shell Manual}, for details. 15215 15216The default Mac OS X @command{sh} was originally Zsh; it was changed to 15217Bash in Mac OS X 10.2. 15218@end table 15219 15220@node Invoking the Shell 15221@section Invoking the Shell 15222@cindex invoking the shell 15223@cindex shell invocation 15224 15225The Korn shell (up to at least version M-12/28/93d) has a bug when 15226invoked on a file whose name does not contain a slash. It first 15227searches for the file's name in @env{PATH}, and if found it executes 15228that rather than the original file. For example, assuming there is a 15229binary executable @file{/usr/bin/script} in your @env{PATH}, the last 15230command in the following example fails because the Korn shell finds 15231@file{/usr/bin/script} and refuses to execute it as a shell script: 15232 15233@example 15234$ @kbd{touch xxyzzyz script} 15235$ @kbd{ksh xxyzzyz} 15236$ @kbd{ksh ./script} 15237$ @kbd{ksh script} 15238ksh: script: cannot execute 15239@end example 15240 15241Bash 2.03 has a bug when invoked with the @option{-c} option: if the 15242option-argument ends in backslash-newline, Bash incorrectly reports a 15243syntax error. The problem does not occur if a character follows the 15244backslash: 15245 15246@example 15247$ @kbd{$ bash -c 'echo foo \} 15248> @kbd{'} 15249bash: -c: line 2: syntax error: unexpected end of file 15250$ @kbd{bash -c 'echo foo \} 15251> @kbd{ '} 15252foo 15253@end example 15254 15255@noindent 15256@xref{Backslash-Newline-Empty}, for how this can cause problems in makefiles. 15257 15258@node Here-Documents 15259@section Here-Documents 15260@cindex Here-documents 15261@cindex Shell here-documents 15262 15263Don't rely on @samp{\} being preserved just because it has no special 15264meaning together with the next symbol. In the native @command{sh} 15265on OpenBSD 2.7 @samp{\"} expands to @samp{"} in here-documents with 15266unquoted delimiter. As a general rule, if @samp{\\} expands to @samp{\} 15267use @samp{\\} to get @samp{\}. 15268 15269With OpenBSD 2.7's @command{sh} 15270 15271@example 15272@group 15273$ @kbd{cat <<EOF 15274> \" \\ 15275> EOF} 15276" \ 15277@end group 15278@end example 15279 15280@noindent 15281and with Bash: 15282 15283@example 15284@group 15285bash-2.04$ @kbd{cat <<EOF 15286> \" \\ 15287> EOF} 15288\" \ 15289@end group 15290@end example 15291 15292Using command substitutions in a here-document that is fed to a shell 15293function is not portable. For example, with Solaris 10 @command{/bin/sh}: 15294 15295@example 15296$ @kbd{kitty () @{ cat; @}} 15297$ @kbd{kitty <<EOF 15298> `echo ok` 15299> EOF} 15300/tmp/sh199886: cannot open 15301$ @kbd{echo $?} 153021 15303@end example 15304 15305Some shells mishandle large here-documents: for example, 15306Solaris 10 @command{dtksh} and the UnixWare 7.1.1 Posix shell, which are 15307derived from Korn shell version M-12/28/93d, mishandle braced variable 15308expansion that crosses a 1024- or 4096-byte buffer boundary 15309within a here-document. Only the part of the variable name after the boundary 15310is used. For example, @code{$@{variable@}} could be replaced by the expansion 15311of @code{$@{ble@}}. If the end of the variable name is aligned with the block 15312boundary, the shell reports an error, as if you used @code{$@{@}}. 15313Instead of @code{$@{variable-default@}}, the shell may expand 15314@code{$@{riable-default@}}, or even @code{$@{fault@}}. This bug can often 15315be worked around by omitting the braces: @code{$variable}. The bug was 15316fixed in 15317@samp{ksh93g} (1998-04-30) but as of 2006 many operating systems were 15318still shipping older versions with the bug. 15319 15320Empty here-documents are not portable either; with the following code, 15321@command{zsh} up to at least version 4.3.10 creates a file with a single 15322newline, whereas other shells create an empty file: 15323 15324@example 15325cat >file <<EOF 15326EOF 15327@end example 15328 15329Many shells (including the Bourne shell) implement here-documents 15330inefficiently. In particular, some shells can be extremely inefficient when 15331a single statement contains many here-documents. For instance if your 15332@file{configure.ac} includes something like: 15333 15334@example 15335@group 15336if <cross_compiling>; then 15337 assume this and that 15338else 15339 check this 15340 check that 15341 check something else 15342 @dots{} 15343 on and on forever 15344 @dots{} 15345fi 15346@end group 15347@end example 15348 15349A shell parses the whole @code{if}/@code{fi} construct, creating 15350temporary files for each here-document in it. Some shells create links 15351for such here-documents on every @code{fork}, so that the clean-up code 15352they had installed correctly removes them. It is creating the links 15353that can take the shell forever. 15354 15355Moving the tests out of the @code{if}/@code{fi}, or creating multiple 15356@code{if}/@code{fi} constructs, would improve the performance 15357significantly. Anyway, this kind of construct is not exactly the 15358typical use of Autoconf. In fact, it's even not recommended, because M4 15359macros can't look into shell conditionals, so we may fail to expand a 15360macro when it was expanded before in a conditional path, and the 15361condition turned out to be false at runtime, and we end up not 15362executing the macro at all. 15363 15364Be careful with the use of @samp{<<-} to unindent here-documents. The 15365behavior is only portable for stripping leading @key{TAB}s, and things 15366can silently break if an overzealous editor converts to using leading 15367spaces (not all shells are nice enough to warn about unterminated 15368here-documents). 15369 15370@example 15371$ @kbd{printf 'cat <<-x\n\t1\n\t 2\n\tx\n' | bash && echo done} 153721 15373 2 15374done 15375$ @kbd{printf 'cat <<-x\n 1\n 2\n x\n' | bash-3.2 && echo done} 15376 1 15377 2 15378 x 15379done 15380@end example 15381 15382@node File Descriptors 15383@section File Descriptors 15384@cindex Descriptors 15385@cindex File descriptors 15386@cindex Shell file descriptors 15387 15388Most shells, if not all (including Bash, Zsh, Ash), output traces on 15389stderr, even for subshells. This might result in undesirable content 15390if you meant to capture the standard-error output of the inner command: 15391 15392@example 15393$ @kbd{ash -x -c '(eval "echo foo >&2") 2>stderr'} 15394$ @kbd{cat stderr} 15395+ eval echo foo >&2 15396+ echo foo 15397foo 15398$ @kbd{bash -x -c '(eval "echo foo >&2") 2>stderr'} 15399$ @kbd{cat stderr} 15400+ eval 'echo foo >&2' 15401++ echo foo 15402foo 15403$ @kbd{zsh -x -c '(eval "echo foo >&2") 2>stderr'} 15404@i{# Traces on startup files deleted here.} 15405$ @kbd{cat stderr} 15406+zsh:1> eval echo foo >&2 15407+zsh:1> echo foo 15408foo 15409@end example 15410 15411@noindent 15412One workaround is to grep out uninteresting lines, hoping not to remove 15413good ones. 15414 15415If you intend to redirect both standard error and standard output, 15416redirect standard output first. This works better with HP-UX, 15417since its shell mishandles tracing if standard error is redirected 15418first: 15419 15420@example 15421$ @kbd{sh -x -c ': 2>err >out'} 15422+ : 15423+ 2> err $ @kbd{cat err} 154241> out 15425@end example 15426 15427Don't try to redirect the standard error of a command substitution. It 15428must be done @emph{inside} the command substitution. When running 15429@samp{: `cd /zorglub` 2>/dev/null} expect the error message to 15430escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly. 15431 15432On the other hand, some shells, such as Solaris or FreeBSD 15433@command{/bin/sh}, warn about missing programs before performing 15434redirections. Therefore, to silently check whether a program exists, it 15435is necessary to perform redirections on a subshell or brace group: 15436@example 15437$ @kbd{/bin/sh -c 'nosuch 2>/dev/null'} 15438nosuch: not found 15439$ @kbd{/bin/sh -c '(nosuch) 2>/dev/null'} 15440$ @kbd{/bin/sh -c '@{ nosuch; @} 2>/dev/null'} 15441$ @kbd{bash -c 'nosuch 2>/dev/null'} 15442@end example 15443 15444FreeBSD 6.2 sh may mix the trace output lines from the statements in a 15445shell pipeline. 15446 15447It is worth noting that Zsh (but not Ash nor Bash) makes it possible 15448in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}. 15449 15450Some shells, like @command{ash}, don't recognize bi-directional 15451redirection (@samp{<>}). And even on shells that recognize it, it is 15452not portable to use on fifos: Posix does not require read-write support 15453for named pipes, and Cygwin does not support it: 15454 15455@example 15456$ @kbd{mkfifo fifo} 15457$ @kbd{exec 5<>fifo} 15458$ @kbd{echo hi >&5} 15459bash: echo: write error: Communication error on send 15460@end example 15461 15462@noindent 15463Furthermore, versions of @command{dash} before 0.5.6 mistakenly truncate 15464regular files when using @samp{<>}: 15465 15466@example 15467$ @kbd{echo a > file} 15468$ @kbd{bash -c ': 1<>file'; cat file} 15469a 15470$ @kbd{dash -c ': 1<>file'; cat file} 15471$ rm a 15472@end example 15473 15474When catering to old systems, don't redirect the same file descriptor 15475several times, as you are doomed to failure under Ultrix. 15476 15477@example 15478ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995 15479UWS V4.4 (Rev. 11) 15480$ @kbd{eval 'echo matter >fullness' >void} 15481illegal io 15482$ @kbd{eval '(echo matter >fullness)' >void} 15483illegal io 15484$ @kbd{(eval '(echo matter >fullness)') >void} 15485Ambiguous output redirect. 15486@end example 15487 15488@noindent 15489In each case the expected result is of course @file{fullness} containing 15490@samp{matter} and @file{void} being empty. However, this bug is 15491probably not of practical concern to modern platforms. 15492 15493Solaris 10 @command{sh} will try to optimize away a @command{:} command 15494(even if it is redirected) in a loop after the first iteration, or in a 15495shell function after the first call: 15496 15497@example 15498$ @kbd{for i in 1 2 3 ; do : >x$i; done} 15499$ @kbd{ls x*} 15500x1 15501$ @kbd{f () @{ : >$1; @}; f y1; f y2; f y3;} 15502$ @kbd{ls y*} 15503y1 15504@end example 15505 15506@noindent 15507As a workaround, @command{echo} or @command{eval} can be used. 15508 15509Don't rely on file descriptors 0, 1, and 2 remaining closed in a 15510subsidiary program. If any of these descriptors is closed, the 15511operating system may open an unspecified file for the descriptor in the 15512new process image. Posix 2008 says this may be done only if the 15513subsidiary program is set-user-ID or set-group-ID, but HP-UX 11.23 does 15514it even for ordinary programs, and the next version of Posix will allow 15515HP-UX behavior. 15516 15517If you want a file descriptor above 2 to be inherited into a child 15518process, then you must use redirections specific to that command or a 15519containing subshell or command group, rather than relying on 15520@command{exec} in the shell. In @command{ksh} as well as HP-UX 15521@command{sh}, file descriptors above 2 which are opened using 15522@samp{exec @var{n}>file} are closed by a subsequent @samp{exec} (such as 15523that involved in the fork-and-exec which runs a program or script): 15524 15525@example 15526$ @kbd{echo 'echo hello >&5' >k} 15527$ @kbd{/bin/sh -c 'exec 5>t; ksh ./k; exec 5>&-; cat t} 15528hello 15529$ @kbd{bash -c 'exec 5>t; ksh ./k; exec 5>&-; cat t} 15530hello 15531$ @kbd{ksh -c 'exec 5>t; ksh ./k; exec 5>&-; cat t} 15532./k[1]: 5: cannot open [Bad file number] 15533$ @kbd{ksh -c '(ksh ./k) 5>t; cat t'} 15534hello 15535$ @kbd{ksh -c '@{ ksh ./k; @} 5>t; cat t'} 15536hello 15537$ @kbd{ksh -c '5>t ksh ./k; cat t} 15538hello 15539@end example 15540 15541Don't rely on duplicating a closed file descriptor to cause an 15542error. With Solaris @command{/bin/sh}, failed duplication is silently 15543ignored, which can cause unintended leaks to the original file 15544descriptor. In this example, observe the leak to standard output: 15545 15546@example 15547$ @kbd{bash -c 'echo hi >&3' 3>&-; echo $?} 15548bash: 3: Bad file descriptor 155491 15550$ @kbd{/bin/sh -c 'echo hi >&3' 3>&-; echo $?} 15551hi 155520 15553@end example 15554 15555Fortunately, an attempt to close an already closed file descriptor will 15556portably succeed. Likewise, it is safe to use either style of 15557@samp{@var{n}<&-} or @samp{@var{n}>&-} for closing a file descriptor, 15558even if it doesn't match the read/write mode that the file descriptor 15559was opened with. 15560 15561DOS variants cannot rename or remove open files, such as in 15562@samp{mv foo bar >foo} or @samp{rm foo >foo}, even though this is 15563perfectly portable among Posix hosts. 15564 15565A few ancient systems reserved some file descriptors. By convention, 15566file descriptor 3 was opened to @file{/dev/tty} when you logged into 15567Eighth Edition (1985) through Tenth Edition Unix (1989). File 15568descriptor 4 had a special use on the Stardent/Kubota Titan (circa 155691990), though we don't now remember what it was. Both these systems are 15570obsolete, so it's now safe to treat file descriptors 3 and 4 like any 15571other file descriptors. 15572 15573On the other hand, you can't portably use multi-digit file descriptors. 15574Solaris @command{ksh} doesn't understand any file descriptor larger than 15575@samp{9}: 15576 15577@example 15578$ @kbd{bash -c 'exec 10>&-'; echo $?} 155790 15580$ @kbd{ksh -c 'exec 9>&-'; echo $?} 155810 15582$ @kbd{ksh -c 'exec 10>&-'; echo $?} 15583ksh[1]: exec: 10: not found 15584127 15585@end example 15586 15587@c <http://lists.gnu.org/archive/html/bug-autoconf/2011-09/msg00004.html> 15588@node Signal Handling 15589@section Signal Handling 15590@cindex Signal handling in the shell 15591@cindex Signals, shells and 15592 15593Portable handling of signals within the shell is another major source of 15594headaches. This is worsened by the fact that various different, mutually 15595incompatible approaches are possible in this area, each with its 15596distinctive merits and demerits. A detailed description of these possible 15597approaches, as well as of their pros and cons, can be found in 15598@uref{http://www.cons.org/cracauer/sigint.html, this article}. 15599 15600Solaris 10 @command{/bin/sh} automatically traps most signals by default; 15601@c See: <http://dbaspot.com/shell/396118-bourne-shell-exit-code-term.html> 15602the shell still exits with error upon termination by one of those signals, 15603but in such a case the exit status might be somewhat unexpected (even if 15604allowed by POSIX, strictly speaking): 15605 15606@example 15607$ @kbd{bash -c 'kill -1 $$'; echo $?} # Will exit 128 + (signal number). 15608Hangup 15609129 15610$ @kbd{/bin/ksh -c 'kill -15 $$'; echo $?} # Likewise. 15611Terminated 15612143 15613$ @kbd{for sig in 1 2 3 15; do} 15614> @kbd{ echo $sig:} 15615> @kbd{ /bin/sh -c "kill -$s \$\$"; echo $?} 15616> @kbd{done} 15617signal 1: 15618Hangup 15619129 15620signal 2: 15621208 15622signal 3: 15623208 15624signal 15: 15625208 15626@end example 15627 15628This gets even worse if one is using the POSIX `wait' interface to get 15629details about the shell process terminations: it will result in the shell 15630having exited normally, rather than by receiving a signal. 15631 15632@example 15633$ @kbd{cat > foo.c <<'END'} 15634#include <stdio.h> /* for printf */ 15635#include <stdlib.h> /* for system */ 15636#include <sys/wait.h> /* for WIF* macros */ 15637int main(void) 15638@{ 15639 int status = system ("kill -15 $$"); 15640 printf ("Terminated by signal: %s\n", 15641 WIFSIGNALED (status) ? "yes" : "no"); 15642 printf ("Exited normally: %s\n", 15643 WIFEXITED (status) ? "yes" : "no"); 15644 return 0; 15645@} 15646END 15647@c $$ font-lock 15648$ @kbd{cc -o foo foo.c} 15649$ @kbd{./a.out} # On GNU/Linux 15650Terminated by signal: no 15651Exited normally: yes 15652$ @kbd{./a.out} # On Solaris 10 15653Terminated by signal: yes 15654Exited normally: no 15655@end example 15656 15657Various shells seem to handle @code{SIGQUIT} specially: they ignore it even 15658if it is not blocked, and even if the shell is not running interactively 15659(in fact, even if the shell has no attached tty); among these shells 15660are at least Bash (from version 2 onwards), Zsh 4.3.12, Solaris 10 15661@code{/bin/ksh} and @code{/usr/xpg4/bin/sh}, and AT&T @code{ksh93} (2011). 15662Still, @code{SIGQUIT} seems to be trappable quite portably within all 15663these shells. OTOH, some other shells doesn't special-case the handling 15664of @code{SIGQUIT}; among these shells are at least @code{pdksh} 5.2.14, 15665Solaris 10 and NetBSD 5.1 @code{/bin/sh}, and the Almquist Shell 0.5.5.1. 15666 15667@c See: <http://mail.opensolaris.org/pipermail/ksh93-integration-discuss/2009-February/004121.html> 15668Some shells (especially Korn shells and derivatives) might try to 15669propagate to themselves a signal that has killed a child process; this is 15670not a bug, but a conscious design choice (although its overall value might 15671be debatable). The exact details of how this is attained vary from shell 15672to shell. For example, upon running @code{perl -e 'kill 2, $$'}, after 15673the perl process has been interrupted AT&T @code{ksh93} (2011) will 15674proceed to send itself a @code{SIGINT}, while Solaris 10 @code{/bin/ksh} 15675and @code{/usr/xpg4/bin/sh} will proceed to exit with status 130 (i.e., 15676128 + 2). In any case, if there is an active trap associated with 15677@code{SIGINT}, those shells will correctly execute it. 15678 15679@c See: <http://www.austingroupbugs.net/view.php?id=51> 15680Some Korn shells, when a child process die due receiving a signal with 15681signal number @var{n}, can leave in @samp{$?} an exit status of 15682256+@var{n} instead of the more common 128+@var{n}. Observe the 15683difference between AT&T @code{ksh93} (2011) and @code{bash} 4.1.5 on 15684Debian: 15685 15686@example 15687$ @kbd{/bin/ksh -c 'sh -c "kill -1 \$\$"; echo $?'} 15688/bin/ksh: line 1: 7837: Hangup 15689257 15690$ @kbd{/bin/bash -c 'sh -c "kill -1 \$\$"; echo $?'} 15691/bin/bash: line 1: 7861 Hangup (sh -c "kill -1 \$\$") 15692129 15693@end example 15694 15695@noindent 15696This @command{ksh} behavior is allowed by POSIX, if implemented with 15697due care; see this @uref{http://www.austingroupbugs.net/view.php?id=51, 15698Austin Group discussion} for more background. However, if it is not 15699implemented with proper care, such a behavior might cause problems 15700in some corner cases. To see why, assume we have a ``wrapper'' script 15701like this: 15702 15703@example 15704#!/bin/sh 15705# Ignore some signals in the shell only, not in its child processes. 15706trap : 1 2 13 15 15707wrapped_command "$@@" 15708ret=$? 15709other_command 15710exit $ret 15711@end example 15712 15713@noindent 15714If @command{wrapped_command} is interrupted by a @code{SIGHUP} (which 15715has signal number 1), @code{ret} will be set to 257. Unless the 15716@command{exit} shell builtin is smart enough to understand that such 15717a value can only have originated from a signal, and adjust the final 15718wait status of the shell appropriately, the value 257 will just get 15719truncated to 1 by the closing @code{exit} call, so that a caller of 15720the script will have no way to determine that termination by a signal 15721was involved. Observe the different behavior of AT&T @code{ksh93} 15722(2011) and @code{bash} 4.1.5 on Debian: 15723 15724@example 15725$ @kbd{cat foo.sh} 15726#!/bin/sh 15727sh -c 'kill -1 $$' 15728ret=$? 15729echo $ret 15730exit $ret 15731$ @kbd{/bin/ksh foo.sh; echo $?} 15732foo.sh: line 2: 12479: Hangup 15733257 157341 15735$ @kbd{/bin/bash foo.sh; echo $?} 15736foo.sh: line 2: 12487 Hangup (sh -c 'kill -1 $$') 15737129 15738129 15739@end example 15740 15741@node File System Conventions 15742@section File System Conventions 15743@cindex File system conventions 15744 15745Autoconf uses shell-script processing extensively, so the file names 15746that it processes should not contain characters that are special to the 15747shell. Special characters include space, tab, newline, NUL, and 15748the following: 15749 15750@example 15751" # $ & ' ( ) * ; < = > ? [ \ ` | 15752@end example 15753 15754Also, file names should not begin with @samp{~} or @samp{-}, and should 15755contain neither @samp{-} immediately after @samp{/} nor @samp{~} 15756immediately after @samp{:}. On Posix-like platforms, directory names 15757should not contain @samp{:}, as this runs afoul of @samp{:} used as the 15758path separator. 15759 15760These restrictions apply not only to the files that you distribute, but 15761also to the absolute file names of your source, build, and destination 15762directories. 15763 15764On some Posix-like platforms, @samp{!} and @samp{^} are special too, so 15765they should be avoided. 15766 15767Posix lets implementations treat leading @file{//} specially, but 15768requires leading @file{///} and beyond to be equivalent to @file{/}. 15769Most Unix variants treat @file{//} like @file{/}. However, some treat 15770@file{//} as a ``super-root'' that can provide access to files that are 15771not otherwise reachable from @file{/}. The super-root tradition began 15772with Apollo Domain/OS, which died out long ago, but unfortunately Cygwin 15773has revived it. 15774 15775While @command{autoconf} and friends are usually run on some Posix 15776variety, they can be used on other systems, most notably DOS 15777variants. This impacts several assumptions regarding file names. 15778 15779@noindent 15780For example, the following code: 15781 15782@example 15783case $foo_dir in 15784 /*) # Absolute 15785 ;; 15786 *) 15787 foo_dir=$dots$foo_dir ;; 15788esac 15789@end example 15790 15791@noindent 15792fails to properly detect absolute file names on those systems, because 15793they can use a drivespec, and usually use a backslash as directory 15794separator. If you want to be portable to DOS variants (at the 15795price of rejecting valid but oddball Posix file names like @file{a:\b}), 15796you can check for absolute file names like this: 15797 15798@cindex absolute file names, detect 15799@example 15800case $foo_dir in 15801 [\\/]* | ?:[\\/]* ) # Absolute 15802 ;; 15803 *) 15804 foo_dir=$dots$foo_dir ;; 15805esac 15806@end example 15807 15808@noindent 15809Make sure you quote the brackets if appropriate and keep the backslash as 15810first character (@pxref{case, , Limitations of Shell Builtins}). 15811 15812Also, because the colon is used as part of a drivespec, these systems don't 15813use it as path separator. When creating or accessing paths, you can use the 15814@code{PATH_SEPARATOR} output variable instead. @command{configure} sets this 15815to the appropriate value for the build system (@samp{:} or @samp{;}) when it 15816starts up. 15817 15818File names need extra care as well. While DOS variants 15819that are Posixy enough to run @command{autoconf} (such as DJGPP) 15820are usually able to handle long file names properly, there are still 15821limitations that can seriously break packages. Several of these issues 15822can be easily detected by the 15823@uref{ftp://@/ftp.gnu.org/@/gnu/@/non-gnu/@/doschk/@/doschk-1.1.tar.gz, doschk} 15824package. 15825 15826A short overview follows; problems are marked with SFN/LFN to 15827indicate where they apply: SFN means the issues are only relevant to 15828plain DOS, not to DOS under Microsoft Windows 15829variants, while LFN identifies problems that exist even under 15830Microsoft Windows variants. 15831 15832@table @asis 15833@item No multiple dots (SFN) 15834DOS cannot handle multiple dots in file names. This is an especially 15835important thing to remember when building a portable configure script, 15836as @command{autoconf} uses a .in suffix for template files. 15837 15838This is perfectly OK on Posix variants: 15839 15840@example 15841AC_CONFIG_HEADERS([config.h]) 15842AC_CONFIG_FILES([source.c foo.bar]) 15843AC_OUTPUT 15844@end example 15845 15846@noindent 15847but it causes problems on DOS, as it requires @samp{config.h.in}, 15848@samp{source.c.in} and @samp{foo.bar.in}. To make your package more portable 15849to DOS-based environments, you should use this instead: 15850 15851@example 15852AC_CONFIG_HEADERS([config.h:config.hin]) 15853AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in]) 15854AC_OUTPUT 15855@end example 15856 15857@item No leading dot (SFN) 15858DOS cannot handle file names that start with a dot. This is usually 15859not important for @command{autoconf}. 15860 15861@item Case insensitivity (LFN) 15862DOS is case insensitive, so you cannot, for example, have both a 15863file called @samp{INSTALL} and a directory called @samp{install}. This 15864also affects @command{make}; if there's a file called @samp{INSTALL} in 15865the directory, @samp{make install} does nothing (unless the 15866@samp{install} target is marked as PHONY). 15867 15868@item The 8+3 limit (SFN) 15869Because the DOS file system only stores the first 8 characters of 15870the file name and the first 3 of the extension, those must be unique. 15871That means that @file{foobar-part1.c}, @file{foobar-part2.c} and 15872@file{foobar-prettybird.c} all resolve to the same file name 15873(@file{FOOBAR-P.C}). The same goes for @file{foo.bar} and 15874@file{foo.bartender}. 15875 15876The 8+3 limit is not usually a problem under Microsoft Windows, as it 15877uses numeric 15878tails in the short version of file names to make them unique. However, a 15879registry setting can turn this behavior off. While this makes it 15880possible to share file trees containing long file names between SFN 15881and LFN environments, it also means the above problem applies there 15882as well. 15883 15884@item Invalid characters (LFN) 15885Some characters are invalid in DOS file names, and should therefore 15886be avoided. In a LFN environment, these are @samp{/}, @samp{\}, 15887@samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}. 15888In a SFN environment, other characters are also invalid. These 15889include @samp{+}, @samp{,}, @samp{[} and @samp{]}. 15890 15891@item Invalid names (LFN) 15892Some DOS file names are reserved, and cause problems if you 15893try to use files with those names. These names include @file{CON}, 15894@file{AUX}, @file{COM1}, @file{COM2}, @file{COM3}, @file{COM4}, 15895@file{LPT1}, @file{LPT2}, @file{LPT3}, @file{NUL}, and @file{PRN}. 15896File names are case insensitive, so even names like 15897@file{aux/config.guess} are disallowed. 15898 15899@end table 15900 15901@node Shell Pattern Matching 15902@section Shell Pattern Matching 15903@cindex Shell pattern matching 15904 15905Nowadays portable patterns can use negated character classes like 15906@samp{[!-aeiou]}. The older syntax @samp{[^-aeiou]} is supported by 15907some shells but not others; hence portable scripts should never use 15908@samp{^} as the first character of a bracket pattern. 15909 15910Outside the C locale, patterns like @samp{[a-z]} are problematic since 15911they may match characters that are not lower-case letters. 15912 15913@node Shell Substitutions 15914@section Shell Substitutions 15915@cindex Shell substitutions 15916 15917Contrary to a persistent urban legend, the Bourne shell does not 15918systematically split variables and back-quoted expressions, in particular 15919on the right-hand side of assignments and in the argument of @code{case}. 15920For instance, the following code: 15921 15922@example 15923case "$given_srcdir" in 15924.) top_srcdir="`echo "$dots" | sed 's|/$||'`" ;; 15925*) top_srcdir="$dots$given_srcdir" ;; 15926esac 15927@end example 15928 15929@noindent 15930is more readable when written as: 15931 15932@example 15933case $given_srcdir in 15934.) top_srcdir=`echo "$dots" | sed 's|/$||'` ;; 15935*) top_srcdir=$dots$given_srcdir ;; 15936esac 15937@end example 15938 15939@noindent 15940and in fact it is even @emph{more} portable: in the first case of the 15941first attempt, the computation of @code{top_srcdir} is not portable, 15942since not all shells properly understand @code{"`@dots{}"@dots{}"@dots{}`"}, 15943for example Solaris 10 ksh: 15944 15945@example 15946$ @kbd{foo="`echo " bar" | sed 's, ,,'`"} 15947ksh: : cannot execute 15948ksh: bar | sed 's, ,,': cannot execute 15949@end example 15950 15951@noindent 15952Posix does not specify behavior for this sequence. On the other hand, 15953behavior for @code{"`@dots{}\"@dots{}\"@dots{}`"} is specified by Posix, 15954but in practice, not all shells understand it the same way: pdksh 5.2.14 15955prints spurious quotes when in Posix mode: 15956 15957@example 15958$ @kbd{echo "`echo \"hello\"`"} 15959hello 15960$ @kbd{set -o posix} 15961$ @kbd{echo "`echo \"hello\"`"} 15962"hello" 15963@end example 15964 15965@noindent 15966There is just no portable way to use double-quoted strings inside 15967double-quoted back-quoted expressions (pfew!). 15968 15969Bash 4.1 has a bug where quoted empty strings adjacent to unquoted 15970parameter expansions are elided during word splitting. Meanwhile, zsh 15971does not perform word splitting except when in Bourne compatibility 15972mode. In the example below, the correct behavior is to have five 15973arguments to the function, and exactly two spaces on either side of the 15974middle @samp{-}, since word splitting collapses multiple spaces in 15975@samp{$f} but leaves empty arguments intact. 15976 15977@example 15978$ @kbd{bash -c 'n() @{ echo "$#$@@"; @}; f=" - "; n - ""$f"" -'} 159793- - - 15980$ @kbd{ksh -c 'n() @{ echo "$#$@@"; @}; f=" - "; n - ""$f"" -'} 159815- - - 15982$ @kbd{zsh -c 'n() @{ echo "$#$@@"; @}; f=" - "; n - ""$f"" -'} 159833- - - 15984$ @kbd{zsh -c 'emulate sh;} 15985> @kbd{n() @{ echo "$#$@@"; @}; f=" - "; n - ""$f"" -'} 159865- - - 15987@end example 15988 15989@noindent 15990You can work around this by doing manual word splitting, such as using 15991@samp{"$str" $list} rather than @samp{"$str"$list}. 15992 15993There are also portability pitfalls with particular expansions: 15994 15995@table @code 15996@item $@@ 15997@cindex @code{"$@@"} 15998One of the most famous shell-portability issues is related to 15999@samp{"$@@"}. When there are no positional arguments, Posix says 16000that @samp{"$@@"} is supposed to be equivalent to nothing, but the 16001original Unix version 7 Bourne shell treated it as equivalent to 16002@samp{""} instead, and this behavior survives in later implementations 16003like Digital Unix 5.0. 16004 16005The traditional way to work around this portability problem is to use 16006@samp{$@{1+"$@@"@}}. Unfortunately this method does not work with 16007Zsh (3.x and 4.x), which is used on Mac OS X@. When emulating 16008the Bourne shell, Zsh performs word splitting on @samp{$@{1+"$@@"@}}: 16009 16010@example 16011zsh $ @kbd{emulate sh} 16012zsh $ @kbd{for i in "$@@"; do echo $i; done} 16013Hello World 16014! 16015zsh $ @kbd{for i in $@{1+"$@@"@}; do echo $i; done} 16016Hello 16017World 16018! 16019@end example 16020 16021@noindent 16022Zsh handles plain @samp{"$@@"} properly, but we can't use plain 16023@samp{"$@@"} because of the portability problems mentioned above. 16024One workaround relies on Zsh's ``global aliases'' to convert 16025@samp{$@{1+"$@@"@}} into @samp{"$@@"} by itself: 16026 16027@example 16028test "$@{ZSH_VERSION+set@}" = set && alias -g '$@{1+"$@@"@}'='"$@@"' 16029@end example 16030 16031Zsh only recognizes this alias when a shell word matches it exactly; 16032@samp{"foo"$@{1+"$@@"@}} remains subject to word splitting. Since this 16033case always yields at least one shell word, use plain @samp{"$@@"}. 16034 16035A more conservative workaround is to avoid @samp{"$@@"} if it is 16036possible that there may be no positional arguments. For example, 16037instead of: 16038 16039@example 16040cat conftest.c "$@@" 16041@end example 16042 16043you can use this instead: 16044 16045@example 16046case $# in 160470) cat conftest.c;; 16048*) cat conftest.c "$@@";; 16049esac 16050@end example 16051 16052Autoconf macros often use the @command{set} command to update 16053@samp{$@@}, so if you are writing shell code intended for 16054@command{configure} you should not assume that the value of @samp{$@@} 16055persists for any length of time. 16056 16057 16058@item $@{10@} 16059@cindex positional parameters 16060The 10th, 11th, @dots{} positional parameters can be accessed only after 16061a @code{shift}. The 7th Edition shell reported an error if given 16062@code{$@{10@}}, and 16063Solaris 10 @command{/bin/sh} still acts that way: 16064 16065@example 16066$ @kbd{set 1 2 3 4 5 6 7 8 9 10} 16067$ @kbd{echo $@{10@}} 16068bad substitution 16069@end example 16070 16071Conversely, not all shells obey the Posix rule that when braces are 16072omitted, multiple digits beyond a @samp{$} imply the single-digit 16073positional parameter expansion concatenated with the remaining literal 16074digits. To work around the issue, you must use braces. 16075 16076@example 16077$ @kbd{bash -c 'set a b c d e f g h i j; echo $10 $@{1@}0'} 16078a0 a0 16079$ @kbd{dash -c 'set a b c d e f g h i j; echo $10 $@{1@}0'} 16080j a0 16081@end example 16082 16083@item $@{@var{var}:-@var{value}@} 16084@c Info cannot handle `:' in index entries. 16085@ifnotinfo 16086@cindex @code{$@{@var{var}:-@var{value}@}} 16087@end ifnotinfo 16088@cindex @code{$@{@var{var}-@var{value}@}} 16089Old BSD shells, including the Ultrix @code{sh}, don't accept the 16090colon for any shell substitution, and complain and die. 16091Similarly for $@{@var{var}:=@var{value}@}, $@{@var{var}:?@var{value}@}, etc. 16092However, all shells that support functions allow the use of colon in 16093shell substitution, and since m4sh requires functions, you can portably 16094use null variable substitution patterns in configure scripts. 16095 16096@item $@{@var{var}+@var{value}@} 16097@cindex @code{$@{@var{var}+@var{value}@}} 16098When using @samp{$@{@var{var}-@var{value}@}} or 16099@samp{$@{@var{var}-@var{value}@}} for providing alternate substitutions, 16100@var{value} must either be a single shell word, quoted, or in the 16101context of an unquoted here-document. Solaris 16102@command{/bin/sh} complains otherwise. 16103 16104@example 16105$ @kbd{/bin/sh -c 'echo $@{a-b c@}'} 16106/bin/sh: bad substitution 16107$ @kbd{/bin/sh -c 'echo $@{a-'\''b c'\''@}'} 16108b c 16109$ @kbd{/bin/sh -c 'echo "$@{a-b c@}"'} 16110b c 16111$ @kbd{/bin/sh -c 'cat <<EOF 16112$@{a-b c@} 16113EOF} 16114b c 16115@end example 16116 16117According to Posix, if an expansion occurs inside double quotes, then 16118the use of unquoted double quotes within @var{value} is unspecified, and 16119any single quotes become literal characters; in that case, escaping must 16120be done with backslash. Likewise, the use of unquoted here-documents is 16121a case where double quotes have unspecified results: 16122 16123@example 16124$ @kbd{/bin/sh -c 'echo "$@{a-"b c"@}"'} 16125/bin/sh: bad substitution 16126$ @kbd{ksh -c 'echo "$@{a-"b c"@}"'} 16127b c 16128$ @kbd{bash -c 'echo "$@{a-"b c"@}"'} 16129b c 16130$ @kbd{/bin/sh -c 'a=; echo $@{a+'\''b c'\''@}'} 16131b c 16132$ @kbd{/bin/sh -c 'a=; echo "$@{a+'\''b c'\''@}"'} 16133'b c' 16134$ @kbd{/bin/sh -c 'a=; echo "$@{a+\"b c\"@}"'} 16135"b c" 16136$ @kbd{/bin/sh -c 'a=; echo "$@{a+b c@}"'} 16137b c 16138$ @kbd{/bin/sh -c 'cat <<EOF 16139$@{a-"b c"@} 16140EOF'} 16141"b c" 16142$ @kbd{/bin/sh -c 'cat <<EOF 16143$@{a-'b c'@} 16144EOF'} 16145'b c' 16146$ @kbd{bash -c 'cat <<EOF 16147$@{a-"b c"@} 16148EOF'} 16149b c 16150$ @kbd{bash -c 'cat <<EOF 16151$@{a-'b c'@} 16152EOF'} 16153'b c' 16154@end example 16155 16156Perhaps the easiest way to work around quoting issues in a manner 16157portable to all shells is to place the results in a temporary variable, 16158then use @samp{$t} as the @var{value}, rather than trying to inline 16159the expression needing quoting. 16160 16161@example 16162$ @kbd{/bin/sh -c 't="b c\"'\''@}\\"; echo "$@{a-$t@}"'} 16163b c"'@}\ 16164$ @kbd{ksh -c 't="b c\"'\''@}\\"; echo "$@{a-$t@}"'} 16165b c"'@}\ 16166$ @kbd{bash -c 't="b c\"'\''@}\\"; echo "$@{a-$t@}"'} 16167b c"'@}\ 16168@end example 16169 16170@item $@{@var{var}=@var{value}@} 16171@cindex @code{$@{@var{var}=@var{value}@}} 16172When using @samp{$@{@var{var}=@var{value}@}} to assign a default value 16173to @var{var}, remember that even though the assignment to @var{var} does 16174not undergo file name expansion, the result of the variable expansion 16175does unless the expansion occurred within double quotes. In particular, 16176when using @command{:} followed by unquoted variable expansion for the 16177side effect of setting a default value, if the final value of 16178@samp{$var} contains any globbing characters (either from @var{value} or 16179from prior contents), the shell has to spend time performing file name 16180expansion and field splitting even though those results will not be 16181used. Therefore, it is a good idea to consider double quotes when performing 16182default initialization; while remembering how this impacts any quoting 16183characters appearing in @var{value}. 16184 16185@example 16186$ @kbd{time bash -c ': "$@{a=/usr/bin/*@}"; echo "$a"'} 16187/usr/bin/* 16188 16189real 0m0.005s 16190user 0m0.002s 16191sys 0m0.003s 16192$ @kbd{time bash -c ': $@{a=/usr/bin/*@}; echo "$a"'} 16193/usr/bin/* 16194 16195real 0m0.039s 16196user 0m0.026s 16197sys 0m0.009s 16198$ @kbd{time bash -c 'a=/usr/bin/*; : $@{a=noglob@}; echo "$a"'} 16199/usr/bin/* 16200 16201real 0m0.031s 16202user 0m0.020s 16203sys 0m0.010s 16204 16205$ @kbd{time bash -c 'a=/usr/bin/*; : "$@{a=noglob@}"; echo "$a"'} 16206/usr/bin/* 16207 16208real 0m0.006s 16209user 0m0.002s 16210sys 0m0.003s 16211@end example 16212 16213As with @samp{+} and @samp{-}, you must use quotes when using @samp{=} 16214if the @var{value} contains more than one shell word; either single 16215quotes for just the @var{value}, or double quotes around the entire 16216expansion: 16217 16218@example 16219$ @kbd{: $@{var1='Some words'@}} 16220$ @kbd{: "$@{var2=like this@}"} 16221$ @kbd{echo $var1 $var2} 16222Some words like this 16223@end example 16224 16225@noindent 16226otherwise some shells, such as Solaris @command{/bin/sh} or on Digital 16227Unix V 5.0, die because of a ``bad substitution''. Meanwhile, Posix 16228requires that with @samp{=}, quote removal happens prior to the 16229assignment, and the expansion be the final contents of @var{var} without 16230quoting (and thus subject to field splitting), in contrast to the 16231behavior with @samp{-} passing the quoting through to the final 16232expansion. However, @command{bash} 4.1 does not obey this rule. 16233 16234@example 16235$ @kbd{ksh -c 'echo $@{var-a\ \ b@}'} 16236a b 16237$ @kbd{ksh -c 'echo $@{var=a\ \ b@}'} 16238a b 16239$ @kbd{bash -c 'echo $@{var=a\ \ b@}'} 16240a b 16241@end example 16242 16243Finally, Posix states that when mixing @samp{$@{a=b@}} with regular 16244commands, it is unspecified whether the assignments affect the parent 16245shell environment. It is best to perform assignments independently from 16246commands, to avoid the problems demonstrated in this example: 16247 16248@example 16249$ @kbd{bash -c 'x= y=$@{x:=b@} sh -c "echo +\$x+\$y+";echo -$x-'} 16250+b+b+ 16251-b- 16252$ @kbd{/bin/sh -c 'x= y=$@{x:=b@} sh -c "echo +\$x+\$y+";echo -$x-'} 16253++b+ 16254-- 16255$ @kbd{ksh -c 'x= y=$@{x:=b@} sh -c "echo +\$x+\$y+";echo -$x-'} 16256+b+b+ 16257-- 16258@end example 16259 16260@item $@{@var{var}=@var{value}@} 16261@cindex @code{$@{@var{var}=@var{literal}@}} 16262Solaris @command{/bin/sh} has a frightening bug in its handling of 16263literal assignments. Imagine you need set a variable to a string containing 16264@samp{@}}. This @samp{@}} character confuses Solaris @command{/bin/sh} 16265when the affected variable was already set. This bug can be exercised 16266by running: 16267 16268@example 16269$ @kbd{unset foo} 16270$ @kbd{foo=$@{foo='@}'@}} 16271$ @kbd{echo $foo} 16272@} 16273$ @kbd{foo=$@{foo='@}' # no error; this hints to what the bug is} 16274$ @kbd{echo $foo} 16275@} 16276$ @kbd{foo=$@{foo='@}'@}} 16277$ @kbd{echo $foo} 16278@}@} 16279 ^ ugh! 16280@end example 16281 16282It seems that @samp{@}} is interpreted as matching @samp{$@{}, even 16283though it is enclosed in single quotes. The problem doesn't happen 16284using double quotes, or when using a temporary variable holding the 16285problematic string. 16286 16287@item $@{@var{var}=@var{expanded-value}@} 16288@cindex @code{$@{@var{var}=@var{expanded-value}@}} 16289On Ultrix, 16290running 16291 16292@example 16293default="yu,yaa" 16294: $@{var="$default"@} 16295@end example 16296 16297@noindent 16298sets @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of 16299each char is set. You don't observe the phenomenon using a simple 16300@samp{echo $var} since apparently the shell resets the 8th bit when it 16301expands $var. Here are two means to make this shell confess its sins: 16302 16303@example 16304$ @kbd{cat -v <<EOF 16305$var 16306EOF} 16307@end example 16308 16309@noindent 16310and 16311 16312@example 16313$ @kbd{set | grep '^var=' | cat -v} 16314@end example 16315 16316One classic incarnation of this bug is: 16317 16318@example 16319default="a b c" 16320: $@{list="$default"@} 16321for c in $list; do 16322 echo $c 16323done 16324@end example 16325 16326@noindent 16327You'll get @samp{a b c} on a single line. Why? Because there are no 16328spaces in @samp{$list}: there are @samp{M- }, i.e., spaces with the 8th 16329bit set, hence no IFS splitting is performed!!! 16330 16331One piece of good news is that Ultrix works fine with @samp{: 16332$@{list=$default@}}; i.e., if you @emph{don't} quote. The bad news is 16333then that QNX 4.25 then sets @var{list} to the @emph{last} item of 16334@var{default}! 16335 16336The portable way out consists in using a double assignment, to switch 16337the 8th bit twice on Ultrix: 16338 16339@example 16340list=$@{list="$default"@} 16341@end example 16342 16343@noindent 16344@dots{}but beware of the @samp{@}} bug from Solaris (see above). For safety, 16345use: 16346 16347@example 16348test "$@{var+set@}" = set || var=@var{@{value@}} 16349@end example 16350 16351@item $@{#@var{var}@} 16352@itemx $@{@var{var}%@var{word}@} 16353@itemx $@{@var{var}%%@var{word}@} 16354@itemx $@{@var{var}#@var{word}@} 16355@itemx $@{@var{var}##@var{word}@} 16356@cindex @code{$@{#@var{var}@}} 16357@cindex @code{$@{@var{var}%@var{word}@}} 16358@cindex @code{$@{@var{var}%%@var{word}@}} 16359@cindex @code{$@{@var{var}#@var{word}@}} 16360@cindex @code{$@{@var{var}##@var{word}@}} 16361Posix requires support for these usages, but they do not work with many 16362traditional shells, e.g., Solaris 10 @command{/bin/sh}. 16363 16364Also, @command{pdksh} 5.2.14 mishandles some @var{word} forms. For 16365example if @samp{$1} is @samp{a/b} and @samp{$2} is @samp{a}, then 16366@samp{$@{1#$2@}} should yield @samp{/b}, but with @command{pdksh} it 16367yields the empty string. 16368 16369 16370@item `@var{commands}` 16371@cindex @code{`@var{commands}`} 16372@cindex Command Substitution 16373Posix requires shells to trim all trailing newlines from command 16374output before substituting it, so assignments like 16375@samp{dir=`echo "$file" | tr a A`} do not work as expected if 16376@samp{$file} ends in a newline. 16377 16378While in general it makes no sense, do not substitute a single builtin 16379with side effects, because Ash 0.2, trying to optimize, does not fork a 16380subshell to perform the command. 16381 16382For instance, if you wanted to check that @command{cd} is silent, do not 16383use @samp{test -z "`cd /`"} because the following can happen: 16384 16385@example 16386$ @kbd{pwd} 16387/tmp 16388$ @kbd{test -z "`cd /`" && pwd} 16389/ 16390@end example 16391 16392@noindent 16393The result of @samp{foo=`exit 1`} is left as an exercise to the reader. 16394 16395The MSYS shell leaves a stray byte in the expansion of a double-quoted 16396command substitution of a native program, if the end of the substitution 16397is not aligned with the end of the double quote. This may be worked 16398around by inserting another pair of quotes: 16399 16400@example 16401$ @kbd{echo "`printf 'foo\r\n'` bar" > broken} 16402$ @kbd{echo "`printf 'foo\r\n'`"" bar" | cmp - broken} 16403- broken differ: char 4, line 1 16404@end example 16405 16406Upon interrupt or SIGTERM, some shells may abort a command substitution, 16407replace it with a null string, and wrongly evaluate the enclosing 16408command before entering the trap or ending the script. This can lead to 16409spurious errors: 16410 16411@example 16412$ @kbd{sh -c 'if test `sleep 5; echo hi` = hi; then echo yes; fi'} 16413$ @kbd{^C} 16414sh: test: hi: unexpected operator/operand 16415@end example 16416 16417@noindent 16418You can avoid this by assigning the command substitution to a temporary 16419variable: 16420 16421@example 16422$ @kbd{sh -c 'res=`sleep 5; echo hi` 16423 if test "x$res" = xhi; then echo yes; fi'} 16424$ @kbd{^C} 16425@end example 16426 16427@item $(@var{commands}) 16428@cindex @code{$(@var{commands})} 16429This construct is meant to replace @samp{`@var{commands}`}, 16430and it has most of the problems listed under @code{`@var{commands}`}. 16431 16432This construct can be 16433nested while this is impossible to do portably with back quotes. 16434Unfortunately it is not yet universally supported. Most notably, even recent 16435releases of Solaris don't support it: 16436 16437@example 16438$ @kbd{showrev -c /bin/sh | grep version} 16439Command version: SunOS 5.10 Generic 121005-03 Oct 2006 16440$ @kbd{echo $(echo blah)} 16441syntax error: `(' unexpected 16442@end example 16443 16444@noindent 16445nor does IRIX 6.5's Bourne shell: 16446@example 16447$ @kbd{uname -a} 16448IRIX firebird-image 6.5 07151432 IP22 16449$ @kbd{echo $(echo blah)} 16450$(echo blah) 16451@end example 16452 16453If you do use @samp{$(@var{commands})}, make sure that the commands 16454do not start with a parenthesis, as that would cause confusion with 16455a different notation @samp{$((@var{expression}))} that in modern 16456shells is an arithmetic expression not a command. To avoid the 16457confusion, insert a space between the two opening parentheses. 16458 16459Avoid @var{commands} that contain unbalanced parentheses in 16460here-documents, comments, or case statement patterns, as many shells 16461mishandle them. For example, Bash 3.1, @samp{ksh88}, @command{pdksh} 164625.2.14, and Zsh 4.2.6 all mishandle the following valid command: 16463 16464@example 16465echo $(case x in x) echo hello;; esac) 16466@end example 16467 16468 16469@item $((@var{expression})) 16470@cindex @code{$((@var{expression}))} 16471Arithmetic expansion is not portable as some shells (most 16472notably Solaris 10 @command{/bin/sh}) don't support it. 16473 16474Among shells that do support @samp{$(( ))}, not all of them obey the 16475Posix rule that octal and hexadecimal constants must be recognized: 16476 16477@example 16478$ @kbd{bash -c 'echo $(( 010 + 0x10 ))'} 1647924 16480$ @kbd{zsh -c 'echo $(( 010 + 0x10 ))'} 1648126 16482$ @kbd{zsh -c 'emulate sh; echo $(( 010 + 0x10 ))'} 1648324 16484$ @kbd{pdksh -c 'echo $(( 010 + 0x10 ))'} 16485pdksh: 010 + 0x10 : bad number `0x10' 16486$ @kbd{pdksh -c 'echo $(( 010 ))'} 1648710 16488@end example 16489 16490When it is available, using arithmetic expansion provides a noticeable 16491speedup in script execution; but testing for support requires 16492@command{eval} to avoid syntax errors. The following construct is used 16493by @code{AS_VAR_ARITH} to provide arithmetic computation when all 16494arguments are provided in decimal and without a leading zero, and all 16495operators are properly quoted and appear as distinct arguments: 16496 16497@example 16498if ( eval 'test $(( 1 + 1 )) = 2' ) 2>/dev/null; then 16499 eval 'func_arith () 16500 @{ 16501 func_arith_result=$(( $* )) 16502 @}' 16503else 16504 func_arith () 16505 @{ 16506 func_arith_result=`expr "$@@"` 16507 @} 16508fi 16509func_arith 1 + 1 16510foo=$func_arith_result 16511@end example 16512 16513 16514@item ^ 16515@cindex @code{^} quoting 16516Always quote @samp{^}, otherwise traditional shells such as 16517@command{/bin/sh} on Solaris 10 treat this like @samp{|}. 16518 16519@end table 16520 16521 16522@node Assignments 16523@section Assignments 16524@cindex Shell assignments 16525 16526When setting several variables in a row, be aware that the order of the 16527evaluation is undefined. For instance @samp{foo=1 foo=2; echo $foo} 16528gives @samp{1} with Solaris @command{/bin/sh}, but @samp{2} with Bash. 16529You must use 16530@samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}. 16531 16532Don't rely on the following to find @file{subdir/program}: 16533 16534@example 16535PATH=subdir$PATH_SEPARATOR$PATH program 16536@end example 16537 16538@noindent 16539as this does not work with Zsh 3.0.6. Use something like this 16540instead: 16541 16542@example 16543(PATH=subdir$PATH_SEPARATOR$PATH; export PATH; exec program) 16544@end example 16545 16546Don't rely on the exit status of an assignment: Ash 0.2 does not change 16547the status and propagates that of the last statement: 16548 16549@example 16550$ @kbd{false || foo=bar; echo $?} 165511 16552$ @kbd{false || foo=`:`; echo $?} 165530 16554@end example 16555 16556@noindent 16557and to make things even worse, QNX 4.25 just sets the exit status 16558to 0 in any case: 16559 16560@example 16561$ @kbd{foo=`exit 1`; echo $?} 165620 16563@end example 16564 16565To assign default values, follow this algorithm: 16566 16567@enumerate 16568@item 16569If the default value is a literal and does not contain any closing 16570brace, use: 16571 16572@example 16573: "$@{var='my literal'@}" 16574@end example 16575 16576@item 16577If the default value contains no closing brace, has to be expanded, and 16578the variable being initialized is not intended to be IFS-split 16579(i.e., it's not a list), then use: 16580 16581@example 16582: $@{var="$default"@} 16583@end example 16584 16585@item 16586If the default value contains no closing brace, has to be expanded, and 16587the variable being initialized is intended to be IFS-split (i.e., it's a list), 16588then use: 16589 16590@example 16591var=$@{var="$default"@} 16592@end example 16593 16594@item 16595If the default value contains a closing brace, then use: 16596 16597@example 16598test "$@{var+set@}" = set || var="has a '@}'" 16599@end example 16600@end enumerate 16601 16602In most cases @samp{var=$@{var="$default"@}} is fine, but in case of 16603doubt, just use the last form. @xref{Shell Substitutions}, items 16604@samp{$@{@var{var}:-@var{value}@}} and @samp{$@{@var{var}=@var{value}@}} 16605for the rationale. 16606 16607@node Parentheses 16608@section Parentheses in Shell Scripts 16609@cindex Shell parentheses 16610 16611Beware of two opening parentheses in a row, as many shell 16612implementations treat them specially, and Posix says that a portable 16613script cannot use @samp{((} outside the @samp{$((} form used for shell 16614arithmetic. In traditional shells, @samp{((cat))} behaves like 16615@samp{(cat)}; but many shells, including 16616Bash and the Korn shell, treat @samp{((cat))} as an arithmetic 16617expression equivalent to @samp{let "cat"}, and may or may not report an 16618error when they detect that @samp{cat} is not a number. As another 16619example, @samp{pdksh} 5.2.14 does not treat the following code 16620as a traditional shell would: 16621 16622@example 16623if ((true) || false); then 16624 echo ok 16625fi 16626@end example 16627 16628@noindent 16629To work around this problem, insert a space between the two opening 16630parentheses. There is a similar problem and workaround with 16631@samp{$((}; see @ref{Shell Substitutions}. 16632 16633@node Slashes 16634@section Slashes in Shell Scripts 16635@cindex Shell slashes 16636 16637Unpatched Tru64 5.1 @command{sh} omits the last slash of command-line 16638arguments that contain two trailing slashes: 16639 16640@example 16641$ @kbd{echo / // /// //// .// //.} 16642/ / // /// ./ //. 16643$ @kbd{x=//} 16644$ @kbd{eval "echo \$x"} 16645/ 16646$ @kbd{set -x} 16647$ @kbd{echo abc | tr -t ab //} 16648+ echo abc 16649+ tr -t ab / 16650/bc 16651@end example 16652 16653Unpatched Tru64 4.0 @command{sh} adds a slash after @samp{"$var"} if the 16654variable is empty and the second double-quote is followed by a word that 16655begins and ends with slash: 16656 16657@example 16658$ @kbd{sh -xc 'p=; echo "$p"/ouch/'} 16659p= 16660+ echo //ouch/ 16661//ouch/ 16662@end example 16663 16664However, our understanding is that patches are available, so perhaps 16665it's not worth worrying about working around these horrendous bugs. 16666 16667@node Special Shell Variables 16668@section Special Shell Variables 16669@cindex Shell variables 16670@cindex Special shell variables 16671 16672Some shell variables should not be used, since they can have a deep 16673influence on the behavior of the shell. In order to recover a sane 16674behavior from the shell, some variables should be unset; M4sh takes 16675care of this and provides fallback values, whenever needed, to cater 16676for a very old @file{/bin/sh} that does not support @command{unset}. 16677(@pxref{Portable Shell, , Portable Shell Programming}). 16678 16679As a general rule, shell variable names containing a lower-case letter 16680are safe; you can define and use these variables without worrying about 16681their effect on the underlying system, and without worrying about 16682whether the shell changes them unexpectedly. (The exception is the 16683shell variable @code{status}, as described below.) 16684 16685Here is a list of names that are known to cause trouble. This list is 16686not exhaustive, but you should be safe if you avoid the name 16687@code{status} and names containing only upper-case letters and 16688underscores. 16689 16690@c Alphabetical order, case insensitive, `A' before `a'. 16691@table @code 16692@item ? 16693Not all shells correctly reset @samp{$?} after conditionals (@pxref{if, 16694, Limitations of Shell Builtins}). Not all shells manage @samp{$?} 16695correctly in shell functions (@pxref{Shell Functions}) or in traps 16696(@pxref{trap, , Limitations of Shell Builtins}). Not all shells reset 16697@samp{$?} to zero after an empty command. 16698 16699@example 16700$ @kbd{bash -c 'false; $empty; echo $?'} 167010 16702$ @kbd{zsh -c 'false; $empty; echo $?'} 167031 16704@end example 16705 16706@item _ 16707@evindex _ 16708Many shells reserve @samp{$_} for various purposes, e.g., the name of 16709the last command executed. 16710 16711@item BIN_SH 16712@evindex BIN_SH 16713In Tru64, if @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of 16714the standard shell conform to Posix. 16715 16716@item CDPATH 16717@evindex CDPATH 16718When this variable is set it specifies a list of directories to search 16719when invoking @code{cd} with a relative file name that did not start 16720with @samp{./} or @samp{../}. Posix 167211003.1-2001 says that if a nonempty directory name from @env{CDPATH} 16722is used successfully, @code{cd} prints the resulting absolute 16723file name. Unfortunately this output can break idioms like 16724@samp{abs=`cd src && pwd`} because @code{abs} receives the name twice. 16725Also, many shells do not conform to this part of Posix; for 16726example, @command{zsh} prints the result only if a directory name 16727other than @file{.} was chosen from @env{CDPATH}. 16728 16729In practice the shells that have this problem also support 16730@command{unset}, so you can work around the problem as follows: 16731 16732@example 16733(unset CDPATH) >/dev/null 2>&1 && unset CDPATH 16734@end example 16735 16736You can also avoid output by ensuring that your directory name is 16737absolute or anchored at @samp{./}, as in @samp{abs=`cd ./src && pwd`}. 16738 16739Configure scripts use M4sh, which automatically unsets @env{CDPATH} if 16740possible, so you need not worry about this problem in those scripts. 16741 16742@item CLICOLOR_FORCE 16743@evindex CLICOLOR_FORCE 16744When this variable is set, some implementations of tools like 16745@command{ls} attempt to add color to their output via terminal escape 16746sequences, even when the output is not directed to a terminal, and can 16747thus cause spurious failures in scripts. Configure scripts use M4sh, 16748which automatically unsets this variable. 16749 16750@item DUALCASE 16751@evindex DUALCASE 16752In the MKS shell, case statements and file name generation are 16753case-insensitive unless @env{DUALCASE} is nonzero. 16754Autoconf-generated scripts export this variable when they start up. 16755 16756@item ENV 16757@itemx MAIL 16758@itemx MAILPATH 16759@itemx PS1 16760@itemx PS2 16761@itemx PS4 16762@evindex ENV 16763@evindex MAIL 16764@evindex MAILPATH 16765@evindex PS1 16766@evindex PS2 16767@evindex PS4 16768These variables should not matter for shell scripts, since they are 16769supposed to affect only interactive shells. However, at least one 16770shell (the pre-3.0 UWIN Korn shell) gets confused about 16771whether it is interactive, which means that (for example) a @env{PS1} 16772with a side effect can unexpectedly modify @samp{$?}. To work around 16773this bug, M4sh scripts (including @file{configure} scripts) do something 16774like this: 16775 16776@example 16777(unset ENV) >/dev/null 2>&1 && unset ENV MAIL MAILPATH 16778PS1='$ ' 16779PS2='> ' 16780PS4='+ ' 16781@end example 16782 16783@noindent 16784(actually, there is some complication due to bugs in @command{unset}; 16785@pxref{unset, , Limitations of Shell Builtins}). 16786 16787@item FPATH 16788@evindex FPATH 16789The Korn shell uses @env{FPATH} to find shell functions, so avoid 16790@env{FPATH} in portable scripts. @env{FPATH} is consulted after 16791@env{PATH}, but you still need to be wary of tests that use @env{PATH} 16792to find whether a command exists, since they might report the wrong 16793result if @env{FPATH} is also set. 16794 16795@item GREP_OPTIONS 16796@evindex GREP_OPTIONS 16797When this variable is set, some implementations of @command{grep} honor 16798these options, even if the options include direction to enable colored 16799output via terminal escape sequences, and the result can cause spurious 16800failures when the output is not directed to a terminal. Configure 16801scripts use M4sh, which automatically unsets this variable. 16802 16803@item IFS 16804@evindex IFS 16805Long ago, shell scripts inherited @env{IFS} from the environment, 16806but this caused many problems so modern shells ignore any environment 16807settings for @env{IFS}. 16808 16809Don't set the first character of @env{IFS} to backslash. Indeed, 16810Bourne shells use the first character (backslash) when joining the 16811components in @samp{"$@@"} and some shells then reinterpret (!)@: the 16812backslash escapes, so you can end up with backspace and other strange 16813characters. 16814 16815The proper value for @env{IFS} (in regular code, not when performing 16816splits) is @samp{@key{SPC}@key{TAB}@key{RET}}. The first character is 16817especially important, as it is used to join the arguments in @samp{$*}; 16818however, note that traditional shells, but also bash-2.04, fail to adhere 16819to this and join with a space anyway. 16820 16821M4sh guarantees that @env{IFS} will have the default value at the 16822beginning of a script, and many macros within autoconf rely on this 16823setting. It is okay to use blocks of shell code that temporarily change 16824the value of @env{IFS} in order to split on another character, but 16825remember to restore it before expanding further macros. 16826 16827Unsetting @code{IFS} instead of resetting it to the default sequence 16828is not suggested, since code that tries to save and restore the 16829variable's value will incorrectly reset it to an empty value, thus 16830disabling field splitting: 16831 16832@example 16833unset IFS 16834# default separators used for field splitting 16835 16836save_IFS=$IFS 16837IFS=: 16838# ... 16839IFS=$save_IFS 16840# no field splitting performed 16841@end example 16842 16843@item LANG 16844@itemx LC_ALL 16845@itemx LC_COLLATE 16846@itemx LC_CTYPE 16847@itemx LC_MESSAGES 16848@itemx LC_MONETARY 16849@itemx LC_NUMERIC 16850@itemx LC_TIME 16851@evindex LANG 16852@evindex LC_ALL 16853@evindex LC_COLLATE 16854@evindex LC_CTYPE 16855@evindex LC_MESSAGES 16856@evindex LC_MONETARY 16857@evindex LC_NUMERIC 16858@evindex LC_TIME 16859 16860You should set all these variables to @samp{C} because so much 16861configuration code assumes the C locale and Posix requires that locale 16862environment variables be set to @samp{C} if the C locale is desired; 16863@file{configure} scripts and M4sh do that for you. 16864Export these variables after setting them. 16865 16866@c However, some older, nonstandard 16867@c systems (notably SCO) break if locale environment variables 16868@c are set to @samp{C}, so when running on these systems 16869@c Autoconf-generated scripts unset the variables instead. 16870 16871@item LANGUAGE 16872@evindex LANGUAGE 16873 16874@env{LANGUAGE} is not specified by Posix, but it is a GNU 16875extension that overrides @env{LC_ALL} in some cases, so you (or M4sh) 16876should set it too. 16877 16878@item LC_ADDRESS 16879@itemx LC_IDENTIFICATION 16880@itemx LC_MEASUREMENT 16881@itemx LC_NAME 16882@itemx LC_PAPER 16883@itemx LC_TELEPHONE 16884@evindex LC_ADDRESS 16885@evindex LC_IDENTIFICATION 16886@evindex LC_MEASUREMENT 16887@evindex LC_NAME 16888@evindex LC_PAPER 16889@evindex LC_TELEPHONE 16890 16891These locale environment variables are GNU extensions. They 16892are treated like their Posix brethren (@env{LC_COLLATE}, 16893etc.)@: as described above. 16894 16895@item LINENO 16896@evindex LINENO 16897Most modern shells provide the current line number in @code{LINENO}. 16898Its value is the line number of the beginning of the current command. 16899M4sh, and hence Autoconf, attempts to execute @command{configure} with 16900a shell that supports @code{LINENO}. If no such shell is available, it 16901attempts to implement @code{LINENO} with a Sed prepass that replaces each 16902instance of the string @code{$LINENO} (not followed by an alphanumeric 16903character) with the line's number. In M4sh scripts you should execute 16904@code{AS_LINENO_PREPARE} so that these workarounds are included in 16905your script; configure scripts do this automatically in @code{AC_INIT}. 16906 16907You should not rely on @code{LINENO} within @command{eval} or shell 16908functions, as the behavior differs in practice. The presence of a 16909quoted newline within simple commands can alter which line number is 16910used as the starting point for @code{$LINENO} substitutions within that 16911command. Also, the possibility of the Sed prepass means that you should 16912not rely on @code{$LINENO} when quoted, when in here-documents, or when 16913line continuations are used. Subshells should be OK, though. In the 16914following example, lines 1, 9, and 14 are portable, but the other 16915instances of @code{$LINENO} do not have deterministic values: 16916 16917@example 16918@group 16919$ @kbd{cat lineno} 16920echo 1. $LINENO 16921echo "2. $LINENO 169223. $LINENO" 16923cat <<EOF 169245. $LINENO 169256. $LINENO 169267. \$LINENO 16927EOF 16928( echo 9. $LINENO ) 16929eval 'echo 10. $LINENO' 16930eval 'echo 11. $LINENO 16931echo 12. $LINENO' 16932echo 13. '$LINENO' 16933echo 14. $LINENO ' 1693415.' $LINENO 16935f () @{ echo $1 $LINENO; 16936echo $1 $LINENO @} 16937f 18. 16938echo 19. \ 16939$LINENO 16940@end group 16941@group 16942$ @kbd{bash-3.2 ./lineno} 169431. 1 169442. 3 169453. 3 169465. 4 169476. 4 169487. $LINENO 169499. 9 1695010. 10 1695111. 12 1695212. 13 1695313. $LINENO 1695414. 14 1695515. 14 1695618. 16 1695718. 17 1695819. 19 16959@end group 16960@group 16961$ @kbd{zsh-4.3.4 ./lineno} 169621. 1 169632. 2 169643. 2 169655. 4 169666. 4 169677. $LINENO 169689. 9 1696910. 1 1697011. 1 1697112. 2 1697213. $LINENO 1697314. 14 1697415. 14 1697518. 0 1697618. 1 1697719. 19 16978@end group 16979@group 16980$ @kbd{pdksh-5.2.14 ./lineno} 169811. 1 169822. 2 169833. 2 169845. 4 169856. 4 169867. $LINENO 169879. 9 1698810. 0 1698911. 0 1699012. 0 1699113. $LINENO 1699214. 14 1699315. 14 1699418. 16 1699518. 17 1699619. 19 16997@end group 16998@group 16999$ @kbd{sed '=' <lineno |} 17000> @kbd{ sed '} 17001> @kbd{ N} 17002> @kbd{ s,$,-,} 17003> @kbd{ t loop} 17004> @kbd{ :loop} 17005> @kbd{ s,^\([0-9]*\)\(.*\)[$]LINENO\([^a-zA-Z0-9_]\),\1\2\1\3,} 17006> @kbd{ t loop} 17007> @kbd{ s,-$,,} 17008> @kbd{ s,^[0-9]*\n,,} 17009> @kbd{ ' |} 17010> @kbd{ sh} 170111. 1 170122. 2 170133. 3 170145. 5 170156. 6 170167. \7 170179. 9 1701810. 10 1701911. 11 1702012. 12 1702113. 13 1702214. 14 1702315. 15 1702418. 16 1702518. 17 1702619. 20 17027@end group 17028@end example 17029 17030In particular, note that @file{config.status} (and any other subsidiary 17031script created by @code{AS_INIT_GENERATED}) might report line numbers 17032relative to the parent script as a result of the potential Sed pass. 17033 17034@item NULLCMD 17035@evindex NULLCMD 17036When executing the command @samp{>foo}, @command{zsh} executes 17037@samp{$NULLCMD >foo} unless it is operating in Bourne shell 17038compatibility mode and the @command{zsh} version is newer 17039than 3.1.6-dev-18. If you are using an older @command{zsh} 17040and forget to set @env{NULLCMD}, 17041your script might be suspended waiting for data on its standard input. 17042 17043@item options 17044@evindex options 17045For @command{zsh} 4.3.10, @env{options} is treated as an associative 17046array even after @code{emulate sh}, so it should not be used. 17047 17048@item PATH_SEPARATOR 17049@evindex PATH_SEPARATOR 17050On DJGPP systems, the @env{PATH_SEPARATOR} environment 17051variable can be set to either @samp{:} or @samp{;} to control the path 17052separator Bash uses to set up certain environment variables (such as 17053@env{PATH}). You can set this variable to @samp{;} if you want 17054@command{configure} to use @samp{;} as a separator; this might be useful 17055if you plan to use non-Posix shells to execute files. @xref{File System 17056Conventions}, for more information about @code{PATH_SEPARATOR}. 17057 17058@item POSIXLY_CORRECT 17059@evindex POSIXLY_CORRECT 17060In the GNU environment, exporting @env{POSIXLY_CORRECT} with any value 17061(even empty) causes programs to try harder to conform to Posix. 17062Autoconf does not directly manipulate this variable, but @command{bash} 17063ties the shell variable @env{POSIXLY_CORRECT} to whether the script is 17064running in Posix mode. Therefore, take care when exporting or unsetting 17065this variable, so as not to change whether @command{bash} is in Posix 17066mode. 17067 17068@example 17069$ @kbd{bash --posix -c 'set -o | grep posix} 17070> @kbd{unset POSIXLY_CORRECT} 17071> @kbd{set -o | grep posix'} 17072posix on 17073posix off 17074@end example 17075 17076@item PWD 17077@evindex PWD 17078Posix 1003.1-2001 requires that @command{cd} and 17079@command{pwd} must update the @env{PWD} environment variable to point 17080to the logical name of the current directory, but traditional shells 17081do not support this. This can cause confusion if one shell instance 17082maintains @env{PWD} but a subsidiary and different shell does not know 17083about @env{PWD} and executes @command{cd}; in this case @env{PWD} 17084points to the wrong directory. Use @samp{`pwd`} rather than 17085@samp{$PWD}. 17086 17087@item RANDOM 17088@evindex RANDOM 17089Many shells provide @code{RANDOM}, a variable that returns a different 17090integer each time it is used. Most of the time, its value does not 17091change when it is not used, but on IRIX 6.5 the value changes all 17092the time. This can be observed by using @command{set}. It is common 17093practice to use @code{$RANDOM} as part of a file name, but code 17094shouldn't rely on @code{$RANDOM} expanding to a nonempty string. 17095 17096@item status 17097@evindex status 17098This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6), 17099hence read-only. Do not use it. 17100@end table 17101 17102@node Shell Functions 17103@section Shell Functions 17104@cindex Shell Functions 17105 17106Nowadays, it is difficult to find a shell that does not support 17107shell functions at all. However, some differences should be expected. 17108 17109When declaring a shell function, you must include whitespace between the 17110@samp{)} after the function name and the start of the compound 17111expression, to avoid upsetting @command{ksh}. While it is possible to 17112use any compound command, most scripts use @samp{@{@dots{}@}}. 17113 17114@example 17115$ @kbd{/bin/sh -c 'a()@{ echo hi;@}; a'} 17116hi 17117$ @kbd{ksh -c 'a()@{ echo hi;@}; a'} 17118ksh: syntax error at line 1: `@}' unexpected 17119$ @kbd{ksh -c 'a() @{ echo hi;@}; a'} 17120hi 17121@end example 17122 17123Inside a shell function, you should not rely on the error status of a 17124subshell if the last command of that subshell was @code{exit} or 17125@code{trap}, as this triggers bugs in zsh 4.x; while Autoconf tries to 17126find a shell that does not exhibit the bug, zsh might be the only shell 17127present on the user's machine. 17128 17129Likewise, the state of @samp{$?} is not reliable when entering a shell 17130function. This has the effect that using a function as the first 17131command in a @command{trap} handler can cause problems. 17132 17133@example 17134$ @kbd{bash -c 'foo() @{ echo $?; @}; trap foo 0; (exit 2); exit 2'; echo $?} 171352 171362 17137$ @kbd{ash -c 'foo() @{ echo $?; @}; trap foo 0; (exit 2); exit 2'; echo $?} 171380 171392 17140@end example 17141 17142DJGPP bash 2.04 has a bug in that @command{return} from a 17143shell function which also used a command substitution causes a 17144segmentation fault. To work around the issue, you can use 17145@command{return} from a subshell, or @samp{AS_SET_STATUS} as last command 17146in the execution flow of the function (@pxref{Common Shell Constructs}). 17147 17148Not all shells treat shell functions as simple commands impacted by 17149@samp{set -e}, for example with Solaris 10 @command{/bin/sh}: 17150 17151@example 17152$ @kbd{bash -c 'f() @{ return 1; @}; set -e; f; echo oops'} 17153$ @kbd{/bin/sh -c 'f() @{ return 1; @}; set -e; f; echo oops'} 17154oops 17155@end example 17156 17157Shell variables and functions may share the same namespace, for example 17158with Solaris 10 @command{/bin/sh}: 17159 17160@example 17161$ @kbd{f () @{ :; @}; f=; f} 17162f: not found 17163@end example 17164 17165@noindent 17166For this reason, Autoconf (actually M4sh, @pxref{Programming in M4sh}) 17167uses the prefix @samp{as_fn_} for its functions. 17168 17169Handling of positional parameters and shell options varies among shells. 17170For example, Korn shells reset and restore trace output (@samp{set -x}) 17171and other options upon function entry and exit. Inside a function, 17172IRIX sh sets @samp{$0} to the function name. 17173 17174It is not portable to pass temporary environment variables to shell 17175functions. Solaris @command{/bin/sh} does not see the variable. 17176Meanwhile, not all shells follow the Posix rule that the assignment must 17177affect the current environment in the same manner as special built-ins. 17178 17179@example 17180$ @kbd{/bin/sh -c 'func() @{ echo $a;@}; a=1 func; echo $a'} 17181@result{} 17182@result{} 17183$ @kbd{ash -c 'func() @{ echo $a;@}; a=1 func; echo $a'} 17184@result{}1 17185@result{} 17186$ @kbd{bash -c 'set -o posix; func() @{ echo $a;@}; a=1 func; echo $a'} 17187@result{}1 17188@result{}1 17189@end example 17190 17191Some ancient Bourne shell variants with function support did not reset 17192@samp{$@var{i}, @var{i} >= 0}, upon function exit, so effectively the 17193arguments of the script were lost after the first function invocation. 17194It is probably not worth worrying about these shells any more. 17195 17196With AIX sh, a @command{trap} on 0 installed in a shell function 17197triggers at function exit rather than at script exit. @xref{trap, , 17198Limitations of Shell Builtins}. 17199 17200@node Limitations of Builtins 17201@section Limitations of Shell Builtins 17202@cindex Shell builtins 17203@cindex Limitations of shell builtins 17204 17205No, no, we are serious: some shells do have limitations! :) 17206 17207You should always keep in mind that any builtin or command may support 17208options, and therefore differ in behavior with arguments 17209starting with a dash. For instance, even the innocent @samp{echo "$word"} 17210can give unexpected results when @code{word} starts with a dash. It is 17211often possible to avoid this problem using @samp{echo "x$word"}, taking 17212the @samp{x} into account later in the pipe. Many of these limitations 17213can be worked around using M4sh (@pxref{Programming in M4sh}). 17214 17215@c This table includes things like `@command{test} (files)', so we can't 17216@c use @table @command. 17217@table @asis 17218@item @command{.} 17219@c -------------- 17220@prindex @command{.} 17221Use @command{.} only with regular files (use @samp{test -f}). Bash 172222.03, for instance, chokes on @samp{. /dev/null}. Remember that 17223@command{.} uses @env{PATH} if its argument contains no slashes. Also, 17224some shells, including bash 3.2, implicitly append the current directory 17225to this @env{PATH} search, even though Posix forbids it. So if you want 17226to use @command{.} on a file @file{foo} in the current directory, you 17227must use @samp{. ./foo}. 17228 17229Not all shells gracefully handle syntax errors within a sourced file. 17230On one extreme, some non-interactive shells abort the entire script. On 17231the other, @command{zsh} 4.3.10 has a bug where it fails to react to the 17232syntax error. 17233 17234@example 17235$ @kbd{echo 'fi' > syntax} 17236$ @kbd{bash -c '. ./syntax; echo $?'} 17237./syntax: line 1: syntax error near unexpected token `fi' 17238./syntax: line 1: `fi' 172391 17240$ @kbd{ash -c '. ./syntax; echo $?'} 17241./syntax: 1: Syntax error: "fi" unexpected 17242$ @kbd{zsh -c '. ./syntax; echo $?'} 17243./syntax:1: parse error near `fi' 172440 17245@end example 17246 17247@item @command{!} 17248@c -------------- 17249@prindex @command{!} 17250The Unix version 7 shell did not support 17251negating the exit status of commands with @command{!}, and this feature 17252is still absent from some shells (e.g., Solaris @command{/bin/sh}). 17253Other shells, such as FreeBSD @command{/bin/sh} or @command{ash}, have 17254bugs when using @command{!}: 17255 17256@example 17257$ @kbd{sh -c '! : | :'; echo $?} 172581 17259$ @kbd{ash -c '! : | :'; echo $?} 172600 17261$ @kbd{sh -c '! @{ :; @}'; echo $?} 172621 17263$ @kbd{ash -c '! @{ :; @}'; echo $?} 17264@{: not found 17265Syntax error: "@}" unexpected 172662 17267@end example 17268 17269Shell code like this: 17270 17271@example 17272if ! cmp file1 file2 >/dev/null 2>&1; then 17273 echo files differ or trouble 17274fi 17275@end example 17276 17277is therefore not portable in practice. Typically it is easy to rewrite 17278such code, e.g.: 17279 17280@example 17281cmp file1 file2 >/dev/null 2>&1 || 17282 echo files differ or trouble 17283@end example 17284 17285More generally, one can always rewrite @samp{! @var{command}} as: 17286 17287@example 17288if @var{command}; then (exit 1); else :; fi 17289@end example 17290 17291 17292@item @command{@{...@}} 17293@c -------------------- 17294@prindex @command{@{...@}} 17295Bash 3.2 (and earlier versions) sometimes does not properly set 17296@samp{$?} when failing to write redirected output of a compound command. 17297This problem is most commonly observed with @samp{@{@dots{}@}}; it does 17298not occur with @samp{(@dots{})}. For example: 17299 17300@example 17301$ @kbd{bash -c '@{ echo foo; @} >/bad; echo $?'} 17302bash: line 1: /bad: Permission denied 173030 17304$ @kbd{bash -c 'while :; do echo; done >/bad; echo $?'} 17305bash: line 1: /bad: Permission denied 173060 17307@end example 17308 17309To work around the bug, prepend @samp{:;}: 17310 17311@example 17312$ @kbd{bash -c ':;@{ echo foo; @} >/bad; echo $?'} 17313bash: line 1: /bad: Permission denied 173141 17315@end example 17316 17317Posix requires a syntax error if a brace list has no contents. However, 17318not all shells obey this rule; and on shells where empty lists are 17319permitted, the effect on @samp{$?} is inconsistent. To avoid problems, 17320ensure that a brace list is never empty. 17321 17322@example 17323$ @kbd{bash -c 'false; @{ @}; echo $?' || echo $?} 17324bash: line 1: syntax error near unexpected token `@}' 17325bash: line 1: `false; @{ @}; echo $?' 173262 17327$ @kbd{zsh -c 'false; @{ @}; echo $?' || echo $?} 173281 17329$ @kbd{pdksh -c 'false; @{ @}; echo $?' || echo $?} 173300 17331@end example 17332 17333 17334@item @command{break} 17335@c ------------------ 17336@prindex @command{break} 17337The use of @samp{break 2} etc.@: is safe. 17338 17339 17340@anchor{case} 17341@item @command{case} 17342@c ----------------- 17343@prindex @command{case} 17344You don't need to quote the argument; no splitting is performed. 17345 17346You don't need the final @samp{;;}, but you should use it. 17347 17348Posix requires support for @code{case} patterns with opening 17349parentheses like this: 17350 17351@example 17352case $file_name in 17353 (*.c) echo "C source code";; 17354esac 17355@end example 17356 17357@noindent 17358but the @code{(} in this example is not portable to many Bourne 17359shell implementations, which is a pity for those of us using tools that 17360rely on balanced parentheses. For instance, with Solaris 17361@command{/bin/sh}: 17362 17363@example 17364$ @kbd{case foo in (foo) echo foo;; esac} 17365@error{}syntax error: `(' unexpected 17366@end example 17367 17368@noindent 17369The leading @samp{(} can be omitted safely. Unfortunately, there are 17370contexts where unbalanced parentheses cause other problems, such as when 17371using a syntax-highlighting editor that searches for the balancing 17372counterpart, or more importantly, when using a case statement as an 17373underquoted argument to an Autoconf macro. @xref{Balancing 17374Parentheses}, for tradeoffs involved in various styles of dealing with 17375unbalanced @samp{)}. 17376 17377Zsh handles pattern fragments derived from parameter expansions or 17378command substitutions as though quoted: 17379 17380@example 17381$ pat=\?; case aa in ?$pat) echo match;; esac 17382$ pat=\?; case a? in ?$pat) echo match;; esac 17383match 17384@end example 17385 17386@noindent 17387Because of a bug in its @code{fnmatch}, Bash fails to properly 17388handle backslashes in character classes: 17389 17390@example 17391bash-2.02$ @kbd{case /tmp in [/\\]*) echo OK;; esac} 17392bash-2.02$ 17393@end example 17394 17395@noindent 17396This is extremely unfortunate, since you are likely to use this code to 17397handle Posix or MS-DOS absolute file names. To work around this 17398bug, always put the backslash first: 17399 17400@example 17401bash-2.02$ @kbd{case '\TMP' in [\\/]*) echo OK;; esac} 17402OK 17403bash-2.02$ @kbd{case /tmp in [\\/]*) echo OK;; esac} 17404OK 17405@end example 17406 17407Many Bourne shells cannot handle closing brackets in character classes 17408correctly. 17409 17410Some shells also have problems with backslash escaping in case you do not want 17411to match the backslash: both a backslash and the escaped character match this 17412pattern. To work around this, specify the character class in a variable, so 17413that quote removal does not apply afterwards, and the special characters don't 17414have to be backslash-escaped: 17415 17416@example 17417$ @kbd{case '\' in [\<]) echo OK;; esac} 17418OK 17419$ @kbd{scanset='[<]'; case '\' in $scanset) echo OK;; esac} 17420$ 17421@end example 17422 17423Even with this, Solaris @command{ksh} matches a backslash if the set 17424contains any 17425of the characters @samp{|}, @samp{&}, @samp{(}, or @samp{)}. 17426 17427Conversely, Tru64 @command{ksh} (circa 2003) erroneously always matches 17428a closing parenthesis if not specified in a character class: 17429 17430@example 17431$ @kbd{case foo in *\)*) echo fail ;; esac} 17432fail 17433$ @kbd{case foo in *')'*) echo fail ;; esac} 17434fail 17435@end example 17436 17437Some shells, such as Ash 0.3.8, are confused by an empty 17438@code{case}/@code{esac}: 17439 17440@example 17441ash-0.3.8 $ @kbd{case foo in esac;} 17442@error{}Syntax error: ";" unexpected (expecting ")") 17443@end example 17444 17445Posix requires @command{case} to give an exit status of 0 if no cases 17446match. However, @command{/bin/sh} in Solaris 10 does not obey this 17447rule. Meanwhile, it is unclear whether a case that matches, but 17448contains no statements, must also change the exit status to 0. The M4sh 17449macro @code{AS_CASE} works around these inconsistencies. 17450 17451@example 17452$ @kbd{bash -c 'case `false` in ?) ;; esac; echo $?'} 174530 17454$ @kbd{/bin/sh -c 'case `false` in ?) ;; esac; echo $?'} 17455255 17456@end example 17457 17458 17459@item @command{cd} 17460@c --------------- 17461@prindex @command{cd} 17462Posix 1003.1-2001 requires that @command{cd} must support 17463the @option{-L} (``logical'') and @option{-P} (``physical'') options, 17464with @option{-L} being the default. However, traditional shells do 17465not support these options, and their @command{cd} command has the 17466@option{-P} behavior. 17467 17468Portable scripts should assume neither option is supported, and should 17469assume neither behavior is the default. This can be a bit tricky, 17470since the Posix default behavior means that, for example, 17471@samp{ls ..} and @samp{cd ..} may refer to different directories if 17472the current logical directory is a symbolic link. It is safe to use 17473@code{cd @var{dir}} if @var{dir} contains no @file{..} components. 17474Also, Autoconf-generated scripts check for this problem when computing 17475variables like @code{ac_top_srcdir} (@pxref{Configuration Actions}), 17476so it is safe to @command{cd} to these variables. 17477 17478Posix states that behavior is undefined if @command{cd} is given an 17479explicit empty argument. Some shells do nothing, some change to the 17480first entry in @env{CDPATH}, some change to @env{HOME}, and some exit 17481the shell rather than returning an error. Unfortunately, this means 17482that if @samp{$var} is empty, then @samp{cd "$var"} is less predictable 17483than @samp{cd $var} (at least the latter is well-behaved in all shells 17484at changing to @env{HOME}, although this is probably not what you wanted 17485in a script). You should check that a directory name was supplied 17486before trying to change locations. 17487 17488@xref{Special Shell Variables}, for portability problems involving 17489@command{cd} and the @env{CDPATH} environment variable. 17490Also please see the discussion of the @command{pwd} command. 17491 17492 17493@anchor{echo} 17494@item @command{echo} 17495@c ----------------- 17496@prindex @command{echo} 17497The simple @command{echo} is probably the most surprising source of 17498portability troubles. It is not possible to use @samp{echo} portably 17499unless both options and escape sequences are omitted. Don't expect any 17500option. 17501 17502Do not use backslashes in the arguments, as there is no consensus on 17503their handling. For @samp{echo '\n' | wc -l}, the @command{sh} of 17504Solaris outputs 2, but Bash and Zsh (in @command{sh} emulation mode) output 1. 17505The problem is truly @command{echo}: all the shells 17506understand @samp{'\n'} as the string composed of a backslash and an 17507@samp{n}. Within a command substitution, @samp{echo 'string\c'} will 17508mess up the internal state of ksh88 on AIX 6.1 so that it will print 17509the first character @samp{s} only, followed by a newline, and then 17510entirely drop the output of the next echo in a command substitution. 17511 17512Because of these problems, do not pass a string containing arbitrary 17513characters to @command{echo}. For example, @samp{echo "$foo"} is safe 17514only if you know that @var{foo}'s value cannot contain backslashes and 17515cannot start with @samp{-}. 17516 17517If this may not be true, @command{printf} is in general safer and 17518easier to use than @command{echo} and @command{echo -n}. Thus, scripts 17519where portability is not a major concern should use @command{printf 17520'%s\n'} whenever @command{echo} could fail, and similarly use 17521@command{printf %s} instead of @command{echo -n}. For portable shell 17522scripts, instead, it is suggested to use a here-document like this: 17523 17524@example 17525cat <<EOF 17526$foo 17527EOF 17528@end example 17529 17530Alternatively, M4sh provides @code{AS_ECHO} and @code{AS_ECHO_N} macros 17531which choose between various portable implementations: @samp{echo} 17532or @samp{print} where they work, @command{printf} if it is available, 17533or else other creative tricks in order to work around the above problems. 17534 17535 17536@item @command{eval} 17537@c ----------------- 17538@prindex @command{eval} 17539The @command{eval} command is useful in limited circumstances, e.g., 17540using commands like @samp{eval table_$key=\$value} and @samp{eval 17541value=table_$key} to simulate a hash table when the key is known to be 17542alphanumeric. 17543 17544You should also be wary of common bugs in @command{eval} implementations. 17545In some shell implementations (e.g., older @command{ash}, OpenBSD 3.8 17546@command{sh}, @command{pdksh} v5.2.14 99/07/13.2, and @command{zsh} 175474.2.5), the arguments of @samp{eval} are evaluated in a context where 17548@samp{$?} is 0, so they exhibit behavior like this: 17549 17550@example 17551$ @kbd{false; eval 'echo $?'} 175520 17553@end example 17554 17555The correct behavior here is to output a nonzero value, 17556but portable scripts should not rely on this. 17557 17558You should not rely on @code{LINENO} within @command{eval}. 17559@xref{Special Shell Variables}. 17560 17561Note that, even though these bugs are easily avoided, 17562@command{eval} is tricky to use on arbitrary arguments. 17563It is obviously unwise to use @samp{eval $cmd} if the string value of 17564@samp{cmd} was derived from an untrustworthy source. But even if the 17565string value is valid, @samp{eval $cmd} might not work as intended, 17566since it causes field splitting and file name expansion to occur twice, 17567once for the @command{eval} and once for the command itself. It is 17568therefore safer to use @samp{eval "$cmd"}. For example, if @var{cmd} 17569has the value @samp{cat test?.c}, @samp{eval $cmd} might expand to the 17570equivalent of @samp{cat test;.c} if there happens to be a file named 17571@file{test;.c} in the current directory; and this in turn 17572mistakenly attempts to invoke @command{cat} on the file @file{test} and 17573then execute the command @command{.c}. To avoid this problem, use 17574@samp{eval "$cmd"} rather than @samp{eval $cmd}. 17575 17576However, suppose that you want to output the text of the evaluated 17577command just before executing it. Assuming the previous example, 17578@samp{echo "Executing: $cmd"} outputs @samp{Executing: cat test?.c}, but 17579this output doesn't show the user that @samp{test;.c} is the actual name 17580of the copied file. Conversely, @samp{eval "echo Executing: $cmd"} 17581works on this example, but it fails with @samp{cmd='cat foo >bar'}, 17582since it mistakenly replaces the contents of @file{bar} by the 17583string @samp{cat foo}. No simple, general, and portable solution to 17584this problem is known. 17585 17586@item @command{exec} 17587@c ----------------- 17588@prindex @command{exec} 17589Posix describes several categories of shell built-ins. Special 17590built-ins (such as @command{exit}) must impact the environment of the 17591current shell, and need not be available through @command{exec}. All 17592other built-ins are regular, and must not propagate variable assignments 17593to the environment of the current shell. However, the group of regular 17594built-ins is further distinguished by commands that do not require a 17595@env{PATH} search (such as @command{cd}), in contrast to built-ins that 17596are offered as a more efficient version of something that must still be 17597found in a @env{PATH} search (such as @command{echo}). Posix is not 17598clear on whether @command{exec} must work with the list of 17 utilities 17599that are invoked without a @env{PATH} search, and many platforms lack an 17600executable for some of those built-ins: 17601 17602@example 17603$ @kbd{sh -c 'exec cd /tmp'} 17604sh: line 0: exec: cd: not found 17605@end example 17606 17607All other built-ins that provide utilities specified by Posix must have 17608a counterpart executable that exists on @env{PATH}, although Posix 17609allows @command{exec} to use the built-in instead of the executable. 17610For example, contrast @command{bash} 3.2 and @command{pdksh} 5.2.14: 17611 17612@example 17613$ @kbd{bash -c 'pwd --version' | head -n1} 17614bash: line 0: pwd: --: invalid option 17615pwd: usage: pwd [-LP] 17616$ @kbd{bash -c 'exec pwd --version' | head -n1} 17617pwd (GNU coreutils) 6.10 17618$ @kbd{pdksh -c 'exec pwd --version' | head -n1} 17619pdksh: pwd: --: unknown option 17620@end example 17621 17622When it is desired to avoid a regular shell built-in, the workaround is 17623to use some other forwarding command, such as @command{env} or 17624@command{nice}, that will ensure a path search: 17625 17626@example 17627$ @kbd{pdksh -c 'exec true --version' | head -n1} 17628$ @kbd{pdksh -c 'nice true --version' | head -n1} 17629true (GNU coreutils) 6.10 17630$ @kbd{pdksh -c 'env true --version' | head -n1} 17631true (GNU coreutils) 6.10 17632@end example 17633 17634@item @command{exit} 17635@c ----------------- 17636@prindex @command{exit} 17637The default value of @command{exit} is supposed to be @code{$?}; 17638unfortunately, some shells, such as the DJGPP port of Bash 2.04, just 17639perform @samp{exit 0}. 17640 17641@example 17642bash-2.04$ @kbd{foo=`exit 1` || echo fail} 17643fail 17644bash-2.04$ @kbd{foo=`(exit 1)` || echo fail} 17645fail 17646bash-2.04$ @kbd{foo=`(exit 1); exit` || echo fail} 17647bash-2.04$ 17648@end example 17649 17650Using @samp{exit $?} restores the expected behavior. 17651 17652Some shell scripts, such as those generated by @command{autoconf}, use a 17653trap to clean up before exiting. If the last shell command exited with 17654nonzero status, the trap also exits with nonzero status so that the 17655invoker can tell that an error occurred. 17656 17657Unfortunately, in some shells, such as Solaris @command{/bin/sh}, an exit 17658trap ignores the @code{exit} command's argument. In these shells, a trap 17659cannot determine whether it was invoked by plain @code{exit} or by 17660@code{exit 1}. Instead of calling @code{exit} directly, use the 17661@code{AC_MSG_ERROR} macro that has a workaround for this problem. 17662 17663 17664@anchor{export} 17665@item @command{export} 17666@c ------------------- 17667@prindex @command{export} 17668The builtin @command{export} dubs a shell variable @dfn{environment 17669variable}. Each update of exported variables corresponds to an update 17670of the environment variables. Conversely, each environment variable 17671received by the shell when it is launched should be imported as a shell 17672variable marked as exported. 17673 17674Alas, many shells, such as Solaris @command{/bin/sh}, 17675IRIX 6.3, IRIX 5.2, 17676AIX 4.1.5, and Digital Unix 4.0, forget to 17677@command{export} the environment variables they receive. As a result, 17678two variables coexist: the environment variable and the shell 17679variable. The following code demonstrates this failure: 17680 17681@example 17682#!/bin/sh 17683echo $FOO 17684FOO=bar 17685echo $FOO 17686exec /bin/sh $0 17687@end example 17688 17689@noindent 17690when run with @samp{FOO=foo} in the environment, these shells print 17691alternately @samp{foo} and @samp{bar}, although they should print only 17692@samp{foo} and then a sequence of @samp{bar}s. 17693 17694Therefore you should @command{export} again each environment variable 17695that you update; the export can occur before or after the assignment. 17696 17697Posix is not clear on whether the @command{export} of an undefined 17698variable causes the variable to be defined with the value of an empty 17699string, or merely marks any future definition of a variable by that name 17700for export. Various shells behave differently in this regard: 17701 17702@example 17703$ @kbd{sh -c 'export foo; env | grep foo'} 17704$ @kbd{ash -c 'export foo; env | grep foo'} 17705foo= 17706@end example 17707 17708Posix requires @command{export} to honor assignments made as arguments, 17709but older shells do not support this, including @command{/bin/sh} in 17710Solaris 10. Portable scripts should separate assignments and exports 17711into different statements. 17712 17713@example 17714$ @kbd{bash -c 'export foo=bar; echo $foo'} 17715bar 17716$ @kbd{/bin/sh -c 'export foo=bar; echo $foo'} 17717/bin/sh: foo=bar: is not an identifier 17718$ @kbd{/bin/sh -c 'export foo; foo=bar; echo $foo'} 17719bar 17720@end example 17721 17722@item @command{false} 17723@c ------------------ 17724@prindex @command{false} 17725Don't expect @command{false} to exit with status 1: in native 17726Solaris @file{/bin/false} exits with status 255. 17727 17728 17729@item @command{for} 17730@c ---------------- 17731@prindex @command{for} 17732To loop over positional arguments, use: 17733 17734@example 17735for arg 17736do 17737 echo "$arg" 17738done 17739@end example 17740 17741@noindent 17742You may @emph{not} leave the @code{do} on the same line as @code{for}, 17743since some shells improperly grok: 17744 17745@example 17746for arg; do 17747 echo "$arg" 17748done 17749@end example 17750 17751If you want to explicitly refer to the positional arguments, given the 17752@samp{$@@} bug (@pxref{Shell Substitutions}), use: 17753 17754@example 17755for arg in $@{1+"$@@"@}; do 17756 echo "$arg" 17757done 17758@end example 17759 17760@noindent 17761But keep in mind that Zsh, even in Bourne shell emulation mode, performs 17762word splitting on @samp{$@{1+"$@@"@}}; see @ref{Shell Substitutions}, 17763item @samp{$@@}, for more. 17764 17765In Solaris @command{/bin/sh}, when the list of arguments of a 17766@command{for} loop starts with @emph{unquoted} tokens looking like 17767variable assignments, the loop is not executed on those tokens: 17768 17769@example 17770$ @kbd{/bin/sh -c 'for v in a=b c=d x e=f; do echo $v; done'} 17771x 17772e=f 17773@end example 17774 17775@noindent 17776Thankfully, quoting the assignment-like tokens, or starting the list 17777with other tokens (including unquoted variable expansion that results in 17778an assignment-like result), avoids the problem, so it is easy to work 17779around: 17780 17781@example 17782$ @kbd{/bin/sh -c 'for v in "a=b"; do echo $v; done'} 17783a=b 17784$ @kbd{/bin/sh -c 'x=a=b; for v in $x c=d; do echo $v; done'} 17785a=b 17786c=d 17787@end example 17788 17789@anchor{if} 17790@item @command{if} 17791@c --------------- 17792@prindex @command{if} 17793Using @samp{!} is not portable. Instead of: 17794 17795@example 17796if ! cmp -s file file.new; then 17797 mv file.new file 17798fi 17799@end example 17800 17801@noindent 17802use: 17803 17804@example 17805if cmp -s file file.new; then :; else 17806 mv file.new file 17807fi 17808@end example 17809 17810@noindent 17811Or, especially if the @dfn{else} branch is short, you can use @code{||}. 17812In M4sh, the @code{AS_IF} macro provides an easy way to write these kinds 17813of conditionals: 17814 17815@example 17816AS_IF([cmp -s file file.new], [], [mv file.new file]) 17817@end example 17818 17819This is especially useful in other M4 macros, where the @dfn{then} and 17820@dfn{else} branches might be macro arguments. 17821 17822Some very old shells did not reset the exit status from an @command{if} 17823with no @command{else}: 17824 17825@example 17826$ @kbd{if (exit 42); then true; fi; echo $?} 1782742 17828@end example 17829 17830@noindent 17831whereas a proper shell should have printed @samp{0}. But this is no 17832longer a portability problem; any shell that supports functions gets it 17833correct. However, it explains why some makefiles have lengthy 17834constructs: 17835 17836@example 17837if test -f "$file"; then 17838 install "$file" "$dest" 17839else 17840 : 17841fi 17842@end example 17843 17844 17845@item @command{printf} 17846@c ------------------ 17847@prindex @command{printf} 17848A format string starting with a @samp{-} can cause problems. 17849Bash interprets it as an option and 17850gives an error. And @samp{--} to mark the end of options is not good 17851in the NetBSD Almquist shell (e.g., 0.4.6) which takes that 17852literally as the format string. Putting the @samp{-} in a @samp{%c} 17853or @samp{%s} is probably easiest: 17854 17855@example 17856printf %s -foo 17857@end example 17858 17859Bash 2.03 mishandles an escape sequence that happens to evaluate to @samp{%}: 17860 17861@example 17862$ @kbd{printf '\045'} 17863bash: printf: `%': missing format character 17864@end example 17865 17866Large outputs may cause trouble. On Solaris 2.5.1 through 10, for 17867example, @file{/usr/bin/printf} is buggy, so when using 17868@command{/bin/sh} the command @samp{printf %010000x 123} normally dumps 17869core. 17870 17871Since @command{printf} is not always a shell builtin, there is a 17872potential speed penalty for using @code{printf '%s\n'} as a replacement 17873for an @command{echo} that does not interpret @samp{\} or leading 17874@samp{-}. With Solaris @command{ksh}, it is possible to use @code{print 17875-r --} for this role instead. 17876 17877@xref{echo, , Limitations of Shell Builtins} for a discussion of 17878portable alternatives to both @command{printf} and @command{echo}. 17879 17880 17881@item @command{pwd} 17882@c ---------------- 17883@prindex @command{pwd} 17884With modern shells, plain @command{pwd} outputs a ``logical'' 17885directory name, some of whose components may be symbolic links. These 17886directory names are in contrast to ``physical'' directory names, whose 17887components are all directories. 17888 17889Posix 1003.1-2001 requires that @command{pwd} must support 17890the @option{-L} (``logical'') and @option{-P} (``physical'') options, 17891with @option{-L} being the default. However, traditional shells do 17892not support these options, and their @command{pwd} command has the 17893@option{-P} behavior. 17894 17895Portable scripts should assume neither option is supported, and should 17896assume neither behavior is the default. Also, on many hosts 17897@samp{/bin/pwd} is equivalent to @samp{pwd -P}, but Posix 17898does not require this behavior and portable scripts should not rely on 17899it. 17900 17901Typically it's best to use plain @command{pwd}. On modern hosts this 17902outputs logical directory names, which have the following advantages: 17903 17904@itemize @bullet 17905@item 17906Logical names are what the user specified. 17907@item 17908Physical names may not be portable from one installation 17909host to another due to network file system gymnastics. 17910@item 17911On modern hosts @samp{pwd -P} may fail due to lack of permissions to 17912some parent directory, but plain @command{pwd} cannot fail for this 17913reason. 17914@end itemize 17915 17916Also please see the discussion of the @command{cd} command. 17917 17918 17919@item @command{read} 17920@c ----------------- 17921@prindex @command{read} 17922No options are portable, not even support @option{-r} (Solaris 17923@command{/bin/sh} for example). Tru64/OSF 5.1 @command{sh} treats 17924@command{read} as a special built-in, so it may exit if input is 17925redirected from a non-existent or unreadable file. 17926 17927 17928@anchor{set} 17929@item @command{set} 17930@c ---------------- 17931@prindex @command{set} 17932With the FreeBSD 6.0 shell, the @command{set} command (without 17933any options) does not sort its output. 17934 17935The @command{set} builtin faces the usual problem with arguments 17936starting with a 17937dash. Modern shells such as Bash or Zsh understand @option{--} to specify 17938the end of the options (any argument after @option{--} is a parameter, 17939even @samp{-x} for instance), but many traditional shells (e.g., Solaris 1794010 @command{/bin/sh}) simply stop option 17941processing as soon as a non-option argument is found. Therefore, use 17942@samp{dummy} or simply @samp{x} to end the option processing, and use 17943@command{shift} to pop it out: 17944 17945@example 17946set x $my_list; shift 17947@end example 17948 17949Avoid @samp{set -}, e.g., @samp{set - $my_list}. Posix no 17950longer requires support for this command, and in traditional shells 17951@samp{set - $my_list} resets the @option{-v} and @option{-x} options, which 17952makes scripts harder to debug. 17953 17954Some nonstandard shells do not recognize more than one option 17955(e.g., @samp{set -e -x} assigns @samp{-x} to the command line). It is 17956better to combine them: 17957 17958@example 17959set -ex 17960@end example 17961 17962@cindex @command{set -e} 17963The option @option{-e} has historically been underspecified, with enough 17964ambiguities to cause numerous differences across various shell 17965implementations; see for example 17966@uref{http://www.in-ulm.de/@/~mascheck/@/various/@/set-e/, this overview}, 17967or @uref{http://www.austingroupbugs.net/@/view.php?id=52, this link}, 17968documenting a change to Posix 2008 to match @command{ksh88} behavior. 17969Note that mixing @code{set -e} and shell functions is asking for surprises: 17970 17971@example 17972set -e 17973doit() 17974@{ 17975 rm file 17976 echo one 17977@} 17978doit || echo two 17979@end example 17980 17981@noindent 17982According to the recommendation, @samp{one} should always be output 17983regardless of whether the @command{rm} failed, because it occurs within 17984the body of the shell function @samp{doit} invoked on the left side of 17985@samp{||}, where the effects of @samp{set -e} are not enforced. 17986Likewise, @samp{two} should never be printed, since the failure of 17987@command{rm} does not abort the function, such that the status of 17988@samp{doit} is 0. 17989 17990The BSD shell has had several problems with the @option{-e} 17991option. Older versions of the BSD 17992shell (circa 1990) mishandled @samp{&&}, @samp{||}, @samp{if}, and 17993@samp{case} when @option{-e} was in effect, causing the shell to exit 17994unexpectedly in some cases. This was particularly a problem with 17995makefiles, and led to circumlocutions like @samp{sh -c 'test -f file || 17996touch file'}, where the seemingly-unnecessary @samp{sh -c '@dots{}'} 17997wrapper works around the bug (@pxref{Failure in Make Rules}). 17998 17999Even relatively-recent versions of the BSD shell (e.g., OpenBSD 3.4) 18000wrongly exit with @option{-e} if the last command within a compound 18001statement fails and is guarded by an @samp{&&} only. For example: 18002 18003@example 18004#! /bin/sh 18005set -e 18006foo='' 18007test -n "$foo" && exit 1 18008echo one 18009if :; then 18010 test -n "$foo" && exit 1 18011 echo two 18012 test -n "$foo" && exit 1 18013fi 18014echo three 18015@end example 18016 18017@noindent 18018does not print @samp{three}. One workaround is to change the last 18019instance of @samp{test -n "$foo" && exit 1} to be @samp{if test -n 18020"$foo"; then exit 1; fi} instead. Another possibility is to warn BSD 18021users not to use @samp{sh -e}. 18022 18023When @samp{set -e} is in effect, a failed command substitution in 18024Solaris @command{/bin/sh} cannot be ignored, even with @samp{||}. 18025 18026@example 18027$ @kbd{/bin/sh -c 'set -e; foo=`false` || echo foo; echo bar'} 18028$ @kbd{bash -c 'set -e; foo=`false` || echo foo; echo bar'} 18029foo 18030bar 18031@end example 18032 18033@noindent 18034Moreover, a command substitution, successful or not, causes this shell to 18035exit from a failing outer command even in presence of an @samp{&&} list: 18036 18037@example 18038$ @kbd{bash -c 'set -e; false `true` && echo notreached; echo ok'} 18039ok 18040$ @kbd{sh -c 'set -e; false `true` && echo notreached; echo ok'} 18041$ 18042@end example 18043 18044Portable scripts should not use @samp{set -e} if @command{trap} is used 18045to install an exit handler. This is because Tru64/OSF 5.1 @command{sh} 18046sometimes enters the trap handler with the exit status of the command 18047prior to the one that triggered the errexit handler: 18048 18049@example 18050$ @kbd{sh -ec 'trap '\''echo $?'\'' 0; false'} 180510 18052$ @kbd{sh -c 'set -e; trap '\''echo $?'\'' 0; false'} 180531 18054@end example 18055 18056@noindent 18057Thus, when writing a script in M4sh, rather than trying to rely on 18058@samp{set -e}, it is better to append @samp{|| AS_EXIT} to any 18059statement where it is desirable to abort on failure. 18060 18061@cindex @command{set -b} 18062@cindex @command{set -m} 18063Job control is not provided by all shells, so the use of @samp{set -m} 18064or @samp{set -b} must be done with care. When using @command{zsh} in 18065native mode, asynchronous notification (@samp{set -b}) is enabled by 18066default, and using @samp{emulate sh} to switch to Posix mode does not 18067clear this setting (although asynchronous notification has no impact 18068unless job monitoring is also enabled). Also, @command{zsh} 4.3.10 and 18069earlier have a bug where job control can be manipulated in interactive 18070shells, but not in subshells or scripts. Furthermore, some shells, like 18071@command{pdksh}, fail to treat subshells as interactive, even though the 18072parent shell was. 18073 18074@example 18075$ @kbd{echo $ZSH_VERSION} 180764.3.10 18077$ @kbd{set -m; echo $?} 180780 18079$ @kbd{zsh -c 'set -m; echo $?'} 18080set: can't change option: -m 18081$ @kbd{(set -m); echo $?} 18082set: can't change option: -m 180831 18084$ @kbd{pdksh -ci 'echo $-; (echo $-)'} 18085cim 18086c 18087@end example 18088 18089@cindex @command{set -n} 18090Use of @command{set -n} (typically via @command{sh -n script}) to 18091validate a script is not foolproof. Modern @command{ksh93} tries to be 18092helpful by informing you about better syntax, but switching the script 18093to use the suggested syntax in order to silence the warnings would 18094render the script no longer portable to older shells: 18095 18096@example 18097$ @kbd{ksh -nc '``'} 18098ksh: warning: line 1: `...` obsolete, use $(...) 180990 18100@end example 18101 18102Furthermore, on ancient hosts, such as SunOS 4, @command{sh -n} could go 18103into an infinite loop; even with that bug fixed, Solaris 8 18104@command{/bin/sh} takes extremely long to parse large scripts. Autoconf 18105itself uses @command{sh -n} within its testsuite to check that correct 18106scripts were generated, but only after first probing for other shell 18107features (such as @code{test -n "$@{BASH_VERSION+set@}"}) that indicate 18108a reasonably fast and working implementation. 18109 18110@item @command{shift} 18111@c ------------------ 18112@prindex @command{shift} 18113Not only is @command{shift}ing a bad idea when there is nothing left to 18114shift, but in addition it is not portable: the shell of MIPS 18115RISC/OS 4.52 refuses to do it. 18116 18117Don't use @samp{shift 2} etc.; while it in the SVR1 shell (1983), 18118it is also absent in many pre-Posix shells. 18119 18120 18121@item @command{source} 18122@c ------------------- 18123@prindex @command{source} 18124This command is not portable, as Posix does not require it; use 18125@command{.} instead. 18126 18127 18128@item @command{test} 18129@c ----------------- 18130@prindex @command{test} 18131The @code{test} program is the way to perform many file and string 18132tests. It is often invoked by the alternate name @samp{[}, but using 18133that name in Autoconf code is asking for trouble since it is an M4 quote 18134character. 18135 18136The @option{-a}, @option{-o}, @samp{(}, and @samp{)} operands are not 18137present in all implementations, and have been marked obsolete by Posix 181382008. This is because there are inherent ambiguities in using them. 18139For example, @samp{test "$1" -a "$2"} looks like a binary operator to 18140check whether two strings are both non-empty, but if @samp{$1} is the 18141literal @samp{!}, then some implementations of @command{test} treat it 18142as a negation of the unary operator @option{-a}. 18143 18144Thus, portable uses of @command{test} should never have more than four 18145arguments, and scripts should use shell constructs like @samp{&&} and 18146@samp{||} instead. If you combine @samp{&&} and @samp{||} in the same 18147statement, keep in mind that they have equal precedence, so it is often 18148better to parenthesize even when this is redundant. For example: 18149 18150@smallexample 18151# Not portable: 18152test "X$a" = "X$b" -a \ 18153 '(' "X$c" != "X$d" -o "X$e" = "X$f" ')' 18154 18155# Portable: 18156test "X$a" = "X$b" && 18157 @{ test "X$c" != "X$d" || test "X$e" = "X$f"; @} 18158@end smallexample 18159 18160@command{test} does not process options like most other commands do; for 18161example, it does not recognize the @option{--} argument as marking the 18162end of options. 18163 18164It is safe to use @samp{!} as a @command{test} operator. For example, 18165@samp{if test ! -d foo; @dots{}} is portable even though @samp{if ! test 18166-d foo; @dots{}} is not. 18167 18168 18169@item @command{test} (files) 18170@c ------------------------- 18171To enable @command{configure} scripts to support cross-compilation, they 18172shouldn't do anything that tests features of the build system instead of 18173the host system. But occasionally you may find it necessary to check 18174whether some arbitrary file exists. To do so, use @samp{test -f}, 18175@samp{test -r}, or @samp{test -x}. Do not use @samp{test -e}, because 18176Solaris 10 @command{/bin/sh} 18177lacks it. To test for symbolic links on systems that have them, use 18178@samp{test -h} rather than @samp{test -L}; either form conforms to 18179Posix 1003.1-2001, but older shells like Solaris 8 18180@code{/bin/sh} support only @option{-h}. 18181 18182For historical reasons, Posix reluctantly allows implementations of 18183@samp{test -x} that will succeed for the root user, even if no execute 18184permissions are present. Furthermore, shells do not all agree on 18185whether Access Control Lists should affect @samp{test -r}, @samp{test 18186-w}, and @samp{test -x}; some shells base test results strictly on the 18187current user id compared to file owner and mode, as if by 18188@code{stat(2)}; while other shells base test results on whether the 18189current user has the given right, even if that right is only granted by 18190an ACL, as if by @code{faccessat(2)}. Furthermore, there is a classic 18191time of check to time of use race between any use of @command{test} 18192followed by operating on the just-checked file. Therefore, it is a good 18193idea to write scripts that actually attempt an operation, and are 18194prepared for the resulting failure if permission is denied, rather than 18195trying to avoid an operation based solely on whether @command{test} 18196guessed that it might not be permitted. 18197 18198@item @command{test} (strings) 18199@c --------------------------- 18200Posix says that @samp{test "@var{string}"} succeeds if @var{string} is 18201not null, but this usage is not portable to traditional platforms like 18202Solaris 10 @command{/bin/sh}, which mishandle strings like @samp{!} and 18203@samp{-n}. 18204 18205Posix also says that @samp{test ! "@var{string}"}, 18206@samp{test -n "@var{string}"} and 18207@samp{test -z "@var{string}"} work with any string, but many 18208shells (such as Solaris, AIX 3.2, UNICOS 10.0.0.6, 18209Digital Unix 4, etc.)@: get confused if 18210@var{string} looks like an operator: 18211 18212@example 18213$ @kbd{test -n =} 18214test: argument expected 18215$ @kbd{test ! -n} 18216test: argument expected 18217$ @kbd{test -z ")"; echo $?} 182180 18219@end example 18220 18221Similarly, Posix says that both @samp{test "@var{string1}" = "@var{string2"}} 18222and @samp{test "@var{string1}" != "@var{string2"}} work for any pairs of 18223strings, but in practice this is not true for troublesome strings that 18224look like operators or parentheses, or that begin with @samp{-}. 18225 18226It is best to protect such strings with a leading @samp{X}, e.g., 18227@samp{test "X@var{string}" != X} rather than @samp{test -n 18228"@var{string}"} or @samp{test ! "@var{string}"}. 18229 18230It is common to find variations of the following idiom: 18231 18232@example 18233test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" && 18234 @var{action} 18235@end example 18236 18237@noindent 18238to take an action when a token matches a given pattern. Such constructs 18239should be avoided by using: 18240 18241@example 18242case $ac_feature in 18243 *[!-a-zA-Z0-9_]*) @var{action};; 18244esac 18245@end example 18246 18247If the pattern is a complicated regular expression that cannot be 18248expressed as a shell pattern, use something like this instead: 18249 18250@example 18251expr "X$ac_feature" : 'X.*[^-a-zA-Z0-9_]' >/dev/null && 18252 @var{action} 18253@end example 18254 18255@samp{expr "X@var{foo}" : "X@var{bar}"} is more robust than @samp{echo 18256"X@var{foo}" | grep "^X@var{bar}"}, because it avoids problems when 18257@samp{@var{foo}} contains backslashes. 18258 18259 18260@anchor{trap} 18261@item @command{trap} 18262@c ----------------- 18263@prindex @command{trap} 18264It is safe to trap at least the signals 1, 2, 13, and 15. You can also 18265trap 0, i.e., have the @command{trap} run when the script ends (either via an 18266explicit @command{exit}, or the end of the script). The trap for 0 should be 18267installed outside of a shell function, or AIX 5.3 @command{/bin/sh} 18268will invoke the trap at the end of this function. 18269 18270Posix says that @samp{trap - 1 2 13 15} resets the traps for the 18271specified signals to their default values, but many common shells (e.g., 18272Solaris @command{/bin/sh}) misinterpret this and attempt to execute a 18273``command'' named @command{-} when the specified conditions arise. 18274Posix 2008 also added a requirement to support @samp{trap 1 2 13 15} to 18275reset traps, as this is supported by a larger set of shells, but there 18276are still shells like @command{dash} that mistakenly try to execute 18277@command{1} instead of resetting the traps. Therefore, there is no 18278portable workaround, except for @samp{trap - 0}, for which 18279@samp{trap '' 0} is a portable substitute. 18280 18281Although Posix is not absolutely clear on this point, it is widely 18282admitted that when entering the trap @samp{$?} should be set to the exit 18283status of the last command run before the trap. The ambiguity can be 18284summarized as: ``when the trap is launched by an @command{exit}, what is 18285the @emph{last} command run: that before @command{exit}, or 18286@command{exit} itself?'' 18287 18288Bash considers @command{exit} to be the last command, while Zsh and 18289Solaris @command{/bin/sh} consider that when the trap is run it is 18290@emph{still} in the @command{exit}, hence it is the previous exit status 18291that the trap receives: 18292 18293@example 18294$ @kbd{cat trap.sh} 18295trap 'echo $?' 0 18296(exit 42); exit 0 18297$ @kbd{zsh trap.sh} 1829842 18299$ @kbd{bash trap.sh} 183000 18301@end example 18302 18303The portable solution is then simple: when you want to @samp{exit 42}, 18304run @samp{(exit 42); exit 42}, the first @command{exit} being used to 18305set the exit status to 42 for Zsh, and the second to trigger the trap 18306and pass 42 as exit status for Bash. In M4sh, this is covered by using 18307@code{AS_EXIT}. 18308 18309The shell in FreeBSD 4.0 has the following bug: @samp{$?} is 18310reset to 0 by empty lines if the code is inside @command{trap}. 18311 18312@example 18313$ @kbd{trap 'false} 18314 18315echo $?' 0 18316$ @kbd{exit} 183170 18318@end example 18319 18320@noindent 18321Fortunately, this bug only affects @command{trap}. 18322 18323Several shells fail to execute an exit trap that is defined inside a 18324subshell, when the last command of that subshell is not a builtin. A 18325workaround is to use @samp{exit $?} as the shell builtin. 18326 18327@example 18328$ @kbd{bash -c '(trap "echo hi" 0; /bin/true)'} 18329hi 18330$ @kbd{/bin/sh -c '(trap "echo hi" 0; /bin/true)'} 18331$ @kbd{/bin/sh -c '(trap "echo hi" 0; /bin/true; exit $?)'} 18332hi 18333@end example 18334 18335@noindent 18336Likewise, older implementations of @command{bash} failed to preserve 18337@samp{$?} across an exit trap consisting of a single cleanup command. 18338 18339@example 18340$ @kbd{bash -c 'trap "/bin/true" 0; exit 2'; echo $?} 183412 18342$ @kbd{bash-2.05b -c 'trap "/bin/true" 0; exit 2'; echo $?} 183430 18344$ @kbd{bash-2.05b -c 'trap ":; /bin/true" 0; exit 2'; echo $?} 183452 18346@end example 18347 18348@item @command{true} 18349@c ----------------- 18350@prindex @command{true} 18351@c Info cannot handle `:' in index entries. 18352@c @prindex @command{:} 18353Don't worry: as far as we know @command{true} is portable. 18354Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the 18355portable shell community tends to prefer using @command{:}. This has a 18356funny side effect: when asked whether @command{false} is more portable 18357than @command{true} Alexandre Oliva answered: 18358 18359@quotation 18360In a sense, yes, because if it doesn't exist, the shell will produce an 18361exit status of failure, which is correct for @command{false}, but not 18362for @command{true}. 18363@end quotation 18364 18365Remember that even though @samp{:} ignores its arguments, it still takes 18366time to compute those arguments. It is a good idea to use double quotes 18367around any arguments to @samp{:} to avoid time spent in field splitting 18368and file name expansion. 18369 18370 18371@anchor{unset} 18372@item @command{unset} 18373@c ------------------ 18374@prindex @command{unset} 18375In some nonconforming shells (e.g., Solaris 10 @command{/bin/ksh} and 18376@command{/usr/xpg4/bin/sh}, NetBSD 5.99.43 sh, or Bash 2.05a), 18377@code{unset FOO} fails when @code{FOO} is not set. This can interfere 18378with @code{set -e} operation. You can use 18379 18380@smallexample 18381FOO=; unset FOO 18382@end smallexample 18383 18384@noindent 18385if you are not sure that @code{FOO} is set. 18386 18387A few ancient shells lack @command{unset} entirely. For some variables 18388such as @code{PS1}, you can use a neutralizing value instead: 18389 18390@smallexample 18391PS1='$ ' 18392@end smallexample 18393 18394Usually, shells that do not support @command{unset} need less effort to 18395make the environment sane, so for example is not a problem if you cannot 18396unset @command{CDPATH} on those shells. However, Bash 2.01 mishandles 18397@code{unset MAIL} and @code{unset MAILPATH} in some cases and dumps core. 18398So, you should do something like 18399 18400@smallexample 18401( (unset MAIL) || exit 1) >/dev/null 2>&1 && unset MAIL || : 18402@end smallexample 18403 18404@noindent 18405@xref{Special Shell Variables}, for some neutralizing values. Also, see 18406@ref{export, , Limitations of Builtins}, for 18407the case of environment variables. 18408 18409@item @command{wait} 18410@c ----------------- 18411@prindex @command{wait} 18412The exit status of @command{wait} is not always reliable. 18413@end table 18414 18415@node Limitations of Usual Tools 18416@section Limitations of Usual Tools 18417@cindex Limitations of usual tools 18418 18419The small set of tools you can expect to find on any machine can still 18420include some limitations you should be aware of. 18421 18422@comment Between this list and the list of builtins above, we should 18423@comment mention all the tools in GNU Coding Standards ``Utilities in 18424@comment Makefiles''. 18425 18426@c This table includes things like `@command{expr} (|)', so we can't 18427@c use @table @command. 18428@table @asis 18429@anchor{awk} 18430@item @command{awk} 18431@c ---------------- 18432@prindex @command{awk} 18433Don't leave white space before the opening parenthesis in a user function call. 18434Posix does not allow this and GNU Awk rejects it: 18435 18436@example 18437$ @kbd{gawk 'function die () @{ print "Aaaaarg!" @} 18438 BEGIN @{ die () @}'} 18439gawk: cmd. line:2: BEGIN @{ die () @} 18440gawk: cmd. line:2: ^ parse error 18441$ @kbd{gawk 'function die () @{ print "Aaaaarg!" @} 18442 BEGIN @{ die() @}'} 18443Aaaaarg! 18444@end example 18445 18446Posix says that if a program contains only @samp{BEGIN} actions, and 18447contains no instances of @code{getline}, then the program merely 18448executes the actions without reading input. However, traditional Awk 18449implementations (such as Solaris 10 @command{awk}) read and discard 18450input in this case. Portable scripts can redirect input from 18451@file{/dev/null} to work around the problem. For example: 18452 18453@example 18454awk 'BEGIN @{print "hello world"@}' </dev/null 18455@end example 18456 18457Posix says that in an @samp{END} action, @samp{$NF} (and presumably, 18458@samp{$1}) retain their value from the last record read, if no 18459intervening @samp{getline} occurred. However, some implementations 18460(such as Solaris 10 @samp{/usr/bin/awk}, @samp{nawk}, or Darwin 18461@samp{awk}) reset these variables. A workaround is to use an 18462intermediate variable prior to the @samp{END} block. For example: 18463 18464@example 18465$ @kbd{cat end.awk} 18466@{ tmp = $1 @} 18467END @{ print "a", $1, $NF, "b", tmp @} 18468$ @kbd{echo 1 | awk -f end.awk} 18469a b 1 18470$ @kbd{echo 1 | gawk -f end.awk} 18471a 1 1 b 1 18472@end example 18473 18474If you want your program to be deterministic, don't depend on @code{for} 18475on arrays: 18476 18477@example 18478$ @kbd{cat for.awk} 18479END @{ 18480 arr["foo"] = 1 18481 arr["bar"] = 1 18482 for (i in arr) 18483 print i 18484@} 18485$ @kbd{gawk -f for.awk </dev/null} 18486foo 18487bar 18488$ @kbd{nawk -f for.awk </dev/null} 18489bar 18490foo 18491@end example 18492 18493Some Awk implementations, such as HP-UX 11.0's native one, 18494mishandle anchors: 18495 18496@example 18497$ @kbd{echo xfoo | $AWK '/foo|^bar/ @{ print @}'} 18498$ @kbd{echo bar | $AWK '/foo|^bar/ @{ print @}'} 18499bar 18500$ @kbd{echo xfoo | $AWK '/^bar|foo/ @{ print @}'} 18501xfoo 18502$ @kbd{echo bar | $AWK '/^bar|foo/ @{ print @}'} 18503bar 18504@end example 18505 18506@noindent 18507Either do not depend on such patterns (i.e., use @samp{/^(.*foo|bar)/}, 18508or use a simple test to reject such implementations. 18509 18510On @samp{ia64-hp-hpux11.23}, Awk mishandles @code{printf} conversions 18511after @code{%u}: 18512 18513@example 18514$ @kbd{awk 'BEGIN @{ printf "%u %d\n", 0, -1 @}'} 185150 0 18516@end example 18517 18518AIX version 5.2 has an arbitrary limit of 399 on the 18519length of regular expressions and literal strings in an Awk program. 18520 18521Traditional Awk implementations derived from Unix version 7, such as 18522Solaris @command{/bin/awk}, have many limitations and do not 18523conform to Posix. Nowadays @code{AC_PROG_AWK} (@pxref{Particular 18524Programs}) finds you an Awk that doesn't have these problems, but if 18525for some reason you prefer not to use @code{AC_PROG_AWK} you may need to 18526address them. For more detailed descriptions, see @ref{Language 18527History, , @command{awk} language history, gawk, GNU Awk User's Guide}. 18528 18529Traditional Awk does not support multidimensional arrays or user-defined 18530functions. 18531 18532Traditional Awk does not support the @option{-v} option. You can use 18533assignments after the program instead, e.g., @code{$AWK '@{print v 18534$1@}' v=x}; however, don't forget that such assignments are not 18535evaluated until they are encountered (e.g., after any @code{BEGIN} 18536action). 18537 18538Traditional Awk does not support the keywords @code{delete} or @code{do}. 18539 18540Traditional Awk does not support the expressions 18541@code{@var{a}?@var{b}:@var{c}}, @code{!@var{a}}, @code{@var{a}^@var{b}}, 18542or @code{@var{a}^=@var{b}}. 18543 18544Traditional Awk does not support the predefined @code{CONVFMT} or 18545@code{ENVIRON} variables. 18546 18547Traditional Awk supports only the predefined functions @code{exp}, @code{index}, 18548@code{int}, @code{length}, @code{log}, @code{split}, @code{sprintf}, 18549@code{sqrt}, and @code{substr}. 18550 18551Traditional Awk @code{getline} is not at all compatible with Posix; 18552avoid it. 18553 18554Traditional Awk has @code{for (i in a) @dots{}} but no other uses of the 18555@code{in} keyword. For example, it lacks @code{if (i in a) @dots{}}. 18556 18557In code portable to both traditional and modern Awk, @code{FS} must be a 18558string containing just one ordinary character, and similarly for the 18559field-separator argument to @code{split}. 18560 18561Traditional Awk has a limit of 99 fields in a record. Since some Awk 18562implementations, like Tru64's, split the input even if you don't refer 18563to any field in the script, to circumvent this problem, set @samp{FS} 18564to an unusual character and use @code{split}. 18565 18566Traditional Awk has a limit of at most 99 bytes in a number formatted by 18567@code{OFMT}; for example, @code{OFMT="%.300e"; print 0.1;} typically 18568dumps core. 18569 18570The original version of Awk had a limit of at most 99 bytes per 18571@code{split} field, 99 bytes per @code{substr} substring, and 99 bytes 18572per run of non-special characters in a @code{printf} format, but these 18573bugs have been fixed on all practical hosts that we know of. 18574 18575HP-UX 11.00 and IRIX 6.5 Awk require that input files have a line length 18576of at most 3070 bytes. 18577 18578@item @command{basename} 18579@c --------------------- 18580@prindex @command{basename} 18581Not all hosts have a working @command{basename}. 18582You can use @command{expr} instead. 18583 18584@c AS_BASENAME is to be replaced by a better API. 18585@ignore 18586Not all hosts have a working @command{basename}, and you should instead 18587use @code{AS_BASENAME} (@pxref{Programming in M4sh}), followed by 18588@command{expr} if you need to strip a suffix. For example: 18589 18590@example 18591a=`basename "$aname"` # This is not portable. 18592a=`AS_BASENAME(["$aname"])` # This is more portable. 18593 18594# This is not portable. 18595c=`basename "$cname" .c` 18596 18597# This is more portable. 18598c=`AS_BASENAME(["$cname"])` 18599case $c in 18600?*.c) c=`expr "X$c" : 'X\(.*\)\.c'`;; 18601esac 18602@end example 18603@end ignore 18604 18605 18606@item @command{cat} 18607@c ---------------- 18608@prindex @command{cat} 18609Don't rely on any option. 18610 18611 18612@item @command{cc} 18613@c --------------- 18614@prindex @command{cc} 18615The command @samp{cc -c foo.c} traditionally produces an object file 18616named @file{foo.o}. Most compilers allow @option{-c} to be combined 18617with @option{-o} to specify a different object file name, but 18618Posix does not require this combination and a few compilers 18619lack support for it. @xref{C Compiler}, for how GNU Make 18620tests for this feature with @code{AC_PROG_CC_C_O}. 18621 18622When a compilation such as @samp{cc -o foo foo.c} fails, some compilers 18623(such as CDS on Reliant Unix) leave a @file{foo.o}. 18624 18625HP-UX @command{cc} doesn't accept @file{.S} files to preprocess and 18626assemble. @samp{cc -c foo.S} appears to succeed, but in fact does 18627nothing. 18628 18629The default executable, produced by @samp{cc foo.c}, can be 18630 18631@itemize 18632@item @file{a.out} --- usual Posix convention. 18633@item @file{b.out} --- i960 compilers (including @command{gcc}). 18634@item @file{a.exe} --- DJGPP port of @command{gcc}. 18635@item @file{a_out.exe} --- GNV @command{cc} wrapper for DEC C on OpenVMS. 18636@item @file{foo.exe} --- various MS-DOS compilers. 18637@end itemize 18638 18639The C compiler's traditional name is @command{cc}, but other names like 18640@command{gcc} are common. Posix 1003.1-2001 specifies the 18641name @command{c99}, but older Posix editions specified 18642@command{c89} and anyway these standard names are rarely used in 18643practice. Typically the C compiler is invoked from makefiles that use 18644@samp{$(CC)}, so the value of the @samp{CC} make variable selects the 18645compiler name. 18646 18647@item @command{chgrp} 18648@itemx @command{chown} 18649@c ------------------- 18650@prindex @command{chgrp} 18651@prindex @command{chown} 18652It is not portable to change a file's group to a group that the owner 18653does not belong to. 18654 18655@item @command{chmod} 18656@c ------------------ 18657@prindex @command{chmod} 18658Avoid usages like @samp{chmod -w file}; use @samp{chmod a-w file} 18659instead, for two reasons. First, plain @option{-w} does not necessarily 18660make the file unwritable, since it does not affect mode bits that 18661correspond to bits in the file mode creation mask. Second, 18662Posix says that the @option{-w} might be interpreted as an 18663implementation-specific option, not as a mode; Posix suggests 18664using @samp{chmod -- -w file} to avoid this confusion, but unfortunately 18665@samp{--} does not work on some older hosts. 18666 18667 18668@item @command{cmp} 18669@c ---------------- 18670@prindex @command{cmp} 18671@command{cmp} performs a raw data comparison of two files, while 18672@command{diff} compares two text files. Therefore, if you might compare 18673DOS files, even if only checking whether two files are different, use 18674@command{diff} to avoid spurious differences due to differences of 18675newline encoding. 18676 18677 18678@item @command{cp} 18679@c --------------- 18680@prindex @command{cp} 18681Avoid the @option{-r} option, since Posix 1003.1-2004 marks it as 18682obsolescent and its behavior on special files is implementation-defined. 18683Use @option{-R} instead. On GNU hosts the two options 18684are equivalent, but on Solaris hosts (for example) @code{cp -r} 18685reads from pipes instead of replicating them. AIX 5.3 @code{cp -R} may 18686corrupt its own memory with some directory hierarchies and error out or 18687dump core: 18688 18689@example 18690@kbd{mkdir -p 12345678/12345678/12345678/12345678} 18691@kbd{touch 12345678/12345678/x} 18692@kbd{cp -R 12345678 t} 18693cp: 0653-440 12345678/12345678/: name too long. 18694@end example 18695 18696Some @command{cp} implementations (e.g., BSD/OS 4.2) do not allow 18697trailing slashes at the end of nonexistent destination directories. To 18698avoid this problem, omit the trailing slashes. For example, use 18699@samp{cp -R source /tmp/newdir} rather than @samp{cp -R source 18700/tmp/newdir/} if @file{/tmp/newdir} does not exist. 18701 18702@c This is thanks to Ian. 18703The ancient SunOS 4 @command{cp} does not support @option{-f}, although 18704its @command{mv} does. 18705 18706@cindex timestamp resolution 18707Traditionally, file timestamps had 1-second resolution, and @samp{cp 18708-p} copied the timestamps exactly. However, many modern file systems 18709have timestamps with 1-nanosecond resolution. Unfortunately, some older 18710@samp{cp -p} implementations truncate timestamps when copying files, 18711which can cause the destination file to appear to be older than the 18712source. The exact amount of truncation depends on the resolution of 18713the system calls that @command{cp} uses. Traditionally this was 18714@code{utime}, which has 1-second resolution. Less-ancient @command{cp} 18715implementations such as GNU Core Utilities 5.0.91 (2003) use 18716@code{utimes}, which has 1-microsecond resolution. Modern 18717implementations such as GNU Core Utilities 6.12 (2008) can set timestamps to 18718the full nanosecond resolution, using the modern system calls 18719@code{futimens} and @code{utimensat} when they are available. As of 187202011, though, many platforms do not yet fully support these new system 18721calls. 18722 18723Bob Proulx notes that @samp{cp -p} always @emph{tries} to copy 18724ownerships. But whether it actually does copy ownerships or not is a 18725system dependent policy decision implemented by the kernel. If the 18726kernel allows it then it happens. If the kernel does not allow it then 18727it does not happen. It is not something @command{cp} itself has control 18728over. 18729 18730In Unix System V any user can chown files to any other user, and System 18731V also has a non-sticky @file{/tmp}. That probably derives from the 18732heritage of System V in a business environment without hostile users. 18733BSD changed this 18734to be a more secure model where only root can @command{chown} files and 18735a sticky @file{/tmp} is used. That undoubtedly derives from the heritage 18736of BSD in a campus environment. 18737 18738GNU/Linux and Solaris by default follow BSD, but 18739can be configured to allow a System V style @command{chown}. On the 18740other hand, HP-UX follows System V, but can 18741be configured to use the modern security model and disallow 18742@command{chown}. Since it is an administrator-configurable parameter 18743you can't use the name of the kernel as an indicator of the behavior. 18744 18745 18746 18747@item @command{date} 18748@c ----------------- 18749@prindex @command{date} 18750Some versions of @command{date} do not recognize special @samp{%} directives, 18751and unfortunately, instead of complaining, they just pass them through, 18752and exit with success: 18753 18754@example 18755$ @kbd{uname -a} 18756OSF1 medusa.sis.pasteur.fr V5.1 732 alpha 18757$ @kbd{date "+%s"} 18758%s 18759@end example 18760 18761 18762@item @command{diff} 18763@c ----------------- 18764@prindex @command{diff} 18765Option @option{-u} is nonportable. 18766 18767Some implementations, such as Tru64's, fail when comparing to 18768@file{/dev/null}. Use an empty file instead. 18769 18770 18771@item @command{dirname} 18772@c -------------------- 18773@prindex @command{dirname} 18774Not all hosts have a working @command{dirname}, and you should instead 18775use @code{AS_DIRNAME} (@pxref{Programming in M4sh}). For example: 18776 18777@example 18778dir=`dirname "$file"` # This is not portable. 18779dir=`AS_DIRNAME(["$file"])` # This is more portable. 18780@end example 18781 18782 18783@item @command{egrep} 18784@c ------------------ 18785@prindex @command{egrep} 18786Posix 1003.1-2001 no longer requires @command{egrep}, 18787but many hosts do not yet support the Posix 18788replacement @code{grep -E}. Also, some traditional implementations do 18789not work on long input lines. To work around these problems, invoke 18790@code{AC_PROG_EGREP} and then use @code{$EGREP}. 18791 18792Portable extended regular expressions should use @samp{\} only to escape 18793characters in the string @samp{$()*+.?[\^@{|}. For example, @samp{\@}} 18794is not portable, even though it typically matches @samp{@}}. 18795 18796The empty alternative is not portable. Use @samp{?} instead. For 18797instance with Digital Unix v5.0: 18798 18799@example 18800> printf "foo\n|foo\n" | $EGREP '^(|foo|bar)$' 18801|foo 18802> printf "bar\nbar|\n" | $EGREP '^(foo|bar|)$' 18803bar| 18804> printf "foo\nfoo|\n|bar\nbar\n" | $EGREP '^(foo||bar)$' 18805foo 18806|bar 18807@end example 18808 18809@command{$EGREP} also suffers the limitations of @command{grep} 18810(@pxref{grep, , Limitations of Usual Tools}). 18811 18812@item @command{expr} 18813@c ----------------- 18814@prindex @command{expr} 18815Not all implementations obey the Posix rule that @samp{--} separates 18816options from arguments; likewise, not all implementations provide the 18817extension to Posix that the first argument can be treated as part of a 18818valid expression rather than an invalid option if it begins with 18819@samp{-}. When performing arithmetic, use @samp{expr 0 + $var} if 18820@samp{$var} might be a negative number, to keep @command{expr} from 18821interpreting it as an option. 18822 18823No @command{expr} keyword starts with @samp{X}, so use @samp{expr 18824X"@var{word}" : 'X@var{regex}'} to keep @command{expr} from 18825misinterpreting @var{word}. 18826 18827Don't use @code{length}, @code{substr}, @code{match} and @code{index}. 18828 18829@item @command{expr} (@samp{|}) 18830@prindex @command{expr} (@samp{|}) 18831You can use @samp{|}. Although Posix does require that @samp{expr 18832''} return the empty string, it does not specify the result when you 18833@samp{|} together the empty string (or zero) with the empty string. For 18834example: 18835 18836@example 18837expr '' \| '' 18838@end example 18839 18840Posix 1003.2-1992 returns the empty string 18841for this case, but traditional Unix returns @samp{0} (Solaris is 18842one such example). In Posix 1003.1-2001, the specification was 18843changed to match traditional Unix's behavior (which is 18844bizarre, but it's too late to fix this). Please note that the same 18845problem does arise when the empty string results from a computation, 18846as in: 18847 18848@example 18849expr bar : foo \| foo : bar 18850@end example 18851 18852@noindent 18853Avoid this portability problem by avoiding the empty string. 18854 18855 18856@item @command{expr} (@samp{:}) 18857@c ---------------------------- 18858@prindex @command{expr} 18859Portable @command{expr} regular expressions should use @samp{\} to 18860escape only characters in the string @samp{$()*.0123456789[\^n@{@}}. 18861For example, alternation, @samp{\|}, is common but Posix does not 18862require its support, so it should be avoided in portable scripts. 18863Similarly, @samp{\+} and @samp{\?} should be avoided. 18864 18865Portable @command{expr} regular expressions should not begin with 18866@samp{^}. Patterns are automatically anchored so leading @samp{^} is 18867not needed anyway. 18868 18869On the other hand, the behavior of the @samp{$} anchor is not portable 18870on multi-line strings. Posix is ambiguous whether the anchor applies to 18871each line, as was done in older versions of the GNU Core Utilities, or 18872whether it applies only to the end of the overall string, as in 18873Coreutils 6.0 and most other implementations. 18874 18875@example 18876$ @kbd{baz='foo} 18877> @kbd{bar'} 18878$ @kbd{expr "X$baz" : 'X\(foo\)$'} 18879 18880$ @kbd{expr-5.97 "X$baz" : 'X\(foo\)$'} 18881foo 18882@end example 18883 18884The Posix standard is ambiguous as to whether 18885@samp{expr 'a' : '\(b\)'} outputs @samp{0} or the empty string. 18886In practice, it outputs the empty string on most platforms, but portable 18887scripts should not assume this. For instance, the QNX 4.25 native 18888@command{expr} returns @samp{0}. 18889 18890One might think that a way to get a uniform behavior would be to use 18891the empty string as a default value: 18892 18893@example 18894expr a : '\(b\)' \| '' 18895@end example 18896 18897@noindent 18898Unfortunately this behaves exactly as the original expression; see the 18899@command{expr} (@samp{|}) entry for more information. 18900 18901Some ancient @command{expr} implementations (e.g., SunOS 4 @command{expr} and 18902Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes 18903@command{expr} to fail if the matched substring is longer than 120 18904bytes. In this case, you might want to fall back on @samp{echo|sed} if 18905@command{expr} fails. Nowadays this is of practical importance only for 18906the rare installer who mistakenly puts @file{/usr/ucb} before 18907@file{/usr/bin} in @env{PATH}. 18908 18909On Mac OS X 10.4, @command{expr} mishandles the pattern @samp{[^-]} in 18910some cases. For example, the command 18911@example 18912expr Xpowerpc-apple-darwin8.1.0 : 'X[^-]*-[^-]*-\(.*\)' 18913@end example 18914 18915@noindent 18916outputs @samp{apple-darwin8.1.0} rather than the correct @samp{darwin8.1.0}. 18917This particular case can be worked around by substituting @samp{[^--]} 18918for @samp{[^-]}. 18919 18920Don't leave, there is some more! 18921 18922The QNX 4.25 @command{expr}, in addition of preferring @samp{0} to 18923the empty string, has a funny behavior in its exit status: it's always 1 18924when parentheses are used! 18925 18926@example 18927$ @kbd{val=`expr 'a' : 'a'`; echo "$?: $val"} 189280: 1 18929$ @kbd{val=`expr 'a' : 'b'`; echo "$?: $val"} 189301: 0 18931 18932$ @kbd{val=`expr 'a' : '\(a\)'`; echo "?: $val"} 189331: a 18934$ @kbd{val=`expr 'a' : '\(b\)'`; echo "?: $val"} 189351: 0 18936@end example 18937 18938@noindent 18939In practice this can be a big problem if you are ready to catch failures 18940of @command{expr} programs with some other method (such as using 18941@command{sed}), since you may get twice the result. For instance 18942 18943@example 18944$ @kbd{expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'} 18945@end example 18946 18947@noindent 18948outputs @samp{a} on most hosts, but @samp{aa} on QNX 4.25. A 18949simple workaround consists of testing @command{expr} and using a variable 18950set to @command{expr} or to @command{false} according to the result. 18951 18952Tru64 @command{expr} incorrectly treats the result as a number, if it 18953can be interpreted that way: 18954 18955@example 18956$ @kbd{expr 00001 : '.*\(...\)'} 189571 18958@end example 18959 18960On HP-UX 11, @command{expr} only supports a single 18961sub-expression. 18962 18963@example 18964$ @kbd{expr 'Xfoo' : 'X\(f\(oo\)*\)$'} 18965expr: More than one '\(' was used. 18966@end example 18967 18968 18969@item @command{fgrep} 18970@c ------------------ 18971@prindex @command{fgrep} 18972Posix 1003.1-2001 no longer requires @command{fgrep}, 18973but many hosts do not yet support the Posix 18974replacement @code{grep -F}. Also, some traditional implementations do 18975not work on long input lines. To work around these problems, invoke 18976@code{AC_PROG_FGREP} and then use @code{$FGREP}. 18977 18978Tru64/OSF 5.1 @command{fgrep} does not match an empty pattern. 18979 18980 18981@item @command{find} 18982@c ----------------- 18983@prindex @command{find} 18984The option @option{-maxdepth} seems to be GNU specific. 18985Tru64 v5.1, NetBSD 1.5 and Solaris @command{find} 18986commands do not understand it. 18987 18988The replacement of @samp{@{@}} is guaranteed only if the argument is 18989exactly @emph{@{@}}, not if it's only a part of an argument. For 18990instance on DU, and HP-UX 10.20 and HP-UX 11: 18991 18992@example 18993$ @kbd{touch foo} 18994$ @kbd{find . -name foo -exec echo "@{@}-@{@}" \;} 18995@{@}-@{@} 18996@end example 18997 18998@noindent 18999while GNU @command{find} reports @samp{./foo-./foo}. 19000 19001 19002@anchor{grep} 19003@item @command{grep} 19004@c ----------------- 19005@prindex @command{grep} 19006Portable scripts can rely on the @command{grep} options @option{-c}, 19007@option{-l}, @option{-n}, and @option{-v}, but should avoid other 19008options. For example, don't use @option{-w}, as Posix does not require 19009it and Irix 6.5.16m's @command{grep} does not support it. Also, 19010portable scripts should not combine @option{-c} with @option{-l}, 19011as Posix does not allow this. 19012 19013Some of the options required by Posix are not portable in practice. 19014Don't use @samp{grep -q} to suppress output, because many @command{grep} 19015implementations (e.g., Solaris) do not support @option{-q}. 19016Don't use @samp{grep -s} to suppress output either, because Posix 19017says @option{-s} does not suppress output, only some error messages; 19018also, the @option{-s} option of traditional @command{grep} behaved 19019like @option{-q} does in most modern implementations. Instead, 19020redirect the standard output and standard error (in case the file 19021doesn't exist) of @code{grep} to @file{/dev/null}. Check the exit 19022status of @code{grep} to determine whether it found a match. 19023 19024The QNX4 implementation fails to count lines with @code{grep -c '$'}, 19025but works with @code{grep -c '^'}. Other alternatives for counting 19026lines are to use @code{sed -n '$='} or @code{wc -l}. 19027 19028Some traditional @command{grep} implementations do not work on long 19029input lines. On AIX the default @code{grep} silently truncates long 19030lines on the input before matching. 19031 19032Also, many implementations do not support multiple regexps 19033with @option{-e}: they either reject @option{-e} entirely (e.g., Solaris) 19034or honor only the last pattern (e.g., IRIX 6.5 and NeXT). To 19035work around these problems, invoke @code{AC_PROG_GREP} and then use 19036@code{$GREP}. 19037 19038Another possible workaround for the multiple @option{-e} problem is to 19039separate the patterns by newlines, for example: 19040 19041@example 19042grep 'foo 19043bar' in.txt 19044@end example 19045 19046@noindent 19047except that this fails with traditional @command{grep} 19048implementations and with OpenBSD 3.8 @command{grep}. 19049 19050Traditional @command{grep} implementations (e.g., Solaris) do not 19051support the @option{-E} or @option{-F} options. To work around these 19052problems, invoke @code{AC_PROG_EGREP} and then use @code{$EGREP}, and 19053similarly for @code{AC_PROG_FGREP} and @code{$FGREP}. Even if you are 19054willing to require support for Posix @command{grep}, your script should 19055not use both @option{-E} and @option{-F}, since Posix does not allow 19056this combination. 19057 19058Portable @command{grep} regular expressions should use @samp{\} only to 19059escape characters in the string @samp{$()*.0123456789[\^@{@}}. For example, 19060alternation, @samp{\|}, is common but Posix does not require its 19061support in basic regular expressions, so it should be avoided in 19062portable scripts. Solaris and HP-UX @command{grep} do not support it. 19063Similarly, the following escape sequences should also be avoided: 19064@samp{\<}, @samp{\>}, @samp{\+}, @samp{\?}, @samp{\`}, @samp{\'}, 19065@samp{\B}, @samp{\b}, @samp{\S}, @samp{\s}, @samp{\W}, and @samp{\w}. 19066 19067Posix does not specify the behavior of @command{grep} on binary files. 19068An example where this matters is using BSD @command{grep} to 19069search text that includes embedded ANSI escape sequences for 19070colored output to terminals (@samp{\033[m} is the sequence to restore 19071normal output); the behavior depends on whether input is seekable: 19072 19073@example 19074$ @kbd{printf 'esc\033[mape\n' > sample} 19075$ @kbd{grep . sample} 19076Binary file sample matches 19077$ @kbd{cat sample | grep .} 19078escape 19079@end example 19080 19081 19082@item @command{join} 19083@c ----------------- 19084@prindex @command{join} 19085Solaris 8 @command{join} has bugs when the second operand is standard 19086input, and when standard input is a pipe. For example, the following 19087shell script causes Solaris 8 @command{join} to loop forever: 19088 19089@example 19090cat >file <<'EOF' 190911 x 190922 y 19093EOF 19094cat file | join file - 19095@end example 19096 19097Use @samp{join - file} instead. 19098 19099On NetBSD, @command{join -a 1 file1 file2} mistakenly behaves like 19100@command{join -a 1 -a 2 1 file1 file2}, resulting in a usage warning; 19101the workaround is to use @command{join -a1 file1 file2} instead. 19102 19103@item @command{ln} 19104@c --------------- 19105@prindex @command{ln} 19106@cindex Symbolic links 19107Don't rely on @command{ln} having a @option{-f} option. Symbolic links 19108are not available on old systems; use @samp{$(LN_S)} as a portable substitute. 19109 19110For versions of the DJGPP before 2.04, 19111@command{ln} emulates symbolic links 19112to executables by generating a stub that in turn calls the real 19113program. This feature also works with nonexistent files like in the 19114Posix spec. So @samp{ln -s file link} generates @file{link.exe}, 19115which attempts to call @file{file.exe} if run. But this feature only 19116works for executables, so @samp{cp -p} is used instead for these 19117systems. DJGPP versions 2.04 and later have full support 19118for symbolic links. 19119 19120 19121@item @command{ls} 19122@c --------------- 19123@prindex @command{ls} 19124@cindex Listing directories 19125The portable options are @option{-acdilrtu}. Current practice is for 19126@option{-l} to output both owner and group, even though ancient versions 19127of @command{ls} omitted the group. 19128 19129On ancient hosts, @samp{ls foo} sent the diagnostic @samp{foo not found} 19130to standard output if @file{foo} did not exist. Hence a shell command 19131like @samp{sources=`ls *.c 2>/dev/null`} did not always work, since it 19132was equivalent to @samp{sources='*.c not found'} in the absence of 19133@samp{.c} files. This is no longer a practical problem, since current 19134@command{ls} implementations send diagnostics to standard error. 19135 19136The behavior of @command{ls} on a directory that is being concurrently 19137modified is not always predictable, because of a data race where cached 19138information returned by @code{readdir} does not match the current 19139directory state. In fact, MacOS 10.5 has an intermittent bug where 19140@code{readdir}, and thus @command{ls}, sometimes lists a file more than 19141once if other files were added or removed from the directory immediately 19142prior to the @command{ls} call. Since @command{ls} already sorts its 19143output, the duplicate entries can be avoided by piping the results 19144through @code{uniq}. 19145 19146@anchor{mkdir} 19147@item @command{mkdir} 19148@c ------------------ 19149@prindex @command{mkdir} 19150@cindex Making directories 19151No @command{mkdir} option is portable to older systems. Instead of 19152@samp{mkdir -p @var{file-name}}, you should use 19153@code{AS_MKDIR_P(@var{file-name})} (@pxref{Programming in M4sh}) 19154or @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs}). 19155 19156Combining the @option{-m} and @option{-p} options, as in @samp{mkdir -m 19157go-w -p @var{dir}}, often leads to trouble. FreeBSD 19158@command{mkdir} incorrectly attempts to change the permissions of 19159@var{dir} even if it already exists. HP-UX 11.23 and 19160IRIX 6.5 @command{mkdir} often assign the wrong permissions to 19161any newly-created parents of @var{dir}. 19162 19163Posix does not clearly specify whether @samp{mkdir -p foo} 19164should succeed when @file{foo} is a symbolic link to an already-existing 19165directory. The GNU Core Utilities 5.1.0 @command{mkdir} 19166succeeds, but Solaris @command{mkdir} fails. 19167 19168Traditional @code{mkdir -p} implementations suffer from race conditions. 19169For example, if you invoke @code{mkdir -p a/b} and @code{mkdir -p a/c} 19170at the same time, both processes might detect that @file{a} is missing, 19171one might create @file{a}, then the other might try to create @file{a} 19172and fail with a @code{File exists} diagnostic. The GNU Core 19173Utilities (@samp{fileutils} version 4.1), FreeBSD 5.0, 19174NetBSD 2.0.2, and OpenBSD 2.4 are known to be 19175race-free when two processes invoke @code{mkdir -p} simultaneously, but 19176earlier versions are vulnerable. Solaris @command{mkdir} is still 19177vulnerable as of Solaris 10, and other traditional Unix systems are 19178probably vulnerable too. This possible race is harmful in parallel 19179builds when several Make rules call @code{mkdir -p} to 19180construct directories. You may use 19181@code{install-sh -d} as a safe replacement, provided this script is 19182recent enough; the copy shipped with Autoconf 2.60 and Automake 1.10 is 19183OK, but copies from older versions are vulnerable. 19184 19185 19186@item @command{mkfifo} 19187@itemx @command{mknod} 19188@c ------------------- 19189@prindex @command{mkfifo} 19190@prindex @command{mknod} 19191The GNU Coding Standards state that @command{mknod} is safe to use on 19192platforms where it has been tested to exist; but it is generally portable 19193only for creating named FIFOs, since device numbers are 19194platform-specific. Autotest uses @command{mkfifo} to implement parallel 19195testsuites. Posix states that behavior is unspecified when opening a 19196named FIFO for both reading and writing; on at least Cygwin, this 19197results in failure on any attempt to read or write to that file 19198descriptor. 19199 19200@item @command{mktemp} 19201@c ------------------- 19202@prindex @command{mktemp} 19203@cindex Creating temporary files 19204Shell scripts can use temporary files safely with @command{mktemp}, but 19205it does not exist on all systems. A portable way to create a safe 19206temporary file name is to create a temporary directory with mode 700 and 19207use a file inside this directory. Both methods prevent attackers from 19208gaining control, though @command{mktemp} is far less likely to fail 19209gratuitously under attack. 19210 19211Here is sample code to create a new temporary directory @samp{$dir} safely: 19212 19213@example 19214# Create a temporary directory $dir in $TMPDIR (default /tmp). 19215# Use mktemp if possible; otherwise fall back on mkdir, 19216# with $RANDOM to make collisions less likely. 19217: "$@{TMPDIR:=/tmp@}" 19218@{ 19219 dir=` 19220 (umask 077 && mktemp -d "$TMPDIR/fooXXXXXX") 2>/dev/null 19221 ` && 19222 test -d "$dir" 19223@} || @{ 19224 dir=$TMPDIR/foo$$-$RANDOM 19225@c $$ restore font-lock 19226 (umask 077 && mkdir "$dir") 19227@} || exit $? 19228@end example 19229 19230 19231@item @command{mv} 19232@c --------------- 19233@prindex @command{mv} 19234@cindex Moving open files 19235The only portable options are @option{-f} and @option{-i}. 19236 19237Moving individual files between file systems is portable (it was in Unix 19238version 6), 19239but it is not always atomic: when doing @samp{mv new existing}, there's 19240a critical section where neither the old nor the new version of 19241@file{existing} actually exists. 19242 19243On some systems moving files from @file{/tmp} can sometimes cause 19244undesirable (but perfectly valid) warnings, even if you created these 19245files. This is because @file{/tmp} belongs to a group that ordinary 19246users are not members of, and files created in @file{/tmp} inherit 19247the group of @file{/tmp}. When the file is copied, @command{mv} issues 19248a diagnostic without failing: 19249 19250@smallexample 19251$ @kbd{touch /tmp/foo} 19252$ @kbd{mv /tmp/foo .} 19253@error{}mv: ./foo: set owner/group (was: 100/0): Operation not permitted 19254$ @kbd{echo $?} 192550 19256$ @kbd{ls foo} 19257foo 19258@end smallexample 19259 19260@noindent 19261This annoying behavior conforms to Posix, unfortunately. 19262 19263Moving directories across mount points is not portable, use @command{cp} 19264and @command{rm}. 19265 19266DOS variants cannot rename or remove open files, and do not 19267support commands like @samp{mv foo bar >foo}, even though this is 19268perfectly portable among Posix hosts. 19269 19270 19271@item @command{od} 19272@c --------------- 19273@prindex @command{od} 19274 19275In Mac OS X 10.3, @command{od} does not support the 19276standard Posix options @option{-A}, @option{-j}, @option{-N}, or 19277@option{-t}, or the XSI option @option{-s}. The only 19278supported Posix option is @option{-v}, and the only supported 19279XSI options are those in @option{-bcdox}. The BSD 19280@command{hexdump} program can be used instead. 19281 19282This problem no longer exists in Mac OS X 10.4.3. 19283 19284 19285@item @command{rm} 19286@c --------------- 19287@prindex @command{rm} 19288The @option{-f} and @option{-r} options are portable. 19289 19290It is not portable to invoke @command{rm} without options or operands. 19291On the other hand, Posix now requires @command{rm -f} to silently 19292succeed when there are no operands (useful for constructs like 19293@command{rm -rf $filelist} without first checking if @samp{$filelist} 19294was empty). But this was not always portable; at least NetBSD 19295@command{rm} built before 2008 would fail with a diagnostic. 19296 19297A file might not be removed even if its parent directory is writable 19298and searchable. Many Posix hosts cannot remove a mount point, a named 19299stream, a working directory, or a last link to a file that is being 19300executed. 19301 19302DOS variants cannot rename or remove open files, and do not 19303support commands like @samp{rm foo >foo}, even though this is 19304perfectly portable among Posix hosts. 19305 19306@item @command{rmdir} 19307@c ------------------ 19308@prindex @command{rmdir} 19309Just as with @command{rm}, some platforms refuse to remove a working 19310directory. 19311 19312@anchor{sed} 19313@item @command{sed} 19314@c ---------------- 19315@prindex @command{sed} 19316Patterns should not include the separator (unless escaped), even as part 19317of a character class. In conformance with Posix, the Cray 19318@command{sed} rejects @samp{s/[^/]*$//}: use @samp{s%[^/]*$%%}. 19319Even when escaped, patterns should not include separators that are also 19320used as @command{sed} metacharacters. For example, GNU sed 4.0.9 rejects 19321@samp{s,x\@{1\,\@},,}, while sed 4.1 strips the backslash before the comma 19322before evaluating the basic regular expression. 19323 19324Avoid empty patterns within parentheses (i.e., @samp{\(\)}). Posix does 19325not require support for empty patterns, and Unicos 9 @command{sed} rejects 19326them. 19327 19328Unicos 9 @command{sed} loops endlessly on patterns like @samp{.*\n.*}. 19329 19330Sed scripts should not use branch labels longer than 7 characters and 19331should not contain comments; AIX 5.3 @command{sed} rejects indented comments. 19332HP-UX sed has a limit of 99 commands (not counting @samp{:} commands) and 1933348 labels, which cannot be circumvented by using more than one script 19334file. It can execute up to 19 reads with the @samp{r} command per cycle. 19335Solaris @command{/usr/ucb/sed} rejects usages that exceed a limit of 19336about 6000 bytes for the internal representation of commands. 19337 19338Avoid redundant @samp{;}, as some @command{sed} implementations, such as 19339NetBSD 1.4.2's, incorrectly try to interpret the second 19340@samp{;} as a command: 19341 19342@example 19343$ @kbd{echo a | sed 's/x/x/;;s/x/x/'} 19344sed: 1: "s/x/x/;;s/x/x/": invalid command code ; 19345@end example 19346 19347Some @command{sed} implementations have a buffer limited to 4000 bytes, 19348and this limits the size of input lines, output lines, and internal 19349buffers that can be processed portably. Likewise, 19350not all @command{sed} implementations can handle embedded @code{NUL} or 19351a missing trailing newline. 19352 19353Remember that ranges within a bracket expression of a regular expression 19354are only well-defined in the @samp{C} (or @samp{POSIX}) locale. 19355Meanwhile, support for character classes like @samp{[[:upper:]]} is not 19356yet universal, so if you cannot guarantee the setting of @env{LC_ALL}, 19357it is better to spell out a range @samp{[ABCDEFGHIJKLMNOPQRSTUVWXYZ]} 19358than to rely on @samp{[A-Z]}. 19359 19360Additionally, Posix states that regular expressions are only 19361well-defined on characters. Unfortunately, there exist platforms such 19362as MacOS X 10.5 where not all 8-bit byte values are valid characters, 19363even though that platform has a single-byte @samp{C} locale. And Posix 19364allows the existence of a multi-byte @samp{C} locale, although that does 19365not yet appear to be a common implementation. At any rate, it means 19366that not all bytes will be matched by the regular expression @samp{.}: 19367 19368@example 19369$ @kbd{printf '\200\n' | LC_ALL=C sed -n /./p | wc -l} 193700 19371$ @kbd{printf '\200\n' | LC_ALL=en_US.ISO8859-1 sed -n /./p | wc -l} 193721 19373@end example 19374 19375Portable @command{sed} regular expressions should use @samp{\} only to escape 19376characters in the string @samp{$()*.0123456789[\^n@{@}}. For example, 19377alternation, @samp{\|}, is common but Posix does not require its 19378support, so it should be avoided in portable scripts. Solaris 19379@command{sed} does not support alternation; e.g., @samp{sed '/a\|b/d'} 19380deletes only lines that contain the literal string @samp{a|b}. 19381Similarly, @samp{\+} and @samp{\?} should be avoided. 19382 19383Anchors (@samp{^} and @samp{$}) inside groups are not portable. 19384 19385Nested parentheses in patterns (e.g., @samp{\(\(a*\)b*)\)}) are 19386quite portable to current hosts, but was not supported by some ancient 19387@command{sed} implementations like SVR3. 19388 19389Some @command{sed} implementations, e.g., Solaris, restrict the special 19390role of the asterisk @samp{*} to one-character regular expressions and 19391back-references, and the special role of interval expressions 19392@samp{\@{@var{m}\@}}, @samp{\@{@var{m},\@}}, or @samp{\@{@var{m},@var{n}\@}} 19393to one-character regular expressions. This may lead to unexpected behavior: 19394 19395@example 19396$ @kbd{echo '1*23*4' | /usr/bin/sed 's/\(.\)*/x/g'} 19397x2x4 19398$ @kbd{echo '1*23*4' | /usr/xpg4/bin/sed 's/\(.\)*/x/g'} 19399x 19400@end example 19401 19402The @option{-e} option is mostly portable. 19403However, its argument 19404cannot start with @samp{a}, @samp{c}, or @samp{i}, 19405as this runs afoul of a Tru64 5.1 bug. 19406Also, its argument cannot be empty, as this fails on AIX 5.3. 19407Some people prefer to use @samp{-e}: 19408 19409@example 19410sed -e '@var{command-1}' \ 19411 -e '@var{command-2}' 19412@end example 19413 19414@noindent 19415as opposed to the equivalent: 19416 19417@example 19418sed ' 19419 @var{command-1} 19420 @var{command-2} 19421' 19422@end example 19423 19424@noindent 19425The following usage is sometimes equivalent: 19426 19427@example 19428sed '@var{command-1};@var{command-2}' 19429@end example 19430 19431but Posix says that this use of a semicolon has undefined effect if 19432@var{command-1}'s verb is @samp{@{}, @samp{a}, @samp{b}, @samp{c}, 19433@samp{i}, @samp{r}, @samp{t}, @samp{w}, @samp{:}, or @samp{#}, so you 19434should use semicolon only with simple scripts that do not use these 19435verbs. 19436 19437Posix up to the 2008 revision requires the argument of the @option{-e} 19438option to be a syntactically complete script. GNU @command{sed} allows 19439to pass multiple script fragments, each as argument of a separate 19440@option{-e} option, that are then combined, with newlines between the 19441fragments, and a future Posix revision may allow this as well. This 19442approach is not portable with script fragments ending in backslash; for 19443example, the @command{sed} programs on Solaris 10, HP-UX 11, and AIX 19444don't allow splitting in this case: 19445 19446@example 19447$ @kbd{echo a | sed -n -e 'i\} 19448@kbd{0'} 194490 19450$ @kbd{echo a | sed -n -e 'i\' -e 0} 19451Unrecognized command: 0 19452@end example 19453 19454@noindent 19455In practice, however, this technique of joining fragments 19456through @option{-e} works for multiple @command{sed} functions within 19457@samp{@{} and @samp{@}}, even if that is not specified by Posix: 19458 19459@example 19460@c The quote around the closing brace silences interactive zsh. 19461$ @kbd{echo a | sed -n -e '/a/@{' -e s/a/b/ -e p -e '@}'} 19462b 19463@end example 19464 19465Commands inside @{ @} brackets are further restricted. Posix 2008 says that 19466they cannot be preceded by addresses, @samp{!}, or @samp{;}, and that 19467each command must be followed immediately by a newline, without any 19468intervening blanks or semicolons. The closing bracket must be alone on 19469a line, other than white space preceding or following it. However, a 19470future version of Posix may standardize the use of addresses within brackets. 19471 19472Contrary to yet another urban legend, you may portably use @samp{&} in 19473the replacement part of the @code{s} command to mean ``what was 19474matched''. All descendants of Unix version 7 @command{sed} 19475(at least; we 19476don't have first hand experience with older @command{sed} implementations) have 19477supported it. 19478 19479Posix requires that you must not have any white space between 19480@samp{!} and the following command. It is OK to have blanks between 19481the address and the @samp{!}. For instance, on Solaris: 19482 19483@example 19484$ @kbd{echo "foo" | sed -n '/bar/ ! p'} 19485@error{}Unrecognized command: /bar/ ! p 19486$ @kbd{echo "foo" | sed -n '/bar/! p'} 19487@error{}Unrecognized command: /bar/! p 19488$ @kbd{echo "foo" | sed -n '/bar/ !p'} 19489foo 19490@end example 19491 19492Posix also says that you should not combine @samp{!} and @samp{;}. If 19493you use @samp{!}, it is best to put it on a command that is delimited by 19494newlines rather than @samp{;}. 19495 19496Also note that Posix requires that the @samp{b}, @samp{t}, @samp{r}, and 19497@samp{w} commands be followed by exactly one space before their argument. 19498On the other hand, no white space is allowed between @samp{:} and the 19499subsequent label name. 19500 19501If a sed script is specified on the command line and ends in an 19502@samp{a}, @samp{c}, or @samp{i} command, the last line of inserted text 19503should be followed by a newline. Otherwise some @command{sed} 19504implementations (e.g., OpenBSD 3.9) do not append a newline to the 19505inserted text. 19506 19507Many @command{sed} implementations (e.g., MacOS X 10.4, 19508OpenBSD 3.9, Solaris 10 19509@command{/usr/ucb/sed}) strip leading white space from the text of 19510@samp{a}, @samp{c}, and @samp{i} commands. Prepend a backslash to 19511work around this incompatibility with Posix: 19512 19513@example 19514$ @kbd{echo flushleft | sed 'a\} 19515> @kbd{ indented} 19516> @kbd{'} 19517flushleft 19518indented 19519$ @kbd{echo foo | sed 'a\} 19520> @kbd{\ indented} 19521> @kbd{'} 19522flushleft 19523 indented 19524@end example 19525 19526Posix requires that with an empty regular expression, the last non-empty 19527regular expression from either an address specification or substitution 19528command is applied. However, busybox 1.6.1 complains when using a 19529substitution command with a replacement containing a back-reference to 19530an empty regular expression; the workaround is repeating the regular 19531expression. 19532 19533@example 19534$ @kbd{echo abc | busybox sed '/a\(b\)c/ s//\1/'} 19535sed: No previous regexp. 19536$ @kbd{echo abc | busybox sed '/a\(b\)c/ s/a\(b\)c/\1/'} 19537b 19538@end example 19539 19540 19541@item @command{sed} (@samp{t}) 19542@c --------------------------- 19543@prindex @command{sed} (@samp{t}) 19544Some old systems have @command{sed} that ``forget'' to reset their 19545@samp{t} flag when starting a new cycle. For instance on MIPS 19546RISC/OS, and on IRIX 5.3, if you run the following @command{sed} 19547script (the line numbers are not actual part of the texts): 19548 19549@example 19550s/keep me/kept/g # a 19551t end # b 19552s/.*/deleted/g # c 19553:end # d 19554@end example 19555 19556@noindent 19557on 19558 19559@example 19560delete me # 1 19561delete me # 2 19562keep me # 3 19563delete me # 4 19564@end example 19565 19566@noindent 19567you get 19568 19569@example 19570deleted 19571delete me 19572kept 19573deleted 19574@end example 19575 19576@noindent 19577instead of 19578 19579@example 19580deleted 19581deleted 19582kept 19583deleted 19584@end example 19585 19586Why? When processing line 1, (c) matches, therefore sets the @samp{t} 19587flag, and the output is produced. When processing 19588line 2, the @samp{t} flag is still set (this is the bug). Command (a) 19589fails to match, but @command{sed} is not supposed to clear the @samp{t} 19590flag when a substitution fails. Command (b) sees that the flag is set, 19591therefore it clears it, and jumps to (d), hence you get @samp{delete me} 19592instead of @samp{deleted}. When processing line (3), @samp{t} is clear, 19593(a) matches, so the flag is set, hence (b) clears the flags and jumps. 19594Finally, since the flag is clear, line 4 is processed properly. 19595 19596There are two things one should remember about @samp{t} in @command{sed}. 19597Firstly, always remember that @samp{t} jumps if @emph{some} substitution 19598succeeded, not only the immediately preceding substitution. Therefore, 19599always use a fake @samp{t clear} followed by a @samp{:clear} on the next 19600line, to reset the @samp{t} flag where needed. 19601 19602Secondly, you cannot rely on @command{sed} to clear the flag at each new 19603cycle. 19604 19605One portable implementation of the script above is: 19606 19607@example 19608t clear 19609:clear 19610s/keep me/kept/g 19611t end 19612s/.*/deleted/g 19613:end 19614@end example 19615 19616@item @command{sleep} 19617@c ------------------ 19618@prindex @command{sleep} 19619Using @command{sleep} is generally portable. However, remember that 19620adding a @command{sleep} to work around timestamp issues, with a minimum 19621granularity of one second, doesn't scale well for parallel builds on 19622modern machines with sub-second process completion. 19623 19624@item @command{sort} 19625@c ----------------- 19626@prindex @command{sort} 19627Remember that sort order is influenced by the current locale. Inside 19628@file{configure}, the C locale is in effect, but in Makefile snippets, 19629you may need to specify @code{LC_ALL=C sort}. 19630 19631@item @command{tar} 19632@c ---------------- 19633@prindex @command{tar} 19634There are multiple file formats for @command{tar}; if you use Automake, 19635the macro @code{AM_INIT_AUTOMAKE} has some options controlling which 19636level of portability to use. 19637 19638@anchor{touch} 19639@item @command{touch} 19640@c ------------------ 19641@prindex @command{touch} 19642@cindex timestamp resolution 19643If you specify the desired timestamp (e.g., with the @option{-r} 19644option), older @command{touch} implementations use the @code{utime} or 19645@code{utimes} system call, which can result in the same kind of 19646timestamp truncation problems that @samp{cp -p} has. 19647 19648On ancient BSD systems, @command{touch} or any command that 19649results in an empty file does not update the timestamps, so use a 19650command like @command{echo} as a workaround. 19651Also, 19652GNU @command{touch} 3.16r (and presumably all before that) 19653fails to work on SunOS 4.1.3 when the empty file is on an 19654NFS-mounted 4.2 volume. 19655However, these problems are no longer of practical concern. 19656 19657@item @command{tr} 19658@c --------------- 19659@prindex @command{tr} 19660@cindex carriage return, deleting 19661@cindex newline, deleting 19662@cindex deleting carriage return 19663Not all versions of @command{tr} handle all backslash character escapes. 19664For example, Solaris 10 @command{/usr/ucb/tr} falls over, even though 19665Solaris contains more modern @command{tr} in other locations. 19666Using octal escapes is more portable for carriage returns, since 19667@samp{\015} is the same for both ASCII and EBCDIC, and since use of 19668literal carriage returns in scripts causes a number of other problems. 19669But for other characters, like newline, using octal escapes ties the 19670operation to ASCII, so it is better to use literal characters. 19671 19672@example 19673$ @kbd{@{ echo moon; echo light; @} | /usr/ucb/tr -d '\n' ; echo} 19674moo 19675light 19676$ @kbd{@{ echo moon; echo light; @} | /usr/bin/tr -d '\n' ; echo} 19677moonlight 19678$ @kbd{@{ echo moon; echo light; @} | /usr/ucb/tr -d '\012' ; echo} 19679moonlight 19680$ @kbd{nl='} 19681@kbd{'; @{ echo moon; echo light; @} | /usr/ucb/tr -d "$nl" ; echo} 19682moonlight 19683@end example 19684 19685Not all versions of @command{tr} recognize direct ranges of characters: at 19686least Solaris @command{/usr/bin/tr} still fails to do so. But you can 19687use @command{/usr/xpg4/bin/tr} instead, or add brackets (which in Posix 19688transliterate to themselves). 19689 19690@example 19691$ @kbd{echo "Hazy Fantazy" | LC_ALL=C /usr/bin/tr a-z A-Z} 19692HAZy FAntAZy 19693$ @kbd{echo "Hazy Fantazy" | LC_ALL=C /usr/bin/tr '[a-z]' '[A-Z]'} 19694HAZY FANTAZY 19695$ @kbd{echo "Hazy Fantazy" | LC_ALL=C /usr/xpg4/bin/tr a-z A-Z} 19696HAZY FANTAZY 19697@end example 19698 19699When providing two arguments, be sure the second string is at least as 19700long as the first. 19701 19702@example 19703$ @kbd{echo abc | /usr/xpg4/bin/tr bc d} 19704adc 19705$ @kbd{echo abc | coreutils/tr bc d} 19706add 19707@end example 19708 19709Posix requires @command{tr} to operate on binary files. But at least 19710Solaris @command{/usr/ucb/tr} and @command{/usr/bin/tr} silently discard 19711@code{NUL} in the input prior to doing any translation. When using 19712@command{tr} to process a binary file that may contain @code{NUL} bytes, 19713it is necessary to use @command{/usr/xpg4/bin/tr} instead, or 19714@command{/usr/xpg6/bin/tr} if that is available. 19715 19716@example 19717$ @kbd{printf 'a\0b' | /usr/ucb/tr x x | od -An -tx1} 19718 61 62 19719$ @kbd{printf 'a\0b' | /usr/bin/tr x x | od -An -tx1} 19720 61 62 19721$ @kbd{printf 'a\0b' | /usr/xpg4/bin/tr x x | od -An -tx1} 19722 61 00 62 19723@end example 19724 19725Solaris @command{/usr/ucb/tr} additionally fails to handle @samp{\0} as the 19726octal escape for @code{NUL}. 19727 19728@example 19729$ @kbd{printf 'abc' | /usr/ucb/tr 'bc' '\0d' | od -An -tx1} 19730 61 62 63 19731$ @kbd{printf 'abc' | /usr/bin/tr 'bc' '\0d' | od -An -tx1} 19732 61 00 64 19733$ @kbd{printf 'abc' | /usr/xpg4/bin/tr 'bc' '\0d' | od -An -tx1} 19734 61 00 64 19735@end example 19736 19737@end table 19738 19739 19740@node Portable Make 19741@chapter Portable Make Programming 19742@prindex @command{make} 19743@cindex Limitations of @command{make} 19744 19745Writing portable makefiles is an art. Since a makefile's commands are 19746executed by the shell, you must consider the shell portability issues 19747already mentioned. However, other issues are specific to @command{make} 19748itself. 19749 19750@menu 19751* $< in Ordinary Make Rules:: $< in ordinary rules 19752* Failure in Make Rules:: Failing portably in rules 19753* Special Chars in Names:: Special Characters in Macro Names 19754* Backslash-Newline-Empty:: Empty lines after backslash-newline 19755* Backslash-Newline Comments:: Spanning comments across line boundaries 19756* Long Lines in Makefiles:: Line length limitations 19757* Macros and Submakes:: @code{make macro=value} and submakes 19758* The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues 19759* The Make Macro SHELL:: @code{$(SHELL)} portability issues 19760* Parallel Make:: Parallel @command{make} quirks 19761* Comments in Make Rules:: Other problems with Make comments 19762* Newlines in Make Rules:: Using literal newlines in rules 19763* Comments in Make Macros:: Other problems with Make comments in macros 19764* Trailing whitespace in Make Macros:: Macro substitution problems 19765* Command-line Macros and whitespace:: Whitespace trimming of values 19766* obj/ and Make:: Don't name a subdirectory @file{obj} 19767* make -k Status:: Exit status of @samp{make -k} 19768* VPATH and Make:: @code{VPATH} woes 19769* Single Suffix Rules:: Single suffix rules and separated dependencies 19770* Timestamps and Make:: Subsecond timestamp resolution 19771@end menu 19772 19773@node $< in Ordinary Make Rules 19774@section @code{$<} in Ordinary Make Rules 19775 19776Posix says that the @samp{$<} construct in makefiles can be 19777used only in inference rules and in the @samp{.DEFAULT} rule; its 19778meaning in ordinary rules is unspecified. Solaris @command{make} 19779for instance replaces it with the empty string. OpenBSD (3.0 and 19780later) @command{make} diagnoses these uses and errors out. 19781 19782@node Failure in Make Rules 19783@section Failure in Make Rules 19784 19785Posix 2008 requires that @command{make} must invoke each command with 19786the equivalent of a @samp{sh -e -c} subshell, which causes the 19787subshell to exit immediately if a subsidiary simple-command fails, 19788although not all @command{make} implementations have historically 19789followed this rule. For 19790example, the command @samp{touch T; rm -f U} may attempt to 19791remove @file{U} even if the @command{touch} fails, although this is not 19792permitted with Posix make. One way to work around failures in simple 19793commands is to reword them so that they always succeed, e.g., @samp{touch 19794T || :; rm -f U}. 19795However, even this approach can run into common bugs in BSD 19796implementations of the @option{-e} option of @command{sh} and 19797@command{set} (@pxref{set, , Limitations of Shell Builtins}), so if you 19798are worried 19799about porting to buggy BSD shells it may be simpler to migrate 19800complicated @command{make} actions into separate scripts. 19801 19802@node Special Chars in Names 19803@section Special Characters in Make Macro Names 19804 19805Posix limits macro names to nonempty strings containing only 19806ASCII letters and digits, @samp{.}, and @samp{_}. Many 19807@command{make} implementations allow a wider variety of characters, but 19808portable makefiles should avoid them. It is portable to start a name 19809with a special character, e.g., @samp{$(.FOO)}. 19810 19811Some ancient @command{make} implementations don't support leading 19812underscores in macro names. An example is NEWS-OS 4.2R. 19813 19814@example 19815$ @kbd{cat Makefile} 19816_am_include = # 19817_am_quote = 19818all:; @@echo this is test 19819$ @kbd{make} 19820Make: Must be a separator on rules line 2. Stop. 19821$ @kbd{cat Makefile2} 19822am_include = # 19823am_quote = 19824all:; @@echo this is test 19825$ @kbd{make -f Makefile2} 19826this is test 19827@end example 19828 19829@noindent 19830However, this problem is no longer of practical concern. 19831 19832@node Backslash-Newline-Empty 19833@section Backslash-Newline Before Empty Lines 19834 19835A bug in Bash 2.03 can cause problems if a Make rule contains a 19836backslash-newline followed by line that expands to nothing. 19837For example, on Solaris 8: 19838 19839@example 19840SHELL = /bin/bash 19841EMPTY = 19842foo: 19843 touch foo \ 19844 $(EMPTY) 19845@end example 19846 19847@noindent 19848executes 19849 19850@example 19851/bin/bash -c 'touch foo \ 19852' 19853@end example 19854 19855@noindent 19856which fails with a syntax error, due to the Bash bug. To avoid this 19857problem, avoid nullable macros in the last line of a multiline command. 19858 19859@c This has been seen on ia64 hpux 11.20, and on one hppa hpux 10.20, 19860@c but another hppa hpux 10.20 didn't have it. Bob Proulx 19861@c <bob@proulx.com> thinks it was in hpux 8.0 too. 19862On some versions of HP-UX, @command{make} reads multiple newlines 19863following a backslash, continuing to the next non-empty line. For 19864example, 19865 19866@example 19867FOO = one \ 19868 19869BAR = two 19870 19871test: 19872 : FOO is "$(FOO)" 19873 : BAR is "$(BAR)" 19874@end example 19875 19876@noindent 19877shows @code{FOO} equal to @code{one BAR = two}. Other implementations 19878sensibly let a backslash continue only to the immediately following 19879line. 19880 19881@node Backslash-Newline Comments 19882@section Backslash-Newline in Make Comments 19883 19884According to Posix, Make comments start with @code{#} 19885and continue until an unescaped newline is reached. 19886 19887@example 19888$ @kbd{cat Makefile} 19889# A = foo \ 19890 bar \ 19891 baz 19892 19893all: 19894 @@echo ok 19895$ @kbd{make} # GNU make 19896ok 19897@end example 19898 19899@noindent 19900However this is not always the case. Some implementations 19901discard everything from @code{#} through the end of the line, ignoring any 19902trailing backslash. 19903 19904@example 19905$ @kbd{pmake} # BSD make 19906"Makefile", line 3: Need an operator 19907Fatal errors encountered -- cannot continue 19908@end example 19909 19910@noindent 19911Therefore, if you want to comment out a multi-line definition, prefix each 19912line with @code{#}, not only the first. 19913 19914@example 19915# A = foo \ 19916# bar \ 19917# baz 19918@end example 19919 19920@node Long Lines in Makefiles 19921@section Long Lines in Makefiles 19922 19923Tru64 5.1's @command{make} has been reported to crash when given a 19924makefile with lines longer than around 20 kB. Earlier versions are 19925reported to exit with @code{Line too long} diagnostics. 19926 19927@node Macros and Submakes 19928@section @code{make macro=value} and Submakes 19929 19930A command-line variable definition such as @code{foo=bar} overrides any 19931definition of @code{foo} in a makefile. Some @command{make} 19932implementations (such as GNU @command{make}) propagate this 19933override to subsidiary invocations of @command{make}. Some other 19934implementations do not pass the substitution along to submakes. 19935 19936@example 19937$ @kbd{cat Makefile} 19938foo = foo 19939one: 19940 @@echo $(foo) 19941 $(MAKE) two 19942two: 19943 @@echo $(foo) 19944$ @kbd{make foo=bar} # GNU make 3.79.1 19945bar 19946make two 19947make[1]: Entering directory `/home/adl' 19948bar 19949make[1]: Leaving directory `/home/adl' 19950$ @kbd{pmake foo=bar} # BSD make 19951bar 19952pmake two 19953foo 19954@end example 19955 19956You have a few possibilities if you do want the @code{foo=bar} override 19957to propagate to submakes. One is to use the @option{-e} 19958option, which causes all environment variables to have precedence over 19959the makefile macro definitions, and declare foo as an environment 19960variable: 19961 19962@example 19963$ @kbd{env foo=bar make -e} 19964@end example 19965 19966The @option{-e} option is propagated to submakes automatically, 19967and since the environment is inherited between @command{make} 19968invocations, the @code{foo} macro is overridden in 19969submakes as expected. 19970 19971This syntax (@code{foo=bar make -e}) is portable only when used 19972outside of a makefile, for instance from a script or from the 19973command line. When run inside a @command{make} rule, GNU 19974@command{make} 3.80 and prior versions forget to propagate the 19975@option{-e} option to submakes. 19976 19977Moreover, using @option{-e} could have unexpected side effects if your 19978environment contains some other macros usually defined by the 19979makefile. (See also the note about @code{make -e} and @code{SHELL} 19980below.) 19981 19982If you can foresee all macros that a user might want to override, then 19983you can propagate them to submakes manually, from your makefile: 19984 19985@example 19986foo = foo 19987one: 19988 @@echo $(foo) 19989 $(MAKE) foo=$(foo) two 19990two: 19991 @@echo $(foo) 19992@end example 19993 19994Another way to propagate a variable to submakes in a portable way is to 19995expand an extra variable in every invocation of @samp{$(MAKE)} within 19996your makefile: 19997 19998@example 19999foo = foo 20000one: 20001 @@echo $(foo) 20002 $(MAKE) $(SUBMAKEFLAGS) two 20003two: 20004 @@echo $(foo) 20005@end example 20006 20007Users must be aware that this technique is in use to take advantage of 20008it, e.g.@: with @code{make foo=bar SUBMAKEFLAGS='foo=bar'}, but it 20009allows any macro to be overridden. Makefiles generated by 20010@command{automake} use this technique, expanding @code{$(AM_MAKEFLAGS)} 20011on the command lines of submakes (@pxref{Subdirectories, , Automake, 20012automake, GNU Automake}). 20013 20014@node The Make Macro MAKEFLAGS 20015@section The Make Macro MAKEFLAGS 20016@cindex @code{MAKEFLAGS} and @command{make} 20017@cindex @command{make} and @code{MAKEFLAGS} 20018 20019Posix requires @command{make} to use @code{MAKEFLAGS} to affect the 20020current and recursive invocations of make, but allows implementations 20021several formats for the variable. It is tricky to parse 20022@code{$MAKEFLAGS} to determine whether @option{-s} for silent execution 20023or @option{-k} for continued execution are in effect. For example, you 20024cannot assume that the first space-separated word in @code{$MAKEFLAGS} 20025contains single-letter options, since in the Cygwin version of 20026GNU @command{make} it is either @option{--unix} or 20027@option{--win32} with the second word containing single-letter options. 20028 20029@example 20030$ @kbd{cat Makefile} 20031all: 20032 @@echo MAKEFLAGS = $(MAKEFLAGS) 20033$ @kbd{make} 20034MAKEFLAGS = --unix 20035$ @kbd{make -k} 20036MAKEFLAGS = --unix -k 20037@end example 20038 20039@node The Make Macro SHELL 20040@section The Make Macro @code{SHELL} 20041@cindex @code{SHELL} and @command{make} 20042@cindex @command{make} and @code{SHELL} 20043 20044Posix-compliant @command{make} internally uses the @code{$(SHELL)} 20045macro to spawn shell processes and execute Make rules. This 20046is a builtin macro supplied by @command{make}, but it can be modified 20047by a makefile or by a command-line argument. 20048 20049Not all @command{make} implementations define this @code{SHELL} macro. 20050Tru64 20051@command{make} is an example; this implementation always uses 20052@code{/bin/sh}. So it's a good idea to always define @code{SHELL} in 20053your makefiles. If you use Autoconf, do 20054 20055@example 20056SHELL = @@SHELL@@ 20057@end example 20058 20059@noindent 20060If you use Automake, this is done for you. 20061 20062Do not force @code{SHELL = /bin/sh} because that is not correct 20063everywhere. Remember, @file{/bin/sh} is not Posix compliant on many 20064systems, such as FreeBSD 4, NetBSD 3, AIX 3, Solaris 10, or Tru64. 20065Additionally, DJGPP lacks @code{/bin/sh}, and when its 20066GNU @command{make} port sees such a setting it enters a 20067special emulation mode where features like pipes and redirections are 20068emulated on top of DOS's @command{command.com}. Unfortunately this 20069emulation is incomplete; for instance it does not handle command 20070substitutions. Using @code{@@SHELL@@} means that your makefile will 20071benefit from the same improved shell, such as @command{bash} or 20072@command{ksh}, that was discovered during @command{configure}, so that 20073you aren't fighting two different sets of shell bugs between the two 20074contexts. 20075 20076Posix-compliant @command{make} should never acquire the value of 20077$(SHELL) from the environment, even when @code{make -e} is used 20078(otherwise, think about what would happen to your rules if 20079@code{SHELL=/bin/tcsh}). 20080 20081However not all @command{make} implementations have this exception. 20082For instance it's not surprising that Tru64 @command{make} doesn't 20083protect @code{SHELL}, since it doesn't use it. 20084 20085@example 20086$ @kbd{cat Makefile} 20087SHELL = /bin/sh 20088FOO = foo 20089all: 20090 @@echo $(SHELL) 20091 @@echo $(FOO) 20092$ @kbd{env SHELL=/bin/tcsh FOO=bar make -e} # Tru64 Make 20093/bin/tcsh 20094bar 20095$ @kbd{env SHELL=/bin/tcsh FOO=bar gmake -e} # GNU make 20096/bin/sh 20097bar 20098@end example 20099 20100Conversely, @command{make} is not supposed to export any changes to the 20101macro @code{SHELL} to child processes. Again, many implementations 20102break this rule: 20103 20104@example 20105$ @kbd{cat Makefile} 20106all: 20107 @@echo $(SHELL) 20108 @@printenv SHELL 20109$ @kbd{env SHELL=sh make -e SHELL=/bin/ksh} # BSD Make, GNU make 3.80 20110/bin/ksh 20111/bin/ksh 20112$ @kbd{env SHELL=sh gmake -e SHELL=/bin/ksh} # GNU make 3.81 20113/bin/ksh 20114sh 20115@end example 20116 20117@node Parallel Make 20118@section Parallel Make 20119@cindex Parallel @command{make} 20120 20121Support for parallel execution in @command{make} implementation varies. 20122Generally, using GNU make is your best bet. 20123 20124When NetBSD or FreeBSD @command{make} are run in parallel mode, they will 20125reuse the same shell for multiple commands within one recipe. This can 20126have various unexpected consequences. For example, changes of directories 20127or variables persist between recipes, so that: 20128 20129@example 20130all: 20131 @@var=value; cd /; pwd; echo $$var; echo $$$$ 20132 @@pwd; echo $$var; echo $$$$ 20133@end example 20134 20135@noindent 20136may output the following with @code{make -j1}, at least on NetBSD up to 201375.1 and FreeBSD up to 8.2: 20138 20139@example 20140/ 20141value 2014232235 20143/ 20144value 2014532235 20146@end example 20147 20148@noindent 20149while without @option{-j1}, or with @option{-B}, the output looks less 20150surprising: 20151 20152@example 20153/ 20154value 2015532238 20156/tmp 20157 2015832239 20159@end example 20160 20161@noindent 20162Another consequence is that, if one command in a recipe uses @code{exit 0} 20163to indicate a successful exit, the shell will be gone and the remaining 20164commands of this recipe will not be executed. 20165 20166The BSD @command{make} implementations, when run in parallel mode, 20167will also pass the @command{Makefile} recipes to the shell through 20168its standard input, thus making it unusable from the recipes: 20169 20170@example 20171$ @kbd{cat Makefile} 20172read: 20173 @@read line; echo LINE: $$line 20174@c $$ @c restore font-lock 20175$ @kbd{echo foo | make read} 20176LINE: foo 20177$ @kbd{echo foo | make -j1 read} # NetBSD 5.1 and FreeBSD 8.2 20178LINE: 20179@end example 20180 20181@noindent 20182Moreover, when FreeBSD @command{make} (up at least to 8.2) is run in 20183parallel mode, it implements the @code{@@} and @code{-} ``recipe 20184modifiers'' by dynamically modifying the active shell flags. This 20185behavior has the effects of potentially clobbering the exit status 20186of recipes silenced with the @code{@@} modifier if they also unset 20187the @option{errexit} shell flag, and of mangling the output in 20188unexpected ways: 20189 20190@example 20191$ @kbd{cat Makefile} 20192a: 20193 @@echo $$-; set +e; false 20194b: 20195 -echo $$-; false; echo set - 20196$ @kbd{make a; echo status: $?} 20197ehBc 20198*** Error code 1 20199status: 1 20200$ @kbd{make -j1 a; echo status: $?} 20201ehB 20202status: 0 20203$ @kbd{make b} 20204echo $-; echo set - 20205hBc 20206set - 20207$ @kbd{make -j1 b} 20208echo $-; echo hvB 20209@end example 20210 20211@noindent 20212You can avoid all these issues by using the @option{-B} option to enable 20213compatibility semantics. However, that will effectively also disable 20214all parallelism as that will cause prerequisites to be updated in the 20215order they are listed in a rule. 20216 20217Some make implementations (among them, FreeBSD @command{make}, NetBSD 20218@command{make}, and Solaris @command{dmake}), when invoked with a 20219@option{-j@var{N}} option, connect the standard output and standard 20220error of all their child processes to pipes or temporary regular 20221files. This can lead to subtly different semantics in the behavior 20222of the spawned processes. For example, even if the @command{make} 20223standard output is connected to a tty, the recipe command will not be: 20224 20225@example 20226$ @kbd{cat Makefile} 20227all: 20228 @@test -t 1 && echo "Is a tty" || echo "Is not a tty" 20229$ @kbd{make -j 2} # FreeBSD 8.2 make 20230Is not a tty 20231$ @kbd{make -j 2} # NetBSD 5.1 make 20232--- all --- 20233Is not a tty 20234$ @kbd{dmake -j 2} # Solaris 10 dmake 20235@var{hostname} --> 1 job 20236@var{hostname} --> Job output 20237Is not a tty 20238@end example 20239 20240@noindent 20241On the other hand: 20242 20243@example 20244$ @kbd{make -j 2} # GNU make, Heirloom make 20245Is a tty 20246@end example 20247 20248@noindent 20249The above examples also show additional status output produced in parallel 20250mode for targets being updated by Solaris @command{dmake} and NetBSD 20251@command{make} (but @emph{not} by FreeBSD @command{make}). 20252 20253Furthermore, parallel runs of those @command{make} implementations will 20254route standard error from commands that they spawn into their own 20255standard output, and may remove leading whitespace from output lines. 20256 20257 20258@node Comments in Make Rules 20259@section Comments in Make Rules 20260@cindex Comments in @file{Makefile} rules 20261@cindex @file{Makefile} rules and comments 20262 20263Never put comments in a rule. 20264 20265Some @command{make} treat anything starting with a tab as a command for 20266the current rule, even if the tab is immediately followed by a @code{#}. 20267The @command{make} from Tru64 Unix V5.1 is one of them. The following 20268makefile runs @code{# foo} through the shell. 20269 20270@example 20271all: 20272 # foo 20273@end example 20274 20275As a workaround, you can use the @command{:} no-op command with a string 20276argument that gets ignored: 20277 20278@example 20279all: 20280 : "foo" 20281@end example 20282 20283Conversely, if you want to use the @samp{#} character in some command, 20284you can only do so by expanding it inside a rule (@pxref{Comments in 20285Make Macros}). So for example, if @samp{COMMENT_CHAR} is substituted by 20286@command{config.status} as @samp{#}, then the following substitutes 20287@samp{@@COMMENT_CHAR@@} in a generated header: 20288 20289@example 20290foo.h: foo.h.in 20291 sed -e 's|@@''COMMENT_CHAR''@@|@@COMMENT_CHAR@@|g' \ 20292 $(srcdir)/foo.h.in > $@@ 20293@end example 20294 20295The funny shell quoting avoids a substitution at @command{config.status} 20296run time of the left-hand side of the @command{sed} @samp{s} command. 20297 20298@node Newlines in Make Rules 20299@section Newlines in Make Rules 20300@cindex Newlines in @file{Makefile} rules 20301@cindex @file{Makefile} rules and newlines 20302 20303In shell scripts, newlines can be used inside string literals. But in 20304the shell statements of @file{Makefile} rules, this is not possible: 20305A newline not preceded by a backslash is a separator between shell 20306statements. Whereas a newline that is preceded by a backslash becomes 20307part of the shell statement according to POSIX, but gets replaced, 20308together with the backslash that precedes it, by a space in GNU 20309@command{make} 3.80 and older. So, how can a newline be used in a string 20310literal? 20311 20312The trick is to set up a shell variable that contains a newline: 20313 20314@example 20315nlinit=`echo 'nl="'; echo '"'`; eval "$$nlinit" 20316@end example 20317 20318For example, in order to create a multiline @samp{sed} expression that 20319inserts a blank line after every line of a file, this code can be used: 20320 20321@example 20322nlinit=`echo 'nl="'; echo '"'`; eval "$$nlinit"; \ 20323sed -e "s/\$$/\\$$@{nl@}/" < input > output 20324@end example 20325 20326@node Comments in Make Macros 20327@section Comments in Make Macros 20328@cindex Comments in @file{Makefile} macros 20329@cindex @file{Makefile} macros and comments 20330 20331Avoid putting comments in macro values as far as possible. Posix 20332specifies that the text starting from the @samp{#} sign until the end of 20333the line is to be ignored, which has the unfortunate effect of 20334disallowing them even within quotes. Thus, the following might lead to 20335a syntax error at compile time: 20336 20337@example 20338CPPFLAGS = "-DCOMMENT_CHAR='#'" 20339@end example 20340 20341@noindent 20342as @samp{CPPFLAGS} may be expanded to @samp{"-DCOMMENT_CHAR='}. 20343 20344Most @command{make} implementations disregard this and treat single and 20345double quotes specially here. Also, GNU @command{make} lets you put 20346@samp{#} into a macro value by escaping it with a backslash, i.e., 20347@samp{\#}. However, neither of these usages are portable. 20348@xref{Comments in Make Rules}, for a portable alternative. 20349 20350Even without quoting involved, comments can have surprising effects, 20351because the whitespace before them is part of the variable value: 20352 20353@example 20354foo = bar # trailing comment 20355print: ; @@echo "$(foo)." 20356@end example 20357 20358@noindent 20359prints @samp{bar .}, which is usually not intended, and can expose 20360@command{make} bugs as described below. 20361 20362@node Trailing whitespace in Make Macros 20363@section Trailing whitespace in Make Macros 20364@cindex whitespace in @file{Makefile} macros 20365@cindex @file{Makefile} macros and whitespace 20366 20367GNU @command{make} 3.80 mistreats trailing whitespace in macro 20368substitutions and appends another spurious suffix: 20369 20370@example 20371empty = 20372foo = bar $(empty) 20373print: ; @@echo $(foo:=.test) 20374@end example 20375 20376@noindent 20377prints @samp{bar.test .test}. 20378 20379BSD and Solaris @command{make} implementations do not honor trailing 20380whitespace in macro definitions as Posix requires: 20381 20382@example 20383foo = bar # Note the space after "bar". 20384print: ; @@echo $(foo)t 20385@end example 20386 20387@noindent 20388prints @samp{bart} instead of @samp{bar t}. To work around this, you 20389can use a helper macro as in the previous example. 20390 20391 20392@node Command-line Macros and whitespace 20393@section Command-line Macros and whitespace 20394@cindex whitespace in command-line macros 20395@cindex command-line, macros set on 20396@cindex environment, macros set from 20397 20398Some @command{make} implementations may strip trailing whitespace off 20399of macros set on the command line in addition to leading whitespace. 20400Further, some may strip leading whitespace off of macros set from 20401environment variables: 20402 20403@example 20404$ @kbd{echo 'print: ; @@echo "x$(foo)x$(bar)x"' | 20405 foo=' f f ' make -f - bar=' b b '} 20406x f f xb b x # AIX, BSD, GNU make 20407xf f xb b x # HP-UX, IRIX, Tru64/OSF make 20408x f f xb bx # Solaris make 20409@end example 20410 20411 20412@node obj/ and Make 20413@section The @file{obj/} Subdirectory and Make 20414@cindex @file{obj/}, subdirectory 20415@cindex BSD @command{make} and @file{obj/} 20416 20417Never name one of your subdirectories @file{obj/} if you don't like 20418surprises. 20419 20420If an @file{obj/} directory exists, BSD @command{make} enters it 20421before reading the makefile. Hence the makefile in the 20422current directory is not read. 20423 20424@example 20425$ @kbd{cat Makefile} 20426all: 20427 echo Hello 20428$ @kbd{cat obj/Makefile} 20429all: 20430 echo World 20431$ @kbd{make} # GNU make 20432echo Hello 20433Hello 20434$ @kbd{pmake} # BSD make 20435echo World 20436World 20437@end example 20438 20439@node make -k Status 20440@section Exit Status of @code{make -k} 20441@cindex @code{make -k} 20442 20443Do not rely on the exit status of @code{make -k}. Some implementations 20444reflect whether they encountered an error in their exit status; other 20445implementations always succeed. 20446 20447@example 20448$ @kbd{cat Makefile} 20449all: 20450 false 20451$ @kbd{make -k; echo exit status: $?} # GNU make 20452false 20453make: *** [all] Error 1 20454exit status: 2 20455$ @kbd{pmake -k; echo exit status: $?} # BSD make 20456false 20457*** Error code 1 (continuing) 20458exit status: 0 20459@end example 20460 20461@node VPATH and Make 20462@section @code{VPATH} and Make 20463@cindex @code{VPATH} 20464 20465Posix does not specify the semantics of @code{VPATH}. Typically, 20466@command{make} supports @code{VPATH}, but its implementation is not 20467consistent. 20468 20469Autoconf and Automake support makefiles whose usages of @code{VPATH} are 20470portable to recent-enough popular implementations of @command{make}, but 20471to keep the resulting makefiles portable, a package's makefile 20472prototypes must take the following issues into account. These issues 20473are complicated and are often poorly understood, and installers who use 20474@code{VPATH} should expect to find many bugs in this area. If you use 20475@code{VPATH}, the simplest way to avoid these portability bugs is to 20476stick with GNU @command{make}, since it is the most 20477commonly-used @command{make} among Autoconf users. 20478 20479Here are some known issues with some @code{VPATH} 20480implementations. 20481 20482@menu 20483* Variables listed in VPATH:: @code{VPATH} must be literal on ancient hosts 20484* VPATH and Double-colon:: Problems with @samp{::} on ancient hosts 20485* $< in Explicit Rules:: @code{$<} does not work in ordinary rules 20486* Automatic Rule Rewriting:: @code{VPATH} goes wild on Solaris 20487* Tru64 Directory Magic:: @command{mkdir} goes wild on Tru64 20488* Make Target Lookup:: More details about @code{VPATH} lookup 20489@end menu 20490 20491@node Variables listed in VPATH 20492@subsection Variables listed in @code{VPATH} 20493@cindex @code{VPATH} and variables 20494@cindex variables and @code{VPATH} 20495 20496Do not set @code{VPATH} to the value of another variable, for example 20497@samp{VPATH = $(srcdir)}, because some ancient versions of 20498@command{make} do not do variable substitutions on the value of 20499@code{VPATH}. For example, use this 20500 20501@example 20502srcdir = @@srcdir@@ 20503VPATH = @@srcdir@@ 20504@end example 20505 20506@noindent 20507rather than @samp{VPATH = $(srcdir)}. Note that with GNU 20508Automake, there is no need to set this yourself. 20509 20510@node VPATH and Double-colon 20511@subsection @code{VPATH} and Double-colon Rules 20512@cindex @code{VPATH} and double-colon rules 20513@cindex double-colon rules and @code{VPATH} 20514 20515With ancient versions of Sun @command{make}, 20516any assignment to @code{VPATH} causes @command{make} to execute only 20517the first set of double-colon rules. 20518However, this problem is no longer of practical concern. 20519 20520@node $< in Explicit Rules 20521@subsection @code{$<} Not Supported in Explicit Rules 20522@cindex explicit rules, @code{$<}, and @code{VPATH} 20523@cindex @code{$<}, explicit rules, and @code{VPATH} 20524@cindex @code{VPATH}, explicit rules, and @code{$<} 20525 20526Using @code{$<} in explicit rules is not portable. 20527The prerequisite file must be named explicitly in the rule. If you want 20528to find the prerequisite via a @code{VPATH} search, you have to code the 20529whole thing manually. @xref{Build Directories}. 20530 20531@node Automatic Rule Rewriting 20532@subsection Automatic Rule Rewriting 20533@cindex @code{VPATH} and automatic rule rewriting 20534@cindex automatic rule rewriting and @code{VPATH} 20535 20536Some @command{make} implementations, such as Solaris and Tru64, 20537search for prerequisites in @code{VPATH} and 20538then rewrite each occurrence as a plain word in the rule. 20539For instance: 20540 20541@example 20542# This isn't portable to GNU make. 20543VPATH = ../pkg/src 20544f.c: if.c 20545 cp if.c f.c 20546@end example 20547 20548@noindent 20549executes @code{cp ../pkg/src/if.c f.c} if @file{if.c} is 20550found in @file{../pkg/src}. 20551 20552However, this rule leads to real problems in practice. For example, if 20553the source directory contains an ordinary file named @file{test} that is 20554used in a dependency, Solaris @command{make} rewrites commands like 20555@samp{if test -r foo; @dots{}} to @samp{if ../pkg/src/test -r foo; 20556@dots{}}, which is typically undesirable. In fact, @command{make} is 20557completely unaware of shell syntax used in the rules, so the VPATH 20558rewrite can potentially apply to @emph{any} whitespace-separated word 20559in a rule, including shell variables, functions, and keywords. 20560 20561@example 20562$ @kbd{mkdir build} 20563$ @kbd{cd build} 20564$ @kbd{cat > Makefile <<'END'} 20565VPATH = .. 20566all: arg func for echo 20567 func () @{ for arg in "$$@@"; do echo $$arg; done; @}; \ 20568 func "hello world" 20569END 20570$ @kbd{touch ../arg ../func ../for ../echo} 20571$ @kbd{make} 20572../func () @{ ../for ../arg in "$@@"; do ../echo $arg; done; @}; \ 20573../func "hello world" 20574sh: syntax error at line 1: `do' unexpected 20575*** Error code 2 20576@end example 20577 20578@noindent 20579To avoid this problem, portable makefiles should never mention a source 20580file or dependency whose name is that of a shell keyword like @file{for} 20581or @file{until}, a shell command like @command{cat} or @command{gcc} or 20582@command{test}, or a shell function or variable used in the corresponding 20583@command{Makefile} recipe. 20584 20585Because of these problems GNU @command{make} and many other @command{make} 20586implementations do not rewrite commands, so portable makefiles should 20587search @code{VPATH} manually. It is tempting to write this: 20588 20589@smallexample 20590# This isn't portable to Solaris make. 20591VPATH = ../pkg/src 20592f.c: if.c 20593 cp `test -f if.c || echo $(VPATH)/`if.c f.c 20594@end smallexample 20595 20596@noindent 20597However, the ``prerequisite rewriting'' still applies here. So if 20598@file{if.c} is in @file{../pkg/src}, Solaris and Tru64 @command{make} 20599execute 20600 20601@smallexample 20602cp `test -f ../pkg/src/if.c || echo ../pkg/src/`if.c f.c 20603@end smallexample 20604 20605@noindent 20606which reduces to 20607 20608@example 20609cp if.c f.c 20610@end example 20611 20612@noindent 20613and thus fails. Oops. 20614 20615A simple workaround, and good practice anyway, is to use @samp{$?} and 20616@samp{$@@} when possible: 20617 20618@smallexample 20619VPATH = ../pkg/src 20620f.c: if.c 20621 cp $? $@@ 20622@end smallexample 20623 20624@noindent 20625but this does not generalize well to commands with multiple 20626prerequisites. A more general workaround is to rewrite the rule so that 20627the prerequisite @file{if.c} never appears as a plain word. For 20628example, these three rules would be safe, assuming @file{if.c} is in 20629@file{../pkg/src} and the other files are in the working directory: 20630 20631@smallexample 20632VPATH = ../pkg/src 20633f.c: if.c f1.c 20634 cat `test -f ./if.c || echo $(VPATH)/`if.c f1.c >$@@ 20635g.c: if.c g1.c 20636 cat `test -f 'if.c' || echo $(VPATH)/`if.c g1.c >$@@ 20637h.c: if.c h1.c 20638 cat `test -f "if.c" || echo $(VPATH)/`if.c h1.c >$@@ 20639@end smallexample 20640 20641Things get worse when your prerequisites are in a macro. 20642 20643@example 20644VPATH = ../pkg/src 20645HEADERS = f.h g.h h.h 20646install-HEADERS: $(HEADERS) 20647 for i in $(HEADERS); do \ 20648 $(INSTALL) -m 644 \ 20649 `test -f $$i || echo $(VPATH)/`$$i \ 20650 $(DESTDIR)$(includedir)/$$i; \ 20651@c $$ restore font-lock 20652 done 20653@end example 20654 20655The above @code{install-HEADERS} rule is not Solaris-proof because @code{for 20656i in $(HEADERS);} is expanded to @code{for i in f.h g.h h.h;} 20657where @code{f.h} and @code{g.h} are plain words and are hence 20658subject to @code{VPATH} adjustments. 20659 20660If the three files are in @file{../pkg/src}, the rule is run as: 20661 20662@example 20663for i in ../pkg/src/f.h ../pkg/src/g.h h.h; do \ 20664 install -m 644 \ 20665 `test -f $i || echo ../pkg/src/`$i \ 20666 /usr/local/include/$i; \ 20667done 20668@end example 20669 20670where the two first @command{install} calls fail. For instance, 20671consider the @code{f.h} installation: 20672 20673@example 20674install -m 644 \ 20675 `test -f ../pkg/src/f.h || \ 20676 echo ../pkg/src/ \ 20677 `../pkg/src/f.h \ 20678 /usr/local/include/../pkg/src/f.h; 20679@end example 20680 20681@noindent 20682It reduces to: 20683 20684@example 20685install -m 644 \ 20686 ../pkg/src/f.h \ 20687 /usr/local/include/../pkg/src/f.h; 20688@end example 20689 20690Note that the manual @code{VPATH} search did not cause any problems here; 20691however this command installs @file{f.h} in an incorrect directory. 20692 20693Trying to quote @code{$(HEADERS)} in some way, as we did for 20694@code{foo.c} a few makefiles ago, does not help: 20695 20696@example 20697install-HEADERS: $(HEADERS) 20698 headers='$(HEADERS)'; \ 20699 for i in $$headers; do \ 20700 $(INSTALL) -m 644 \ 20701 `test -f $$i || echo $(VPATH)/`$$i \ 20702 $(DESTDIR)$(includedir)/$$i; \ 20703 done 20704@end example 20705 20706Now, @code{headers='$(HEADERS)'} macro-expands to: 20707 20708@example 20709headers='f.h g.h h.h' 20710@end example 20711 20712@noindent 20713but @code{g.h} is still a plain word. (As an aside, the idiom 20714@code{headers='$(HEADERS)'; for i in $$headers;} is a good 20715idea if @code{$(HEADERS)} can be empty, because some shells diagnose a 20716syntax error on @code{for i in;}.) 20717 20718One workaround is to strip this unwanted @file{../pkg/src/} prefix manually: 20719 20720@example 20721VPATH = ../pkg/src 20722HEADERS = f.h g.h h.h 20723install-HEADERS: $(HEADERS) 20724 headers='$(HEADERS)'; \ 20725 for i in $$headers; do \ 20726 i=`expr "$$i" : '$(VPATH)/\(.*\)'`; 20727 $(INSTALL) -m 644 \ 20728 `test -f $$i || echo $(VPATH)/`$$i \ 20729 $(DESTDIR)$(includedir)/$$i; \ 20730@c $$ restore font-lock 20731 done 20732@end example 20733 20734Automake does something similar. However the above hack works only if 20735the files listed in @code{HEADERS} are in the current directory or a 20736subdirectory; they should not be in an enclosing directory. If we had 20737@code{HEADERS = ../f.h}, the above fragment would fail in a VPATH 20738build with Tru64 @command{make}. The reason is that not only does 20739Tru64 @command{make} rewrite dependencies, but it also simplifies 20740them. Hence @code{../f.h} becomes @code{../pkg/f.h} instead of 20741@code{../pkg/src/../f.h}. This obviously defeats any attempt to strip 20742a leading @file{../pkg/src/} component. 20743 20744The following example makes the behavior of Tru64 @command{make} 20745more apparent. 20746 20747@example 20748$ @kbd{cat Makefile} 20749VPATH = sub 20750all: ../foo 20751 echo ../foo 20752$ @kbd{ls} 20753Makefile foo 20754$ @kbd{make} 20755echo foo 20756foo 20757@end example 20758 20759@noindent 20760Dependency @file{../foo} was found in @file{sub/../foo}, but Tru64 20761@command{make} simplified it as @file{foo}. (Note that the @file{sub/} 20762directory does not even exist, this just means that the simplification 20763occurred before the file was checked for.) 20764 20765For the record here is how SunOS 4 @command{make} behaves on this 20766example. 20767 20768@smallexample 20769$ @kbd{make} 20770make: Fatal error: Don't know how to make target `../foo' 20771$ @kbd{mkdir sub} 20772$ @kbd{make} 20773echo sub/../foo 20774sub/../foo 20775@end smallexample 20776 20777 20778@node Tru64 Directory Magic 20779@subsection Tru64 @command{make} Creates Prerequisite Directories Magically 20780@cindex @code{VPATH} and prerequisite directories 20781@cindex prerequisite directories and @code{VPATH} 20782 20783When a prerequisite is a subdirectory of @code{VPATH}, Tru64 20784@command{make} creates it in the current directory. 20785 20786@example 20787$ @kbd{mkdir -p foo/bar build} 20788$ @kbd{cd build} 20789$ @kbd{cat >Makefile <<END 20790VPATH = .. 20791all: foo/bar 20792END} 20793$ @kbd{make} 20794mkdir foo 20795mkdir foo/bar 20796@end example 20797 20798This can yield unexpected results if a rule uses a manual @code{VPATH} 20799search as presented before. 20800 20801@example 20802VPATH = .. 20803all : foo/bar 20804 command `test -d foo/bar || echo ../`foo/bar 20805@end example 20806 20807The above @command{command} is run on the empty @file{foo/bar} 20808directory that was created in the current directory. 20809 20810@node Make Target Lookup 20811@subsection Make Target Lookup 20812@cindex @code{VPATH}, resolving target pathnames 20813 20814GNU @command{make} uses a complex algorithm to decide when it 20815should use files found via a @code{VPATH} search. @xref{Search 20816Algorithm, , How Directory Searches are Performed, make, The GNU Make 20817Manual}. 20818 20819If a target needs to be rebuilt, GNU @command{make} discards the 20820file name found during the @code{VPATH} search for this target, and 20821builds the file locally using the file name given in the makefile. 20822If a target does not need to be rebuilt, GNU @command{make} uses the 20823file name found during the @code{VPATH} search. 20824 20825Other @command{make} implementations, like NetBSD @command{make}, are 20826easier to describe: the file name found during the @code{VPATH} search 20827is used whether the target needs to be rebuilt or not. Therefore 20828new files are created locally, but existing files are updated at their 20829@code{VPATH} location. 20830 20831OpenBSD and FreeBSD @command{make}, however, 20832never perform a 20833@code{VPATH} search for a dependency that has an explicit rule. 20834This is extremely annoying. 20835 20836When attempting a @code{VPATH} build for an autoconfiscated package 20837(e.g., @code{mkdir build && cd build && ../configure}), this means 20838GNU 20839@command{make} builds everything locally in the @file{build} 20840directory, while BSD @command{make} builds new files locally and 20841updates existing files in the source directory. 20842 20843@example 20844$ @kbd{cat Makefile} 20845VPATH = .. 20846all: foo.x bar.x 20847foo.x bar.x: newer.x 20848 @@echo Building $@@ 20849$ @kbd{touch ../bar.x} 20850$ @kbd{touch ../newer.x} 20851$ @kbd{make} # GNU make 20852Building foo.x 20853Building bar.x 20854$ @kbd{pmake} # NetBSD make 20855Building foo.x 20856Building ../bar.x 20857$ @kbd{fmake} # FreeBSD make, OpenBSD make 20858Building foo.x 20859Building bar.x 20860$ @kbd{tmake} # Tru64 make 20861Building foo.x 20862Building bar.x 20863$ @kbd{touch ../bar.x} 20864$ @kbd{make} # GNU make 20865Building foo.x 20866$ @kbd{pmake} # NetBSD make 20867Building foo.x 20868$ @kbd{fmake} # FreeBSD make, OpenBSD make 20869Building foo.x 20870Building bar.x 20871$ @kbd{tmake} # Tru64 make 20872Building foo.x 20873Building bar.x 20874@end example 20875 20876Note how NetBSD @command{make} updates @file{../bar.x} in its 20877VPATH location, and how FreeBSD, OpenBSD, and Tru64 20878@command{make} always 20879update @file{bar.x}, even when @file{../bar.x} is up to date. 20880 20881Another point worth mentioning is that once GNU @command{make} has 20882decided to ignore a @code{VPATH} file name (e.g., it ignored 20883@file{../bar.x} in the above example) it continues to ignore it when 20884the target occurs as a prerequisite of another rule. 20885 20886The following example shows that GNU @command{make} does not look up 20887@file{bar.x} in @code{VPATH} before performing the @code{.x.y} rule, 20888because it ignored the @code{VPATH} result of @file{bar.x} while running 20889the @code{bar.x: newer.x} rule. 20890 20891@example 20892$ @kbd{cat Makefile} 20893VPATH = .. 20894all: bar.y 20895bar.x: newer.x 20896 @@echo Building $@@ 20897.SUFFIXES: .x .y 20898.x.y: 20899 cp $< $@@ 20900$ @kbd{touch ../bar.x} 20901$ @kbd{touch ../newer.x} 20902$ @kbd{make} # GNU make 20903Building bar.x 20904cp bar.x bar.y 20905cp: cannot stat `bar.x': No such file or directory 20906make: *** [bar.y] Error 1 20907$ @kbd{pmake} # NetBSD make 20908Building ../bar.x 20909cp ../bar.x bar.y 20910$ @kbd{rm bar.y} 20911$ @kbd{fmake} # FreeBSD make, OpenBSD make 20912echo Building bar.x 20913cp bar.x bar.y 20914cp: cannot stat `bar.x': No such file or directory 20915*** Error code 1 20916$ @kbd{tmake} # Tru64 make 20917Building bar.x 20918cp: bar.x: No such file or directory 20919*** Exit 1 20920@end example 20921 20922Note that if you drop away the command from the @code{bar.x: newer.x} 20923rule, GNU @command{make} magically starts to work: it 20924knows that @code{bar.x} hasn't been updated, therefore it doesn't 20925discard the result from @code{VPATH} (@file{../bar.x}) in succeeding 20926uses. Tru64 also works, but FreeBSD and OpenBSD 20927still don't. 20928 20929@example 20930$ @kbd{cat Makefile} 20931VPATH = .. 20932all: bar.y 20933bar.x: newer.x 20934.SUFFIXES: .x .y 20935.x.y: 20936 cp $< $@@ 20937$ @kbd{touch ../bar.x} 20938$ @kbd{touch ../newer.x} 20939$ @kbd{make} # GNU make 20940cp ../bar.x bar.y 20941$ @kbd{rm bar.y} 20942$ @kbd{pmake} # NetBSD make 20943cp ../bar.x bar.y 20944$ @kbd{rm bar.y} 20945$ @kbd{fmake} # FreeBSD make, OpenBSD make 20946cp bar.x bar.y 20947cp: cannot stat `bar.x': No such file or directory 20948*** Error code 1 20949$ @kbd{tmake} # Tru64 make 20950cp ../bar.x bar.y 20951@end example 20952 20953It seems the sole solution that would please every @command{make} 20954implementation is to never rely on @code{VPATH} searches for targets. 20955In other words, @code{VPATH} should be reserved to unbuilt sources. 20956 20957 20958@node Single Suffix Rules 20959@section Single Suffix Rules and Separated Dependencies 20960@cindex Single Suffix Inference Rule 20961@cindex Rule, Single Suffix Inference 20962A @dfn{Single Suffix Rule} is basically a usual suffix (inference) rule 20963(@samp{.from.to:}), but which @emph{destination} suffix is empty 20964(@samp{.from:}). 20965 20966@cindex Separated Dependencies 20967@dfn{Separated dependencies} simply refers to listing the prerequisite 20968of a target, without defining a rule. Usually one can list on the one 20969hand side, the rules, and on the other hand side, the dependencies. 20970 20971Solaris @command{make} does not support separated dependencies for 20972targets defined by single suffix rules: 20973 20974@example 20975$ @kbd{cat Makefile} 20976.SUFFIXES: .in 20977foo: foo.in 20978.in: 20979 cp $< $@@ 20980$ @kbd{touch foo.in} 20981$ @kbd{make} 20982$ @kbd{ls} 20983Makefile foo.in 20984@end example 20985 20986@noindent 20987while GNU Make does: 20988 20989@example 20990$ @kbd{gmake} 20991cp foo.in foo 20992$ @kbd{ls} 20993Makefile foo foo.in 20994@end example 20995 20996Note it works without the @samp{foo: foo.in} dependency. 20997 20998@example 20999$ @kbd{cat Makefile} 21000.SUFFIXES: .in 21001.in: 21002 cp $< $@@ 21003$ @kbd{make foo} 21004cp foo.in foo 21005@end example 21006 21007@noindent 21008and it works with double suffix inference rules: 21009 21010@example 21011$ @kbd{cat Makefile} 21012foo.out: foo.in 21013.SUFFIXES: .in .out 21014.in.out: 21015 cp $< $@@ 21016$ @kbd{make} 21017cp foo.in foo.out 21018@end example 21019 21020As a result, in such a case, you have to write target rules. 21021 21022@node Timestamps and Make 21023@section Timestamp Resolution and Make 21024@cindex timestamp resolution 21025Traditionally, file timestamps had 1-second resolution, and 21026@command{make} used those timestamps to determine whether one file was 21027newer than the other. However, many modern file systems have 21028timestamps with 1-nanosecond resolution. Some @command{make} 21029implementations look at the entire timestamp; others ignore the 21030fractional part, which can lead to incorrect results. Normally this 21031is not a problem, but in some extreme cases you may need to use tricks 21032like @samp{sleep 1} to work around timestamp truncation bugs. 21033 21034Commands like @samp{cp -p} and @samp{touch -r} typically do not copy 21035file timestamps to their full resolutions (@pxref{touch, , Limitations of Usual 21036Tools}). Hence you should be wary of rules like this: 21037 21038@example 21039dest: src 21040 cp -p src dest 21041@end example 21042 21043as @file{dest} often appears to be older than @file{src} after the 21044timestamp is truncated, and this can cause @command{make} to do 21045needless rework the next time it is invoked. To work around this 21046problem, you can use a timestamp file, e.g.: 21047 21048@example 21049dest-stamp: src 21050 cp -p src dest 21051 date >dest-stamp 21052@end example 21053 21054Apart from timestamp resolution, there are also differences in handling 21055equal timestamps. HP-UX @command{make} updates targets if it has the 21056same time stamp as one of its prerequisites, in violation of Posix rules. 21057 21058This can cause spurious rebuilds for repeated runs of @command{make}. 21059This in turn can cause @command{make} to fail if it tries to rebuild 21060generated files in a possibly read-only source tree with tools not 21061present on the end-user machine. Use GNU @command{make} instead. 21062 21063 21064 21065@c ======================================== Portable C and C++ Programming 21066 21067@node Portable C and C++ 21068@chapter Portable C and C++ Programming 21069@cindex Portable C and C++ programming 21070 21071C and C++ programs often use low-level features of the underlying 21072system, and therefore are often more difficult to make portable to other 21073platforms. 21074 21075Several standards have been developed to help make your programs more 21076portable. If you write programs with these standards in mind, you can 21077have greater confidence that your programs work on a wide variety 21078of systems. 21079@ifhtml 21080@uref{http://@/gcc.gnu.org/@/onlinedocs/@/gcc/@/Standards.html, Language 21081Standards Supported by GCC} 21082@end ifhtml 21083@ifnothtml 21084@xref{Standards, , Language Standards Supported by 21085GCC, gcc, Using the GNU Compiler Collection 21086(GCC)}, 21087@end ifnothtml 21088for a list of C-related standards. Many programs also assume the 21089@uref{http://@/www.opengroup.org/@/susv3, Posix standard}. 21090 21091Some old code is written to be portable to K&R C, which predates any C 21092standard. K&R C compilers are no longer of practical interest, though, 21093and the rest of section assumes at least C89, the first C standard. 21094 21095Program portability is a huge topic, and this section can only briefly 21096introduce common pitfalls. @xref{System Portability, , Portability 21097between System Types, standards, The GNU Coding Standards}, for 21098more information. 21099 21100@menu 21101* Varieties of Unportability:: How to make your programs unportable 21102* Integer Overflow:: When integers get too large 21103* Preprocessor Arithmetic:: @code{#if} expression problems 21104* Null Pointers:: Properties of null pointers 21105* Buffer Overruns:: Subscript errors and the like 21106* Volatile Objects:: @code{volatile} and signals 21107* Floating Point Portability:: Portable floating-point arithmetic 21108* Exiting Portably:: Exiting and the exit status 21109@end menu 21110 21111@node Varieties of Unportability 21112@section Varieties of Unportability 21113@cindex portability 21114 21115Autoconf tests and ordinary programs often need to test what is allowed 21116on a system, and therefore they may need to deliberately exceed the 21117boundaries of what the standards allow, if only to see whether an 21118optional feature is present. When you write such a program, you should 21119keep in mind the difference between constraints, unspecified behavior, 21120and undefined behavior. 21121 21122In C, a @dfn{constraint} is a rule that the compiler must enforce. An 21123example constraint is that C programs must not declare a bit-field with 21124negative width. Tests can therefore reliably assume that programs with 21125negative-width bit-fields are rejected by a compiler that conforms 21126to the standard. 21127 21128@dfn{Unspecified behavior} is valid behavior, where the standard allows 21129multiple possibilities. For example, the order of evaluation of 21130function arguments is unspecified. Some unspecified behavior is 21131@dfn{implementation-defined}, i.e., documented by the implementation, 21132but since Autoconf tests cannot read the documentation they cannot 21133distinguish between implementation-defined and other unspecified 21134behavior. It is common for Autoconf tests to probe implementations to 21135determine otherwise-unspecified behavior. 21136 21137@dfn{Undefined behavior} is invalid behavior, where the standard allows 21138the implementation to do anything it pleases. For example, 21139dereferencing a null pointer leads to undefined behavior. If possible, 21140test programs should avoid undefined behavior, since a program with 21141undefined behavior might succeed on a test that should fail. 21142 21143The above rules apply to programs that are intended to conform to the 21144standard. However, strictly-conforming programs are quite rare, since 21145the standards are so limiting. A major goal of Autoconf is to support 21146programs that use implementation features not described by the standard, 21147and it is fairly common for test programs to violate the above rules, if 21148the programs work well enough in practice. 21149 21150@node Integer Overflow 21151@section Integer Overflow 21152@cindex integer overflow 21153@cindex overflow, signed integer 21154@cindex signed integer overflow 21155@cindex wraparound arithmetic 21156 21157In practice many portable C programs assume that signed integer overflow wraps 21158around reliably using two's complement arithmetic. Yet the C standard 21159says that program behavior is undefined on overflow, and in a few cases 21160C programs do not work on some modern implementations because their 21161overflows do not wrap around as their authors expected. Conversely, in 21162signed integer remainder, the C standard requires overflow 21163behavior that is commonly not implemented. 21164 21165@menu 21166* Integer Overflow Basics:: Why integer overflow is a problem 21167* Signed Overflow Examples:: Examples of code assuming wraparound 21168* Optimization and Wraparound:: Optimizations that break uses of wraparound 21169* Signed Overflow Advice:: Practical advice for signed overflow issues 21170* Signed Integer Division:: @code{INT_MIN / -1} and @code{INT_MIN % -1} 21171@end menu 21172 21173@node Integer Overflow Basics 21174@subsection Basics of Integer Overflow 21175@cindex integer overflow 21176@cindex overflow, signed integer 21177@cindex signed integer overflow 21178@cindex wraparound arithmetic 21179 21180In languages like C, unsigned integer overflow reliably wraps around; 21181e.g., @code{UINT_MAX + 1} yields zero. 21182This is guaranteed by the C standard and is 21183portable in practice, unless you specify aggressive, 21184nonstandard optimization options 21185suitable only for special applications. 21186 21187In contrast, the C standard says that signed integer overflow leads to 21188undefined behavior where a program can do anything, including dumping 21189core or overrunning a buffer. The misbehavior can even precede the 21190overflow. Such an overflow can occur during addition, subtraction, 21191multiplication, division, and left shift. 21192 21193Despite this requirement of the standard, many C programs and Autoconf 21194tests assume that signed integer overflow silently wraps around modulo a 21195power of two, using two's complement arithmetic, so long as you cast the 21196resulting value to a signed integer type or store it into a signed 21197integer variable. If you use conservative optimization flags, such 21198programs are generally portable to the vast majority of modern 21199platforms, with a few exceptions discussed later. 21200 21201For historical reasons the C standard also allows implementations with 21202ones' complement or signed magnitude arithmetic, but it is safe to 21203assume two's complement nowadays. 21204 21205Also, overflow can occur when converting an out-of-range value to a 21206signed integer type. Here a standard implementation must define what 21207happens, but this might include raising an exception. In practice all 21208known implementations support silent wraparound in this case, so you need 21209not worry about other possibilities. 21210 21211@node Signed Overflow Examples 21212@subsection Examples of Code Assuming Wraparound Overflow 21213@cindex integer overflow 21214@cindex overflow, signed integer 21215@cindex signed integer overflow 21216@cindex wraparound arithmetic 21217 21218There has long been a tension between what the C standard requires for 21219signed integer overflow, and what C programs commonly assume. The 21220standard allows aggressive optimizations based on assumptions that 21221overflow never occurs, but many practical C programs rely on overflow 21222wrapping around. These programs do not conform to the standard, but 21223they commonly work in practice because compiler writers are 21224understandably reluctant to implement optimizations that would break 21225many programs, unless perhaps a user specifies aggressive optimization. 21226 21227The C Standard says that if a program has signed integer overflow its 21228behavior is undefined, and the undefined behavior can even precede the 21229overflow. To take an extreme example: 21230 21231@c Inspired by Robert Dewar's example in 21232@c <http://gcc.gnu.org/ml/gcc/2007-01/msg00038.html> (2007-01-01). 21233@example 21234if (password == expected_password) 21235 allow_superuser_privileges (); 21236else if (counter++ == INT_MAX) 21237 abort (); 21238else 21239 printf ("%d password mismatches\n", counter); 21240@end example 21241 21242@noindent 21243If the @code{int} variable @code{counter} equals @code{INT_MAX}, 21244@code{counter++} must overflow and the behavior is undefined, so the C 21245standard allows the compiler to optimize away the test against 21246@code{INT_MAX} and the @code{abort} call. 21247Worse, if an earlier bug in the program lets the compiler deduce that 21248@code{counter == INT_MAX} or that @code{counter} previously overflowed, 21249the C standard allows the compiler to optimize away the password test 21250and generate code that allows superuser privileges unconditionally. 21251 21252Despite this requirement by the standard, it has long been common for C 21253code to assume wraparound arithmetic after signed overflow, and all 21254known practical C implementations support some C idioms that assume 21255wraparound signed arithmetic, even if the idioms do not conform 21256strictly to the standard. If your code looks like the following 21257examples it will almost surely work with real-world compilers. 21258 21259Here is an example derived from the 7th Edition Unix implementation of 21260@code{atoi} (1979-01-10): 21261 21262@example 21263char *p; 21264int f, n; 21265@dots{} 21266while (*p >= '0' && *p <= '9') 21267 n = n * 10 + *p++ - '0'; 21268return (f ? -n : n); 21269@end example 21270 21271@noindent 21272Even if the input string is in range, on most modern machines this has 21273signed overflow when computing the most negative integer (the @code{-n} 21274overflows) or a value near an extreme integer (the first @code{+} 21275overflows). 21276 21277Here is another example, derived from the 7th Edition implementation of 21278@code{rand} (1979-01-10). Here the programmer expects both 21279multiplication and addition to wrap on overflow: 21280 21281@example 21282static long int randx = 1; 21283@dots{} 21284randx = randx * 1103515245 + 12345; 21285return (randx >> 16) & 077777; 21286@end example 21287 21288In the following example, derived from the GNU C Library 2.5 21289implementation of @code{mktime} (2006-09-09), the code assumes 21290wraparound arithmetic in @code{+} to detect signed overflow: 21291 21292@example 21293time_t t, t1, t2; 21294int sec_requested, sec_adjustment; 21295@dots{} 21296t1 = t + sec_requested; 21297t2 = t1 + sec_adjustment; 21298if (((t1 < t) != (sec_requested < 0)) 21299 | ((t2 < t1) != (sec_adjustment < 0))) 21300 return -1; 21301@end example 21302 21303If your code looks like these examples, it is probably safe even though 21304it does not strictly conform to the C standard. This might lead one to 21305believe that one can generally assume wraparound on overflow, but that 21306is not always true, as can be seen in the next section. 21307 21308@node Optimization and Wraparound 21309@subsection Optimizations That Break Wraparound Arithmetic 21310@cindex loop induction 21311 21312Compilers sometimes generate code that is incompatible with wraparound 21313integer arithmetic. A simple example is an algebraic simplification: a 21314compiler might translate @code{(i * 2000) / 1000} to @code{i * 2} 21315because it assumes that @code{i * 2000} does not overflow. The 21316translation is not equivalent to the original when overflow occurs: 21317e.g., in the typical case of 32-bit signed two's complement wraparound 21318@code{int}, if @code{i} has type @code{int} and value @code{1073742}, 21319the original expression returns @minus{}2147483 but the optimized 21320version returns the mathematically correct value 2147484. 21321 21322More subtly, loop induction optimizations often exploit the undefined 21323behavior of signed overflow. Consider the following contrived function 21324@code{sumc}: 21325 21326@example 21327int 21328sumc (int lo, int hi) 21329@{ 21330 int sum = 0; 21331 int i; 21332 for (i = lo; i <= hi; i++) 21333 sum ^= i * 53; 21334 return sum; 21335@} 21336@end example 21337 21338@noindent 21339To avoid multiplying by 53 each time through the loop, an optimizing 21340compiler might internally transform @code{sumc} to the equivalent of the 21341following: 21342 21343@example 21344int 21345transformed_sumc (int lo, int hi) 21346@{ 21347 int sum = 0; 21348 int hic = hi * 53; 21349 int ic; 21350 for (ic = lo * 53; ic <= hic; ic += 53) 21351 sum ^= ic; 21352 return sum; 21353@} 21354@end example 21355 21356@noindent 21357This transformation is allowed by the C standard, but it is invalid for 21358wraparound arithmetic when @code{INT_MAX / 53 < hi}, because then the 21359overflow in computing expressions like @code{hi * 53} can cause the 21360expression @code{i <= hi} to yield a different value from the 21361transformed expression @code{ic <= hic}. 21362 21363For this reason, compilers that use loop induction and similar 21364techniques often do not support reliable wraparound arithmetic when a 21365loop induction variable like @code{ic} is involved. Since loop 21366induction variables are generated by the compiler, and are not visible 21367in the source code, it is not always trivial to say whether the problem 21368affects your code. 21369 21370Hardly any code actually depends on wraparound arithmetic in cases like 21371these, so in practice these loop induction optimizations are almost 21372always useful. However, edge cases in this area can cause problems. 21373For example: 21374 21375@example 21376int j; 21377for (j = 1; 0 < j; j *= 2) 21378 test (j); 21379@end example 21380 21381@noindent 21382Here, the loop attempts to iterate through all powers of 2 that 21383@code{int} can represent, but the C standard allows a compiler to 21384optimize away the comparison and generate an infinite loop, 21385under the argument that behavior is undefined on overflow. As of this 21386writing this optimization is not done by any production version of 21387GCC with @option{-O2}, but it might be performed by other 21388compilers, or by more aggressive GCC optimization options, 21389and the GCC developers have not decided whether it will 21390continue to work with GCC and @option{-O2}. 21391 21392@node Signed Overflow Advice 21393@subsection Practical Advice for Signed Overflow Issues 21394@cindex integer overflow 21395@cindex overflow, signed integer 21396@cindex signed integer overflow 21397@cindex wraparound arithmetic 21398 21399Ideally the safest approach is to avoid signed integer overflow 21400entirely. For example, instead of multiplying two signed integers, you 21401can convert them to unsigned integers, multiply the unsigned values, 21402then test whether the result is in signed range. 21403 21404Rewriting code in this way will be inconvenient, though, particularly if 21405the signed values might be negative. Also, it may hurt 21406performance. Using unsigned arithmetic to check for overflow is 21407particularly painful to do portably and efficiently when dealing with an 21408integer type like @code{uid_t} whose width and signedness vary from 21409platform to platform. 21410 21411Furthermore, many C applications pervasively assume wraparound behavior 21412and typically it is not easy to find and remove all these assumptions. 21413Hence it is often useful to maintain nonstandard code that assumes 21414wraparound on overflow, instead of rewriting the code. The rest of this 21415section attempts to give practical advice for this situation. 21416 21417If your code wants to detect signed integer overflow in @code{sum = a + 21418b}, it is generally safe to use an expression like @code{(sum < a) != (b 21419< 0)}. 21420 21421If your code uses a signed loop index, make sure that the index cannot 21422overflow, along with all signed expressions derived from the index. 21423Here is a contrived example of problematic code with two instances of 21424overflow. 21425 21426@example 21427for (i = INT_MAX - 10; i <= INT_MAX; i++) 21428 if (i + 1 < 0) 21429 @{ 21430 report_overflow (); 21431 break; 21432 @} 21433@end example 21434 21435@noindent 21436Because of the two overflows, a compiler might optimize away or 21437transform the two comparisons in a way that is incompatible with the 21438wraparound assumption. 21439 21440If your code uses an expression like @code{(i * 2000) / 1000} and you 21441actually want the multiplication to wrap around on overflow, use 21442unsigned arithmetic 21443to do it, e.g., @code{((int) (i * 2000u)) / 1000}. 21444 21445If your code assumes wraparound behavior and you want to insulate it 21446against any GCC optimizations that would fail to support that 21447behavior, you should use GCC's @option{-fwrapv} option, which 21448causes signed overflow to wrap around reliably (except for division and 21449remainder, as discussed in the next section). 21450 21451If you need to port to platforms where signed integer overflow does not 21452reliably wrap around (e.g., due to hardware overflow checking, or to 21453highly aggressive optimizations), you should consider debugging with 21454GCC's @option{-ftrapv} option, which causes signed overflow to 21455raise an exception. 21456 21457@node Signed Integer Division 21458@subsection Signed Integer Division and Integer Overflow 21459@cindex division, integer 21460 21461Overflow in signed 21462integer division is not always harmless: for example, on CPUs of the 21463i386 family, dividing @code{INT_MIN} by @code{-1} yields a SIGFPE signal 21464which by default terminates the program. Worse, taking the remainder 21465of these two values typically yields the same signal on these CPUs, 21466even though the C standard requires @code{INT_MIN % -1} to yield zero 21467because the expression does not overflow. 21468 21469@node Preprocessor Arithmetic 21470@section Preprocessor Arithmetic 21471@cindex preprocessor arithmetic 21472 21473In C99, preprocessor arithmetic, used for @code{#if} expressions, must 21474be evaluated as if all signed values are of type @code{intmax_t} and all 21475unsigned values of type @code{uintmax_t}. Many compilers are buggy in 21476this area, though. For example, as of 2007, Sun C mishandles @code{#if 21477LLONG_MIN < 0} on a platform with 32-bit @code{long int} and 64-bit 21478@code{long long int}. Also, some older preprocessors mishandle 21479constants ending in @code{LL}. To work around these problems, you can 21480compute the value of expressions like @code{LONG_MAX < LLONG_MAX} at 21481@code{configure}-time rather than at @code{#if}-time. 21482 21483@node Null Pointers 21484@section Properties of Null Pointers 21485@cindex null pointers 21486 21487Most modern hosts reliably fail when you attempt to dereference a null 21488pointer. 21489 21490On almost all modern hosts, null pointers use an all-bits-zero internal 21491representation, so you can reliably use @code{memset} with 0 to set all 21492the pointers in an array to null values. 21493 21494If @code{p} is a null pointer to an object type, the C expression 21495@code{p + 0} always evaluates to @code{p} on modern hosts, even though 21496the standard says that it has undefined behavior. 21497 21498@node Buffer Overruns 21499@section Buffer Overruns and Subscript Errors 21500@cindex buffer overruns 21501 21502Buffer overruns and subscript errors are the most common dangerous 21503errors in C programs. They result in undefined behavior because storing 21504outside an array typically modifies storage that is used by some other 21505object, and most modern systems lack runtime checks to catch these 21506errors. Programs should not rely on buffer overruns being caught. 21507 21508There is one exception to the usual rule that a portable program cannot 21509address outside an array. In C, it is valid to compute the address just 21510past an object, e.g., @code{&a[N]} where @code{a} has @code{N} elements, 21511so long as you do not dereference the resulting pointer. But it is not 21512valid to compute the address just before an object, e.g., @code{&a[-1]}; 21513nor is it valid to compute two past the end, e.g., @code{&a[N+1]}. On 21514most platforms @code{&a[-1] < &a[0] && &a[N] < &a[N+1]}, but this is not 21515reliable in general, and it is usually easy enough to avoid the 21516potential portability problem, e.g., by allocating an extra unused array 21517element at the start or end. 21518 21519@uref{http://@/valgrind.org/, Valgrind} can catch many overruns. 21520GCC 21521users might also consider using the @option{-fmudflap} option to catch 21522overruns. 21523 21524Buffer overruns are usually caused by off-by-one errors, but there are 21525more subtle ways to get them. 21526 21527Using @code{int} values to index into an array or compute array sizes 21528causes problems on typical 64-bit hosts where an array index might 21529be @math{2^{31}} or larger. Index values of type @code{size_t} avoid this 21530problem, but cannot be negative. Index values of type @code{ptrdiff_t} 21531are signed, and are wide enough in practice. 21532 21533If you add or multiply two numbers to calculate an array size, e.g., 21534@code{malloc (x * sizeof y + z)}, havoc ensues if the addition or 21535multiplication overflows. 21536 21537Many implementations of the @code{alloca} function silently misbehave 21538and can generate buffer overflows if given sizes that are too large. 21539The size limits are implementation dependent, but are at least 4000 21540bytes on all platforms that we know about. 21541 21542The standard functions @code{asctime}, @code{asctime_r}, @code{ctime}, 21543@code{ctime_r}, and @code{gets} are prone to buffer overflows, and 21544portable code should not use them unless the inputs are known to be 21545within certain limits. The time-related functions can overflow their 21546buffers if given timestamps out of range (e.g., a year less than -999 21547or greater than 9999). Time-related buffer overflows cannot happen with 21548recent-enough versions of the GNU C library, but are possible 21549with other 21550implementations. The @code{gets} function is the worst, since it almost 21551invariably overflows its buffer when presented with an input line larger 21552than the buffer. 21553 21554@node Volatile Objects 21555@section Volatile Objects 21556@cindex volatile objects 21557 21558The keyword @code{volatile} is often misunderstood in portable code. 21559Its use inhibits some memory-access optimizations, but programmers often 21560wish that it had a different meaning than it actually does. 21561 21562@code{volatile} was designed for code that accesses special objects like 21563memory-mapped device registers whose contents spontaneously change. 21564Such code is inherently low-level, and it is difficult to specify 21565portably what @code{volatile} means in these cases. The C standard 21566says, ``What constitutes an access to an object that has 21567volatile-qualified type is implementation-defined,'' so in theory each 21568implementation is supposed to fill in the gap by documenting what 21569@code{volatile} means for that implementation. In practice, though, 21570this documentation is usually absent or incomplete. 21571 21572One area of confusion is the distinction between objects defined with 21573volatile types, and volatile lvalues. From the C standard's point of 21574view, an object defined with a volatile type has externally visible 21575behavior. You can think of such objects as having little oscilloscope 21576probes attached to them, so that the user can observe some properties of 21577accesses to them, just as the user can observe data written to output 21578files. However, the standard does not make it clear whether users can 21579observe accesses by volatile lvalues to ordinary objects. For example: 21580 21581@example 21582/* Declare and access a volatile object. 21583 Accesses to X are "visible" to users. */ 21584static int volatile x; 21585x = 1; 21586 21587/* Access two ordinary objects via a volatile lvalue. 21588 It's not clear whether accesses to *P are "visible". */ 21589int y; 21590int *z = malloc (sizeof (int)); 21591int volatile *p; 21592p = &y; 21593*p = 1; 21594p = z; 21595*p = 1; 21596@end example 21597 21598Programmers often wish that @code{volatile} meant ``Perform the memory 21599access here and now, without merging several memory accesses, without 21600changing the memory word size, and without reordering.'' But the C 21601standard does not require this. For objects defined with a volatile 21602type, accesses must be done before the next sequence point; but 21603otherwise merging, reordering, and word-size change is allowed. Worse, 21604it is not clear from the standard whether volatile lvalues provide more 21605guarantees in general than nonvolatile lvalues, if the underlying 21606objects are ordinary. 21607 21608Even when accessing objects defined with a volatile type, 21609the C standard allows only 21610extremely limited signal handlers: the behavior is undefined if a signal 21611handler reads any nonlocal object, or writes to any nonlocal object 21612whose type is not @code{sig_atomic_t volatile}, or calls any standard 21613library function other than @code{abort}, @code{signal}, and (if C99) 21614@code{_Exit}. Hence C compilers need not worry about a signal handler 21615disturbing ordinary computation, unless the computation accesses a 21616@code{sig_atomic_t volatile} lvalue that is not a local variable. 21617(There is an obscure exception for accesses via a pointer to a volatile 21618character, since it may point into part of a @code{sig_atomic_t 21619volatile} object.) Posix 21620adds to the list of library functions callable from a portable signal 21621handler, but otherwise is like the C standard in this area. 21622 21623Some C implementations allow memory-access optimizations within each 21624translation unit, such that actual behavior agrees with the behavior 21625required by the standard only when calling a function in some other 21626translation unit, and a signal handler acts like it was called from a 21627different translation unit. The C standard hints that in these 21628implementations, objects referred to by signal handlers ``would require 21629explicit specification of @code{volatile} storage, as well as other 21630implementation-defined restrictions.'' But unfortunately even for this 21631special case these other restrictions are often not documented well. 21632@xref{Volatiles, , When is a Volatile Object Accessed?, gcc, Using the 21633GNU Compiler Collection (GCC)}, for some 21634restrictions imposed by GCC. @xref{Defining Handlers, , 21635Defining Signal Handlers, libc, The GNU C Library}, for some 21636restrictions imposed by the GNU C library. Restrictions 21637differ on other platforms. 21638 21639If possible, it is best to use a signal handler that fits within the 21640limits imposed by the C and Posix standards. 21641 21642If this is not practical, you can try the following rules of thumb. A 21643signal handler should access only volatile lvalues, preferably lvalues 21644that refer to objects defined with a volatile type, and should not 21645assume that the accessed objects have an internally consistent state 21646if they are larger than a machine word. Furthermore, installers 21647should employ compilers and compiler options that are commonly used 21648for building operating system kernels, because kernels often need more 21649from @code{volatile} than the C Standard requires, and installers who 21650compile an application in a similar environment can sometimes benefit 21651from the extra constraints imposed by kernels on compilers. 21652Admittedly we are handwaving somewhat here, as there are few 21653guarantees in this area; the rules of thumb may help to fix some bugs 21654but there is a good chance that they will not fix them all. 21655 21656For @code{volatile}, C++ has the same problems that C does. 21657Multithreaded applications have even more problems with @code{volatile}, 21658but they are beyond the scope of this section. 21659 21660The bottom line is that using @code{volatile} typically hurts 21661performance but should not hurt correctness. In some cases its use 21662does help correctness, but these cases are often so poorly understood 21663that all too often adding @code{volatile} to a data structure merely 21664alleviates some symptoms of a bug while not fixing the bug in general. 21665 21666@node Floating Point Portability 21667@section Floating Point Portability 21668@cindex floating point 21669 21670Almost all modern systems use IEEE-754 floating point, and it is safe to 21671assume IEEE-754 in most portable code these days. For more information, 21672please see David Goldberg's classic paper 21673@uref{http://@/www.validlab.com/@/goldberg/@/paper.pdf, What Every Computer 21674Scientist Should Know About Floating-Point Arithmetic}. 21675 21676@node Exiting Portably 21677@section Exiting Portably 21678@cindex exiting portably 21679 21680A C or C++ program can exit with status @var{N} by returning 21681@var{N} from the @code{main} function. Portable programs are supposed 21682to exit either with status 0 or @code{EXIT_SUCCESS} to succeed, or with 21683status @code{EXIT_FAILURE} to fail, but in practice it is portable to 21684fail by exiting with status 1, and test programs that assume Posix can 21685fail by exiting with status values from 1 through 255. Programs on 21686SunOS 2.0 (1985) through 3.5.2 (1988) incorrectly exited with zero 21687status when @code{main} returned nonzero, but ancient systems like these 21688are no longer of practical concern. 21689 21690A program can also exit with status @var{N} by passing @var{N} to the 21691@code{exit} function, and a program can fail by calling the @code{abort} 21692function. If a program is specialized to just some platforms, it can fail 21693by calling functions specific to those platforms, e.g., @code{_exit} 21694(Posix) and @code{_Exit} (C99). However, like other functions, an exit 21695function should be declared, typically by including a header. For 21696example, if a C program calls @code{exit}, it should include @file{stdlib.h} 21697either directly or via the default includes (@pxref{Default Includes}). 21698 21699A program can fail due to undefined behavior such as dereferencing a null 21700pointer, but this is not recommended as undefined behavior allows an 21701implementation to do whatever it pleases and this includes exiting 21702successfully. 21703 21704 21705@c ================================================== Manual Configuration 21706 21707@node Manual Configuration 21708@chapter Manual Configuration 21709 21710A few kinds of features can't be guessed automatically by running test 21711programs. For example, the details of the object-file format, or 21712special options that need to be passed to the compiler or linker. You 21713can check for such features using ad-hoc means, such as having 21714@command{configure} check the output of the @code{uname} program, or 21715looking for libraries that are unique to particular systems. However, 21716Autoconf provides a uniform method for handling unguessable features. 21717 21718@menu 21719* Specifying Target Triplets:: Specifying target triplets 21720* Canonicalizing:: Getting the canonical system type 21721* Using System Type:: What to do with the system type 21722@end menu 21723 21724@node Specifying Target Triplets 21725@section Specifying target triplets 21726@cindex System type 21727@cindex Target triplet 21728@c This node used to be named Specifying Names. The @anchor allows old 21729@c links to still work. 21730@anchor{Specifying Names} 21731 21732Autoconf-generated 21733@command{configure} scripts can make decisions based on a canonical name 21734for the system type, or @dfn{target triplet}, which has the form: 21735@samp{@var{cpu}-@var{vendor}-@var{os}}, where @var{os} can be 21736@samp{@var{system}} or @samp{@var{kernel}-@var{system}} 21737 21738@command{configure} can usually guess the canonical name for the type of 21739system it's running on. To do so it runs a script called 21740@command{config.guess}, which infers the name using the @code{uname} 21741command or symbols predefined by the C preprocessor. 21742 21743Alternately, the user can specify the system type with command line 21744arguments to @command{configure} (@pxref{System Type}. Doing so is 21745necessary when 21746cross-compiling. In the most complex case of cross-compiling, three 21747system types are involved. The options to specify them are: 21748 21749@table @option 21750@item --build=@var{build-type} 21751the type of system on which the package is being configured and 21752compiled. It defaults to the result of running @command{config.guess}. 21753Specifying a @var{build-type} that differs from @var{host-type} enables 21754cross-compilation mode. 21755 21756@item --host=@var{host-type} 21757the type of system on which the package runs. By default it is the 21758same as the build machine. Specifying a @var{host-type} that differs 21759from @var{build-type}, when @var{build-type} was also explicitly 21760specified, enables cross-compilation mode. 21761 21762@item --target=@var{target-type} 21763the type of system for which any compiler tools in the package 21764produce code (rarely needed). By default, it is the same as host. 21765@end table 21766 21767If you mean to override the result of @command{config.guess}, use 21768@option{--build}, not @option{--host}, since the latter enables 21769cross-compilation. For historical reasons, 21770whenever you specify @option{--host}, 21771be sure to specify @option{--build} too; this will be fixed in the 21772future. So, to enter cross-compilation mode, use a command like this 21773 21774@example 21775./configure --build=i686-pc-linux-gnu --host=m68k-coff 21776@end example 21777 21778@noindent 21779Note that if you do not specify @option{--host}, @command{configure} 21780fails if it can't run the code generated by the specified compiler. For 21781example, configuring as follows fails: 21782 21783@example 21784./configure CC=m68k-coff-gcc 21785@end example 21786 21787When cross-compiling, @command{configure} will warn about any tools 21788(compilers, linkers, assemblers) whose name is not prefixed with the 21789host type. This is an aid to users performing cross-compilation. 21790Continuing the example above, if a cross-compiler named @command{cc} is 21791used with a native @command{pkg-config}, then libraries found by 21792@command{pkg-config} will likely cause subtle build failures; but using 21793the names @command{m68k-coff-cc} and @command{m68k-coff-pkg-config} 21794avoids any confusion. Avoiding the warning is as simple as creating the 21795correct symlinks naming the cross tools. 21796 21797@cindex @command{config.sub} 21798@command{configure} recognizes short aliases for many system types; for 21799example, @samp{decstation} can be used instead of 21800@samp{mips-dec-ultrix4.2}. @command{configure} runs a script called 21801@command{config.sub} to canonicalize system type aliases. 21802 21803This section deliberately omits the description of the obsolete 21804interface; see @ref{Hosts and Cross-Compilation}. 21805 21806 21807@node Canonicalizing 21808@section Getting the Canonical System Type 21809@cindex System type 21810@cindex Canonical system type 21811 21812The following macros make the system type available to @command{configure} 21813scripts. 21814 21815@ovindex build_alias 21816@ovindex host_alias 21817@ovindex target_alias 21818 21819The variables @samp{build_alias}, @samp{host_alias}, and 21820@samp{target_alias} are always exactly the arguments of @option{--build}, 21821@option{--host}, and @option{--target}; in particular, they are left empty 21822if the user did not use them, even if the corresponding 21823@code{AC_CANONICAL} macro was run. Any configure script may use these 21824variables anywhere. These are the variables that should be used when in 21825interaction with the user. 21826 21827If you need to recognize some special environments based on their system 21828type, run the following macros to get canonical system names. These 21829variables are not set before the macro call. 21830 21831If you use these macros, you must distribute @command{config.guess} and 21832@command{config.sub} along with your source code. @xref{Output}, for 21833information about the @code{AC_CONFIG_AUX_DIR} macro which you can use 21834to control in which directory @command{configure} looks for those scripts. 21835 21836 21837@defmac AC_CANONICAL_BUILD 21838@acindex{CANONICAL_BUILD} 21839@ovindex build 21840@ovindex build_cpu 21841@ovindex build_vendor 21842@ovindex build_os 21843Compute the canonical build-system type variable, @code{build}, and its 21844three individual parts @code{build_cpu}, @code{build_vendor}, and 21845@code{build_os}. 21846 21847If @option{--build} was specified, then @code{build} is the 21848canonicalization of @code{build_alias} by @command{config.sub}, 21849otherwise it is determined by the shell script @command{config.guess}. 21850@end defmac 21851 21852@defmac AC_CANONICAL_HOST 21853@acindex{CANONICAL_HOST} 21854@ovindex host 21855@ovindex host_cpu 21856@ovindex host_vendor 21857@ovindex host_os 21858Compute the canonical host-system type variable, @code{host}, and its 21859three individual parts @code{host_cpu}, @code{host_vendor}, and 21860@code{host_os}. 21861 21862If @option{--host} was specified, then @code{host} is the 21863canonicalization of @code{host_alias} by @command{config.sub}, 21864otherwise it defaults to @code{build}. 21865@end defmac 21866 21867@defmac AC_CANONICAL_TARGET 21868@acindex{CANONICAL_TARGET} 21869@ovindex target 21870@ovindex target_cpu 21871@ovindex target_vendor 21872@ovindex target_os 21873Compute the canonical target-system type variable, @code{target}, and its 21874three individual parts @code{target_cpu}, @code{target_vendor}, and 21875@code{target_os}. 21876 21877If @option{--target} was specified, then @code{target} is the 21878canonicalization of @code{target_alias} by @command{config.sub}, 21879otherwise it defaults to @code{host}. 21880@end defmac 21881 21882Note that there can be artifacts due to the backward compatibility 21883code. @xref{Hosts and Cross-Compilation}, for more. 21884 21885@node Using System Type 21886@section Using the System Type 21887 21888In @file{configure.ac} the system type is generally used by one or more 21889@code{case} statements to select system-specifics. Shell wildcards can 21890be used to match a group of system types. 21891 21892For example, an extra assembler code object file could be chosen, giving 21893access to a CPU cycle counter register. @code{$(CYCLE_OBJ)} in the 21894following would be used in a makefile to add the object to a 21895program or library. 21896 21897@example 21898AS_CASE([$host], 21899 [alpha*-*-*], [CYCLE_OBJ=rpcc.o], 21900 [i?86-*-*], [CYCLE_OBJ=rdtsc.o], 21901 [CYCLE_OBJ=""] 21902) 21903AC_SUBST([CYCLE_OBJ]) 21904@end example 21905 21906@code{AC_CONFIG_LINKS} (@pxref{Configuration Links}) is another good way 21907to select variant source files, for example optimized code for some 21908CPUs. The configured CPU type doesn't always indicate exact CPU types, 21909so some runtime capability checks may be necessary too. 21910 21911@example 21912case $host in 21913 alpha*-*-*) AC_CONFIG_LINKS([dither.c:alpha/dither.c]) ;; 21914 powerpc*-*-*) AC_CONFIG_LINKS([dither.c:powerpc/dither.c]) ;; 21915 *-*-*) AC_CONFIG_LINKS([dither.c:generic/dither.c]) ;; 21916esac 21917@end example 21918 21919The host system type can also be used to find cross-compilation tools 21920with @code{AC_CHECK_TOOL} (@pxref{Generic Programs}). 21921 21922The above examples all show @samp{$host}, since this is where the code 21923is going to run. Only rarely is it necessary to test @samp{$build} 21924(which is where the build is being done). 21925 21926Whenever you're tempted to use @samp{$host} it's worth considering 21927whether some sort of probe would be better. New system types come along 21928periodically or previously missing features are added. Well-written 21929probes can adapt themselves to such things, but hard-coded lists of 21930names can't. Here are some guidelines, 21931 21932@itemize @bullet 21933@item 21934Availability of libraries and library functions should always be checked 21935by probing. 21936@item 21937Variant behavior of system calls is best identified with runtime tests 21938if possible, but bug workarounds or obscure difficulties might have to 21939be driven from @samp{$host}. 21940@item 21941Assembler code is inevitably highly CPU-specific and is best selected 21942according to @samp{$host_cpu}. 21943@item 21944Assembler variations like underscore prefix on globals or ELF versus 21945COFF type directives are however best determined by probing, perhaps 21946even examining the compiler output. 21947@end itemize 21948 21949@samp{$target} is for use by a package creating a compiler or similar. 21950For ordinary packages it's meaningless and should not be used. It 21951indicates what the created compiler should generate code for, if it can 21952cross-compile. @samp{$target} generally selects various hard-coded CPU 21953and system conventions, since usually the compiler or tools under 21954construction themselves determine how the target works. 21955 21956 21957@c ===================================================== Site Configuration. 21958 21959@node Site Configuration 21960@chapter Site Configuration 21961 21962@command{configure} scripts support several kinds of local configuration 21963decisions. There are ways for users to specify where external software 21964packages are, include or exclude optional features, install programs 21965under modified names, and set default values for @command{configure} 21966options. 21967 21968@menu 21969* Help Formatting:: Customizing @samp{configure --help} 21970* External Software:: Working with other optional software 21971* Package Options:: Selecting optional features 21972* Pretty Help Strings:: Formatting help string 21973* Option Checking:: Controlling checking of @command{configure} options 21974* Site Details:: Configuring site details 21975* Transforming Names:: Changing program names when installing 21976* Site Defaults:: Giving @command{configure} local defaults 21977@end menu 21978 21979@node Help Formatting 21980@section Controlling Help Output 21981 21982Users consult @samp{configure --help} to learn of configuration 21983decisions specific to your package. By default, @command{configure} 21984breaks this output into sections for each type of option; within each 21985section, help strings appear in the order @file{configure.ac} defines 21986them: 21987 21988@example 21989Optional Features: 21990 @dots{} 21991 --enable-bar include bar 21992 21993Optional Packages: 21994 @dots{} 21995 --with-foo use foo 21996@end example 21997 21998@defmac AC_PRESERVE_HELP_ORDER 21999@acindex{PRESERVE_HELP_ORDER} 22000 22001Request an alternate @option{--help} format, in which options of all 22002types appear together, in the order defined. Call this macro before any 22003@code{AC_ARG_ENABLE} or @code{AC_ARG_WITH}. 22004 22005@example 22006Optional Features and Packages: 22007 @dots{} 22008 --enable-bar include bar 22009 --with-foo use foo 22010@end example 22011 22012@end defmac 22013 22014@node External Software 22015@section Working With External Software 22016@cindex External software 22017 22018Some packages require, or can optionally use, other software packages 22019that are already installed. The user can give @command{configure} 22020command line options to specify which such external software to use. 22021The options have one of these forms: 22022 22023@c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something 22024@c awful. 22025@example 22026--with-@var{package}@r{[}=@var{arg}@r{]} 22027--without-@var{package} 22028@end example 22029 22030For example, @option{--with-gnu-ld} means work with the GNU linker 22031instead of some other linker. @option{--with-x} means work with The X 22032Window System. 22033 22034The user can give an argument by following the package name with 22035@samp{=} and the argument. Giving an argument of @samp{no} is for 22036packages that are used by default; it says to @emph{not} use the 22037package. An argument that is neither @samp{yes} nor @samp{no} could 22038include a name or number of a version of the other package, to specify 22039more precisely which other package this program is supposed to work 22040with. If no argument is given, it defaults to @samp{yes}. 22041@option{--without-@var{package}} is equivalent to 22042@option{--with-@var{package}=no}. 22043 22044Normally @command{configure} scripts complain about 22045@option{--with-@var{package}} options that they do not support. 22046@xref{Option Checking}, for details, and for how to override the 22047defaults. 22048 22049For each external software package that may be used, @file{configure.ac} 22050should call @code{AC_ARG_WITH} to detect whether the @command{configure} 22051user asked to use it. Whether each package is used or not by default, 22052and which arguments are valid, is up to you. 22053 22054@anchor{AC_ARG_WITH} 22055@defmac AC_ARG_WITH (@var{package}, @var{help-string}, @ 22056 @ovar{action-if-given}, @ovar{action-if-not-given}) 22057@acindex{ARG_WITH} 22058If the user gave @command{configure} the option @option{--with-@var{package}} 22059or @option{--without-@var{package}}, run shell commands 22060@var{action-if-given}. If neither option was given, run shell commands 22061@var{action-if-not-given}. The name @var{package} indicates another 22062software package that this program should work with. It should consist 22063only of alphanumeric characters, dashes, plus signs, and dots. 22064 22065The option's argument is available to the shell commands 22066@var{action-if-given} in the shell variable @code{withval}, which is 22067actually just the value of the shell variable named 22068@code{with_@var{package}}, with any non-alphanumeric characters in 22069@var{package} changed into @samp{_}. You may use that variable instead, 22070if you wish. 22071 22072The argument @var{help-string} is a description of the option that 22073looks like this: 22074@example 22075 --with-readline support fancy command line editing 22076@end example 22077 22078@noindent 22079@var{help-string} may be more than one line long, if more detail is 22080needed. Just make sure the columns line up in @samp{configure 22081--help}. Avoid tabs in the help string. The easiest way to provide the 22082proper leading whitespace is to format your @var{help-string} with the macro 22083@code{AS_HELP_STRING} (@pxref{Pretty Help Strings}). 22084 22085The following example shows how to use the @code{AC_ARG_WITH} macro in 22086a common situation. You want to let the user decide whether to enable 22087support for an external library (e.g., the readline library); if the user 22088specified neither @option{--with-readline} nor @option{--without-readline}, 22089you want to enable support for readline only if the library is available 22090on the system. 22091 22092@c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved. 22093@example 22094AC_ARG_WITH([readline], 22095 [AS_HELP_STRING([--with-readline], 22096 [support fancy command line editing @@<:@@default=check@@:>@@])], 22097 [], 22098 [with_readline=check]) 22099 22100LIBREADLINE= 22101AS_IF([test "x$with_readline" != xno], 22102 [AC_CHECK_LIB([readline], [main], 22103 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"]) 22104 AC_DEFINE([HAVE_LIBREADLINE], [1], 22105 [Define if you have libreadline]) 22106 ], 22107 [if test "x$with_readline" != xcheck; then 22108 AC_MSG_FAILURE( 22109 [--with-readline was given, but test for readline failed]) 22110 fi 22111 ], -lncurses)]) 22112@end example 22113 22114The next example shows how to use @code{AC_ARG_WITH} to give the user the 22115possibility to enable support for the readline library, in case it is still 22116experimental and not well tested, and is therefore disabled by default. 22117 22118@c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved. 22119@example 22120AC_ARG_WITH([readline], 22121 [AS_HELP_STRING([--with-readline], 22122 [enable experimental support for readline])], 22123 [], 22124 [with_readline=no]) 22125 22126LIBREADLINE= 22127AS_IF([test "x$with_readline" != xno], 22128 [AC_CHECK_LIB([readline], [main], 22129 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"]) 22130 AC_DEFINE([HAVE_LIBREADLINE], [1], 22131 [Define if you have libreadline]) 22132 ], 22133 [AC_MSG_FAILURE( 22134 [--with-readline was given, but test for readline failed])], 22135 [-lncurses])]) 22136@end example 22137 22138The last example shows how to use @code{AC_ARG_WITH} to give the user the 22139possibility to disable support for the readline library, given that it is 22140an important feature and that it should be enabled by default. 22141 22142@c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved. 22143@example 22144AC_ARG_WITH([readline], 22145 [AS_HELP_STRING([--without-readline], 22146 [disable support for readline])], 22147 [], 22148 [with_readline=yes]) 22149 22150LIBREADLINE= 22151AS_IF([test "x$with_readline" != xno], 22152 [AC_CHECK_LIB([readline], [main], 22153 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"]) 22154 AC_DEFINE([HAVE_LIBREADLINE], [1], 22155 [Define if you have libreadline]) 22156 ], 22157 [AC_MSG_FAILURE( 22158 [readline test failed (--without-readline to disable)])], 22159 [-lncurses])]) 22160@end example 22161 22162These three examples can be easily adapted to the case where 22163@code{AC_ARG_ENABLE} should be preferred to @code{AC_ARG_WITH} (see 22164@ref{Package Options}). 22165@end defmac 22166 22167@node Package Options 22168@section Choosing Package Options 22169@cindex Package options 22170@cindex Options, package 22171 22172If a software package has optional compile-time features, the user can 22173give @command{configure} command line options to specify whether to 22174compile them. The options have one of these forms: 22175 22176@c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something 22177@c awful. 22178@example 22179--enable-@var{feature}@r{[}=@var{arg}@r{]} 22180--disable-@var{feature} 22181@end example 22182 22183These options allow users to choose which optional features to build and 22184install. @option{--enable-@var{feature}} options should never make a 22185feature behave differently or cause one feature to replace another. 22186They should only cause parts of the program to be built rather than left 22187out. 22188 22189The user can give an argument by following the feature name with 22190@samp{=} and the argument. Giving an argument of @samp{no} requests 22191that the feature @emph{not} be made available. A feature with an 22192argument looks like @option{--enable-debug=stabs}. If no argument is 22193given, it defaults to @samp{yes}. @option{--disable-@var{feature}} is 22194equivalent to @option{--enable-@var{feature}=no}. 22195 22196Normally @command{configure} scripts complain about 22197@option{--enable-@var{package}} options that they do not support. 22198@xref{Option Checking}, for details, and for how to override the 22199defaults. 22200 22201For each optional feature, @file{configure.ac} should call 22202@code{AC_ARG_ENABLE} to detect whether the @command{configure} user asked 22203to include it. Whether each feature is included or not by default, and 22204which arguments are valid, is up to you. 22205 22206@anchor{AC_ARG_ENABLE} 22207@defmac AC_ARG_ENABLE (@var{feature}, @var{help-string}, @ 22208 @ovar{action-if-given}, @ovar{action-if-not-given}) 22209@acindex{ARG_ENABLE} 22210If the user gave @command{configure} the option 22211@option{--enable-@var{feature}} or @option{--disable-@var{feature}}, run 22212shell commands @var{action-if-given}. If neither option was given, run 22213shell commands @var{action-if-not-given}. The name @var{feature} 22214indicates an optional user-level facility. It should consist only of 22215alphanumeric characters, dashes, plus signs, and dots. 22216 22217The option's argument is available to the shell commands 22218@var{action-if-given} in the shell variable @code{enableval}, which is 22219actually just the value of the shell variable named 22220@code{enable_@var{feature}}, with any non-alphanumeric characters in 22221@var{feature} changed into @samp{_}. You may use that variable instead, 22222if you wish. The @var{help-string} argument is like that of 22223@code{AC_ARG_WITH} (@pxref{External Software}). 22224 22225You should format your @var{help-string} with the macro 22226@code{AS_HELP_STRING} (@pxref{Pretty Help Strings}). 22227 22228See the examples suggested with the definition of @code{AC_ARG_WITH} 22229(@pxref{External Software}) to get an idea of possible applications of 22230@code{AC_ARG_ENABLE}. 22231@end defmac 22232 22233@node Pretty Help Strings 22234@section Making Your Help Strings Look Pretty 22235@cindex Help strings 22236 22237Properly formatting the @samp{help strings} which are used in 22238@code{AC_ARG_WITH} (@pxref{External Software}) and @code{AC_ARG_ENABLE} 22239(@pxref{Package Options}) can be challenging. Specifically, you want 22240your own @samp{help strings} to line up in the appropriate columns of 22241@samp{configure --help} just like the standard Autoconf @samp{help 22242strings} do. This is the purpose of the @code{AS_HELP_STRING} macro. 22243 22244@anchor{AS_HELP_STRING} 22245@defmac AS_HELP_STRING (@var{left-hand-side}, @var{right-hand-side} @ 22246 @dvar{indent-column, 26}, @dvar{wrap-column, 79}) 22247@asindex{HELP_STRING} 22248 22249Expands into a help string that looks pretty when the user executes 22250@samp{configure --help}. It is typically used in @code{AC_ARG_WITH} 22251(@pxref{External Software}) or @code{AC_ARG_ENABLE} (@pxref{Package 22252Options}). The following example makes this clearer. 22253 22254@example 22255AC_ARG_WITH([foo], 22256 [AS_HELP_STRING([--with-foo], 22257 [use foo (default is no)])], 22258 [use_foo=$withval], 22259 [use_foo=no]) 22260@end example 22261 22262Then the last few lines of @samp{configure --help} appear like 22263this: 22264 22265@example 22266--enable and --with options recognized: 22267 --with-foo use foo (default is no) 22268@end example 22269 22270Macro expansion is performed on the first argument. However, the second 22271argument of @code{AS_HELP_STRING} is treated as a whitespace separated 22272list of text to be reformatted, and is not subject to macro expansion. 22273Since it is not expanded, it should not be double quoted. 22274@xref{Autoconf Language}, for a more detailed explanation. 22275 22276The @code{AS_HELP_STRING} macro is particularly helpful when the 22277@var{left-hand-side} and/or @var{right-hand-side} are composed of macro 22278arguments, as shown in the following example. Be aware that 22279@var{left-hand-side} may not expand to unbalanced quotes, 22280although quadrigraphs can be used. 22281 22282@example 22283AC_DEFUN([MY_ARG_WITH], 22284 [AC_ARG_WITH(m4_translit([[$1]], [_], [-]), 22285 [AS_HELP_STRING([--with-m4_translit([$1], [_], [-])], 22286 [use $1 (default is $2)])], 22287 [use_[]$1=$withval], 22288 [use_[]$1=$2])]) 22289MY_ARG_WITH([a_b], [no]) 22290@end example 22291@noindent 22292Here, the last few lines of @samp{configure --help} will include: 22293 22294@example 22295--enable and --with options recognized: 22296 --with-a-b use a_b (default is no) 22297@end example 22298 22299The parameters @var{indent-column} and @var{wrap-column} were introduced 22300in Autoconf 2.62. Generally, they should not be specified; they exist 22301for fine-tuning of the wrapping. 22302@example 22303AS_HELP_STRING([--option], [description of option]) 22304@result{} --option description of option 22305AS_HELP_STRING([--option], [description of option], [15], [30]) 22306@result{} --option description of 22307@result{} option 22308@end example 22309@end defmac 22310 22311 22312@node Option Checking 22313@section Controlling Checking of @command{configure} Options 22314@cindex Options, Package 22315 22316The @command{configure} script checks its command-line options against a 22317list of known options, like @option{--help} or @option{--config-cache}. 22318An unknown option ordinarily indicates a mistake by the user and 22319@command{configure} halts with an error. However, by default unknown 22320@option{--with-@var{package}} and @option{--enable-@var{feature}} 22321options elicit only a warning, to support configuring entire source 22322trees. 22323 22324Source trees often contain multiple packages with a top-level 22325@command{configure} script that uses the @code{AC_CONFIG_SUBDIRS} macro 22326(@pxref{Subdirectories}). Because the packages generally support 22327different @option{--with-@var{package}} and 22328@option{--enable-@var{feature}} options, the GNU Coding 22329Standards say they must accept unrecognized options without halting. 22330Even a warning message is undesirable here, so @code{AC_CONFIG_SUBDIRS} 22331automatically disables the warnings. 22332 22333This default behavior may be modified in two ways. First, the installer 22334can invoke @code{configure --disable-option-checking} to disable 22335these warnings, or invoke @code{configure --enable-option-checking=fatal} 22336options to turn them into fatal errors, respectively. Second, the 22337maintainer can use @code{AC_DISABLE_OPTION_CHECKING}. 22338 22339@defmac AC_DISABLE_OPTION_CHECKING 22340@acindex{DISABLE_OPTION_CHECKING} 22341 22342By default, disable warnings related to any unrecognized 22343@option{--with-@var{package}} or @option{--enable-@var{feature}} 22344options. This is implied by @code{AC_CONFIG_SUBDIRS}. 22345 22346The installer can override this behavior by passing 22347@option{--enable-option-checking} (enable warnings) or 22348@option{--enable-option-checking=fatal} (enable errors) to 22349@command{configure}. 22350@end defmac 22351 22352 22353@node Site Details 22354@section Configuring Site Details 22355@cindex Site details 22356 22357Some software packages require complex site-specific information. Some 22358examples are host names to use for certain services, company names, and 22359email addresses to contact. Since some configuration scripts generated 22360by Metaconfig ask for such information interactively, people sometimes 22361wonder how to get that information in Autoconf-generated configuration 22362scripts, which aren't interactive. 22363 22364Such site configuration information should be put in a file that is 22365edited @emph{only by users}, not by programs. The location of the file 22366can either be based on the @code{prefix} variable, or be a standard 22367location such as the user's home directory. It could even be specified 22368by an environment variable. The programs should examine that file at 22369runtime, rather than at compile time. Runtime configuration is more 22370convenient for users and makes the configuration process simpler than 22371getting the information while configuring. @xref{Directory Variables, , 22372Variables for Installation Directories, standards, The GNU Coding 22373Standards}, for more information on where to put data files. 22374 22375@node Transforming Names 22376@section Transforming Program Names When Installing 22377@cindex Transforming program names 22378@cindex Program names, transforming 22379 22380Autoconf supports changing the names of programs when installing them. 22381In order to use these transformations, @file{configure.ac} must call the 22382macro @code{AC_ARG_PROGRAM}. 22383 22384@defmac AC_ARG_PROGRAM 22385@acindex{ARG_PROGRAM} 22386@ovindex program_transform_name 22387Place in output variable @code{program_transform_name} a sequence of 22388@code{sed} commands for changing the names of installed programs. 22389 22390If any of the options described below are given to @command{configure}, 22391program names are transformed accordingly. Otherwise, if 22392@code{AC_CANONICAL_TARGET} has been called and a @option{--target} value 22393is given, the target type followed by a dash is used as a prefix. 22394Otherwise, no program name transformation is done. 22395@end defmac 22396 22397@menu 22398* Transformation Options:: @command{configure} options to transform names 22399* Transformation Examples:: Sample uses of transforming names 22400* Transformation Rules:: Makefile uses of transforming names 22401@end menu 22402 22403@node Transformation Options 22404@subsection Transformation Options 22405 22406You can specify name transformations by giving @command{configure} these 22407command line options: 22408 22409@table @option 22410@item --program-prefix=@var{prefix} 22411prepend @var{prefix} to the names; 22412 22413@item --program-suffix=@var{suffix} 22414append @var{suffix} to the names; 22415 22416@item --program-transform-name=@var{expression} 22417perform @code{sed} substitution @var{expression} on the names. 22418@end table 22419 22420@node Transformation Examples 22421@subsection Transformation Examples 22422 22423These transformations are useful with programs that can be part of a 22424cross-compilation development environment. For example, a 22425cross-assembler running on a Sun 4 configured with 22426@option{--target=i960-vxworks} is normally installed as 22427@file{i960-vxworks-as}, rather than @file{as}, which could be confused 22428with a native Sun 4 assembler. 22429 22430You can force a program name to begin with @file{g}, if you don't want 22431GNU programs installed on your system to shadow other programs with 22432the same name. For example, if you configure GNU @code{diff} with 22433@option{--program-prefix=g}, then when you run @samp{make install} it is 22434installed as @file{/usr/local/bin/gdiff}. 22435 22436As a more sophisticated example, you could use 22437 22438@example 22439--program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/' 22440@end example 22441@noindent 22442 22443to prepend @samp{g} to most of the program names in a source tree, 22444excepting those like @code{gdb} that already have one and those like 22445@code{less} and @code{lesskey} that aren't GNU programs. (That is 22446assuming that you have a source tree containing those programs that is 22447set up to use this feature.) 22448 22449One way to install multiple versions of some programs simultaneously is 22450to append a version number to the name of one or both. For example, if 22451you want to keep Autoconf version 1 around for awhile, you can configure 22452Autoconf version 2 using @option{--program-suffix=2} to install the 22453programs as @file{/usr/local/bin/autoconf2}, 22454@file{/usr/local/bin/autoheader2}, etc. Nevertheless, pay attention 22455that only the binaries are renamed, therefore you'd have problems with 22456the library files which might overlap. 22457 22458@node Transformation Rules 22459@subsection Transformation Rules 22460 22461Here is how to use the variable @code{program_transform_name} in a 22462@file{Makefile.in}: 22463 22464@example 22465PROGRAMS = cp ls rm 22466transform = @@program_transform_name@@ 22467install: 22468 for p in $(PROGRAMS); do \ 22469 $(INSTALL_PROGRAM) $$p $(DESTDIR)$(bindir)/`echo $$p | \ 22470 sed '$(transform)'`; \ 22471 done 22472 22473uninstall: 22474 for p in $(PROGRAMS); do \ 22475 rm -f $(DESTDIR)$(bindir)/`echo $$p | sed '$(transform)'`; \ 22476@c $$ restore font-lock 22477 done 22478@end example 22479 22480It is guaranteed that @code{program_transform_name} is never empty, and 22481that there are no useless separators. Therefore you may safely embed 22482@code{program_transform_name} within a sed program using @samp{;}: 22483 22484@example 22485transform = @@program_transform_name@@ 22486transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/ 22487@end example 22488 22489Whether to do the transformations on documentation files (Texinfo or 22490@code{man}) is a tricky question; there seems to be no perfect answer, 22491due to the several reasons for name transforming. Documentation is not 22492usually particular to a specific architecture, and Texinfo files do not 22493conflict with system documentation. But they might conflict with 22494earlier versions of the same files, and @code{man} pages sometimes do 22495conflict with system documentation. As a compromise, it is probably 22496best to do name transformations on @code{man} pages but not on Texinfo 22497manuals. 22498 22499@node Site Defaults 22500@section Setting Site Defaults 22501@cindex Site defaults 22502@cindex config.site 22503 22504Autoconf-generated @command{configure} scripts allow your site to provide 22505default values for some configuration values. You do this by creating 22506site- and system-wide initialization files. 22507 22508@evindex CONFIG_SITE 22509If the environment variable @code{CONFIG_SITE} is set, @command{configure} 22510uses its value as the name of a shell script to read; it is recommended 22511that this be an absolute file name. Otherwise, it 22512reads the shell script @file{@var{prefix}/share/config.site} if it exists, 22513then @file{@var{prefix}/etc/config.site} if it exists. Thus, 22514settings in machine-specific files override those in machine-independent 22515ones in case of conflict. 22516 22517Site files can be arbitrary shell scripts, but only certain kinds of 22518code are really appropriate to be in them. Because @command{configure} 22519reads any cache file after it has read any site files, a site file can 22520define a default cache file to be shared between all Autoconf-generated 22521@command{configure} scripts run on that system (@pxref{Cache Files}). If 22522you set a default cache file in a site file, it is a good idea to also 22523set the output variable @code{CC} in that site file, because the cache 22524file is only valid for a particular compiler, but many systems have 22525several available. 22526 22527You can examine or override the value set by a command line option to 22528@command{configure} in a site file; options set shell variables that have 22529the same names as the options, with any dashes turned into underscores. 22530The exceptions are that @option{--without-} and @option{--disable-} options 22531are like giving the corresponding @option{--with-} or @option{--enable-} 22532option and the value @samp{no}. Thus, @option{--cache-file=localcache} 22533sets the variable @code{cache_file} to the value @samp{localcache}; 22534@option{--enable-warnings=no} or @option{--disable-warnings} sets the variable 22535@code{enable_warnings} to the value @samp{no}; @option{--prefix=/usr} sets the 22536variable @code{prefix} to the value @samp{/usr}; etc. 22537 22538Site files are also good places to set default values for other output 22539variables, such as @code{CFLAGS}, if you need to give them non-default 22540values: anything you would normally do, repetitively, on the command 22541line. If you use non-default values for @var{prefix} or 22542@var{exec_prefix} (wherever you locate the site file), you can set them 22543in the site file if you specify it with the @code{CONFIG_SITE} 22544environment variable. 22545 22546You can set some cache values in the site file itself. Doing this is 22547useful if you are cross-compiling, where it is impossible to check features 22548that require running a test program. You could ``prime the cache'' by 22549setting those values correctly for that system in 22550@file{@var{prefix}/etc/config.site}. To find out the names of the cache 22551variables you need to set, see the documentation of the respective 22552Autoconf macro. If the variables or their semantics are undocumented, 22553you may need to look for shell variables with @samp{_cv_} in their names 22554in the affected @command{configure} scripts, or in the Autoconf M4 22555source code for those macros; but in that case, their name or semantics 22556may change in a future Autoconf version. 22557 22558The cache file is careful to not override any variables set in the site 22559files. Similarly, you should not override command-line options in the 22560site files. Your code should check that variables such as @code{prefix} 22561and @code{cache_file} have their default values (as set near the top of 22562@command{configure}) before changing them. 22563 22564Here is a sample file @file{/usr/share/local/@/gnu/share/@/config.site}. The 22565command @samp{configure --prefix=/usr/share/local/gnu} would read this 22566file (if @code{CONFIG_SITE} is not set to a different file). 22567 22568@example 22569# /usr/share/local/gnu/share/config.site for configure 22570# 22571# Change some defaults. 22572test "$prefix" = NONE && prefix=/usr/share/local/gnu 22573test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu 22574test "$sharedstatedir" = '$@{prefix@}/com' && sharedstatedir=/var 22575test "$localstatedir" = '$@{prefix@}/var' && localstatedir=/var 22576 22577# Give Autoconf 2.x generated configure scripts a shared default 22578# cache file for feature test results, architecture-specific. 22579if test "$cache_file" = /dev/null; then 22580 cache_file="$prefix/var/config.cache" 22581 # A cache file is only valid for one C compiler. 22582 CC=gcc 22583fi 22584@end example 22585 22586@c Leave this use of ``File system'' rendered as one word, but 22587@c slightly obfuscated so as not to trigger the syntax-check prohibition. 22588@cindex File@/system Hierarchy Standard 22589@cindex FHS 22590 22591Another use of @file{config.site} is for priming the directory variables 22592@c ``File system'', but slightly obfuscated, as above. 22593in a manner consistent with the File@/system Hierarchy Standard 22594(FHS). Once the following file is installed at 22595@file{/usr/share/config.site}, a user can execute simply 22596@code{./configure --prefix=/usr} to get all the directories chosen in 22597the locations recommended by FHS. 22598 22599@example 22600# /usr/share/config.site for FHS defaults when installing below /usr, 22601# and the respective settings were not changed on the command line. 22602if test "$prefix" = /usr; then 22603 test "$sysconfdir" = '$@{prefix@}/etc' && sysconfdir=/etc 22604 test "$sharedstatedir" = '$@{prefix@}/com' && sharedstatedir=/var 22605 test "$localstatedir" = '$@{prefix@}/var' && localstatedir=/var 22606fi 22607@end example 22608 22609@cindex @file{lib64} 22610@cindex 64-bit libraries 22611Likewise, on platforms where 64-bit libraries are built by default, then 22612installed in @file{/usr/local/@/lib64} instead of @file{/usr/local/@/lib}, 22613it is appropriate to install @file{/usr/local/@/share/config.site}: 22614 22615@example 22616# /usr/local/share/config.site for platforms that prefer 22617# the directory /usr/local/lib64 over /usr/local/lib. 22618test "$libdir" = '$@{exec_prefix@}/lib' && libdir='$@{exec_prefix@}/lib64' 22619@end example 22620 22621 22622@c ============================================== Running configure Scripts. 22623 22624@node Running configure Scripts 22625@chapter Running @command{configure} Scripts 22626@cindex @command{configure} 22627 22628Below are instructions on how to configure a package that uses a 22629@command{configure} script, suitable for inclusion as an @file{INSTALL} 22630file in the package. A plain-text version of @file{INSTALL} which you 22631may use comes with Autoconf. 22632 22633@menu 22634* Basic Installation:: Instructions for typical cases 22635* Compilers and Options:: Selecting compilers and optimization 22636* Multiple Architectures:: Compiling for multiple architectures at once 22637* Installation Names:: Installing in different directories 22638* Optional Features:: Selecting optional features 22639* Particular Systems:: Particular systems 22640* System Type:: Specifying the system type 22641* Sharing Defaults:: Setting site-wide defaults for @command{configure} 22642* Defining Variables:: Specifying the compiler etc. 22643* configure Invocation:: Changing how @command{configure} runs 22644@end menu 22645 22646@set autoconf 22647@include install.texi 22648 22649 22650@c ============================================== config.status Invocation 22651 22652@node config.status Invocation 22653@chapter config.status Invocation 22654@cindex @command{config.status} 22655 22656The @command{configure} script creates a file named @file{config.status}, 22657which actually configures, @dfn{instantiates}, the template files. It 22658also records the configuration options that were specified when the 22659package was last configured in case reconfiguring is needed. 22660 22661Synopsis: 22662@example 22663./config.status @ovar{option}@dots{} @ovar{tag}@dots{} 22664@end example 22665 22666It configures each @var{tag}; if none are specified, all the templates 22667are instantiated. A @var{tag} refers to a file or other tag associated 22668with a configuration action, as specified by an @code{AC_CONFIG_@var{ITEMS}} 22669macro (@pxref{Configuration Actions}). The files must be specified 22670without their dependencies, as in 22671 22672@example 22673./config.status foobar 22674@end example 22675 22676@noindent 22677not 22678 22679@example 22680./config.status foobar:foo.in:bar.in 22681@end example 22682 22683The supported options are: 22684 22685@table @option 22686@item --help 22687@itemx -h 22688Print a summary of the command line options, the list of the template 22689files, and exit. 22690 22691@item --version 22692@itemx -V 22693Print the version number of Autoconf and the configuration settings, 22694and exit. 22695 22696@item --config 22697Print the configuration settings in reusable way, quoted for the shell, 22698and exit. For example, for a debugging build that otherwise reuses the 22699configuration from a different build directory @var{build-dir} of a 22700package in @var{src-dir}, you could use the following: 22701 22702@example 22703args=`@var{build-dir}/config.status --config` 22704eval @var{src-dir}/configure "$args" CFLAGS=-g --srcdir=@var{src-dir} 22705@end example 22706 22707@noindent 22708Note that it may be necessary to override a @option{--srcdir} setting 22709that was saved in the configuration, if the arguments are used in a 22710different build directory. 22711 22712@item --silent 22713@itemx --quiet 22714@itemx -q 22715Do not print progress messages. 22716 22717@item --debug 22718@itemx -d 22719Don't remove the temporary files. 22720 22721@item --file=@var{file}[:@var{template}] 22722Require that @var{file} be instantiated as if 22723@samp{AC_CONFIG_FILES(@var{file}:@var{template})} was used. Both 22724@var{file} and @var{template} may be @samp{-} in which case the standard 22725output and/or standard input, respectively, is used. If a 22726@var{template} file name is relative, it is first looked for in the build 22727tree, and then in the source tree. @xref{Configuration Actions}, for 22728more details. 22729 22730This option and the following ones provide one way for separately 22731distributed packages to share the values computed by @command{configure}. 22732Doing so can be useful if some of the packages need a superset of the 22733features that one of them, perhaps a common library, does. These 22734options allow a @file{config.status} file to create files other than the 22735ones that its @file{configure.ac} specifies, so it can be used for a 22736different package, or for extracting a subset of values. For example, 22737 22738@example 22739echo '@@CC@@' | ./config.status --file=- 22740@end example 22741 22742@noindent 22743provides the value of @code{@@CC@@} on standard output. 22744 22745@item --header=@var{file}[:@var{template}] 22746Same as @option{--file} above, but with @samp{AC_CONFIG_HEADERS}. 22747 22748@item --recheck 22749Ask @file{config.status} to update itself and exit (no instantiation). 22750This option is useful if you change @command{configure}, so that the 22751results of some tests might be different from the previous run. The 22752@option{--recheck} option reruns @command{configure} with the same arguments 22753you used before, plus the @option{--no-create} option, which prevents 22754@command{configure} from running @file{config.status} and creating 22755@file{Makefile} and other files, and the @option{--no-recursion} option, 22756which prevents @command{configure} from running other @command{configure} 22757scripts in subdirectories. (This is so other Make rules can 22758run @file{config.status} when it changes; @pxref{Automatic Remaking}, 22759for an example). 22760@end table 22761 22762@file{config.status} checks several optional environment variables that 22763can alter its behavior: 22764 22765@anchor{CONFIG_SHELL} 22766@defvar CONFIG_SHELL 22767@evindex CONFIG_SHELL 22768The shell with which to run @command{configure}. It must be 22769Bourne-compatible, and the absolute name of the shell should be passed. 22770The default is a shell that supports @code{LINENO} if available, and 22771@file{/bin/sh} otherwise. 22772@end defvar 22773 22774@defvar CONFIG_STATUS 22775@evindex CONFIG_STATUS 22776The file name to use for the shell script that records the 22777configuration. The default is @file{./config.status}. This variable is 22778useful when one package uses parts of another and the @command{configure} 22779scripts shouldn't be merged because they are maintained separately. 22780@end defvar 22781 22782You can use @file{./config.status} in your makefiles. For example, in 22783the dependencies given above (@pxref{Automatic Remaking}), 22784@file{config.status} is run twice when @file{configure.ac} has changed. 22785If that bothers you, you can make each run only regenerate the files for 22786that rule: 22787@example 22788@group 22789config.h: stamp-h 22790stamp-h: config.h.in config.status 22791 ./config.status config.h 22792 echo > stamp-h 22793 22794Makefile: Makefile.in config.status 22795 ./config.status Makefile 22796@end group 22797@end example 22798 22799The calling convention of @file{config.status} has changed; see 22800@ref{Obsolete config.status Use}, for details. 22801 22802 22803@c =================================================== Obsolete Constructs 22804 22805@node Obsolete Constructs 22806@chapter Obsolete Constructs 22807@cindex Obsolete constructs 22808 22809Autoconf changes, and throughout the years some constructs have been 22810obsoleted. Most of the changes involve the macros, but in some cases 22811the tools themselves, or even some concepts, are now considered 22812obsolete. 22813 22814You may completely skip this chapter if you are new to Autoconf. Its 22815intention is mainly to help maintainers updating their packages by 22816understanding how to move to more modern constructs. 22817 22818@menu 22819* Obsolete config.status Use:: Obsolete convention for @command{config.status} 22820* acconfig Header:: Additional entries in @file{config.h.in} 22821* autoupdate Invocation:: Automatic update of @file{configure.ac} 22822* Obsolete Macros:: Backward compatibility macros 22823* Autoconf 1:: Tips for upgrading your files 22824* Autoconf 2.13:: Some fresher tips 22825@end menu 22826 22827@node Obsolete config.status Use 22828@section Obsolete @file{config.status} Invocation 22829 22830@file{config.status} now supports arguments to specify the files to 22831instantiate; see @ref{config.status Invocation}, for more details. 22832Before, environment variables had to be used. 22833 22834@defvar CONFIG_COMMANDS 22835@evindex CONFIG_COMMANDS 22836The tags of the commands to execute. The default is the arguments given 22837to @code{AC_OUTPUT} and @code{AC_CONFIG_COMMANDS} in 22838@file{configure.ac}. 22839@end defvar 22840 22841@defvar CONFIG_FILES 22842@evindex CONFIG_FILES 22843The files in which to perform @samp{@@@var{variable}@@} substitutions. 22844The default is the arguments given to @code{AC_OUTPUT} and 22845@code{AC_CONFIG_FILES} in @file{configure.ac}. 22846@end defvar 22847 22848@defvar CONFIG_HEADERS 22849@evindex CONFIG_HEADERS 22850The files in which to substitute C @code{#define} statements. The 22851default is the arguments given to @code{AC_CONFIG_HEADERS}; if that 22852macro was not called, @file{config.status} ignores this variable. 22853@end defvar 22854 22855@defvar CONFIG_LINKS 22856@evindex CONFIG_LINKS 22857The symbolic links to establish. The default is the arguments given to 22858@code{AC_CONFIG_LINKS}; if that macro was not called, 22859@file{config.status} ignores this variable. 22860@end defvar 22861 22862In @ref{config.status Invocation}, using this old interface, the example 22863would be: 22864 22865@example 22866@group 22867config.h: stamp-h 22868stamp-h: config.h.in config.status 22869 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \ 22870 CONFIG_HEADERS=config.h ./config.status 22871 echo > stamp-h 22872 22873Makefile: Makefile.in config.status 22874 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \ 22875 CONFIG_FILES=Makefile ./config.status 22876@end group 22877@end example 22878 22879@noindent 22880(If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is 22881no need to set @code{CONFIG_HEADERS} in the @command{make} rules. Equally 22882for @code{CONFIG_COMMANDS}, etc.) 22883 22884 22885@node acconfig Header 22886@section @file{acconfig.h} 22887 22888@cindex @file{acconfig.h} 22889@cindex @file{config.h.top} 22890@cindex @file{config.h.bot} 22891 22892In order to produce @file{config.h.in}, @command{autoheader} needs to 22893build or to find templates for each symbol. Modern releases of Autoconf 22894use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader 22895Macros}), but in older releases a file, @file{acconfig.h}, contained the 22896list of needed templates. @command{autoheader} copied comments and 22897@code{#define} and @code{#undef} statements from @file{acconfig.h} in 22898the current directory, if present. This file used to be mandatory if 22899you @code{AC_DEFINE} any additional symbols. 22900 22901Modern releases of Autoconf also provide @code{AH_TOP} and 22902@code{AH_BOTTOM} if you need to prepend/append some information to 22903@file{config.h.in}. Ancient versions of Autoconf had a similar feature: 22904if @file{./acconfig.h} contains the string @samp{@@TOP@@}, 22905@command{autoheader} copies the lines before the line containing 22906@samp{@@TOP@@} into the top of the file that it generates. Similarly, 22907if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@}, 22908@command{autoheader} copies the lines after that line to the end of the 22909file it generates. Either or both of those strings may be omitted. An 22910even older alternate way to produce the same effect in ancient versions 22911of Autoconf is to create the files @file{@var{file}.top} (typically 22912@file{config.h.top}) and/or @file{@var{file}.bot} in the current 22913directory. If they exist, @command{autoheader} copies them to the 22914beginning and end, respectively, of its output. 22915 22916In former versions of Autoconf, the files used in preparing a software 22917package for distribution were: 22918@example 22919@group 22920configure.ac --. .------> autoconf* -----> configure 22921 +---+ 22922[aclocal.m4] --+ `---. 22923[acsite.m4] ---' | 22924 +--> [autoheader*] -> [config.h.in] 22925[acconfig.h] ----. | 22926 +-----' 22927[config.h.top] --+ 22928[config.h.bot] --' 22929@end group 22930@end example 22931 22932Using only the @code{AH_} macros, @file{configure.ac} should be 22933self-contained, and should not depend upon @file{acconfig.h} etc. 22934 22935 22936@node autoupdate Invocation 22937@section Using @command{autoupdate} to Modernize @file{configure.ac} 22938@cindex @command{autoupdate} 22939 22940The @command{autoupdate} program updates a @file{configure.ac} file that 22941calls Autoconf macros by their old names to use the current macro names. 22942In version 2 of Autoconf, most of the macros were renamed to use a more 22943uniform and descriptive naming scheme. @xref{Macro Names}, for a 22944description of the new scheme. Although the old names still work 22945(@pxref{Obsolete Macros}, for a list of the old macros and the corresponding 22946new names), you can make your @file{configure.ac} files more readable 22947and make it easier to use the current Autoconf documentation if you 22948update them to use the new macro names. 22949 22950@evindex SIMPLE_BACKUP_SUFFIX 22951If given no arguments, @command{autoupdate} updates @file{configure.ac}, 22952backing up the original version with the suffix @file{~} (or the value 22953of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is 22954set). If you give @command{autoupdate} an argument, it reads that file 22955instead of @file{configure.ac} and writes the updated file to the 22956standard output. 22957 22958@noindent 22959@command{autoupdate} accepts the following options: 22960 22961@table @option 22962@item --help 22963@itemx -h 22964Print a summary of the command line options and exit. 22965 22966@item --version 22967@itemx -V 22968Print the version number of Autoconf and exit. 22969 22970@item --verbose 22971@itemx -v 22972Report processing steps. 22973 22974@item --debug 22975@itemx -d 22976Don't remove the temporary files. 22977 22978@item --force 22979@itemx -f 22980Force the update even if the file has not changed. Disregard the cache. 22981 22982@item --include=@var{dir} 22983@itemx -I @var{dir} 22984Also look for input files in @var{dir}. Multiple invocations accumulate. 22985Directories are browsed from last to first. 22986 22987@item --prepend-include=@var{dir} 22988@itemx -B @var{dir} 22989Prepend directory @var{dir} to the search path. This is used to include 22990the language-specific files before any third-party macros. 22991@end table 22992 22993@node Obsolete Macros 22994@section Obsolete Macros 22995 22996Several macros are obsoleted in Autoconf, for various reasons (typically 22997they failed to quote properly, couldn't be extended for more recent 22998issues, etc.). They are still supported, but deprecated: their use 22999should be avoided. 23000 23001During the jump from Autoconf version 1 to version 2, most of the 23002macros were renamed to use a more uniform and descriptive naming scheme, 23003but their signature did not change. @xref{Macro Names}, for a 23004description of the new naming scheme. Below, if there is just the mapping 23005from old names to new names for these macros, the reader is invited to 23006refer to the definition of the new macro for the signature and the 23007description. 23008 23009@defmac AC_AIX 23010@acindex{AIX} 23011@cvindex _ALL_SOURCE 23012This macro is a platform-specific subset of 23013@code{AC_USE_SYSTEM_EXTENSIONS} (@pxref{AC_USE_SYSTEM_EXTENSIONS}). 23014@end defmac 23015 23016@defmac AC_ALLOCA 23017@acindex{ALLOCA} 23018Replaced by @code{AC_FUNC_ALLOCA} (@pxref{AC_FUNC_ALLOCA}). 23019@end defmac 23020 23021@defmac AC_ARG_ARRAY 23022@acindex{ARG_ARRAY} 23023Removed because of limited usefulness. 23024@end defmac 23025 23026@defmac AC_C_CROSS 23027@acindex{C_CROSS} 23028This macro is obsolete; it does nothing. 23029@end defmac 23030 23031@defmac AC_C_LONG_DOUBLE 23032@acindex{C_LONG_DOUBLE} 23033@cvindex HAVE_LONG_DOUBLE 23034If the C compiler supports a working @code{long double} type with more 23035range or precision than the @code{double} type, define 23036@code{HAVE_LONG_DOUBLE}. 23037 23038You should use @code{AC_TYPE_LONG_DOUBLE} or 23039@code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}. 23040@end defmac 23041 23042@defmac AC_CANONICAL_SYSTEM 23043@acindex{CANONICAL_SYSTEM} 23044Determine the system type and set output variables to the names of the 23045canonical system types. @xref{Canonicalizing}, for details about the 23046variables this macro sets. 23047 23048The user is encouraged to use either @code{AC_CANONICAL_BUILD}, or 23049@code{AC_CANONICAL_HOST}, or @code{AC_CANONICAL_TARGET}, depending on 23050the needs. Using @code{AC_CANONICAL_TARGET} is enough to run the two 23051other macros (@pxref{Canonicalizing}). 23052@end defmac 23053 23054@defmac AC_CHAR_UNSIGNED 23055@acindex{CHAR_UNSIGNED} 23056Replaced by @code{AC_C_CHAR_UNSIGNED} (@pxref{AC_C_CHAR_UNSIGNED}). 23057@end defmac 23058 23059@defmac AC_CHECK_TYPE (@var{type}, @var{default}) 23060@acindex{CHECK_TYPE} 23061Autoconf, up to 2.13, used to provide this version of 23062@code{AC_CHECK_TYPE}, deprecated because of its flaws. First, although 23063it is a member of the @code{CHECK} clan, it does 23064more than just checking. Secondly, missing types are defined 23065using @code{#define}, not @code{typedef}, and this can lead to 23066problems in the case of pointer types. 23067 23068This use of @code{AC_CHECK_TYPE} is obsolete and discouraged; see 23069@ref{Generic Types}, for the description of the current macro. 23070 23071If the type @var{type} is not defined, define it to be the C (or C++) 23072builtin type @var{default}, e.g., @samp{short int} or @samp{unsigned int}. 23073 23074This macro is equivalent to: 23075 23076@example 23077AC_CHECK_TYPE([@var{type}], [], 23078 [AC_DEFINE_UNQUOTED([@var{type}], [@var{default}], 23079 [Define to `@var{default}' 23080 if <sys/types.h> does not define.])]) 23081@end example 23082 23083In order to keep backward compatibility, the two versions of 23084@code{AC_CHECK_TYPE} are implemented, selected using these heuristics: 23085 23086@enumerate 23087@item 23088If there are three or four arguments, the modern version is used. 23089 23090@item 23091If the second argument appears to be a C or C++ type, then the 23092obsolete version is used. This happens if the argument is a C or C++ 23093@emph{builtin} type or a C identifier ending in @samp{_t}, optionally 23094followed by one of @samp{[(* } and then by a string of zero or more 23095characters taken from the set @samp{[]()* _a-zA-Z0-9}. 23096 23097@item 23098If the second argument is spelled with the alphabet of valid C and C++ 23099types, the user is warned and the modern version is used. 23100 23101@item 23102Otherwise, the modern version is used. 23103@end enumerate 23104 23105@noindent 23106You are encouraged either to use a valid builtin type, or to use the 23107equivalent modern code (see above), or better yet, to use 23108@code{AC_CHECK_TYPES} together with 23109 23110@example 23111#ifndef HAVE_LOFF_T 23112typedef loff_t off_t; 23113#endif 23114@end example 23115@end defmac 23116@c end of AC_CHECK_TYPE 23117 23118@defmac AC_CHECKING (@var{feature-description}) 23119@acindex{CHECKING} 23120Same as 23121 23122@example 23123AC_MSG_NOTICE([checking @var{feature-description}@dots{}] 23124@end example 23125 23126@noindent 23127@xref{AC_MSG_NOTICE}. 23128@end defmac 23129 23130@defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @ 23131 @var{function-body}, @var{action-if-true}, @ovar{action-if-false}) 23132@acindex{COMPILE_CHECK} 23133This is an obsolete version of @code{AC_TRY_COMPILE} itself replaced by 23134@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}), with the 23135addition that it prints @samp{checking for @var{echo-text}} to the 23136standard output first, if @var{echo-text} is non-empty. Use 23137@code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT} instead to print 23138messages (@pxref{Printing Messages}). 23139@end defmac 23140 23141@defmac AC_CONST 23142@acindex{CONST} 23143Replaced by @code{AC_C_CONST} (@pxref{AC_C_CONST}). 23144@end defmac 23145 23146@defmac AC_CROSS_CHECK 23147@acindex{CROSS_CHECK} 23148Same as @code{AC_C_CROSS}, which is obsolete too, and does nothing 23149@code{:-)}. 23150@end defmac 23151 23152@defmac AC_CYGWIN 23153@acindex{CYGWIN} 23154@evindex CYGWIN 23155Check for the Cygwin environment in which case the shell variable 23156@code{CYGWIN} is set to @samp{yes}. Don't use this macro, the dignified 23157means to check the nature of the host is using @code{AC_CANONICAL_HOST} 23158(@pxref{Canonicalizing}). As a matter of fact this macro is defined as: 23159 23160@example 23161AC_REQUIRE([AC_CANONICAL_HOST])[]dnl 23162case $host_os in 23163 *cygwin* ) CYGWIN=yes;; 23164 * ) CYGWIN=no;; 23165esac 23166@end example 23167 23168Beware that the variable @env{CYGWIN} has a special meaning when 23169running Cygwin, and should not be changed. That's yet another reason 23170not to use this macro. 23171@end defmac 23172 23173@defmac AC_DECL_SYS_SIGLIST 23174@acindex{DECL_SYS_SIGLIST} 23175@cvindex SYS_SIGLIST_DECLARED 23176Same as: 23177 23178@example 23179AC_CHECK_DECLS([sys_siglist], [], [], 23180[#include <signal.h> 23181/* NetBSD declares sys_siglist in unistd.h. */ 23182#ifdef HAVE_UNISTD_H 23183# include <unistd.h> 23184#endif 23185]) 23186@end example 23187 23188@noindent 23189@xref{AC_CHECK_DECLS}. 23190@end defmac 23191 23192@defmac AC_DECL_YYTEXT 23193@acindex{DECL_YYTEXT} 23194Does nothing, now integrated in @code{AC_PROG_LEX} (@pxref{AC_PROG_LEX}). 23195@end defmac 23196 23197@defmac AC_DIR_HEADER 23198@acindex{DIR_HEADER} 23199@cvindex DIRENT 23200@cvindex SYSNDIR 23201@cvindex SYSDIR 23202@cvindex NDIR 23203Like calling @code{AC_FUNC_CLOSEDIR_VOID} 23204(@pxref{AC_FUNC_CLOSEDIR_VOID}) and @code{AC_HEADER_DIRENT} 23205(@pxref{AC_HEADER_DIRENT}), 23206but defines a different set of C preprocessor macros to indicate which 23207header file is found: 23208 23209@multitable {@file{sys/ndir.h}} {Old Symbol} {@code{HAVE_SYS_NDIR_H}} 23210@item Header @tab Old Symbol @tab New Symbol 23211@item @file{dirent.h} @tab @code{DIRENT} @tab @code{HAVE_DIRENT_H} 23212@item @file{sys/ndir.h} @tab @code{SYSNDIR} @tab @code{HAVE_SYS_NDIR_H} 23213@item @file{sys/dir.h} @tab @code{SYSDIR} @tab @code{HAVE_SYS_DIR_H} 23214@item @file{ndir.h} @tab @code{NDIR} @tab @code{HAVE_NDIR_H} 23215@end multitable 23216@end defmac 23217 23218@defmac AC_DYNIX_SEQ 23219@acindex{DYNIX_SEQ} 23220If on DYNIX/ptx, add @option{-lseq} to output variable 23221@code{LIBS}. This macro used to be defined as 23222 23223@example 23224AC_CHECK_LIB([seq], [getmntent], [LIBS="-lseq $LIBS"]) 23225@end example 23226 23227@noindent 23228now it is just @code{AC_FUNC_GETMNTENT} (@pxref{AC_FUNC_GETMNTENT}). 23229@end defmac 23230 23231@defmac AC_EXEEXT 23232@acindex{EXEEXT} 23233@ovindex EXEEXT 23234Defined the output variable @code{EXEEXT} based on the output of the 23235compiler, which is now done automatically. Typically set to empty 23236string if Posix and @samp{.exe} if a DOS variant. 23237@end defmac 23238 23239@defmac AC_EMXOS2 23240@acindex{EMXOS2} 23241Similar to @code{AC_CYGWIN} but checks for the EMX environment on OS/2 23242and sets @code{EMXOS2}. Don't use this macro, the dignified means to 23243check the nature of the host is using @code{AC_CANONICAL_HOST} 23244(@pxref{Canonicalizing}). 23245@end defmac 23246 23247@defmac AC_ENABLE (@var{feature}, @var{action-if-given}, @ 23248 @ovar{action-if-not-given}) 23249@acindex{ENABLE} 23250This is an obsolete version of @code{AC_ARG_ENABLE} that does not 23251support providing a help string (@pxref{AC_ARG_ENABLE}). 23252@end defmac 23253 23254@defmac AC_ERROR 23255@acindex{ERROR} 23256Replaced by @code{AC_MSG_ERROR} (@pxref{AC_MSG_ERROR}). 23257@end defmac 23258 23259@defmac AC_FIND_X 23260@acindex{FIND_X} 23261Replaced by @code{AC_PATH_X} (@pxref{AC_PATH_X}). 23262@end defmac 23263 23264@defmac AC_FIND_XTRA 23265@acindex{FIND_XTRA} 23266Replaced by @code{AC_PATH_XTRA} (@pxref{AC_PATH_XTRA}). 23267@end defmac 23268 23269@defmac AC_FOREACH 23270@acindex{FOREACH} 23271Replaced by @code{m4_foreach_w} (@pxref{m4_foreach_w}). 23272@end defmac 23273 23274@defmac AC_FUNC_CHECK 23275@acindex{FUNC_CHECK} 23276Replaced by @code{AC_CHECK_FUNC} (@pxref{AC_CHECK_FUNC}). 23277@end defmac 23278 23279@anchor{AC_FUNC_SETVBUF_REVERSED} 23280@defmac AC_FUNC_SETVBUF_REVERSED 23281@acindex{FUNC_SETVBUF_REVERSED} 23282@cvindex SETVBUF_REVERSED 23283@c @fuindex setvbuf 23284@prindex @code{setvbuf} 23285Do nothing. Formerly, this macro checked whether @code{setvbuf} takes 23286the buffering type as its second argument and the buffer pointer as the 23287third, instead of the other way around, and defined 23288@code{SETVBUF_REVERSED}. However, the last systems to have the problem 23289were those based on SVR2, which became obsolete in 1987, and the macro 23290is no longer needed. 23291@end defmac 23292 23293@defmac AC_FUNC_WAIT3 23294@acindex{FUNC_WAIT3} 23295@cvindex HAVE_WAIT3 23296@c @fuindex wait3 23297@prindex @code{wait3} 23298If @code{wait3} is found and fills in the contents of its third argument 23299(a @samp{struct rusage *}), which HP-UX does not do, define 23300@code{HAVE_WAIT3}. 23301 23302These days portable programs should use @code{waitpid}, not 23303@code{wait3}, as @code{wait3} has been removed from Posix. 23304@end defmac 23305 23306@defmac AC_GCC_TRADITIONAL 23307@acindex{GCC_TRADITIONAL} 23308Replaced by @code{AC_PROG_GCC_TRADITIONAL} (@pxref{AC_PROG_GCC_TRADITIONAL}). 23309@end defmac 23310 23311@defmac AC_GETGROUPS_T 23312@acindex{GETGROUPS_T} 23313Replaced by @code{AC_TYPE_GETGROUPS} (@pxref{AC_TYPE_GETGROUPS}). 23314@end defmac 23315 23316@defmac AC_GETLOADAVG 23317@acindex{GETLOADAVG} 23318Replaced by @code{AC_FUNC_GETLOADAVG} (@pxref{AC_FUNC_GETLOADAVG}). 23319@end defmac 23320 23321@defmac AC_GNU_SOURCE 23322@acindex{GNU_SOURCE} 23323@cvindex _GNU_SOURCE 23324This macro is a platform-specific subset of 23325@code{AC_USE_SYSTEM_EXTENSIONS} (@pxref{AC_USE_SYSTEM_EXTENSIONS}). 23326@end defmac 23327 23328@defmac AC_HAVE_FUNCS 23329@acindex{HAVE_FUNCS} 23330Replaced by @code{AC_CHECK_FUNCS} (@pxref{AC_CHECK_FUNCS}). 23331@end defmac 23332 23333@defmac AC_HAVE_HEADERS 23334@acindex{HAVE_HEADERS} 23335Replaced by @code{AC_CHECK_HEADERS} (@pxref{AC_CHECK_HEADERS}). 23336@end defmac 23337 23338@defmac AC_HAVE_LIBRARY (@var{library}, @ovar{action-if-found}, @ 23339 @ovar{action-if-not-found}, @ovar{other-libraries}) 23340@acindex{HAVE_LIBRARY} 23341This macro is equivalent to calling @code{AC_CHECK_LIB} with a 23342@var{function} argument of @code{main}. In addition, @var{library} can 23343be written as any of @samp{foo}, @option{-lfoo}, or @samp{libfoo.a}. In 23344all of those cases, the compiler is passed @option{-lfoo}. However, 23345@var{library} cannot be a shell variable; it must be a literal name. 23346@xref{AC_CHECK_LIB}. 23347@end defmac 23348 23349@defmac AC_HAVE_POUNDBANG 23350@acindex{HAVE_POUNDBANG} 23351Replaced by @code{AC_SYS_INTERPRETER} (@pxref{AC_SYS_INTERPRETER}). 23352@end defmac 23353 23354@defmac AC_HEADER_CHECK 23355@acindex{HEADER_CHECK} 23356Replaced by @code{AC_CHECK_HEADER} (@pxref{AC_CHECK_HEADER}). 23357@end defmac 23358 23359@defmac AC_HEADER_EGREP 23360@acindex{HEADER_EGREP} 23361Replaced by @code{AC_EGREP_HEADER} (@pxref{AC_EGREP_HEADER}). 23362@end defmac 23363 23364@defmac AC_HELP_STRING 23365@acindex{HELP_STRING} 23366Replaced by @code{AS_HELP_STRING} (@pxref{AS_HELP_STRING}). 23367@end defmac 23368 23369@defmac AC_INIT (@var{unique-file-in-source-dir}) 23370@acindex{INIT} 23371Formerly @code{AC_INIT} used to have a single argument, and was 23372equivalent to: 23373 23374@example 23375AC_INIT 23376AC_CONFIG_SRCDIR(@var{unique-file-in-source-dir}) 23377@end example 23378See @ref{AC_INIT} and @ref{AC_CONFIG_SRCDIR}. 23379@end defmac 23380 23381@defmac AC_INLINE 23382@acindex{INLINE} 23383Replaced by @code{AC_C_INLINE} (@pxref{AC_C_INLINE}). 23384@end defmac 23385 23386@defmac AC_INT_16_BITS 23387@acindex{INT_16_BITS} 23388@cvindex INT_16_BITS 23389If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}. 23390Use @samp{AC_CHECK_SIZEOF(int)} instead (@pxref{AC_CHECK_SIZEOF}). 23391@end defmac 23392 23393@defmac AC_IRIX_SUN 23394@acindex{IRIX_SUN} 23395If on IRIX (Silicon Graphics Unix), add @option{-lsun} to output 23396@code{LIBS}. If you were using it to get @code{getmntent}, use 23397@code{AC_FUNC_GETMNTENT} instead. If you used it for the NIS versions 23398of the password and group functions, use @samp{AC_CHECK_LIB(sun, 23399getpwnam)}. Up to Autoconf 2.13, it used to be 23400 23401@example 23402AC_CHECK_LIB([sun], [getmntent], [LIBS="-lsun $LIBS"]) 23403@end example 23404 23405@noindent 23406now it is defined as 23407 23408@example 23409AC_FUNC_GETMNTENT 23410AC_CHECK_LIB([sun], [getpwnam]) 23411@end example 23412 23413@noindent 23414See @ref{AC_FUNC_GETMNTENT} and @ref{AC_CHECK_LIB}. 23415@end defmac 23416 23417@defmac AC_ISC_POSIX 23418@acindex{ISC_POSIX} 23419@ovindex LIBS 23420This macro adds @option{-lcposix} to output variable @code{LIBS} if 23421necessary for Posix facilities. Sun dropped support for the obsolete 23422INTERACTIVE Systems Corporation Unix on 2006-07-23. New programs 23423need not use this macro. It is implemented as 23424@code{AC_SEARCH_LIBS([strerror], [cposix])} (@pxref{AC_SEARCH_LIBS}). 23425@end defmac 23426 23427@defmac AC_LANG_C 23428@acindex{LANG_C} 23429Same as @samp{AC_LANG([C])} (@pxref{AC_LANG}). 23430@end defmac 23431 23432@defmac AC_LANG_CPLUSPLUS 23433@acindex{LANG_CPLUSPLUS} 23434Same as @samp{AC_LANG([C++])} (@pxref{AC_LANG}). 23435@end defmac 23436 23437@defmac AC_LANG_FORTRAN77 23438@acindex{LANG_FORTRAN77} 23439Same as @samp{AC_LANG([Fortran 77])} (@pxref{AC_LANG}). 23440@end defmac 23441 23442@defmac AC_LANG_RESTORE 23443@acindex{LANG_RESTORE} 23444Select the @var{language} that is saved on the top of the stack, as set 23445by @code{AC_LANG_SAVE}, remove it from the stack, and call 23446@code{AC_LANG(@var{language})}. @xref{Language Choice}, for the 23447preferred way to change languages. 23448@end defmac 23449 23450@defmac AC_LANG_SAVE 23451@acindex{LANG_SAVE} 23452Remember the current language (as set by @code{AC_LANG}) on a stack. 23453The current language does not change. @code{AC_LANG_PUSH} is preferred 23454(@pxref{AC_LANG_PUSH}). 23455@end defmac 23456 23457@defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{}) 23458@acindex{LINK_FILES} 23459This is an obsolete version of @code{AC_CONFIG_LINKS} 23460(@pxref{AC_CONFIG_LINKS}. An updated version of: 23461 23462@example 23463AC_LINK_FILES(config/$machine.h config/$obj_format.h, 23464 host.h object.h) 23465@end example 23466 23467@noindent 23468is: 23469 23470@example 23471AC_CONFIG_LINKS([host.h:config/$machine.h 23472 object.h:config/$obj_format.h]) 23473@end example 23474@end defmac 23475 23476@defmac AC_LN_S 23477@acindex{LN_S} 23478Replaced by @code{AC_PROG_LN_S} (@pxref{AC_PROG_LN_S}). 23479@end defmac 23480 23481@defmac AC_LONG_64_BITS 23482@acindex{LONG_64_BITS} 23483@cvindex LONG_64_BITS 23484Define @code{LONG_64_BITS} if the C type @code{long int} is 64 bits wide. 23485Use the generic macro @samp{AC_CHECK_SIZEOF([long int])} instead 23486(@pxref{AC_CHECK_SIZEOF}). 23487@end defmac 23488 23489@defmac AC_LONG_DOUBLE 23490@acindex{LONG_DOUBLE} 23491If the C compiler supports a working @code{long double} type with more 23492range or precision than the @code{double} type, define 23493@code{HAVE_LONG_DOUBLE}. 23494 23495You should use @code{AC_TYPE_LONG_DOUBLE} or 23496@code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}. 23497@end defmac 23498 23499@defmac AC_LONG_FILE_NAMES 23500@acindex{LONG_FILE_NAMES} 23501Replaced by 23502@example 23503AC_SYS_LONG_FILE_NAMES 23504@end example 23505@noindent 23506@xref{AC_SYS_LONG_FILE_NAMES}. 23507@end defmac 23508 23509@defmac AC_MAJOR_HEADER 23510@acindex{MAJOR_HEADER} 23511Replaced by @code{AC_HEADER_MAJOR} (@pxref{AC_HEADER_MAJOR}). 23512@end defmac 23513 23514@defmac AC_MEMORY_H 23515@acindex{MEMORY_H} 23516@cvindex NEED_MEMORY_H 23517Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were 23518defined in @file{memory.h}. Today it is equivalent to 23519@samp{AC_CHECK_HEADERS([memory.h])} (@pxref{AC_CHECK_HEADERS}). Adjust 23520your code to depend upon 23521@code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}; see @ref{Standard 23522Symbols}. 23523@end defmac 23524 23525@defmac AC_MINGW32 23526@acindex{MINGW32} 23527Similar to @code{AC_CYGWIN} but checks for the MinGW compiler 23528environment and sets @code{MINGW32}. Don't use this macro, the 23529dignified means to check the nature of the host is using 23530@code{AC_CANONICAL_HOST} (@pxref{Canonicalizing}). 23531@end defmac 23532 23533@defmac AC_MINIX 23534@acindex{MINIX} 23535@cvindex _MINIX 23536@cvindex _POSIX_SOURCE 23537@cvindex _POSIX_1_SOURCE 23538This macro is a platform-specific subset of 23539@code{AC_USE_SYSTEM_EXTENSIONS} (@pxref{AC_USE_SYSTEM_EXTENSIONS}). 23540@end defmac 23541 23542@defmac AC_MINUS_C_MINUS_O 23543@acindex{MINUS_C_MINUS_O} 23544Replaced by @code{AC_PROG_CC_C_O} (@pxref{AC_PROG_CC_C_O}). 23545@end defmac 23546 23547@defmac AC_MMAP 23548@acindex{MMAP} 23549Replaced by @code{AC_FUNC_MMAP} (@pxref{AC_FUNC_MMAP}). 23550@end defmac 23551 23552@defmac AC_MODE_T 23553@acindex{MODE_T} 23554Replaced by @code{AC_TYPE_MODE_T} (@pxref{AC_TYPE_MODE_T}). 23555@end defmac 23556 23557@defmac AC_OBJEXT 23558@acindex{OBJEXT} 23559@ovindex OBJEXT 23560Defined the output variable @code{OBJEXT} based on the output of the 23561compiler, after .c files have been excluded. Typically set to @samp{o} 23562if Posix, @samp{obj} if a DOS variant. 23563Now the compiler checking macros handle 23564this automatically. 23565@end defmac 23566 23567@defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion}) 23568@acindex{OBSOLETE} 23569Make M4 print a message to the standard error output warning that 23570@var{this-macro-name} is obsolete, and giving the file and line number 23571where it was called. @var{this-macro-name} should be the name of the 23572macro that is calling @code{AC_OBSOLETE}. If @var{suggestion} is given, 23573it is printed at the end of the warning message; for example, it can be 23574a suggestion for what to use instead of @var{this-macro-name}. 23575 23576For instance 23577 23578@example 23579AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl 23580@end example 23581 23582@noindent 23583You are encouraged to use @code{AU_DEFUN} instead, since it gives better 23584services to the user (@pxref{AU_DEFUN}). 23585@end defmac 23586 23587@defmac AC_OFF_T 23588@acindex{OFF_T} 23589Replaced by @code{AC_TYPE_OFF_T} (@pxref{AC_TYPE_OFF_T}). 23590@end defmac 23591 23592@defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds}) 23593@acindex{OUTPUT} 23594The use of @code{AC_OUTPUT} with arguments is deprecated. This obsoleted 23595interface is equivalent to: 23596 23597@example 23598@group 23599AC_CONFIG_FILES(@var{file}@dots{}) 23600AC_CONFIG_COMMANDS([default], 23601 @var{extra-cmds}, @var{init-cmds}) 23602AC_OUTPUT 23603@end group 23604@end example 23605 23606@noindent 23607See @ref{AC_CONFIG_FILES}, @ref{AC_CONFIG_COMMANDS}, and @ref{AC_OUTPUT}. 23608@end defmac 23609 23610@defmac AC_OUTPUT_COMMANDS (@var{extra-cmds}, @ovar{init-cmds}) 23611@acindex{OUTPUT_COMMANDS} 23612Specify additional shell commands to run at the end of 23613@file{config.status}, and shell commands to initialize any variables 23614from @command{configure}. This macro may be called multiple times. It is 23615obsolete, replaced by @code{AC_CONFIG_COMMANDS} (@pxref{AC_CONFIG_COMMANDS}). 23616 23617Here is an unrealistic example: 23618 23619@example 23620fubar=27 23621AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.], 23622 [fubar=$fubar]) 23623AC_OUTPUT_COMMANDS([echo this is another, extra, bit], 23624 [echo init bit]) 23625@end example 23626 23627Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an 23628additional key, an important difference is that 23629@code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, unlike 23630@code{AC_CONFIG_COMMANDS}. This means that @code{AC_CONFIG_COMMANDS} 23631can safely be given macro calls as arguments: 23632 23633@example 23634AC_CONFIG_COMMANDS(foo, [my_FOO()]) 23635@end example 23636 23637@noindent 23638Conversely, where one level of quoting was enough for literal strings 23639with @code{AC_OUTPUT_COMMANDS}, you need two with 23640@code{AC_CONFIG_COMMANDS}. The following lines are equivalent: 23641 23642@example 23643@group 23644AC_OUTPUT_COMMANDS([echo "Square brackets: []"]) 23645AC_CONFIG_COMMANDS([default], [[echo "Square brackets: []"]]) 23646@end group 23647@end example 23648@end defmac 23649 23650@defmac AC_PID_T 23651@acindex{PID_T} 23652Replaced by @code{AC_TYPE_PID_T} (@pxref{AC_TYPE_PID_T}). 23653@end defmac 23654 23655@defmac AC_PREFIX 23656@acindex{PREFIX} 23657Replaced by @code{AC_PREFIX_PROGRAM} (@pxref{AC_PREFIX_PROGRAM}). 23658@end defmac 23659 23660@defmac AC_PROGRAMS_CHECK 23661@acindex{PROGRAMS_CHECK} 23662Replaced by @code{AC_CHECK_PROGS} (@pxref{AC_CHECK_PROGS}). 23663@end defmac 23664 23665@defmac AC_PROGRAMS_PATH 23666@acindex{PROGRAMS_PATH} 23667Replaced by @code{AC_PATH_PROGS} (@pxref{AC_PATH_PROGS}). 23668@end defmac 23669 23670@defmac AC_PROGRAM_CHECK 23671@acindex{PROGRAM_CHECK} 23672Replaced by @code{AC_CHECK_PROG} (@pxref{AC_CHECK_PROG}). 23673@end defmac 23674 23675@defmac AC_PROGRAM_EGREP 23676@acindex{PROGRAM_EGREP} 23677Replaced by @code{AC_EGREP_CPP} (@pxref{AC_EGREP_CPP}). 23678@end defmac 23679 23680@defmac AC_PROGRAM_PATH 23681@acindex{PROGRAM_PATH} 23682Replaced by @code{AC_PATH_PROG} (@pxref{AC_PATH_PROG}). 23683@end defmac 23684 23685@defmac AC_REMOTE_TAPE 23686@acindex{REMOTE_TAPE} 23687Removed because of limited usefulness. 23688@end defmac 23689 23690@defmac AC_RESTARTABLE_SYSCALLS 23691@acindex{RESTARTABLE_SYSCALLS} 23692This macro was renamed @code{AC_SYS_RESTARTABLE_SYSCALLS}. However, 23693these days portable programs should use @code{sigaction} with 23694@code{SA_RESTART} if they want restartable system calls. They should 23695not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a 23696system call is restartable is a dynamic issue, not a configuration-time 23697issue. 23698@end defmac 23699 23700@defmac AC_RETSIGTYPE 23701@acindex{RETSIGTYPE} 23702Replaced by @code{AC_TYPE_SIGNAL} (@pxref{AC_TYPE_SIGNAL}), which itself 23703is obsolete when assuming C89 or better. 23704@end defmac 23705 23706@defmac AC_RSH 23707@acindex{RSH} 23708Removed because of limited usefulness. 23709@end defmac 23710 23711@defmac AC_SCO_INTL 23712@acindex{SCO_INTL} 23713@ovindex LIBS 23714If on SCO Unix, add @option{-lintl} to output variable @code{LIBS}. This 23715macro used to do this: 23716 23717@example 23718AC_CHECK_LIB([intl], [strftime], [LIBS="-lintl $LIBS"]) 23719@end example 23720 23721@noindent 23722Now it just calls @code{AC_FUNC_STRFTIME} instead (@pxref{AC_FUNC_STRFTIME}). 23723@end defmac 23724 23725@defmac AC_SETVBUF_REVERSED 23726@acindex{SETVBUF_REVERSED} 23727Replaced by 23728@example 23729AC_FUNC_SETVBUF_REVERSED 23730@end example 23731@noindent 23732@xref{AC_FUNC_SETVBUF_REVERSED}. 23733@end defmac 23734 23735@defmac AC_SET_MAKE 23736@acindex{SET_MAKE} 23737Replaced by @code{AC_PROG_MAKE_SET} (@pxref{AC_PROG_MAKE_SET}). 23738@end defmac 23739 23740@defmac AC_SIZEOF_TYPE 23741@acindex{SIZEOF_TYPE} 23742Replaced by @code{AC_CHECK_SIZEOF} (@pxref{AC_CHECK_SIZEOF}). 23743@end defmac 23744 23745@defmac AC_SIZE_T 23746@acindex{SIZE_T} 23747Replaced by @code{AC_TYPE_SIZE_T} (@pxref{AC_TYPE_SIZE_T}). 23748@end defmac 23749 23750@defmac AC_STAT_MACROS_BROKEN 23751@acindex{STAT_MACROS_BROKEN} 23752Replaced by @code{AC_HEADER_STAT} (@pxref{AC_HEADER_STAT}). 23753@end defmac 23754 23755@defmac AC_STDC_HEADERS 23756@acindex{STDC_HEADERS} 23757Replaced by @code{AC_HEADER_STDC} (@pxref{AC_HEADER_STDC}). 23758@end defmac 23759 23760@defmac AC_STRCOLL 23761@acindex{STRCOLL} 23762Replaced by @code{AC_FUNC_STRCOLL} (@pxref{AC_FUNC_STRCOLL}). 23763@end defmac 23764 23765@defmac AC_STRUCT_ST_BLKSIZE 23766@acindex{STRUCT_ST_BLKSIZE} 23767@cvindex HAVE_STRUCT_STAT_ST_BLKSIZE 23768@cvindex HAVE_ST_BLKSIZE 23769If @code{struct stat} contains an @code{st_blksize} member, define 23770@code{HAVE_STRUCT_STAT_ST_BLKSIZE}. The former name, 23771@code{HAVE_ST_BLKSIZE} is to be avoided, as its support will cease in 23772the future. This macro is obsoleted, and should be replaced by 23773 23774@example 23775AC_CHECK_MEMBERS([struct stat.st_blksize]) 23776@end example 23777@noindent 23778@xref{AC_CHECK_MEMBERS}. 23779@end defmac 23780 23781@defmac AC_STRUCT_ST_RDEV 23782@acindex{STRUCT_ST_RDEV} 23783@cvindex HAVE_ST_RDEV 23784@cvindex HAVE_STRUCT_STAT_ST_RDEV 23785If @code{struct stat} contains an @code{st_rdev} member, define 23786@code{HAVE_STRUCT_STAT_ST_RDEV}. The former name for this macro, 23787@code{HAVE_ST_RDEV}, is to be avoided as it will cease to be supported 23788in the future. Actually, even the new macro is obsolete and should be 23789replaced by: 23790@example 23791AC_CHECK_MEMBERS([struct stat.st_rdev]) 23792@end example 23793@noindent 23794@xref{AC_CHECK_MEMBERS}. 23795@end defmac 23796 23797@defmac AC_ST_BLKSIZE 23798@acindex{ST_BLKSIZE} 23799Replaced by @code{AC_CHECK_MEMBERS} (@pxref{AC_CHECK_MEMBERS}). 23800@end defmac 23801 23802@defmac AC_ST_BLOCKS 23803@acindex{ST_BLOCKS} 23804Replaced by @code{AC_STRUCT_ST_BLOCKS} (@pxref{AC_STRUCT_ST_BLOCKS}). 23805@end defmac 23806 23807@defmac AC_ST_RDEV 23808@acindex{ST_RDEV} 23809Replaced by @code{AC_CHECK_MEMBERS} (@pxref{AC_CHECK_MEMBERS}). 23810@end defmac 23811 23812@defmac AC_SYS_RESTARTABLE_SYSCALLS 23813@acindex{SYS_RESTARTABLE_SYSCALLS} 23814@cvindex HAVE_RESTARTABLE_SYSCALLS 23815If the system automatically restarts a system call that is interrupted 23816by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}. This macro does 23817not check whether system calls are restarted in general---it checks whether a 23818signal handler installed with @code{signal} (but not @code{sigaction}) 23819causes system calls to be restarted. It does not check whether system calls 23820can be restarted when interrupted by signals that have no handler. 23821 23822These days portable programs should use @code{sigaction} with 23823@code{SA_RESTART} if they want restartable system calls. They should 23824not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a 23825system call is restartable is a dynamic issue, not a configuration-time 23826issue. 23827@end defmac 23828 23829@defmac AC_SYS_SIGLIST_DECLARED 23830@acindex{SYS_SIGLIST_DECLARED} 23831This macro was renamed @code{AC_DECL_SYS_SIGLIST}. However, even that 23832name is obsolete, as the same functionality is now achieved via 23833@code{AC_CHECK_DECLS} (@pxref{AC_CHECK_DECLS}). 23834@end defmac 23835 23836@defmac AC_TEST_CPP 23837@acindex{TEST_CPP} 23838This macro was renamed @code{AC_TRY_CPP}, which in turn was replaced by 23839@code{AC_PREPROC_IFELSE} (@pxref{AC_PREPROC_IFELSE}). 23840@end defmac 23841 23842@defmac AC_TEST_PROGRAM 23843@acindex{TEST_PROGRAM} 23844This macro was renamed @code{AC_TRY_RUN}, which in turn was replaced by 23845@code{AC_RUN_IFELSE} (@pxref{AC_RUN_IFELSE}). 23846@end defmac 23847 23848@defmac AC_TIMEZONE 23849@acindex{TIMEZONE} 23850Replaced by @code{AC_STRUCT_TIMEZONE} (@pxref{AC_STRUCT_TIMEZONE}). 23851@end defmac 23852 23853@defmac AC_TIME_WITH_SYS_TIME 23854@acindex{TIME_WITH_SYS_TIME} 23855Replaced by @code{AC_HEADER_TIME} (@pxref{AC_HEADER_TIME}). 23856@end defmac 23857 23858@defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @ 23859 @ovar{action-if-true}, @ovar{action-if-false}) 23860@acindex{TRY_COMPILE} 23861Same as: 23862 23863@example 23864AC_COMPILE_IFELSE( 23865 [AC_LANG_PROGRAM([[@var{includes}]], 23866 [[@var{function-body}]])], 23867 [@var{action-if-true}], 23868 [@var{action-if-false}]) 23869@end example 23870 23871@noindent 23872@xref{Running the Compiler}. 23873 23874This macro double quotes both @var{includes} and @var{function-body}. 23875 23876For C and C++, @var{includes} is any @code{#include} statements needed 23877by the code in @var{function-body} (@var{includes} is ignored if 23878the currently selected language is Fortran or Fortran 77). The compiler 23879and compilation flags are determined by the current language 23880(@pxref{Language Choice}). 23881@end defmac 23882 23883@defmac AC_TRY_CPP (@var{input}, @ovar{action-if-true}, @ovar{action-if-false}) 23884@acindex{TRY_CPP} 23885Same as: 23886 23887@example 23888AC_PREPROC_IFELSE( 23889 [AC_LANG_SOURCE([[@var{input}]])], 23890 [@var{action-if-true}], 23891 [@var{action-if-false}]) 23892@end example 23893 23894@noindent 23895@xref{Running the Preprocessor}. 23896 23897This macro double quotes the @var{input}. 23898@end defmac 23899 23900@defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @ 23901 @ovar{action-if-true}, @ovar{action-if-false}) 23902@acindex{TRY_LINK} 23903Same as: 23904 23905@example 23906AC_LINK_IFELSE( 23907 [AC_LANG_PROGRAM([[@var{includes}]], 23908 [[@var{function-body}]])], 23909 [@var{action-if-true}], 23910 [@var{action-if-false}]) 23911@end example 23912 23913@noindent 23914@xref{Running the Compiler}. 23915 23916This macro double quotes both @var{includes} and @var{function-body}. 23917 23918Depending on the current language (@pxref{Language Choice}), create a 23919test program to see whether a function whose body consists of 23920@var{function-body} can be compiled and linked. If the file compiles 23921and links successfully, run shell commands @var{action-if-found}, 23922otherwise run @var{action-if-not-found}. 23923 23924This macro double quotes both @var{includes} and @var{function-body}. 23925 23926For C and C++, @var{includes} is any @code{#include} statements needed 23927by the code in @var{function-body} (@var{includes} is ignored if 23928the currently selected language is Fortran or Fortran 77). The compiler 23929and compilation flags are determined by the current language 23930(@pxref{Language Choice}), and in addition @code{LDFLAGS} and 23931@code{LIBS} are used for linking. 23932@end defmac 23933 23934@defmac AC_TRY_LINK_FUNC (@var{function}, @ovar{action-if-found}, @ 23935 @ovar{action-if-not-found}) 23936@acindex{TRY_LINK_FUNC} 23937This macro is equivalent to 23938@example 23939AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])], 23940 [@var{action-if-found}], [@var{action-if-not-found}]) 23941@end example 23942@noindent 23943@xref{AC_LINK_IFELSE}. 23944@end defmac 23945 23946@defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @ 23947 @ovar{action-if-false}, @dvar{action-if-cross-compiling, AC_MSG_FAILURE}) 23948@acindex{TRY_RUN} 23949Same as: 23950 23951@example 23952AC_RUN_IFELSE( 23953 [AC_LANG_SOURCE([[@var{program}]])], 23954 [@var{action-if-true}], 23955 [@var{action-if-false}], 23956 [@var{action-if-cross-compiling}]) 23957@end example 23958 23959@noindent 23960@xref{Runtime}. 23961@end defmac 23962 23963@anchor{AC_TYPE_SIGNAL} 23964@defmac AC_TYPE_SIGNAL 23965@acindex{TYPE_SIGNAL} 23966@cvindex RETSIGTYPE 23967@hdrindex{signal.h} 23968If @file{signal.h} declares @code{signal} as returning a pointer to a 23969function returning @code{void}, define @code{RETSIGTYPE} to be 23970@code{void}; otherwise, define it to be @code{int}. These days, it is 23971portable to assume C89, and that signal handlers return @code{void}, 23972without needing to use this macro or @code{RETSIGTYPE}. 23973 23974When targeting older K&R C, it is possible to define signal handlers as 23975returning type @code{RETSIGTYPE}, and omit a return statement: 23976 23977@example 23978@group 23979RETSIGTYPE 23980hup_handler () 23981@{ 23982@dots{} 23983@} 23984@end group 23985@end example 23986@end defmac 23987 23988@defmac AC_UID_T 23989@acindex{UID_T} 23990Replaced by @code{AC_TYPE_UID_T} (@pxref{AC_TYPE_UID_T}). 23991@end defmac 23992 23993@defmac AC_UNISTD_H 23994@acindex{UNISTD_H} 23995Same as @samp{AC_CHECK_HEADERS([unistd.h])} (@pxref{AC_CHECK_HEADERS}). 23996@end defmac 23997 23998@defmac AC_USG 23999@acindex{USG} 24000@cvindex USG 24001Define @code{USG} if the BSD string functions are defined in 24002@file{strings.h}. You should no longer depend upon @code{USG}, but on 24003@code{HAVE_STRING_H}; see @ref{Standard Symbols}. 24004@end defmac 24005 24006@defmac AC_UTIME_NULL 24007@acindex{UTIME_NULL} 24008Replaced by @code{AC_FUNC_UTIME_NULL} (@pxref{AC_FUNC_UTIME_NULL}). 24009@end defmac 24010 24011@defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@ovar{cmd}) 24012@acindex{VALIDATE_CACHED_SYSTEM_TUPLE} 24013If the cache file is inconsistent with the current host, target and 24014build system types, it used to execute @var{cmd} or print a default 24015error message. This is now handled by default. 24016@end defmac 24017 24018@defmac AC_VERBOSE (@var{result-description}) 24019@acindex{VERBOSE} 24020Replaced by @code{AC_MSG_RESULT} (@pxref{AC_MSG_RESULT}). 24021@end defmac 24022 24023@defmac AC_VFORK 24024@acindex{VFORK} 24025Replaced by @code{AC_FUNC_FORK} (@pxref{AC_FUNC_FORK}). 24026@end defmac 24027 24028@defmac AC_VPRINTF 24029@acindex{VPRINTF} 24030Replaced by @code{AC_FUNC_VPRINTF} (@pxref{AC_FUNC_VPRINTF}). 24031@end defmac 24032 24033@defmac AC_WAIT3 24034@acindex{WAIT3} 24035This macro was renamed @code{AC_FUNC_WAIT3}. However, these days 24036portable programs should use @code{waitpid}, not @code{wait3}, as 24037@code{wait3} has been removed from Posix. 24038@end defmac 24039 24040@defmac AC_WARN 24041@acindex{WARN} 24042Replaced by @code{AC_MSG_WARN} (@pxref{AC_MSG_WARN}). 24043@end defmac 24044 24045@defmac AC_WITH (@var{package}, @var{action-if-given}, @ 24046 @ovar{action-if-not-given}) 24047@acindex{WITH} 24048This is an obsolete version of @code{AC_ARG_WITH} that does not 24049support providing a help string (@pxref{AC_ARG_WITH}). 24050@end defmac 24051 24052@defmac AC_WORDS_BIGENDIAN 24053@acindex{WORDS_BIGENDIAN} 24054Replaced by @code{AC_C_BIGENDIAN} (@pxref{AC_C_BIGENDIAN}). 24055@end defmac 24056 24057@defmac AC_XENIX_DIR 24058@acindex{XENIX_DIR} 24059@ovindex LIBS 24060This macro used to add @option{-lx} to output variable @code{LIBS} if on 24061Xenix. Also, if @file{dirent.h} is being checked for, added 24062@option{-ldir} to @code{LIBS}. Now it is merely an alias of 24063@code{AC_HEADER_DIRENT} instead, plus some code to detect whether 24064running XENIX on which you should not depend: 24065 24066@example 24067AC_MSG_CHECKING([for Xenix]) 24068AC_EGREP_CPP([yes], 24069[#if defined M_XENIX && !defined M_UNIX 24070 yes 24071#endif], 24072 [AC_MSG_RESULT([yes]); XENIX=yes], 24073 [AC_MSG_RESULT([no]); XENIX=]) 24074@end example 24075@noindent 24076Don't use this macro, the dignified means to check the nature of the 24077host is using @code{AC_CANONICAL_HOST} (@pxref{Canonicalizing}). 24078@end defmac 24079 24080@defmac AC_YYTEXT_POINTER 24081@acindex{YYTEXT_POINTER} 24082This macro was renamed @code{AC_DECL_YYTEXT}, which in turn was 24083integrated into @code{AC_PROG_LEX} (@pxref{AC_PROG_LEX}). 24084@end defmac 24085 24086@node Autoconf 1 24087@section Upgrading From Version 1 24088@cindex Upgrading autoconf 24089@cindex Autoconf upgrading 24090 24091Autoconf version 2 is mostly backward compatible with version 1. 24092However, it introduces better ways to do some things, and doesn't 24093support some of the ugly things in version 1. So, depending on how 24094sophisticated your @file{configure.ac} files are, you might have to do 24095some manual work in order to upgrade to version 2. This chapter points 24096out some problems to watch for when upgrading. Also, perhaps your 24097@command{configure} scripts could benefit from some of the new features in 24098version 2; the changes are summarized in the file @file{NEWS} in the 24099Autoconf distribution. 24100 24101@menu 24102* Changed File Names:: Files you might rename 24103* Changed Makefiles:: New things to put in @file{Makefile.in} 24104* Changed Macros:: Macro calls you might replace 24105* Changed Results:: Changes in how to check test results 24106* Changed Macro Writing:: Better ways to write your own macros 24107@end menu 24108 24109@node Changed File Names 24110@subsection Changed File Names 24111 24112If you have an @file{aclocal.m4} installed with Autoconf (as opposed to 24113in a particular package's source directory), you must rename it to 24114@file{acsite.m4}. @xref{autoconf Invocation}. 24115 24116If you distribute @file{install.sh} with your package, rename it to 24117@file{install-sh} so @command{make} builtin rules don't inadvertently 24118create a file called @file{install} from it. @code{AC_PROG_INSTALL} 24119looks for the script under both names, but it is best to use the new name. 24120 24121If you were using @file{config.h.top}, @file{config.h.bot}, or 24122@file{acconfig.h}, you still can, but you have less clutter if you 24123use the @code{AH_} macros. @xref{Autoheader Macros}. 24124 24125@node Changed Makefiles 24126@subsection Changed Makefiles 24127 24128Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in 24129your @file{Makefile.in} files, so they can take advantage of the values 24130of those variables in the environment when @command{configure} is run. 24131Doing this isn't necessary, but it's a convenience for users. 24132 24133Also add @samp{@@configure_input@@} in a comment to each input file for 24134@code{AC_OUTPUT}, so that the output files contain a comment saying 24135they were produced by @command{configure}. Automatically selecting the 24136right comment syntax for all the kinds of files that people call 24137@code{AC_OUTPUT} on became too much work. 24138 24139Add @file{config.log} and @file{config.cache} to the list of files you 24140remove in @code{distclean} targets. 24141 24142If you have the following in @file{Makefile.in}: 24143 24144@example 24145prefix = /usr/local 24146exec_prefix = $(prefix) 24147@end example 24148 24149@noindent 24150you must change it to: 24151 24152@example 24153prefix = @@prefix@@ 24154exec_prefix = @@exec_prefix@@ 24155@end example 24156 24157@noindent 24158The old behavior of replacing those variables without @samp{@@} 24159characters around them has been removed. 24160 24161@node Changed Macros 24162@subsection Changed Macros 24163 24164Many of the macros were renamed in Autoconf version 2. You can still 24165use the old names, but the new ones are clearer, and it's easier to find 24166the documentation for them. @xref{Obsolete Macros}, for a table showing the 24167new names for the old macros. Use the @command{autoupdate} program to 24168convert your @file{configure.ac} to using the new macro names. 24169@xref{autoupdate Invocation}. 24170 24171Some macros have been superseded by similar ones that do the job better, 24172but are not call-compatible. If you get warnings about calling obsolete 24173macros while running @command{autoconf}, you may safely ignore them, but 24174your @command{configure} script generally works better if you follow 24175the advice that is printed about what to replace the obsolete macros with. In 24176particular, the mechanism for reporting the results of tests has 24177changed. If you were using @command{echo} or @code{AC_VERBOSE} (perhaps 24178via @code{AC_COMPILE_CHECK}), your @command{configure} script's output 24179looks better if you switch to @code{AC_MSG_CHECKING} and 24180@code{AC_MSG_RESULT}. @xref{Printing Messages}. Those macros work best 24181in conjunction with cache variables. @xref{Caching Results}. 24182 24183 24184 24185@node Changed Results 24186@subsection Changed Results 24187 24188If you were checking the results of previous tests by examining the 24189shell variable @code{DEFS}, you need to switch to checking the values of 24190the cache variables for those tests. @code{DEFS} no longer exists while 24191@command{configure} is running; it is only created when generating output 24192files. This difference from version 1 is because properly quoting the 24193contents of that variable turned out to be too cumbersome and 24194inefficient to do every time @code{AC_DEFINE} is called. @xref{Cache 24195Variable Names}. 24196 24197For example, here is a @file{configure.ac} fragment written for Autoconf 24198version 1: 24199 24200@example 24201AC_HAVE_FUNCS(syslog) 24202case "$DEFS" in 24203*-DHAVE_SYSLOG*) ;; 24204*) # syslog is not in the default libraries. See if it's in some other. 24205 saved_LIBS="$LIBS" 24206 for lib in bsd socket inet; do 24207 AC_CHECKING(for syslog in -l$lib) 24208 LIBS="-l$lib $saved_LIBS" 24209 AC_HAVE_FUNCS(syslog) 24210 case "$DEFS" in 24211 *-DHAVE_SYSLOG*) break ;; 24212 *) ;; 24213 esac 24214 LIBS="$saved_LIBS" 24215 done ;; 24216esac 24217@end example 24218 24219Here is a way to write it for version 2: 24220 24221@example 24222AC_CHECK_FUNCS([syslog]) 24223if test "x$ac_cv_func_syslog" = xno; then 24224 # syslog is not in the default libraries. See if it's in some other. 24225 for lib in bsd socket inet; do 24226 AC_CHECK_LIB([$lib], [syslog], [AC_DEFINE([HAVE_SYSLOG]) 24227 LIBS="-l$lib $LIBS"; break]) 24228 done 24229fi 24230@end example 24231 24232If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding 24233backslashes before quotes, you need to remove them. It now works 24234predictably, and does not treat quotes (except back quotes) specially. 24235@xref{Setting Output Variables}. 24236 24237All of the Boolean shell variables set by Autoconf macros now use 24238@samp{yes} for the true value. Most of them use @samp{no} for false, 24239though for backward compatibility some use the empty string instead. If 24240you were relying on a shell variable being set to something like 1 or 24241@samp{t} for true, you need to change your tests. 24242 24243@node Changed Macro Writing 24244@subsection Changed Macro Writing 24245 24246When defining your own macros, you should now use @code{AC_DEFUN} 24247instead of @code{define}. @code{AC_DEFUN} automatically calls 24248@code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE} 24249do not interrupt other macros, to prevent nested @samp{checking@dots{}} 24250messages on the screen. There's no actual harm in continuing to use the 24251older way, but it's less convenient and attractive. @xref{Macro 24252Definitions}. 24253 24254You probably looked at the macros that came with Autoconf as a guide for 24255how to do things. It would be a good idea to take a look at the new 24256versions of them, as the style is somewhat improved and they take 24257advantage of some new features. 24258 24259If you were doing tricky things with undocumented Autoconf internals 24260(macros, variables, diversions), check whether you need to change 24261anything to account for changes that have been made. Perhaps you can 24262even use an officially supported technique in version 2 instead of 24263kludging. Or perhaps not. 24264 24265To speed up your locally written feature tests, add caching to them. 24266See whether any of your tests are of general enough usefulness to 24267encapsulate them into macros that you can share. 24268 24269 24270@node Autoconf 2.13 24271@section Upgrading From Version 2.13 24272@cindex Upgrading autoconf 24273@cindex Autoconf upgrading 24274 24275The introduction of the previous section (@pxref{Autoconf 1}) perfectly 24276suits this section@enddots{} 24277 24278@quotation 24279Autoconf version 2.50 is mostly backward compatible with version 2.13. 24280However, it introduces better ways to do some things, and doesn't 24281support some of the ugly things in version 2.13. So, depending on how 24282sophisticated your @file{configure.ac} files are, you might have to do 24283some manual work in order to upgrade to version 2.50. This chapter 24284points out some problems to watch for when upgrading. Also, perhaps 24285your @command{configure} scripts could benefit from some of the new 24286features in version 2.50; the changes are summarized in the file 24287@file{NEWS} in the Autoconf distribution. 24288@end quotation 24289 24290@menu 24291* Changed Quotation:: Broken code which used to work 24292* New Macros:: Interaction with foreign macros 24293* Hosts and Cross-Compilation:: Bugward compatibility kludges 24294* AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token 24295* AC_ACT_IFELSE vs AC_TRY_ACT:: A more generic scheme for testing sources 24296@end menu 24297 24298@node Changed Quotation 24299@subsection Changed Quotation 24300 24301The most important changes are invisible to you: the implementation of 24302most macros have completely changed. This allowed more factorization of 24303the code, better error messages, a higher uniformity of the user's 24304interface etc. Unfortunately, as a side effect, some construct which 24305used to (miraculously) work might break starting with Autoconf 2.50. 24306The most common culprit is bad quotation. 24307 24308For instance, in the following example, the message is not properly 24309quoted: 24310 24311@example 24312AC_INIT 24313AC_CHECK_HEADERS(foo.h, , 24314 AC_MSG_ERROR(cannot find foo.h, bailing out)) 24315AC_OUTPUT 24316@end example 24317 24318@noindent 24319Autoconf 2.13 simply ignores it: 24320 24321@example 24322$ @kbd{autoconf-2.13; ./configure --silent} 24323creating cache ./config.cache 24324configure: error: cannot find foo.h 24325$ 24326@end example 24327 24328@noindent 24329while Autoconf 2.50 produces a broken @file{configure}: 24330 24331@example 24332$ @kbd{autoconf-2.50; ./configure --silent} 24333configure: error: cannot find foo.h 24334./configure: exit: bad non-numeric arg `bailing' 24335./configure: exit: bad non-numeric arg `bailing' 24336$ 24337@end example 24338 24339The message needs to be quoted, and the @code{AC_MSG_ERROR} invocation 24340too! 24341 24342@example 24343AC_INIT([Example], [1.0], [bug-example@@example.org]) 24344AC_CHECK_HEADERS([foo.h], [], 24345 [AC_MSG_ERROR([cannot find foo.h, bailing out])]) 24346AC_OUTPUT 24347@end example 24348 24349Many many (and many more) Autoconf macros were lacking proper quotation, 24350including no less than@dots{} @code{AC_DEFUN} itself! 24351 24352@example 24353$ @kbd{cat configure.in} 24354AC_DEFUN([AC_PROG_INSTALL], 24355[# My own much better version 24356]) 24357AC_INIT 24358AC_PROG_INSTALL 24359AC_OUTPUT 24360$ @kbd{autoconf-2.13} 24361autoconf: Undefined macros: 24362***BUG in Autoconf--please report*** AC_FD_MSG 24363***BUG in Autoconf--please report*** AC_EPI 24364configure.in:1:AC_DEFUN([AC_PROG_INSTALL], 24365configure.in:5:AC_PROG_INSTALL 24366$ @kbd{autoconf-2.50} 24367$ 24368@end example 24369 24370 24371@node New Macros 24372@subsection New Macros 24373 24374@cindex undefined macro 24375@cindex @code{_m4_divert_diversion} 24376 24377While Autoconf was relatively dormant in the late 1990s, Automake 24378provided Autoconf-like macros for a while. Starting with Autoconf 2.50 24379in 2001, Autoconf provided 24380versions of these macros, integrated in the @code{AC_} namespace, 24381instead of @code{AM_}. But in order to ease the upgrading via 24382@command{autoupdate}, bindings to such @code{AM_} macros are provided. 24383 24384Unfortunately older versions of Automake (e.g., Automake 1.4) 24385did not quote the names of these macros. 24386Therefore, when @command{m4} finds something like 24387@samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, @dots{})} in @file{aclocal.m4}, 24388@code{AM_TYPE_PTRDIFF_T} is 24389expanded, replaced with its Autoconf definition. 24390 24391Fortunately Autoconf catches pre-@code{AC_INIT} expansions, and 24392complains, in its own words: 24393 24394@example 24395$ @kbd{cat configure.ac} 24396AC_INIT([Example], [1.0], [bug-example@@example.org]) 24397AM_TYPE_PTRDIFF_T 24398$ @kbd{aclocal-1.4} 24399$ @kbd{autoconf} 24400aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion 24401aclocal.m4:17: the top level 24402autom4te: m4 failed with exit status: 1 24403$ 24404@end example 24405 24406Modern versions of Automake no longer define most of these 24407macros, and properly quote the names of the remaining macros. 24408If you must use an old Automake, do not depend upon macros from Automake 24409as it is simply not its job 24410to provide macros (but the one it requires itself): 24411 24412@example 24413$ @kbd{cat configure.ac} 24414AC_INIT([Example], [1.0], [bug-example@@example.org]) 24415AM_TYPE_PTRDIFF_T 24416$ @kbd{rm aclocal.m4} 24417$ @kbd{autoupdate} 24418autoupdate: `configure.ac' is updated 24419$ @kbd{cat configure.ac} 24420AC_INIT([Example], [1.0], [bug-example@@example.org]) 24421AC_CHECK_TYPES([ptrdiff_t]) 24422$ @kbd{aclocal-1.4} 24423$ @kbd{autoconf} 24424$ 24425@end example 24426 24427 24428@node Hosts and Cross-Compilation 24429@subsection Hosts and Cross-Compilation 24430@cindex Cross compilation 24431 24432Based on the experience of compiler writers, and after long public 24433debates, many aspects of the cross-compilation chain have changed: 24434 24435@itemize @minus 24436@item 24437the relationship between the build, host, and target architecture types, 24438 24439@item 24440the command line interface for specifying them to @command{configure}, 24441 24442@item 24443the variables defined in @command{configure}, 24444 24445@item 24446the enabling of cross-compilation mode. 24447@end itemize 24448 24449@sp 1 24450 24451The relationship between build, host, and target have been cleaned up: 24452the chain of default is now simply: target defaults to host, host to 24453build, and build to the result of @command{config.guess}. Nevertheless, 24454in order to ease the transition from 2.13 to 2.50, the following 24455transition scheme is implemented. @emph{Do not rely on it}, as it will 24456be completely disabled in a couple of releases (we cannot keep it, as it 24457proves to cause more problems than it cures). 24458 24459They all default to the result of running @command{config.guess}, unless 24460you specify either @option{--build} or @option{--host}. In this case, 24461the default becomes the system type you specified. If you specify both, 24462and they're different, @command{configure} enters cross compilation 24463mode, so it doesn't run any tests that require execution. 24464 24465Hint: if you mean to override the result of @command{config.guess}, 24466prefer @option{--build} over @option{--host}. 24467 24468@sp 1 24469 24470For backward compatibility, @command{configure} accepts a system 24471type as an option by itself. Such an option overrides the 24472defaults for build, host, and target system types. The following 24473configure statement configures a cross toolchain that runs on 24474NetBSD/alpha but generates code for GNU Hurd/sparc, 24475which is also the build platform. 24476 24477@example 24478./configure --host=alpha-netbsd sparc-gnu 24479@end example 24480 24481@sp 1 24482 24483In Autoconf 2.13 and before, the variables @code{build}, @code{host}, 24484and @code{target} had a different semantics before and after the 24485invocation of @code{AC_CANONICAL_BUILD} etc. Now, the argument of 24486@option{--build} is strictly copied into @code{build_alias}, and is left 24487empty otherwise. After the @code{AC_CANONICAL_BUILD}, @code{build} is 24488set to the canonicalized build type. To ease the transition, before, 24489its contents is the same as that of @code{build_alias}. Do @emph{not} 24490rely on this broken feature. 24491 24492For consistency with the backward compatibility scheme exposed above, 24493when @option{--host} is specified but @option{--build} isn't, the build 24494system is assumed to be the same as @option{--host}, and 24495@samp{build_alias} is set to that value. Eventually, this 24496historically incorrect behavior will go away. 24497 24498@sp 1 24499 24500The former scheme to enable cross-compilation proved to cause more harm 24501than good, in particular, it used to be triggered too easily, leaving 24502regular end users puzzled in front of cryptic error messages. 24503@command{configure} could even enter cross-compilation mode only 24504because the compiler was not functional. This is mainly because 24505@command{configure} used to try to detect cross-compilation, instead of 24506waiting for an explicit flag from the user. 24507 24508Now, @command{configure} enters cross-compilation mode if and only if 24509@option{--host} is passed. 24510 24511That's the short documentation. To ease the transition between 2.13 and 24512its successors, a more complicated scheme is implemented. @emph{Do not 24513rely on the following}, as it will be removed in the near future. 24514 24515If you specify @option{--host}, but not @option{--build}, when 24516@command{configure} performs the first compiler test it tries to run 24517an executable produced by the compiler. If the execution fails, it 24518enters cross-compilation mode. This is fragile. Moreover, by the time 24519the compiler test is performed, it may be too late to modify the 24520build-system type: other tests may have already been performed. 24521Therefore, whenever you specify @option{--host}, be sure to specify 24522@option{--build} too. 24523 24524@example 24525./configure --build=i686-pc-linux-gnu --host=m68k-coff 24526@end example 24527 24528@noindent 24529enters cross-compilation mode. The former interface, which 24530consisted in setting the compiler to a cross-compiler without informing 24531@command{configure} is obsolete. For instance, @command{configure} 24532fails if it can't run the code generated by the specified compiler if you 24533configure as follows: 24534 24535@example 24536./configure CC=m68k-coff-gcc 24537@end example 24538 24539 24540@node AC_LIBOBJ vs LIBOBJS 24541@subsection @code{AC_LIBOBJ} vs.@: @code{LIBOBJS} 24542 24543Up to Autoconf 2.13, the replacement of functions was triggered via the 24544variable @code{LIBOBJS}. Since Autoconf 2.50, the macro 24545@code{AC_LIBOBJ} should be used instead (@pxref{Generic Functions}). 24546Starting at Autoconf 2.53, the use of @code{LIBOBJS} is an error. 24547 24548This change is mandated by the unification of the GNU Build System 24549components. In particular, the various fragile techniques used to parse 24550a @file{configure.ac} are all replaced with the use of traces. As a 24551consequence, any action must be traceable, which obsoletes critical 24552variable assignments. Fortunately, @code{LIBOBJS} was the only problem, 24553and it can even be handled gracefully (read, ``without your having to 24554change something''). 24555 24556There were two typical uses of @code{LIBOBJS}: asking for a replacement 24557function, and adjusting @code{LIBOBJS} for Automake and/or Libtool. 24558 24559@sp 1 24560 24561As for function replacement, the fix is immediate: use 24562@code{AC_LIBOBJ}. For instance: 24563 24564@example 24565LIBOBJS="$LIBOBJS fnmatch.o" 24566LIBOBJS="$LIBOBJS malloc.$ac_objext" 24567@end example 24568 24569@noindent 24570should be replaced with: 24571 24572@example 24573AC_LIBOBJ([fnmatch]) 24574AC_LIBOBJ([malloc]) 24575@end example 24576 24577@sp 1 24578 24579@ovindex LIBOBJDIR 24580When used with Automake 1.10 or newer, a suitable value for 24581@code{LIBOBJDIR} is set so that the @code{LIBOBJS} and @code{LTLIBOBJS} 24582can be referenced from any @file{Makefile.am}. Even without Automake, 24583arranging for @code{LIBOBJDIR} to be set correctly enables 24584referencing @code{LIBOBJS} and @code{LTLIBOBJS} in another directory. 24585The @code{LIBOBJDIR} feature is experimental. 24586 24587 24588@node AC_ACT_IFELSE vs AC_TRY_ACT 24589@subsection @code{AC_@var{ACT}_IFELSE} vs.@: @code{AC_TRY_@var{ACT}} 24590@c the anchor keeps the old node name, to try to avoid breaking links 24591@anchor{AC_FOO_IFELSE vs AC_TRY_FOO} 24592 24593@acindex{@var{ACT}_IFELSE} 24594@acindex{TRY_@var{ACT}} 24595Since Autoconf 2.50, internal codes uses @code{AC_PREPROC_IFELSE}, 24596@code{AC_COMPILE_IFELSE}, @code{AC_LINK_IFELSE}, and 24597@code{AC_RUN_IFELSE} on one hand and @code{AC_LANG_SOURCE}, 24598and @code{AC_LANG_PROGRAM} on the other hand instead of the deprecated 24599@code{AC_TRY_CPP}, @code{AC_TRY_COMPILE}, @code{AC_TRY_LINK}, and 24600@code{AC_TRY_RUN}. The motivations where: 24601@itemize @minus 24602@item 24603a more consistent interface: @code{AC_TRY_COMPILE} etc.@: were double 24604quoting their arguments; 24605 24606@item 24607the combinatoric explosion is solved by decomposing on the one hand the 24608generation of sources, and on the other hand executing the program; 24609 24610@item 24611this scheme helps supporting more languages than plain C and C++. 24612@end itemize 24613 24614In addition to the change of syntax, the philosophy has changed too: 24615while emphasis was put on speed at the expense of accuracy, today's 24616Autoconf promotes accuracy of the testing framework at, ahem@dots{}, the 24617expense of speed. 24618 24619 24620As a perfect example of what is @emph{not} to be done, here is how to 24621find out whether a header file contains a particular declaration, such 24622as a typedef, a structure, a structure member, or a function. Use 24623@code{AC_EGREP_HEADER} instead of running @code{grep} directly on the 24624header file; on some systems the symbol might be defined in another 24625header file that the file you are checking includes. 24626 24627As a (bad) example, here is how you should not check for C preprocessor 24628symbols, either defined by header files or predefined by the C 24629preprocessor: using @code{AC_EGREP_CPP}: 24630 24631@example 24632@group 24633AC_EGREP_CPP(yes, 24634[#ifdef _AIX 24635 yes 24636#endif 24637], is_aix=yes, is_aix=no) 24638@end group 24639@end example 24640 24641The above example, properly written would (i) use 24642@code{AC_LANG_PROGRAM}, and (ii) run the compiler: 24643 24644@example 24645@group 24646AC_COMPILE_IFELSE([AC_LANG_PROGRAM( 24647[[#ifndef _AIX 24648 error: This isn't AIX! 24649#endif 24650]])], 24651 [is_aix=yes], 24652 [is_aix=no]) 24653@end group 24654@end example 24655 24656 24657@c ============================= Generating Test Suites with Autotest 24658 24659@node Using Autotest 24660@chapter Generating Test Suites with Autotest 24661 24662@cindex Autotest 24663 24664@display 24665@strong{N.B.: This section describes a feature which is still 24666stabilizing. Although we believe that Autotest is useful as-is, this 24667documentation describes an interface which might change in the future: 24668do not depend upon Autotest without subscribing to the Autoconf mailing 24669lists.} 24670@end display 24671 24672It is paradoxical that portable projects depend on nonportable tools 24673to run their test suite. Autoconf by itself is the paragon of this 24674problem: although it aims at perfectly portability, up to 2.13 its 24675test suite was using DejaGNU, a rich and complex testing 24676framework, but which is far from being standard on Posix systems. 24677Worse yet, it was likely to be missing on the most fragile platforms, 24678the very platforms that are most likely to torture Autoconf and 24679exhibit deficiencies. 24680 24681To circumvent this problem, many package maintainers have developed their 24682own testing framework, based on simple shell scripts whose sole outputs 24683are exit status values describing whether the test succeeded. Most of 24684these tests share common patterns, and this can result in lots of 24685duplicated code and tedious maintenance. 24686 24687Following exactly the same reasoning that yielded to the inception of 24688Autoconf, Autotest provides a test suite generation framework, based on 24689M4 macros building a portable shell script. The suite itself is 24690equipped with automatic logging and tracing facilities which greatly 24691diminish the interaction with bug reporters, and simple timing reports. 24692 24693Autoconf itself has been using Autotest for years, and we do attest that 24694it has considerably improved the strength of the test suite and the 24695quality of bug reports. Other projects are known to use some generation 24696of Autotest, such as Bison, Free Recode, Free Wdiff, GNU Tar, each of 24697them with different needs, and this usage has validated Autotest as a general 24698testing framework. 24699 24700Nonetheless, compared to DejaGNU, Autotest is inadequate for 24701interactive tool testing, which is probably its main limitation. 24702 24703@menu 24704* Using an Autotest Test Suite:: Autotest and the user 24705* Writing Testsuites:: Autotest macros 24706* testsuite Invocation:: Running @command{testsuite} scripts 24707* Making testsuite Scripts:: Using autom4te to create @command{testsuite} 24708@end menu 24709 24710@node Using an Autotest Test Suite 24711@section Using an Autotest Test Suite 24712 24713@menu 24714* testsuite Scripts:: The concepts of Autotest 24715* Autotest Logs:: Their contents 24716@end menu 24717 24718@node testsuite Scripts 24719@subsection @command{testsuite} Scripts 24720 24721@cindex @command{testsuite} 24722 24723Generating testing or validation suites using Autotest is rather easy. 24724The whole validation suite is held in a file to be processed through 24725@command{autom4te}, itself using GNU M4 under the hood, to 24726produce a stand-alone Bourne shell script which then gets distributed. 24727Neither @command{autom4te} nor GNU M4 are needed at 24728the installer's end. 24729 24730@cindex test group 24731Each test of the validation suite should be part of some test group. A 24732@dfn{test group} is a sequence of interwoven tests that ought to be 24733executed together, usually because one test in the group creates data 24734files that a later test in the same group needs to read. Complex test 24735groups make later debugging more tedious. It is much better to 24736keep only a few tests per test group. Ideally there is only one test 24737per test group. 24738 24739For all but the simplest packages, some file such as @file{testsuite.at} 24740does not fully hold all test sources, as these are often easier to 24741maintain in separate files. Each of these separate files holds a single 24742test group, or a sequence of test groups all addressing some common 24743functionality in the package. In such cases, @file{testsuite.at} 24744merely initializes the validation suite, and sometimes does elementary 24745health checking, before listing include statements for all other test 24746files. The special file @file{package.m4}, containing the 24747identification of the package, is automatically included if found. 24748 24749A convenient alternative consists in moving all the global issues 24750(local Autotest macros, elementary health checking, and @code{AT_INIT} 24751invocation) into the file @code{local.at}, and making 24752@file{testsuite.at} be a simple list of @code{m4_include}s of sub test 24753suites. In such case, generating the whole test suite or pieces of it 24754is only a matter of choosing the @command{autom4te} command line 24755arguments. 24756 24757The validation scripts that Autotest produces are by convention called 24758@command{testsuite}. When run, @command{testsuite} executes each test 24759group in turn, producing only one summary line per test to say if that 24760particular test succeeded or failed. At end of all tests, summarizing 24761counters get printed. One debugging directory is left for each test 24762group which failed, if any: such directories are named 24763@file{testsuite.dir/@var{nn}}, where @var{nn} is the sequence number of 24764the test group, and they include: 24765 24766@itemize @bullet 24767@item a debugging script named @file{run} which reruns the test in 24768@dfn{debug mode} (@pxref{testsuite Invocation}). The automatic generation 24769of debugging scripts has the purpose of easing the chase for bugs. 24770 24771@item all the files created with @code{AT_DATA} 24772 24773@item all the Erlang source code files created with @code{AT_CHECK_EUNIT} 24774 24775@item a log of the run, named @file{testsuite.log} 24776@end itemize 24777 24778In the ideal situation, none of the tests fail, and consequently no 24779debugging directory is left behind for validation. 24780 24781It often happens in practice that individual tests in the validation 24782suite need to get information coming out of the configuration process. 24783Some of this information, common for all validation suites, is provided 24784through the file @file{atconfig}, automatically created by 24785@code{AC_CONFIG_TESTDIR}. For configuration information which your 24786testing environment specifically needs, you might prepare an optional 24787file named @file{atlocal.in}, instantiated by @code{AC_CONFIG_FILES}. 24788The configuration process produces @file{atconfig} and @file{atlocal} 24789out of these two input files, and these two produced files are 24790automatically read by the @file{testsuite} script. 24791 24792Here is a diagram showing the relationship between files. 24793 24794@noindent 24795Files used in preparing a software package for distribution: 24796 24797@example 24798 [package.m4] -->. 24799 \ 24800subfile-1.at ->. [local.at] ---->+ 24801 ... \ \ 24802subfile-i.at ---->-- testsuite.at -->-- autom4te* -->testsuite 24803 ... / 24804subfile-n.at ->' 24805@end example 24806 24807@noindent 24808Files used in configuring a software package: 24809 24810@example 24811 .--> atconfig 24812 / 24813[atlocal.in] --> config.status* --< 24814 \ 24815 `--> [atlocal] 24816@end example 24817 24818@noindent 24819Files created during test suite execution: 24820 24821@example 24822atconfig -->. .--> testsuite.log 24823 \ / 24824 >-- testsuite* --< 24825 / \ 24826[atlocal] ->' `--> [testsuite.dir] 24827@end example 24828 24829 24830@node Autotest Logs 24831@subsection Autotest Logs 24832 24833When run, the test suite creates a log file named after itself, e.g., a 24834test suite named @command{testsuite} creates @file{testsuite.log}. It 24835contains a lot of information, usually more than maintainers actually 24836need, but therefore most of the time it contains all that is needed: 24837 24838@table @asis 24839@item command line arguments 24840A bad but unfortunately widespread habit consists of 24841setting environment variables before the command, such as in 24842@samp{CC=my-home-grown-cc ./testsuite}. The test suite does not 24843know this change, hence (i) it cannot report it to you, and (ii) 24844it cannot preserve the value of @code{CC} for subsequent runs. 24845Autoconf faced exactly the same problem, and solved it by asking 24846users to pass the variable definitions as command line arguments. 24847Autotest requires this rule, too, but has no means to enforce it; the log 24848then contains a trace of the variables that were changed by the user. 24849 24850@item @file{ChangeLog} excerpts 24851The topmost lines of all the @file{ChangeLog} files found in the source 24852hierarchy. This is especially useful when bugs are reported against 24853development versions of the package, since the version string does not 24854provide sufficient information to know the exact state of the sources 24855the user compiled. Of course, this relies on the use of a 24856@file{ChangeLog}. 24857 24858@item build machine 24859Running a test suite in a cross-compile environment is not an easy task, 24860since it would mean having the test suite run on a machine @var{build}, 24861while running programs on a machine @var{host}. It is much simpler to 24862run both the test suite and the programs on @var{host}, but then, from 24863the point of view of the test suite, there remains a single environment, 24864@var{host} = @var{build}. The log contains relevant information on the 24865state of the @var{build} machine, including some important environment 24866variables. 24867@c FIXME: How about having an M4sh macro to say `hey, log the value 24868@c of `@dots{}'? This would help both Autoconf and Autotest. 24869 24870@item tested programs 24871The absolute file name and answers to @option{--version} of the tested 24872programs (see @ref{Writing Testsuites}, @code{AT_TESTED}). 24873 24874@item configuration log 24875The contents of @file{config.log}, as created by @command{configure}, 24876are appended. It contains the configuration flags and a detailed report 24877on the configuration itself. 24878@end table 24879 24880 24881@node Writing Testsuites 24882@section Writing @file{testsuite.at} 24883 24884The @file{testsuite.at} is a Bourne shell script making use of special 24885Autotest M4 macros. It often contains a call to @code{AT_INIT} near 24886its beginning followed by one call to @code{m4_include} per source file 24887for tests. Each such included file, or the remainder of 24888@file{testsuite.at} if include files are not used, contain a sequence of 24889test groups. Each test group begins with a call to @code{AT_SETUP}, 24890then an arbitrary number of shell commands or calls to @code{AT_CHECK}, 24891and then completes with a call to @code{AT_CLEANUP}. Multiple test 24892groups can be categorized by a call to @code{AT_BANNER}. 24893 24894All of the public Autotest macros have all-uppercase names in the 24895namespace @samp{^AT_} to prevent them from accidentally conflicting with 24896other text; Autoconf also reserves the namespace @samp{^_AT_} for 24897internal macros. All shell variables used in the testsuite for internal 24898purposes have mostly-lowercase names starting with @samp{at_}. Autotest 24899also uses here-document delimiters in the namespace @samp{^_AT[A-Z]}, and 24900makes use of the file system namespace @samp{^at-}. 24901 24902Since Autoconf is built on top of M4sugar (@pxref{Programming in 24903M4sugar}) and M4sh (@pxref{Programming in M4sh}), you must also be aware 24904of those namespaces (@samp{^_?\(m4\|AS\)_}). In general, you 24905@emph{should not use} the namespace of a package that does not own the 24906macro or shell code you are writing. 24907 24908@defmac AT_INIT (@ovar{name}) 24909@atindex{INIT} 24910@c FIXME: Not clear, plus duplication of the information. 24911Initialize Autotest. Giving a @var{name} to the test suite is 24912encouraged if your package includes several test suites. Before this 24913macro is called, @code{AT_PACKAGE_STRING} and 24914@code{AT_PACKAGE_BUGREPORT} must be defined, which are used to display 24915information about the testsuite to the user. Typically, these macros 24916are provided by a file @file{package.m4} built by @command{make} 24917(@pxref{Making testsuite Scripts}), in order to inherit the package 24918name, version, and bug reporting address from @file{configure.ac}. 24919@end defmac 24920 24921@defmac AT_COPYRIGHT (@var{copyright-notice}) 24922@atindex{COPYRIGHT} 24923@cindex Copyright Notice 24924State that, in addition to the Free Software Foundation's copyright on 24925the Autotest macros, parts of your test suite are covered by 24926@var{copyright-notice}. 24927 24928The @var{copyright-notice} shows up in both the head of 24929@command{testsuite} and in @samp{testsuite --version}. 24930@end defmac 24931 24932@defmac AT_ARG_OPTION (@var{options}, @var{help-text}, @ 24933 @ovar{action-if-given}, @ovar{action-if-not-given}) 24934@atindex{ARG_OPTION} 24935@vrindex at_arg_@var{option} 24936Accept options from the space-separated list @var{options}, a list that 24937has leading dashes removed from the options. Long options will be 24938prefixed with @samp{--}, single-character options with @samp{-}. The 24939first word in this list is the primary @var{option}, any others are 24940assumed to be short-hand aliases. The variable associated with it 24941is @code{at_arg_@var{option}}, with any dashes in @var{option} replaced 24942with underscores. 24943 24944If the user passes @option{--@var{option}} to the @command{testsuite}, 24945the variable will be set to @samp{:}. If the user does not pass the 24946option, or passes @option{--no-@var{option}}, then the variable will be 24947set to @samp{false}. 24948 24949@vrindex at_optarg 24950@vrindex at_optarg_@var{option} 24951@var{action-if-given} is run each time the option is encountered; here, 24952the variable @code{at_optarg} will be set to @samp{:} or @samp{false} as 24953appropriate. @code{at_optarg} is actually just a copy of 24954@code{at_arg_@var{option}}. 24955 24956@var{action-if-not-given} will be run once after option parsing is 24957complete and if no option from @var{options} was used. 24958 24959@var{help-text} is added to the end of the list of options shown in 24960@command{testsuite --help} (@pxref{AS_HELP_STRING}). 24961 24962It is recommended that you use a package-specific prefix to @var{options} 24963names in order to avoid clashes with future Autotest built-in options. 24964@end defmac 24965 24966@defmac AT_ARG_OPTION_ARG (@var{options}, @var{help-text}, @ 24967 @ovar{action-if-given}, @ovar{action-if-not-given}) 24968@atindex{ARG_OPTION_ARG} 24969@vrindex at_arg_@var{option} 24970Accept options with arguments from the space-separated list 24971@var{options}, a list that has leading dashes removed from the options. 24972Long options will be prefixed with @samp{--}, single-character options 24973with @samp{-}. The first word in this list is the primary @var{option}, 24974any others are assumed to be short-hand aliases. The variable associated 24975with it is @code{at_arg_@var{option}}, with any dashes in @var{option} 24976replaced with underscores. 24977 24978If the user passes @option{--@var{option}=@var{arg}} or 24979@option{--@var{option} @var{arg}} to the @command{testsuite}, the 24980variable will be set to @samp{@var{arg}}. 24981 24982@vrindex at_optarg 24983@var{action-if-given} is run each time the option is encountered; here, 24984the variable @code{at_optarg} will be set to @samp{@var{arg}}. 24985@code{at_optarg} is actually just a copy of @code{at_arg_@var{option}}. 24986 24987@var{action-if-not-given} will be run once after option parsing is 24988complete and if no option from @var{options} was used. 24989 24990@var{help-text} is added to the end of the list of options shown in 24991@command{testsuite --help} (@pxref{AS_HELP_STRING}). 24992 24993It is recommended that you use a package-specific prefix to @var{options} 24994names in order to avoid clashes with future Autotest built-in options. 24995@end defmac 24996 24997@defmac AT_COLOR_TESTS 24998@atindex{COLOR_TESTS} 24999Enable colored test results by default when the output is connected to 25000a terminal. 25001@end defmac 25002 25003@defmac AT_TESTED (@var{executables}) 25004@atindex{TESTED} 25005Log the file name and answer to @option{--version} of each program in 25006space-separated list @var{executables}. Several invocations register 25007new executables, in other words, don't fear registering one program 25008several times. 25009 25010Autotest test suites rely on @env{PATH} to find the tested program. 25011This avoids the need to generate absolute names of the various tools, and 25012makes it possible to test installed programs. Therefore, knowing which 25013programs are being exercised is crucial to understanding problems in 25014the test suite itself, or its occasional misuses. It is a good idea to 25015also subscribe foreign programs you depend upon, to avoid incompatible 25016diagnostics. 25017@end defmac 25018 25019@sp 1 25020 25021@defmac AT_BANNER (@var{test-category-name}) 25022@atindex{BANNER} 25023This macro identifies the start of a category of related test groups. 25024When the resulting @file{testsuite} is invoked with more than one test 25025group to run, its output will include a banner containing 25026@var{test-category-name} prior to any tests run from that category. The 25027banner should be no more than about 40 or 50 characters. A blank banner 25028indicates uncategorized tests; an empty line will be inserted after 25029tests from an earlier category, effectively ending that category. 25030@end defmac 25031 25032@defmac AT_SETUP (@var{test-group-name}) 25033@atindex{SETUP} 25034This macro starts a group of related tests, all to be executed in the 25035same subshell. It accepts a single argument, which holds a few words 25036(no more than about 30 or 40 characters) quickly describing the purpose 25037of the test group being started. @var{test-group-name} must not expand 25038to unbalanced quotes, although quadrigraphs can be used. 25039@end defmac 25040 25041@defmac AT_KEYWORDS (@var{keywords}) 25042@atindex{KEYWORDS} 25043Associate the space-separated list of @var{keywords} to the enclosing 25044test group. This makes it possible to run ``slices'' of the test suite. 25045For instance, if some of your test groups exercise some @samp{foo} 25046feature, then using @samp{AT_KEYWORDS(foo)} lets you run 25047@samp{./testsuite -k foo} to run exclusively these test groups. The 25048@var{test-group-name} of the test group is automatically recorded to 25049@code{AT_KEYWORDS}. 25050 25051Several invocations within a test group accumulate new keywords. In 25052other words, don't fear registering the same keyword several times in a 25053test group. 25054@end defmac 25055 25056@defmac AT_CAPTURE_FILE (@var{file}) 25057@atindex{CAPTURE_FILE} 25058If the current test group fails, log the contents of @var{file}. 25059Several identical calls within one test group have no additional effect. 25060@end defmac 25061 25062@defmac AT_FAIL_IF (@var{shell-condition}) 25063@atindex{FAIL_IF} 25064Make the test group fail and skip the rest of its execution, if 25065@var{shell-condition} is true. @var{shell-condition} is a shell expression 25066such as a @code{test} command. Tests before @command{AT_FAIL_IF} 25067will be executed and may still cause the test group to be skipped. 25068You can instantiate this macro many times from within the same test group. 25069 25070You should use this macro only for very simple failure conditions. If the 25071@var{shell-condition} could emit any kind of output you should instead 25072use @command{AT_CHECK} like 25073@example 25074AT_CHECK([if @var{shell-condition}; then exit 99; fi]) 25075@end example 25076@noindent 25077so that such output is properly recorded in the @file{testsuite.log} 25078file. 25079@end defmac 25080 25081@defmac AT_SKIP_IF (@var{shell-condition}) 25082@atindex{SKIP_IF} 25083Determine whether the test should be skipped because it requires 25084features that are unsupported on the machine under test. 25085@var{shell-condition} is a shell expression such as a @code{test} 25086command. Tests before @command{AT_SKIP_IF} will be executed 25087and may still cause the test group to fail. You can instantiate this 25088macro many times from within the same test group. 25089 25090You should use this macro only for very simple skip conditions. If the 25091@var{shell-condition} could emit any kind of output you should instead 25092use @command{AT_CHECK} like 25093@example 25094AT_CHECK([if @var{shell-condition}; then exit 77; fi]) 25095@end example 25096@noindent 25097so that such output is properly recorded in the @file{testsuite.log} 25098file. 25099@end defmac 25100 25101@defmac AT_XFAIL_IF (@var{shell-condition}) 25102@atindex{XFAIL_IF} 25103Determine whether the test is expected to fail because it is a known 25104bug (for unsupported features, you should skip the test). 25105@var{shell-condition} is a shell expression such as a @code{test} 25106command; you can instantiate this macro many times from within the 25107same test group, and one of the conditions is enough to turn 25108the test into an expected failure. 25109@end defmac 25110 25111@defmac AT_CLEANUP 25112@atindex{CLEANUP} 25113End the current test group. 25114@end defmac 25115 25116@sp 1 25117 25118@defmac AT_DATA (@var{file}, @var{contents}) 25119@atindex{DATA} 25120Initialize an input data @var{file} with given @var{contents}. Of 25121course, the @var{contents} have to be properly quoted between square 25122brackets to protect against included commas or spurious M4 25123expansion. @var{contents} must be empty or end with a newline. 25124@var{file} must 25125be a single shell word that expands into a single file name. 25126@end defmac 25127 25128@defmac AT_CHECK (@var{commands}, @dvar{status, 0}, @ovar{stdout}, @ 25129 @ovar{stderr}, @ovar{run-if-fail}, @ovar{run-if-pass}) 25130@defmacx AT_CHECK_UNQUOTED (@var{commands}, @dvar{status, 0}, @ovar{stdout}, @ 25131 @ovar{stderr}, @ovar{run-if-fail}, @ovar{run-if-pass}) 25132@atindex{CHECK} 25133@atindex{CHECK_UNQUOTED} 25134@vrindex at_status 25135Execute a test by performing given shell @var{commands} in a subshell. 25136@var{commands} is output as-is, so shell expansions are honored. These 25137commands should normally exit with @var{status}, while producing expected 25138@var{stdout} and @var{stderr} contents. If @var{commands} exit with 25139unexpected status 77, then the rest of the test group is skipped. If 25140@var{commands} exit with unexpected status 99, then the test group is 25141immediately failed. Otherwise, if this test fails, run shell commands 25142@var{run-if-fail} or, if this test passes, run shell commands 25143@var{run-if-pass}, both inside the current shell execution environment. 25144At the beginning of @var{run-if-fail} and @var{run-if-pass}, the status of 25145@var{commands} is available in the @code{at_status} shell variable. 25146 25147This macro must be invoked in between @code{AT_SETUP} and @code{AT_CLEANUP}. 25148 25149If @var{status} is the literal @samp{ignore}, then the corresponding 25150exit status is not checked, except for the special cases of 77 (skip) 25151and 99 (hard failure). The existence of hard failures allows one to 25152mark a test as an expected failure with @code{AT_XFAIL_IF} because a 25153feature has not yet been implemented, but to still distinguish between 25154gracefully handling the missing feature and dumping core. A hard 25155failure also inhibits post-test actions in @var{run-if-fail}. 25156 25157If the value of the @var{stdout} or @var{stderr} parameter is one of the 25158literals in the following table, then the test treats the output 25159according to the rules of that literal. Otherwise, the value of the 25160parameter is treated as text that must exactly match the output given by 25161@var{commands} on standard output and standard error (including an empty 25162parameter for no output); any differences are captured in the testsuite 25163log and the test is failed (unless an unexpected exit status of 77 25164skipped the test instead). The difference between @code{AT_CHECK} and 25165@code{AT_CHECK_UNQUOTED} is that only the latter performs shell variable 25166expansion (@samp{$}), command substitution (@samp{`}), and backslash 25167escaping (@samp{\}) on comparison text given in the @var{stdout} and 25168@var{stderr} arguments; if the text includes a trailing newline, this 25169would be the same as if it were specified via an unquoted 25170here-document. (However, there is no difference in the interpretation 25171of @var{commands}). 25172 25173@table @samp 25174@item ignore 25175The content of the output is ignored, but still captured in the test 25176group log (if the testsuite is run with option @option{-v}, the test 25177group log is displayed as the test is run; if the test group later 25178fails, the test group log is also copied into the overall testsuite 25179log). This action is valid for both @var{stdout} and @var{stderr}. 25180 25181@item ignore-nolog 25182The content of the output is ignored, and nothing is captured in the log 25183files. If @var{commands} are likely to produce binary output (including 25184long lines) or large amounts of output, then logging the output can make 25185it harder to locate details related to subsequent tests within the 25186group, and could potentially corrupt terminal display of a user running 25187@command{testsuite -v}. 25188 25189@item stdout 25190For the @var{stdout} parameter, capture the content of standard output 25191to both the file @file{stdout} and the test group log. Subsequent 25192commands in the test group can then post-process the file. This action 25193is often used when it is desired to use @command{grep} to look for a 25194substring in the output, or when the output must be post-processed to 25195normalize error messages into a common form. 25196 25197@item stderr 25198Like @samp{stdout}, except that it only works for the @var{stderr} 25199parameter, and the standard error capture file will be named 25200@file{stderr}. 25201 25202@item stdout-nolog 25203@itemx stderr-nolog 25204Like @samp{stdout} or @samp{stderr}, except that the captured output is 25205not duplicated into the test group log. This action is particularly 25206useful for an intermediate check that produces large amounts of data, 25207which will be followed by another check that filters down to the 25208relevant data, as it makes it easier to locate details in the log. 25209 25210@item expout 25211For the @var{stdout} parameter, compare standard output contents with 25212the previously created file @file{expout}, and list any differences in 25213the testsuite log. 25214 25215@item experr 25216Like @samp{expout}, except that it only works for the @var{stderr} 25217parameter, and the standard error contents are compared with 25218@file{experr}. 25219@end table 25220@end defmac 25221 25222@defmac AT_CHECK_EUNIT (@var{module}, @var{test-spec}, @ovar{erlflags}, @ 25223 @ovar{run-if-fail}, @ovar{run-if-pass}) 25224@atindex{CHECK_EUNIT} 25225Initialize and execute an Erlang module named @var{module} that performs 25226tests following the @var{test-spec} EUnit test specification. 25227@var{test-spec} must be a valid EUnit test specification, as defined in 25228the @uref{http://@/erlang.org/@/doc/@/apps/@/eunit/@/index.html, EUnit 25229Reference Manual}. @var{erlflags} are optional command-line options 25230passed to the Erlang interpreter to execute the test Erlang module. 25231Typically, @var{erlflags} defines at least the paths to directories 25232containing the compiled Erlang modules under test, as @samp{-pa path1 25233path2 ...}. 25234 25235For example, the unit tests associated with Erlang module @samp{testme}, 25236which compiled code is in subdirectory @file{src}, can be performed 25237with: 25238 25239@example 25240AT_CHECK_EUNIT([testme_testsuite], [@{module, testme@}], 25241 [-pa "$@{abs_top_builddir@}/src"]) 25242@end example 25243 25244This macro must be invoked in between @code{AT_SETUP} and @code{AT_CLEANUP}. 25245 25246Variables @code{ERL}, @code{ERLC}, and (optionally) @code{ERLCFLAGS} 25247must be defined as the path of the Erlang interpreter, the path of the 25248Erlang compiler, and the command-line flags to pass to the compiler, 25249respectively. Those variables should be configured in 25250@file{configure.ac} using the @command{AC_ERLANG_PATH_ERL} and 25251@command{AC_ERLANG_PATH_ERLC} macros, and the configured values of those 25252variables are automatically defined in the testsuite. If @code{ERL} or 25253@code{ERLC} is not defined, the test group is skipped. 25254 25255If the EUnit library cannot be found, i.e. if module @code{eunit} cannot 25256be loaded, the test group is skipped. Otherwise, if @var{test-spec} is 25257an invalid EUnit test specification, the test group fails. Otherwise, 25258if the EUnit test passes, shell commands @var{run-if-pass} are executed 25259or, if the EUnit test fails, shell commands @var{run-if-fail} are 25260executed and the test group fails. 25261 25262Only the generated test Erlang module is automatically compiled and 25263executed. If @var{test-spec} involves testing other Erlang modules, 25264e.g. module @samp{testme} in the example above, those modules must be 25265already compiled. 25266 25267If the testsuite is run in verbose mode, with option @option{--verbose}, 25268EUnit is also run in verbose mode to output more details about 25269individual unit tests. 25270@end defmac 25271 25272 25273@node testsuite Invocation 25274@section Running @command{testsuite} Scripts 25275@cindex @command{testsuite} 25276 25277Autotest test suites support the following options: 25278 25279@table @option 25280@item --help 25281@itemx -h 25282Display the list of options and exit successfully. 25283 25284@item --version 25285@itemx -V 25286Display the version of the test suite and exit successfully. 25287 25288@item --directory=@var{dir} 25289@itemx -C @var{dir} 25290Change the current directory to @var{dir} before creating any files. 25291Useful for running the testsuite in a subdirectory from a top-level 25292Makefile. 25293 25294@item --jobs@r{[}=@var{n}@r{]} 25295@itemx -j@ovar{n} 25296Run @var{n} tests in parallel, if possible. If @var{n} is not given, 25297run all given tests in parallel. Note that there should be no space 25298before the argument to @option{-j}, as @option{-j @var{number}} denotes 25299the separate arguments @option{-j} and @option{@var{number}}, see below. 25300 25301In parallel mode, the standard input device of the testsuite script is 25302not available to commands inside a test group. Furthermore, banner 25303lines are not printed, and the summary line for each test group is 25304output after the test group completes. Summary lines may appear 25305unordered. If verbose and trace output are enabled (see below), they 25306may appear intermixed from concurrently running tests. 25307 25308Parallel mode requires the @command{mkfifo} command to work, and will be 25309silently disabled otherwise. 25310 25311@item --clean 25312@itemx -c 25313Remove all the files the test suite might have created and exit. Meant 25314for @code{clean} Make targets. 25315 25316@item --list 25317@itemx -l 25318List all the tests (or only the selection), including their possible 25319keywords. 25320@end table 25321 25322@sp 1 25323 25324By default all tests are performed (or described with @option{--list}) 25325silently in the default environment, but the environment, set of tests, 25326and verbosity level can be tuned: 25327 25328@table @samp 25329@item @var{variable}=@var{value} 25330Set the environment @var{variable} to @var{value}. Use this rather 25331than @samp{FOO=foo ./testsuite} as debugging scripts would then run in a 25332different environment. 25333 25334@cindex @code{AUTOTEST_PATH} 25335The variable @code{AUTOTEST_PATH} specifies the testing path to prepend 25336to @env{PATH}. Relative directory names (not starting with 25337@samp{/}) are considered to be relative to the top level of the 25338package being built. All directories are made absolute, first 25339starting from the top level @emph{build} tree, then from the 25340@emph{source} tree. For instance @samp{./testsuite 25341AUTOTEST_PATH=tests:bin} for a @file{/src/foo-1.0} source package built 25342in @file{/tmp/foo} results in @samp{/tmp/foo/tests:/tmp/foo/bin} and 25343then @samp{/src/foo-1.0/tests:/src/foo-1.0/bin} being prepended to 25344@env{PATH}. 25345 25346@item @var{number} 25347@itemx @var{number}-@var{number} 25348@itemx @var{number}- 25349@itemx -@var{number} 25350Add the corresponding test groups, with obvious semantics, to the 25351selection. 25352 25353@item --keywords=@var{keywords} 25354@itemx -k @var{keywords} 25355Add to the selection the test groups with title or keywords (arguments 25356to @code{AT_SETUP} or @code{AT_KEYWORDS}) that match @emph{all} keywords 25357of the comma separated list @var{keywords}, case-insensitively. Use 25358@samp{!} immediately before the keyword to invert the selection for this 25359keyword. By default, the keywords match whole words; enclose them in 25360@samp{.*} to also match parts of words. 25361 25362For example, running 25363 25364@example 25365@kbd{./testsuite -k 'autoupdate,.*FUNC.*'} 25366@end example 25367 25368@noindent 25369selects all tests tagged @samp{autoupdate} @emph{and} with tags 25370containing @samp{FUNC} (as in @samp{AC_CHECK_FUNC}, @samp{AC_FUNC_ALLOCA}, 25371etc.), while 25372 25373@example 25374@kbd{./testsuite -k '!autoupdate' -k '.*FUNC.*'} 25375@end example 25376 25377@noindent 25378selects all tests not tagged @samp{autoupdate} @emph{or} with tags 25379containing @samp{FUNC}. 25380 25381@item --errexit 25382@itemx -e 25383If any test fails, immediately abort testing. This implies 25384@option{--debug}: post test group clean up, and top-level logging 25385are inhibited. This option is meant for the full test 25386suite, it is not really useful for generated debugging scripts. 25387If the testsuite is run in parallel mode using @option{--jobs}, 25388then concurrently running tests will finish before exiting. 25389 25390@item --verbose 25391@itemx -v 25392Force more verbosity in the detailed output of what is being done. This 25393is the default for debugging scripts. 25394 25395@item --color 25396@itemx --color@r{[}=never@r{|}auto@r{|}always@r{]} 25397Enable colored test results. Without an argument, or with @samp{always}, 25398test results will be colored. With @samp{never}, color mode is turned 25399off. Otherwise, if either the macro @code{AT_COLOR_TESTS} is used by 25400the testsuite author, or the argument @samp{auto} is given, then test 25401results are colored if standard output is connected to a terminal. 25402 25403@item --debug 25404@itemx -d 25405Do not remove the files after a test group was performed---but they are 25406still removed @emph{before}, therefore using this option is sane when 25407running several test groups. Create debugging scripts. Do not 25408overwrite the top-level 25409log (in order to preserve a supposedly existing full log file). This is 25410the default for debugging scripts, but it can also be useful to debug 25411the testsuite itself. 25412 25413@item --recheck 25414Add to the selection all test groups that failed or passed unexpectedly 25415during the last non-debugging test run. 25416 25417@item --trace 25418@itemx -x 25419Trigger shell tracing of the test groups. 25420@end table 25421 25422Besides these options accepted by every Autotest testsuite, the 25423testsuite author might have added package-specific options 25424via the @code{AT_ARG_OPTION} and @code{AT_ARG_OPTION_ARG} macros 25425(@pxref{Writing Testsuites}); refer to @command{testsuite --help} and 25426the package documentation for details. 25427 25428 25429@node Making testsuite Scripts 25430@section Making @command{testsuite} Scripts 25431 25432For putting Autotest into movement, you need some configuration and 25433makefile machinery. We recommend, at least if your package uses deep or 25434shallow hierarchies, that you use @file{tests/} as the name of the 25435directory holding all your tests and their makefile. Here is a 25436check list of things to do. 25437 25438@itemize @minus 25439 25440@item 25441@cindex @file{package.m4} 25442@atindex{PACKAGE_STRING} 25443@atindex{PACKAGE_BUGREPORT} 25444@atindex{PACKAGE_NAME} 25445@atindex{PACKAGE_TARNAME} 25446@atindex{PACKAGE_VERSION} 25447@atindex{PACKAGE_URL} 25448Make sure to create the file @file{package.m4}, which defines the 25449identity of the package. It must define @code{AT_PACKAGE_STRING}, the 25450full signature of the package, and @code{AT_PACKAGE_BUGREPORT}, the 25451address to which bug reports should be sent. For sake of completeness, 25452we suggest that you also define @code{AT_PACKAGE_NAME}, 25453@code{AT_PACKAGE_TARNAME}, @code{AT_PACKAGE_VERSION}, and 25454@code{AT_PACKAGE_URL}. 25455@xref{Initializing configure}, for a description of these variables. 25456Be sure to distribute @file{package.m4} and to put it into the source 25457hierarchy: the test suite ought to be shipped! See below for an example 25458@file{Makefile} excerpt. 25459 25460@item 25461Invoke @code{AC_CONFIG_TESTDIR}. 25462 25463@defmac AC_CONFIG_TESTDIR (@var{directory}, @dvar{test-path, directory}) 25464@acindex{CONFIG_TESTDIR} 25465An Autotest test suite is to be configured in @var{directory}. This 25466macro causes @file{@var{directory}/atconfig} to be created by 25467@command{config.status} and sets the default @code{AUTOTEST_PATH} to 25468@var{test-path} (@pxref{testsuite Invocation}). 25469@end defmac 25470 25471@item 25472Still within @file{configure.ac}, as appropriate, ensure that some 25473@code{AC_CONFIG_FILES} command includes substitution for 25474@file{tests/atlocal}. 25475 25476@item 25477The appropriate @file{Makefile} should be modified so the validation in 25478your package is triggered by @samp{make check}. An example is provided 25479below. 25480@end itemize 25481 25482With Automake, here is a minimal example for inclusion in 25483@file{tests/Makefile.am}, in order to link @samp{make check} with a 25484validation suite. 25485 25486@example 25487# The `:;' works around a Bash 3.2 bug when the output is not writable. 25488$(srcdir)/package.m4: $(top_srcdir)/configure.ac 25489 :;@{ \ 25490 echo '# Signature of the current package.' && \ 25491 echo 'm4_define([AT_PACKAGE_NAME],' && \ 25492 echo ' [$(PACKAGE_NAME)])' && \ 25493 echo 'm4_define([AT_PACKAGE_TARNAME],' && \ 25494 echo ' [$(PACKAGE_TARNAME)])' && \ 25495 echo 'm4_define([AT_PACKAGE_VERSION],' && \ 25496 echo ' [$(PACKAGE_VERSION)])' && \ 25497 echo 'm4_define([AT_PACKAGE_STRING],' && \ 25498 echo ' [$(PACKAGE_STRING)])' && \ 25499 echo 'm4_define([AT_PACKAGE_BUGREPORT],' && \ 25500 echo ' [$(PACKAGE_BUGREPORT)])'; \ 25501 echo 'm4_define([AT_PACKAGE_URL],' && \ 25502 echo ' [$(PACKAGE_URL)])'; \ 25503 @} >'$(srcdir)/package.m4' 25504 25505EXTRA_DIST = testsuite.at $(srcdir)/package.m4 $(TESTSUITE) atlocal.in 25506TESTSUITE = $(srcdir)/testsuite 25507 25508check-local: atconfig atlocal $(TESTSUITE) 25509 $(SHELL) '$(TESTSUITE)' $(TESTSUITEFLAGS) 25510 25511installcheck-local: atconfig atlocal $(TESTSUITE) 25512 $(SHELL) '$(TESTSUITE)' AUTOTEST_PATH='$(bindir)' \ 25513 $(TESTSUITEFLAGS) 25514 25515clean-local: 25516 test ! -f '$(TESTSUITE)' || \ 25517 $(SHELL) '$(TESTSUITE)' --clean 25518 25519AUTOM4TE = $(SHELL) $(srcdir)/build-aux/missing --run autom4te 25520AUTOTEST = $(AUTOM4TE) --language=autotest 25521$(TESTSUITE): $(srcdir)/testsuite.at $(srcdir)/package.m4 25522 $(AUTOTEST) -I '$(srcdir)' -o $@@.tmp $@@.at 25523 mv $@@.tmp $@@ 25524@end example 25525 25526Note that the built testsuite is distributed; this is necessary because 25527users might not have Autoconf installed, and thus would not be able to 25528rebuild it. Likewise, the use of @file{missing} provides the user with 25529a nicer error message if they modify a source file to the testsuite, and 25530accidentally trigger the rebuild rules. 25531 25532You might want to list explicitly the dependencies, i.e., the list of 25533the files @file{testsuite.at} includes. 25534 25535If you don't use Automake, you should include the above example in 25536@file{tests/@/Makefile.in}, along with additional lines inspired from 25537the following: 25538 25539@example 25540subdir = tests 25541PACKAGE_NAME = @@PACKAGE_NAME@@ 25542PACKAGE_TARNAME = @@PACKAGE_TARNAME@@ 25543PACKAGE_VERSION = @@PACKAGE_VERSION@@ 25544PACKAGE_STRING = @@PACKAGE_STRING@@ 25545PACKAGE_BUGREPORT = @@PACKAGE_BUGREPORT@@ 25546PACKAGE_URL = @@PACKAGE_URL@@ 25547 25548atconfig: $(top_builddir)/config.status 25549 cd $(top_builddir) && \ 25550 $(SHELL) ./config.status $(subdir)/$@@ 25551 25552atlocal: $(srcdir)/atlocal.in $(top_builddir)/config.status 25553 cd $(top_builddir) && \ 25554 $(SHELL) ./config.status $(subdir)/$@@ 25555@end example 25556 25557@noindent 25558and manage to have @code{$(EXTRA_DIST)} distributed. You will also want 25559to distribute the file @file{build-aux/@/missing} from the Automake 25560project; a copy of this file resides in the Autoconf source tree. 25561 25562With all this in place, and if you have not initialized @samp{TESTSUITEFLAGS} 25563within your makefile, you can fine-tune test suite execution with this 25564variable, for example: 25565 25566@example 25567make check TESTSUITEFLAGS='-v -d -x 75 -k AC_PROG_CC CFLAGS=-g' 25568@end example 25569 25570 25571 25572@c =============================== Frequent Autoconf Questions, with answers 25573 25574@node FAQ 25575@chapter Frequent Autoconf Questions, with answers 25576 25577Several questions about Autoconf come up occasionally. Here some of them 25578are addressed. 25579 25580@menu 25581* Distributing:: Distributing @command{configure} scripts 25582* Why GNU M4:: Why not use the standard M4? 25583* Bootstrapping:: Autoconf and GNU M4 require each other? 25584* Why Not Imake:: Why GNU uses @command{configure} instead of Imake 25585* Defining Directories:: Passing @code{datadir} to program 25586* Autom4te Cache:: What is it? Can I remove it? 25587* Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree 25588* Expanded Before Required:: Expanded Before Required 25589* Debugging:: Debugging @command{configure} scripts 25590@end menu 25591 25592@node Distributing 25593@section Distributing @command{configure} Scripts 25594@cindex License 25595 25596@display 25597What are the restrictions on distributing @command{configure} 25598scripts that Autoconf generates? How does that affect my 25599programs that use them? 25600@end display 25601 25602There are no restrictions on how the configuration scripts that Autoconf 25603produces may be distributed or used. In Autoconf version 1, they were 25604covered by the GNU General Public License. We still encourage 25605software authors to distribute their work under terms like those of the 25606GPL, but doing so is not required to use Autoconf. 25607 25608Of the other files that might be used with @command{configure}, 25609@file{config.h.in} is under whatever copyright you use for your 25610@file{configure.ac}. @file{config.sub} and @file{config.guess} have an 25611exception to the GPL when they are used with an Autoconf-generated 25612@command{configure} script, which permits you to distribute them under the 25613same terms as the rest of your package. @file{install-sh} is from the X 25614Consortium and is not copyrighted. 25615 25616@node Why GNU M4 25617@section Why Require GNU M4? 25618 25619@display 25620Why does Autoconf require GNU M4? 25621@end display 25622 25623Many M4 implementations have hard-coded limitations on the size and 25624number of macros that Autoconf exceeds. They also lack several 25625builtin macros that it would be difficult to get along without in a 25626sophisticated application like Autoconf, including: 25627 25628@example 25629m4_builtin 25630m4_indir 25631m4_bpatsubst 25632__file__ 25633__line__ 25634@end example 25635 25636Autoconf requires version 1.4.6 or later of GNU M4. 25637 25638Since only software maintainers need to use Autoconf, and since GNU 25639M4 is simple to configure and install, it seems reasonable to require 25640GNU M4 to be installed also. Many maintainers of GNU and 25641other free software already have most of the GNU utilities 25642installed, since they prefer them. 25643 25644@node Bootstrapping 25645@section How Can I Bootstrap? 25646@cindex Bootstrap 25647 25648@display 25649If Autoconf requires GNU M4 and GNU M4 has an Autoconf 25650@command{configure} script, how do I bootstrap? It seems like a chicken 25651and egg problem! 25652@end display 25653 25654This is a misunderstanding. Although GNU M4 does come with a 25655@command{configure} script produced by Autoconf, Autoconf is not required 25656in order to run the script and install GNU M4. Autoconf is only 25657required if you want to change the M4 @command{configure} script, which few 25658people have to do (mainly its maintainer). 25659 25660@node Why Not Imake 25661@section Why Not Imake? 25662@cindex Imake 25663 25664@display 25665Why not use Imake instead of @command{configure} scripts? 25666@end display 25667 25668Several people have written addressing this question, so 25669adaptations of their explanations are included here. 25670 25671The following answer is based on one written by Richard Pixley: 25672 25673@quotation 25674Autoconf generated scripts frequently work on machines that it has 25675never been set up to handle before. That is, it does a good job of 25676inferring a configuration for a new system. Imake cannot do this. 25677 25678Imake uses a common database of host specific data. For X11, this makes 25679sense because the distribution is made as a collection of tools, by one 25680central authority who has control over the database. 25681 25682GNU tools are not released this way. Each GNU tool has a 25683maintainer; these maintainers are scattered across the world. Using a 25684common database would be a maintenance nightmare. Autoconf may appear 25685to be this kind of database, but in fact it is not. Instead of listing 25686host dependencies, it lists program requirements. 25687 25688If you view the GNU suite as a collection of native tools, then the 25689problems are similar. But the GNU development tools can be 25690configured as cross tools in almost any host+target permutation. All of 25691these configurations can be installed concurrently. They can even be 25692configured to share host independent files across hosts. Imake doesn't 25693address these issues. 25694 25695Imake templates are a form of standardization. The GNU coding 25696standards address the same issues without necessarily imposing the same 25697restrictions. 25698@end quotation 25699 25700 25701Here is some further explanation, written by Per Bothner: 25702 25703@quotation 25704One of the advantages of Imake is that it is easy to generate large 25705makefiles using the @samp{#include} and macro mechanisms of @command{cpp}. 25706However, @code{cpp} is not programmable: it has limited conditional 25707facilities, and no looping. And @code{cpp} cannot inspect its 25708environment. 25709 25710All of these problems are solved by using @code{sh} instead of 25711@code{cpp}. The shell is fully programmable, has macro substitution, 25712can execute (or source) other shell scripts, and can inspect its 25713environment. 25714@end quotation 25715 25716 25717Paul Eggert elaborates more: 25718 25719@quotation 25720With Autoconf, installers need not assume that Imake itself is already 25721installed and working well. This may not seem like much of an advantage 25722to people who are accustomed to Imake. But on many hosts Imake is not 25723installed or the default installation is not working well, and requiring 25724Imake to install a package hinders the acceptance of that package on 25725those hosts. For example, the Imake template and configuration files 25726might not be installed properly on a host, or the Imake build procedure 25727might wrongly assume that all source files are in one big directory 25728tree, or the Imake configuration might assume one compiler whereas the 25729package or the installer needs to use another, or there might be a 25730version mismatch between the Imake expected by the package and the Imake 25731supported by the host. These problems are much rarer with Autoconf, 25732where each package comes with its own independent configuration 25733processor. 25734 25735Also, Imake often suffers from unexpected interactions between 25736@command{make} and the installer's C preprocessor. The fundamental problem 25737here is that the C preprocessor was designed to preprocess C programs, 25738not makefiles. This is much less of a problem with Autoconf, 25739which uses the general-purpose preprocessor M4, and where the 25740package's author (rather than the installer) does the preprocessing in a 25741standard way. 25742@end quotation 25743 25744 25745Finally, Mark Eichin notes: 25746 25747@quotation 25748Imake isn't all that extensible, either. In order to add new features to 25749Imake, you need to provide your own project template, and duplicate most 25750of the features of the existing one. This means that for a sophisticated 25751project, using the vendor-provided Imake templates fails to provide any 25752leverage---since they don't cover anything that your own project needs 25753(unless it is an X11 program). 25754 25755On the other side, though: 25756 25757The one advantage that Imake has over @command{configure}: 25758@file{Imakefile} files tend to be much shorter (likewise, less redundant) 25759than @file{Makefile.in} files. There is a fix to this, however---at least 25760for the Kerberos V5 tree, we've modified things to call in common 25761@file{post.in} and @file{pre.in} makefile fragments for the 25762entire tree. This means that a lot of common things don't have to be 25763duplicated, even though they normally are in @command{configure} setups. 25764@end quotation 25765 25766 25767@node Defining Directories 25768@section How Do I @code{#define} Installation Directories? 25769 25770@display 25771My program needs library files, installed in @code{datadir} and 25772similar. If I use 25773 25774@example 25775AC_DEFINE_UNQUOTED([DATADIR], [$datadir], 25776 [Define to the read-only architecture-independent 25777 data directory.]) 25778@end example 25779 25780@noindent 25781I get 25782 25783@example 25784#define DATADIR "$@{prefix@}/share" 25785@end example 25786@end display 25787 25788As already explained, this behavior is on purpose, mandated by the 25789GNU Coding Standards, see @ref{Installation Directory 25790Variables}. There are several means to achieve a similar goal: 25791 25792@itemize @minus 25793@item 25794Do not use @code{AC_DEFINE} but use your makefile to pass the 25795actual value of @code{datadir} via compilation flags. 25796@xref{Installation Directory Variables}, for the details. 25797 25798@item 25799This solution can be simplified when compiling a program: you may either 25800extend the @code{CPPFLAGS}: 25801 25802@example 25803CPPFLAGS = -DDATADIR='"$(datadir)"' @@CPPFLAGS@@ 25804@end example 25805 25806@noindent 25807If you are using Automake, you should use @code{AM_CPPFLAGS} instead: 25808 25809@example 25810AM_CPPFLAGS = -DDATADIR='"$(datadir)"' 25811@end example 25812 25813@noindent 25814Alternatively, create a dedicated header file: 25815 25816@example 25817DISTCLEANFILES = myprog-paths.h 25818myprog-paths.h: Makefile 25819 echo '#define DATADIR "$(datadir)"' >$@@ 25820@end example 25821 25822@noindent 25823The gnulib module @samp{configmake} provides such a header with all the 25824standard directory variables defined, @pxref{configmake,,, gnulib, GNU 25825Gnulib}. 25826 25827@item 25828Use @code{AC_DEFINE} but have @command{configure} compute the literal 25829value of @code{datadir} and others. Many people have wrapped macros to 25830automate this task; for an example, see the macro @code{AC_DEFINE_DIR} from 25831the @uref{http://@/www.gnu.org/@/software/@/autoconf-archive/, Autoconf Macro 25832Archive}. 25833 25834This solution does not conform to the GNU Coding Standards. 25835 25836@item 25837Note that all the previous solutions hard wire the absolute name of 25838these directories in the executables, which is not a good property. You 25839may try to compute the names relative to @code{prefix}, and try to 25840find @code{prefix} at runtime, this way your package is relocatable. 25841@end itemize 25842 25843 25844@node Autom4te Cache 25845@section What is @file{autom4te.cache}? 25846 25847@display 25848What is this directory @file{autom4te.cache}? Can I safely remove it? 25849@end display 25850 25851In the GNU Build System, @file{configure.ac} plays a central 25852role and is read by many tools: @command{autoconf} to create 25853@file{configure}, @command{autoheader} to create @file{config.h.in}, 25854@command{automake} to create @file{Makefile.in}, @command{autoscan} to 25855check the completeness of @file{configure.ac}, @command{autoreconf} to 25856check the GNU Build System components that are used. To 25857``read @file{configure.ac}'' actually means to compile it with M4, 25858which can be a long process for complex @file{configure.ac}. 25859 25860This is why all these tools, instead of running directly M4, invoke 25861@command{autom4te} (@pxref{autom4te Invocation}) which, while answering to 25862a specific demand, stores additional information in 25863@file{autom4te.cache} for future runs. For instance, if you run 25864@command{autoconf}, behind the scenes, @command{autom4te} also 25865stores information for the other tools, so that when you invoke 25866@command{autoheader} or @command{automake} etc., reprocessing 25867@file{configure.ac} is not needed. The speed up is frequently 30%, 25868and is increasing with the size of @file{configure.ac}. 25869 25870But it is and remains being simply a cache: you can safely remove it. 25871 25872@sp 1 25873 25874@display 25875Can I permanently get rid of it? 25876@end display 25877 25878The creation of this cache can be disabled from 25879@file{~/.autom4te.cfg}, see @ref{Customizing autom4te}, for more 25880details. You should be aware that disabling the cache slows down the 25881Autoconf test suite by 40%. The more GNU Build System 25882components are used, the more the cache is useful; for instance 25883running @samp{autoreconf -f} on the Core Utilities is twice slower without 25884the cache @emph{although @option{--force} implies that the cache is 25885not fully exploited}, and eight times slower than without 25886@option{--force}. 25887 25888 25889@node Present But Cannot Be Compiled 25890@section Header Present But Cannot Be Compiled 25891 25892The most important guideline to bear in mind when checking for 25893features is to mimic as much as possible the intended use. 25894Unfortunately, old versions of @code{AC_CHECK_HEADER} and 25895@code{AC_CHECK_HEADERS} failed to follow this idea, and called 25896the preprocessor, instead of the compiler, to check for headers. As a 25897result, incompatibilities between headers went unnoticed during 25898configuration, and maintainers finally had to deal with this issue 25899elsewhere. 25900 25901The transition began with Autoconf 2.56. As of Autoconf 2.64 both 25902checks are performed, and @command{configure} complains loudly if the 25903compiler and the preprocessor do not agree. However, only the compiler 25904result is considered. 25905 25906Consider the following example: 25907 25908@smallexample 25909$ @kbd{cat number.h} 25910typedef int number; 25911$ @kbd{cat pi.h} 25912const number pi = 3; 25913$ @kbd{cat configure.ac} 25914AC_INIT([Example], [1.0], [bug-example@@example.org]) 25915AC_CHECK_HEADERS([pi.h]) 25916$ @kbd{autoconf -Wall} 25917$ @kbd{./configure} 25918checking for gcc... gcc 25919checking for C compiler default output file name... a.out 25920checking whether the C compiler works... yes 25921checking whether we are cross compiling... no 25922checking for suffix of executables... 25923checking for suffix of object files... o 25924checking whether we are using the GNU C compiler... yes 25925checking whether gcc accepts -g... yes 25926checking for gcc option to accept ISO C89... none needed 25927checking how to run the C preprocessor... gcc -E 25928checking for grep that handles long lines and -e... grep 25929checking for egrep... grep -E 25930checking for ANSI C header files... yes 25931checking for sys/types.h... yes 25932checking for sys/stat.h... yes 25933checking for stdlib.h... yes 25934checking for string.h... yes 25935checking for memory.h... yes 25936checking for strings.h... yes 25937checking for inttypes.h... yes 25938checking for stdint.h... yes 25939checking for unistd.h... yes 25940checking pi.h usability... no 25941checking pi.h presence... yes 25942configure: WARNING: pi.h: present but cannot be compiled 25943configure: WARNING: pi.h: check for missing prerequisite headers? 25944configure: WARNING: pi.h: see the Autoconf documentation 25945configure: WARNING: pi.h: section "Present But Cannot Be Compiled" 25946configure: WARNING: pi.h: proceeding with the compiler's result 25947configure: WARNING: ## -------------------------------------- ## 25948configure: WARNING: ## Report this to bug-example@@example.org ## 25949configure: WARNING: ## -------------------------------------- ## 25950checking for pi.h... yes 25951@end smallexample 25952 25953@noindent 25954The proper way the handle this case is using the fourth argument 25955(@pxref{Generic Headers}): 25956 25957@example 25958$ @kbd{cat configure.ac} 25959AC_INIT([Example], [1.0], [bug-example@@example.org]) 25960AC_CHECK_HEADERS([number.h pi.h], [], [], 25961[[#ifdef HAVE_NUMBER_H 25962# include <number.h> 25963#endif 25964]]) 25965$ @kbd{autoconf -Wall} 25966$ @kbd{./configure} 25967checking for gcc... gcc 25968checking for C compiler default output... a.out 25969checking whether the C compiler works... yes 25970checking whether we are cross compiling... no 25971checking for suffix of executables... 25972checking for suffix of object files... o 25973checking whether we are using the GNU C compiler... yes 25974checking whether gcc accepts -g... yes 25975checking for gcc option to accept ANSI C... none needed 25976checking for number.h... yes 25977checking for pi.h... yes 25978@end example 25979 25980See @ref{Particular Headers}, for a list of headers with their 25981prerequisites. 25982 25983@node Expanded Before Required 25984@section Expanded Before Required 25985 25986@cindex expanded before required 25987Older versions of Autoconf silently built files with incorrect ordering 25988between dependent macros if an outer macro first expanded, then later 25989indirectly required, an inner macro. Starting with Autoconf 2.64, this 25990situation no longer generates out-of-order code, but results in 25991duplicate output and a syntax warning: 25992 25993@example 25994$ @kbd{cat configure.ac} 25995@result{}AC_DEFUN([TESTA], [[echo in A 25996@result{}if test -n "$SEEN_A" ; then echo duplicate ; fi 25997@result{}SEEN_A=:]]) 25998@result{}AC_DEFUN([TESTB], [AC_REQUIRE([TESTA])[echo in B 25999@result{}if test -z "$SEEN_A" ; then echo bug ; fi]]) 26000@result{}AC_DEFUN([TESTC], [AC_REQUIRE([TESTB])[echo in C]]) 26001@result{}AC_DEFUN([OUTER], [[echo in OUTER] 26002@result{}TESTA 26003@result{}TESTC]) 26004@result{}AC_INIT 26005@result{}OUTER 26006@result{}AC_OUTPUT 26007$ @kbd{autoconf} 26008@result{}configure.ac:11: warning: AC_REQUIRE: 26009@result{} `TESTA' was expanded before it was required 26010@result{}configure.ac:4: TESTB is expanded from... 26011@result{}configure.ac:6: TESTC is expanded from... 26012@result{}configure.ac:7: OUTER is expanded from... 26013@result{}configure.ac:11: the top level 26014@end example 26015 26016@noindent 26017To avoid this warning, decide what purpose the macro in question serves. 26018If it only needs to be expanded once (for example, if it provides 26019initialization text used by later macros), then the simplest fix is to 26020change the macro to be declared with @code{AC_DEFUN_ONCE} 26021(@pxref{One-Shot Macros}), although this only works in Autoconf 2.64 and 26022newer. A more portable fix is to change all 26023instances of direct calls to instead go through @code{AC_REQUIRE} 26024(@pxref{Prerequisite Macros}). If, instead, the macro is parameterized 26025by arguments or by the current definition of other macros in the m4 26026environment, then the macro should always be directly expanded instead 26027of required. 26028 26029For another case study, consider this example trimmed down from an 26030actual package. Originally, the package contained shell code and 26031multiple macro invocations at the top level of @file{configure.ac}: 26032 26033@example 26034AC_DEFUN([FOO], [AC_COMPILE_IFELSE([@dots{}])]) 26035foobar= 26036AC_PROG_CC 26037FOO 26038@end example 26039 26040@noindent 26041but that was getting complex, so the author wanted to offload some of 26042the text into a new macro in another file included via 26043@file{aclocal.m4}. The na@"ive approach merely wraps the text in a new 26044macro: 26045 26046@example 26047AC_DEFUN([FOO], [AC_COMPILE_IFELSE([@dots{}])]) 26048AC_DEFUN([BAR], [ 26049foobar= 26050AC_PROG_CC 26051FOO 26052]) 26053BAR 26054@end example 26055 26056@noindent 26057With older versions of Autoconf, the setting of @samp{foobar=} occurs 26058before the single compiler check, as the author intended. But with 26059Autoconf 2.64, this issues the ``expanded before it was required'' 26060warning for @code{AC_PROG_CC}, and outputs two copies of the compiler 26061check, one before @samp{foobar=}, and one after. To understand why this 26062is happening, remember that the use of @code{AC_COMPILE_IFELSE} includes 26063a call to @code{AC_REQUIRE([AC_PROG_CC])} under the hood. According to 26064the documented semantics of @code{AC_REQUIRE}, this means that 26065@code{AC_PROG_CC} @emph{must} occur before the body of the outermost 26066@code{AC_DEFUN}, which in this case is @code{BAR}, thus preceding the 26067use of @samp{foobar=}. The older versions of Autoconf were broken with 26068regards to the rules of @code{AC_REQUIRE}, which explains why the code 26069changed from one over to two copies of @code{AC_PROG_CC} when upgrading 26070autoconf. In other words, the author was unknowingly relying on a bug 26071exploit to get the desired results, and that exploit broke once the bug 26072was fixed. 26073 26074So, what recourse does the author have, to restore their intended 26075semantics of setting @samp{foobar=} prior to a single compiler check, 26076regardless of whether Autoconf 2.63 or 2.64 is used? One idea is to 26077remember that only @code{AC_DEFUN} is impacted by @code{AC_REQUIRE}; 26078there is always the possibility of using the lower-level 26079@code{m4_define}: 26080 26081@example 26082AC_DEFUN([FOO], [AC_COMPILE_IFELSE([@dots{}])]) 26083m4_define([BAR], [ 26084foobar= 26085AC_PROG_CC 26086FOO 26087]) 26088BAR 26089@end example 26090 26091@noindent 26092This works great if everything is in the same file. However, it does 26093not help in the case where the author wants to have @command{aclocal} 26094find the definition of @code{BAR} from its own file, since 26095@command{aclocal} requires the use of @code{AC_DEFUN}. In this case, a 26096better fix is to recognize that if @code{BAR} also uses 26097@code{AC_REQUIRE}, then there will no longer be direct expansion prior 26098to a subsequent require. Then, by creating yet another helper macro, 26099the author can once again guarantee a single invocation of 26100@code{AC_PROG_CC}, which will still occur after @code{foobar=}. The 26101author can also use @code{AC_BEFORE} to make sure no other macro 26102appearing before @code{BAR} has triggered an unwanted expansion of 26103@code{AC_PROG_CC}. 26104 26105@example 26106AC_DEFUN([FOO], [AC_COMPILE_IFELSE([@dots{}])]) 26107AC_DEFUN([BEFORE_CC], [ 26108foobar= 26109]) 26110AC_DEFUN([BAR], [ 26111AC_BEFORE([$0], [AC_PROG_CC])dnl 26112AC_REQUIRE([BEFORE_CC])dnl 26113AC_REQUIRE([AC_PROG_CC])dnl 26114FOO 26115]) 26116BAR 26117@end example 26118 26119 26120@node Debugging 26121@section Debugging @command{configure} scripts 26122 26123While in general, @command{configure} scripts generated by Autoconf 26124strive to be fairly portable to various systems, compilers, shells, and 26125other tools, it may still be necessary to debug a failing test, broken 26126script or makefile, or fix or override an incomplete, faulty, or erroneous 26127test, especially during macro development. Failures can occur at all levels, 26128in M4 syntax or semantics, shell script issues, or due to bugs in the 26129test or the tools invoked by @command{configure}. Together with the 26130rather arcane error message that @command{m4} and @command{make} may 26131produce when their input contains syntax errors, this can make debugging 26132rather painful. 26133 26134Nevertheless, here is a list of hints and strategies that may help: 26135 26136@itemize 26137@item 26138When @command{autoconf} fails, common causes for error include: 26139 26140@itemize 26141@item 26142mismatched or unbalanced parentheses or braces (@pxref{Balancing 26143Parentheses}), 26144 26145@item under- or overquoted macro arguments (@pxref{Autoconf 26146Language}, @pxref{Quoting and Parameters}, @pxref{Quotation and Nested 26147Macros}), 26148 26149@item spaces between macro name and opening parenthesis (@pxref{Autoconf 26150Language}). 26151@end itemize 26152 26153Typically, it helps to go back to the last working version of the input 26154and compare the differences for each of these errors. Another 26155possibility is to sprinkle pairs of @code{m4_traceon} and 26156@code{m4_traceoff} judiciously in the code, either without a parameter 26157or listing some macro names and watch @command{m4} expand its input 26158verbosely (@pxref{Debugging via autom4te}). 26159 26160@item 26161Sometimes @command{autoconf} succeeds but the generated 26162@command{configure} script has invalid shell syntax. You can detect this 26163case by running @samp{bash -n configure} or @samp{sh -n configure}. 26164If this command fails, the same tips apply, as if @command{autoconf} had 26165failed. 26166 26167@item 26168Debugging @command{configure} script execution may be done by sprinkling 26169pairs of @code{set -x} and @code{set +x} into the shell script before 26170and after the region that contains a bug. Running the whole script with 26171@samp{@var{shell} -vx ./configure 2>&1 | tee @var{log-file}} with a decent 26172@var{shell} may work, but produces lots of output. Here, it can help to 26173search for markers like @samp{checking for} a particular test in the 26174@var{log-file}. 26175 26176@item 26177Alternatively, you might use a shell with debugging capabilities like 26178@uref{http://bashdb.sourceforge.net/, bashdb}. 26179 26180@item 26181When @command{configure} tests produce invalid results for your system, 26182it may be necessary to override them: 26183 26184@itemize 26185@item 26186For programs, tools or libraries variables, preprocessor, compiler, or 26187linker flags, it is often sufficient to override them at @command{make} 26188run time with some care (@pxref{Macros and Submakes}). Since this 26189normally won't cause @command{configure} to be run again with these 26190changed settings, it may fail if the changed variable would have caused 26191different test results from @command{configure}, so this may work only 26192for simple differences. 26193 26194@item 26195Most tests which produce their result in a substituted variable allow to 26196override the test by setting the variable on the @command{configure} 26197command line (@pxref{Compilers and Options}, @pxref{Defining Variables}, 26198@pxref{Particular Systems}). 26199 26200@item 26201Many tests store their result in a cache variable (@pxref{Caching 26202Results}). This lets you override them either on the 26203@command{configure} command line as above, or through a primed cache or 26204site file (@pxref{Cache Files}, @pxref{Site Defaults}). The name of a 26205cache variable is documented with a test macro or may be inferred from 26206@ref{Cache Variable Names}; the precise semantics of undocumented 26207variables are often internal details, subject to change. 26208@end itemize 26209 26210@item 26211Alternatively, @command{configure} may produce invalid results because 26212of uncaught programming errors, in your package or in an upstream 26213library package. For example, when @code{AC_CHECK_LIB} fails to find a 26214library with a specified function, always check @file{config.log}. This 26215will reveal the exact error that produced the failing result: the 26216library linked by @code{AC_CHECK_LIB} probably has a fatal bug. 26217@end itemize 26218 26219Conversely, as macro author, you can make it easier for users of your 26220macro: 26221 26222@itemize 26223@item 26224by minimizing dependencies between tests and between test results as far 26225as possible, 26226 26227@item 26228by using @command{make} variables to factorize and allow 26229override of settings at @command{make} run time, 26230 26231@item 26232by honoring the GNU Coding Standards and not overriding flags 26233reserved for the user except temporarily during @command{configure} 26234tests, 26235 26236@item 26237by not requiring users of your macro to use the cache variables. 26238Instead, expose the result of the test via @var{run-if-true} and 26239@var{run-if-false} parameters. If the result is not a boolean, 26240then provide it through documented shell variables. 26241@end itemize 26242 26243 26244@c ===================================================== History of Autoconf. 26245 26246@node History 26247@chapter History of Autoconf 26248@cindex History of autoconf 26249 26250@emph{This chapter was written by the original author, David MacKenzie.} 26251 26252You may be wondering, Why was Autoconf originally written? How did it 26253get into its present form? (Why does it look like gorilla spit?) If 26254you're not wondering, then this chapter contains no information useful 26255to you, and you might as well skip it. If you @emph{are} wondering, 26256then let there be light@enddots{} 26257 26258@menu 26259* Genesis:: Prehistory and naming of @command{configure} 26260* Exodus:: The plagues of M4 and Perl 26261* Leviticus:: The priestly code of portability arrives 26262* Numbers:: Growth and contributors 26263* Deuteronomy:: Approaching the promises of easy configuration 26264@end menu 26265 26266@node Genesis 26267@section Genesis 26268 26269In June 1991 I was maintaining many of the GNU utilities for the 26270Free Software Foundation. As they were ported to more platforms and 26271more programs were added, the number of @option{-D} options that users 26272had to select in the makefile (around 20) became burdensome. 26273Especially for me---I had to test each new release on a bunch of 26274different systems. So I wrote a little shell script to guess some of 26275the correct settings for the fileutils package, and released it as part 26276of fileutils 2.0. That @command{configure} script worked well enough that 26277the next month I adapted it (by hand) to create similar @command{configure} 26278scripts for several other GNU utilities packages. Brian Berliner 26279also adapted one of my scripts for his CVS revision control system. 26280 26281Later that summer, I learned that Richard Stallman and Richard Pixley 26282were developing similar scripts to use in the GNU compiler tools; 26283so I adapted my @command{configure} scripts to support their evolving 26284interface: using the file name @file{Makefile.in} as the templates; 26285adding @samp{+srcdir}, the first option (of many); and creating 26286@file{config.status} files. 26287 26288@node Exodus 26289@section Exodus 26290 26291As I got feedback from users, I incorporated many improvements, using 26292Emacs to search and replace, cut and paste, similar changes in each of 26293the scripts. As I adapted more GNU utilities packages to use 26294@command{configure} scripts, updating them all by hand became impractical. 26295Rich Murphey, the maintainer of the GNU graphics utilities, sent me 26296mail saying that the @command{configure} scripts were great, and asking if 26297I had a tool for generating them that I could send him. No, I thought, 26298but I should! So I started to work out how to generate them. And the 26299journey from the slavery of hand-written @command{configure} scripts to the 26300abundance and ease of Autoconf began. 26301 26302Cygnus @command{configure}, which was being developed at around that time, 26303is table driven; it is meant to deal mainly with a discrete number of 26304system types with a small number of mainly unguessable features (such as 26305details of the object file format). The automatic configuration system 26306that Brian Fox had developed for Bash takes a similar approach. For 26307general use, it seems to me a hopeless cause to try to maintain an 26308up-to-date database of which features each variant of each operating 26309system has. It's easier and more reliable to check for most features on 26310the fly---especially on hybrid systems that people have hacked on 26311locally or that have patches from vendors installed. 26312 26313I considered using an architecture similar to that of Cygnus 26314@command{configure}, where there is a single @command{configure} script that 26315reads pieces of @file{configure.in} when run. But I didn't want to have 26316to distribute all of the feature tests with every package, so I settled 26317on having a different @command{configure} made from each 26318@file{configure.in} by a preprocessor. That approach also offered more 26319control and flexibility. 26320 26321I looked briefly into using the Metaconfig package, by Larry Wall, 26322Harlan Stenn, and Raphael Manfredi, but I decided not to for several 26323reasons. The @command{Configure} scripts it produces are interactive, 26324which I find quite inconvenient; I didn't like the ways it checked for 26325some features (such as library functions); I didn't know that it was 26326still being maintained, and the @command{Configure} scripts I had 26327seen didn't work on many modern systems (such as System V R4 and NeXT); 26328it wasn't flexible in what it could do in response to a feature's 26329presence or absence; I found it confusing to learn; and it was too big 26330and complex for my needs (I didn't realize then how much Autoconf would 26331eventually have to grow). 26332 26333I considered using Perl to generate my style of @command{configure} 26334scripts, but decided that M4 was better suited to the job of simple 26335textual substitutions: it gets in the way less, because output is 26336implicit. Plus, everyone already has it. (Initially I didn't rely on 26337the GNU extensions to M4.) Also, some of my friends at the 26338University of Maryland had recently been putting M4 front ends on 26339several programs, including @code{tvtwm}, and I was interested in trying 26340out a new language. 26341 26342@node Leviticus 26343@section Leviticus 26344 26345Since my @command{configure} scripts determine the system's capabilities 26346automatically, with no interactive user intervention, I decided to call 26347the program that generates them Autoconfig. But with a version number 26348tacked on, that name would be too long for old Unix file systems, 26349so I shortened it to Autoconf. 26350 26351In the fall of 1991 I called together a group of fellow questers after 26352the Holy Grail of portability (er, that is, alpha testers) to give me 26353feedback as I encapsulated pieces of my handwritten scripts in M4 macros 26354and continued to add features and improve the techniques used in the 26355checks. Prominent among the testers were Fran@,{c}ois Pinard, who came up 26356with the idea of making an Autoconf shell script to run M4 26357and check for unresolved macro calls; Richard Pixley, who suggested 26358running the compiler instead of searching the file system to find 26359include files and symbols, for more accurate results; Karl Berry, who 26360got Autoconf to configure @TeX{} and added the macro index to the 26361documentation; and Ian Lance Taylor, who added support for creating a C 26362header file as an alternative to putting @option{-D} options in a 26363makefile, so he could use Autoconf for his UUCP package. 26364The alpha testers cheerfully adjusted their files again and again as the 26365names and calling conventions of the Autoconf macros changed from 26366release to release. They all contributed many specific checks, great 26367ideas, and bug fixes. 26368 26369@node Numbers 26370@section Numbers 26371 26372In July 1992, after months of alpha testing, I released Autoconf 1.0, 26373and converted many GNU packages to use it. I was surprised by how 26374positive the reaction to it was. More people started using it than I 26375could keep track of, including people working on software that wasn't 26376part of the GNU Project (such as TCL, FSP, and Kerberos V5). 26377Autoconf continued to improve rapidly, as many people using the 26378@command{configure} scripts reported problems they encountered. 26379 26380Autoconf turned out to be a good torture test for M4 implementations. 26381Unix M4 started to dump core because of the length of the 26382macros that Autoconf defined, and several bugs showed up in GNU 26383M4 as well. Eventually, we realized that we needed to use some 26384features that only GNU M4 has. 4.3BSD M4, in 26385particular, has an impoverished set of builtin macros; the System V 26386version is better, but still doesn't provide everything we need. 26387 26388More development occurred as people put Autoconf under more stresses 26389(and to uses I hadn't anticipated). Karl Berry added checks for X11. 26390david zuhn contributed C++ support. Fran@,{c}ois Pinard made it diagnose 26391invalid arguments. Jim Blandy bravely coerced it into configuring 26392GNU Emacs, laying the groundwork for several later improvements. 26393Roland McGrath got it to configure the GNU C Library, wrote the 26394@command{autoheader} script to automate the creation of C header file 26395templates, and added a @option{--verbose} option to @command{configure}. 26396Noah Friedman added the @option{--autoconf-dir} option and 26397@code{AC_MACRODIR} environment variable. (He also coined the term 26398@dfn{autoconfiscate} to mean ``adapt a software package to use 26399Autoconf''.) Roland and Noah improved the quoting protection in 26400@code{AC_DEFINE} and fixed many bugs, especially when I got sick of 26401dealing with portability problems from February through June, 1993. 26402 26403@node Deuteronomy 26404@section Deuteronomy 26405 26406A long wish list for major features had accumulated, and the effect of 26407several years of patching by various people had left some residual 26408cruft. In April 1994, while working for Cygnus Support, I began a major 26409revision of Autoconf. I added most of the features of the Cygnus 26410@command{configure} that Autoconf had lacked, largely by adapting the 26411relevant parts of Cygnus @command{configure} with the help of david zuhn 26412and Ken Raeburn. These features include support for using 26413@file{config.sub}, @file{config.guess}, @option{--host}, and 26414@option{--target}; making links to files; and running @command{configure} 26415scripts in subdirectories. Adding these features enabled Ken to convert 26416GNU @code{as}, and Rob Savoye to convert DejaGNU, to using 26417Autoconf. 26418 26419I added more features in response to other peoples' requests. Many 26420people had asked for @command{configure} scripts to share the results of 26421the checks between runs, because (particularly when configuring a large 26422source tree, like Cygnus does) they were frustratingly slow. Mike 26423Haertel suggested adding site-specific initialization scripts. People 26424distributing software that had to unpack on MS-DOS asked for a way to 26425override the @file{.in} extension on the file names, which produced file 26426names like @file{config.h.in} containing two dots. Jim Avera did an 26427extensive examination of the problems with quoting in @code{AC_DEFINE} 26428and @code{AC_SUBST}; his insights led to significant improvements. 26429Richard Stallman asked that compiler output be sent to @file{config.log} 26430instead of @file{/dev/null}, to help people debug the Emacs 26431@command{configure} script. 26432 26433I made some other changes because of my dissatisfaction with the quality 26434of the program. I made the messages showing results of the checks less 26435ambiguous, always printing a result. I regularized the names of the 26436macros and cleaned up coding style inconsistencies. I added some 26437auxiliary utilities that I had developed to help convert source code 26438packages to use Autoconf. With the help of Fran@,{c}ois Pinard, I made 26439the macros not interrupt each others' messages. (That feature revealed 26440some performance bottlenecks in GNU M4, which he hastily 26441corrected!) I reorganized the documentation around problems people want 26442to solve. And I began a test suite, because experience had shown that 26443Autoconf has a pronounced tendency to regress when we change it. 26444 26445Again, several alpha testers gave invaluable feedback, especially 26446Fran@,{c}ois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn, 26447and Mark Eichin. 26448 26449Finally, version 2.0 was ready. And there was much rejoicing. (And I 26450have free time again. I think. Yeah, right.) 26451 26452 26453@c ========================================================== Appendices 26454 26455 26456@node GNU Free Documentation License 26457@appendix GNU Free Documentation License 26458 26459@include fdl.texi 26460 26461@node Indices 26462@appendix Indices 26463 26464@menu 26465* Environment Variable Index:: Index of environment variables used 26466* Output Variable Index:: Index of variables set in output files 26467* Preprocessor Symbol Index:: Index of C preprocessor symbols defined 26468* Cache Variable Index:: Index of documented cache variables 26469* Autoconf Macro Index:: Index of Autoconf macros 26470* M4 Macro Index:: Index of M4, M4sugar, and M4sh macros 26471* Autotest Macro Index:: Index of Autotest macros 26472* Program & Function Index:: Index of those with portability problems 26473* Concept Index:: General index 26474@end menu 26475 26476@node Environment Variable Index 26477@appendixsec Environment Variable Index 26478 26479This is an alphabetical list of the environment variables that might 26480influence Autoconf checks. 26481 26482@printindex ev 26483 26484@node Output Variable Index 26485@appendixsec Output Variable Index 26486 26487This is an alphabetical list of the variables that Autoconf can 26488substitute into files that it creates, typically one or more 26489makefiles. @xref{Setting Output Variables}, for more information 26490on how this is done. 26491 26492@printindex ov 26493 26494@node Preprocessor Symbol Index 26495@appendixsec Preprocessor Symbol Index 26496 26497This is an alphabetical list of the C preprocessor symbols that the 26498Autoconf macros define. To work with Autoconf, C source code needs to 26499use these names in @code{#if} or @code{#ifdef} directives. 26500 26501@printindex cv 26502 26503@node Cache Variable Index 26504@appendixsec Cache Variable Index 26505 26506This is an alphabetical list of documented cache variables used 26507by macros defined in Autoconf. Autoconf macros may use additional cache 26508variables internally. 26509@ifset shortindexflag 26510To make the list easier to use, the variables are listed without their 26511preceding @samp{ac_cv_}. 26512@end ifset 26513 26514@printindex CA 26515 26516@node Autoconf Macro Index 26517@appendixsec Autoconf Macro Index 26518 26519This is an alphabetical list of the Autoconf macros. 26520@ifset shortindexflag 26521To make the list easier to use, the macros are listed without their 26522preceding @samp{AC_}. 26523@end ifset 26524 26525@printindex AC 26526 26527@node M4 Macro Index 26528@appendixsec M4 Macro Index 26529 26530This is an alphabetical list of the M4, M4sugar, and M4sh macros. 26531@ifset shortindexflag 26532To make the list easier to use, the macros are listed without their 26533preceding @samp{m4_} or @samp{AS_}. The prefix is @samp{m4_} for 26534all-lowercase macro names and @samp{AS_} for all-uppercase macro 26535names. 26536@end ifset 26537 26538@printindex MS 26539 26540@node Autotest Macro Index 26541@appendixsec Autotest Macro Index 26542 26543This is an alphabetical list of the Autotest macros. 26544@ifset shortindexflag 26545To make the list easier to use, the macros are listed without their 26546preceding @samp{AT_}. 26547@end ifset 26548 26549@printindex AT 26550 26551@node Program & Function Index 26552@appendixsec Program and Function Index 26553 26554This is an alphabetical list of the programs and functions whose 26555portability is discussed in this document. 26556 26557@printindex pr 26558 26559@node Concept Index 26560@appendixsec Concept Index 26561 26562This is an alphabetical list of the files, tools, and concepts 26563introduced in this document. 26564 26565@printindex cp 26566 26567@bye 26568 26569@c LocalWords: texinfo setfilename autoconf texi settitle setchapternewpage 26570@c LocalWords: setcontentsaftertitlepage finalout ARG ovar varname dvar acx 26571@c LocalWords: makeinfo dvi defcodeindex ev ov CPP cv Autotest mv defindex fn 26572@c LocalWords: shortindexflag iftex ifset acindex ACindex ifclear ahindex fu 26573@c LocalWords: asindex MSindex atindex ATindex auindex hdrindex prindex FIXME 26574@c LocalWords: msindex alloca fnindex Aaarg indices FSF's dircategory ifnames 26575@c LocalWords: direntry autoscan autoreconf autoheader autoupdate config FDs 26576@c LocalWords: testsuite titlepage Elliston Demaille vskip filll ifnottex hmm 26577@c LocalWords: insertcopying Autoconf's detailmenu Automake Libtool Posix ois 26578@c LocalWords: Systemology Checkpointing Changequote INTERCAL changequote dfn 26579@c LocalWords: Quadrigraphs builtins Shellology acconfig Bugward LIBOBJ Imake 26580@c LocalWords: LIBOBJS IFELSE cindex flushright Pinard Metaconfig uref Simons 26581@c LocalWords: distclean uninstall noindent versioning Tromey dir 26582@c LocalWords: SAMS samp aclocal acsite underquoted emph itemx prepend SUBST 26583@c LocalWords: evindex automake Gettext autopoint gettext symlink libtoolize 26584@c LocalWords: defmac INIT tarname ovindex cvindex BUGREPORT PREREQ asis PROG 26585@c LocalWords: SRCDIR srcdir globbing afterwards cmds foos fooo foooo init cd 26586@c LocalWords: builddir timestamp src Imakefile chmod defvar CFLAGS CPPFLAGS 26587@c LocalWords: CXXFLAGS DEFS DHAVE defvarx FCFLAGS FFLAGS LDFLAGS bindir GCC 26588@c LocalWords: datadir datarootdir docdir dvidir htmldir libdir ifnothtml kbd 26589@c LocalWords: includedir infodir libexecdir localedir localstatedir mandir 26590@c LocalWords: oldincludedir pdfdir PDF psdir PostScript sbindir sysconfdir 26591@c LocalWords: sharedstatedir DDATADIR sed tmp pkgdatadir VPATH conf unistd 26592@c LocalWords: undef endif builtin FUNCS ifndef STACKSEG getb GETB YMP fubar 26593@c LocalWords: PRE dest SUBDIRS subdirs fi struct STDC stdlib stddef INTTYPES 26594@c LocalWords: inttypes STDINT stdint AWK AIX Solaris NeXT env EGREP FGREP yy 26595@c LocalWords: LEXLIB YYTEXT lfl nonportable Automake's LN RANLIB byacc INETD 26596@c LocalWords: inetd prog PROGS progs ranlib lmp lXt lX nsl gethostbyname UX 26597@c LocalWords: NextStep isinf isnan glibc IRIX sunmath lm lsunmath pre sizeof 26598@c LocalWords: ld inline malloc putenv setenv FreeBSD realloc SunOS MinGW 26599@c LocalWords: snprintf vsnprintf sprintf vsprintf sscanf gcc strerror ifdef 26600@c LocalWords: strnlen sysconf PAGESIZE unsetenv va fallback memcpy dst FUNC 26601@c LocalWords: PowerPC GNUC libPW pragma Olibcalls CHOWN chown CLOSEDIR VFORK 26602@c LocalWords: closedir FNMATCH fnmatch vfork FSEEKO LARGEFILE fseeko SVR sc 26603@c LocalWords: largefile GETGROUPS getgroups GETLOADAVG DGUX UMAX NLIST KMEM 26604@c LocalWords: SETGID getloadavg nlist GETMNTENT irix 26605@c LocalWords: getmntent UnixWare GETPGRP getpgid getpgrp Posix's pid LSTAT 26606@c LocalWords: lstat rpl MEMCMP memcmp OpenStep MBRTOWC mbrtowc MKTIME mktime 26607@c LocalWords: localtime MMAP mmap OBSTACK obstack obstacks ARGTYPES timeval 26608@c LocalWords: SETPGRP setpgrp defmacx Hurd SETVBUF setvbuf STRCOLL strcoll 26609@c LocalWords: STRTOD strtod DECL STRFTIME strftime SCO UTIME utime VPRINTF 26610@c LocalWords: DOPRNT vprintf doprnt sp unfixable LIBSOURCE LIBSOURCES Eggert 26611@c LocalWords: linux netinet ia Tru XFree DIRENT NDIR dirent ndir multitable 26612@c LocalWords: NAMLEN strlen namlen MKDEV SYSMACROS makedev RESOLV resolv DNS 26613@c LocalWords: inet structs NAMESER arpa NETDB netdb UTekV UTS GCC's kB 26614@c LocalWords: STDBOOL BOOL stdbool cplusplus bool Bool stdarg tm 26615@c LocalWords: ctype strchr strrchr rindex bcopy memmove memchr WEXITSTATUS 26616@c LocalWords: WIFEXITED TIOCGWINSZ GWINSZ termios preprocess preprocessable 26617@c LocalWords: DECLS strdup calloc BLKSIZE blksize RDEV rdev TZNAME tzname pw 26618@c LocalWords: passwd gecos pwd MBSTATE mbstate wchar RETSIGTYPE hup UID uid 26619@c LocalWords: gid ptrdiff uintmax EXEEXT OBJEXT Ae conftest AXP str 26620@c LocalWords: ALIGNOF WERROR Werror cpp HP's WorkShop egcs un fied stdc CXX 26621@c LocalWords: varargs BIGENDIAN Endianness SPARC endianness grep'ed CONST FC 26622@c LocalWords: const STRINGIZE stringizing PARAMS unprotoize protos KCC cxx 26623@c LocalWords: xlC aCC CXXCPP FREEFORM xlf FLIBS FCLIBS ish SRCEXT XTRA LFS 26624@c LocalWords: ISC lcposix MINIX Minix conditionalized inlines hw dD confdefs 26625@c LocalWords: fputs stdout PREPROC ar UFS HFS QNX realtime fstype STATVFS se 26626@c LocalWords: statvfs STATFS statfs func machfile hdr lelf raboof DEFUN GTK 26627@c LocalWords: GTKMM Grmph ified ine defn baz EOF qar Ahhh changecom algol io 26628@c LocalWords: changeword quadrigraphs quadrigraph dnl SGI atoi overquoting 26629@c LocalWords: Aas Wcross sep args namespace undefine bpatsubst popdef dquote 26630@c LocalWords: bregexp Overquote overquotation meisch maisch meische maische 26631@c LocalWords: miscian DIRNAME dirname MKDIR CATFILE XMKMF TRAVOLTA celsius 26632@c LocalWords: EMX emxos Emacsen Korn DYNIX subshell posix Ksh ksh Pdksh Zsh 26633@c LocalWords: pdksh zsh Allbery Lipe Kubota UWS zorglub stderr eval esac lfn 26634@c LocalWords: drivespec Posixy DJGPP doschk prettybird LPT pfew Zsh's yu yaa 26635@c LocalWords: yM uM aM firebird IP subdir misparses ok Unpatched abc bc zA 26636@c LocalWords: CDPATH DUALCASE LINENO prepass Subshells lineno NULLCMD cmp wc 26637@c LocalWords: MAILPATH scanset arg NetBSD Almquist printf expr cp 26638@c LocalWords: Oliva awk Aaaaarg cmd regex xfoo GNV OpenVMS VM 26639@c LocalWords: sparc Proulx nbar nfoo maxdepth acdilrtu TWG mc 26640@c LocalWords: mkdir exe uname OpenBSD Fileutils mktemp umask TMPDIR guid os 26641@c LocalWords: fooXXXXXX Unicos utimes hpux hppa unescaped 26642@c LocalWords: pmake DOS's gmake ifoo DESTDIR autoconfiscated pc coff mips gg 26643@c LocalWords: dec ultrix cpu wildcards rpcc rdtsc powerpc readline 26644@c LocalWords: withval vxworks gless localcache usr LOFF loff CYGWIN Cygwin 26645@c LocalWords: cygwin SIGLIST siglist SYSNDIR SYSDIR ptx lseq rusage elif MSC 26646@c LocalWords: lfoo POUNDBANG lsun NIS getpwnam SYSCALLS RSH INTL lintl aix 26647@c LocalWords: intl lx ldir syslog bsd EPI toolchain netbsd objext de KNR nn 26648@c LocalWords: fication LTLIBOBJS Wdiff TESTDIR atconfig atlocal akim XFAIL 26649@c LocalWords: ChangeLog prepended errexit smallexample TESTSUITEFLAGS GPL er 26650@c LocalWords: installcheck autotest indir Pixley Bothner Eichin Kerberos adl 26651@c LocalWords: DISTCLEANFILES preprocessor's fileutils Stallman Murphey Stenn 26652@c LocalWords: Manfredi Autoconfig TCL FSP david zuhn Blandy MACRODIR Raeburn 26653@c LocalWords: autoconfiscate Savoye Haertel Avera Meyering fdl appendixsec 26654@c LocalWords: printindex american LIBOBJDIR LibdirTest ERLCFLAGS OBJCFLAGS 26655@c LocalWords: VER Gnulib online xyes strcpy TYPEOF typeof OBJC objcc objc ln 26656@c LocalWords: GOBJC OTP ERLC erl valloc decr dumpdef errprint incr 26657@c LocalWords: esyscmd len maketemp pushdef substr syscmd sysval translit txt 26658@c LocalWords: sinclude foreach myvar tolower toupper uniq BASENAME STDIN 26659@c LocalWords: Dynix basename aname cname macroexpands xno xcheck 26660@c LocalWords: LIBREADLINE lreadline lncurses libreadline 26661 26662@c Local Variables: 26663@c fill-column: 72 26664@c ispell-local-dictionary: "american" 26665@c indent-tabs-mode: nil 26666@c whitespace-check-buffer-indent: nil 26667@c End: 26668