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 200 This manual (@value{UPDATED}) is for GNU Autoconf 201 (version @value{VERSION}), 202 a package for creating scripts to configure source code packages using 203 templates and an M4 macro package. 204 205 Copyright @copyright{} 1992-1996, 1998-2012 Free Software Foundation, 206 Inc. 207 208 @quotation 209 Permission is granted to copy, distribute and/or modify this document 210 under the terms of the GNU Free Documentation License, 211 Version 1.3 or any later version published by the Free Software 212 Foundation; with no Invariant Sections, no Front-Cover texts, and 213 no Back-Cover Texts. A copy of the license is included in the section 214 entitled ``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 296 The 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 303 Making @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 311 Writing @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 317 Initialization 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 333 Substitutions 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 341 Configuration 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 347 Existing 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 363 Common Behavior 364 365 * Standard Symbols:: Symbols defined by the macros 366 * Default Includes:: Includes used by the generic macros 367 368 Alternative Programs 369 370 * Particular Programs:: Special handling to find certain programs 371 * Generic Programs:: How to find other programs 372 373 Library 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 379 Header 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 385 Declarations 386 387 * Particular Declarations:: Macros to check for certain declarations 388 * Generic Declarations:: How to find other declarations 389 390 Structures 391 392 * Particular Structures:: Macros to check for certain structure members 393 * Generic Structures:: How to find other structure members 394 395 Types 396 397 * Particular Types:: Special handling to find certain types 398 * Generic Types:: How to find other types 399 400 Compilers 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 412 Writing 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 423 Writing 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 429 Results 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 437 Caching 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 443 Programming 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 450 M4 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 461 Using @command{autom4te} 462 463 * autom4te Invocation:: A GNU M4 wrapper 464 * Customizing autom4te:: Customizing the Autoconf package 465 466 Programming 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 479 Programming 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 486 Writing 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 495 Dependencies 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 501 Portable 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 519 Portable 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 551 Portable 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 562 Integer 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 570 Manual 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 576 Site 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 587 Transforming 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 593 Running @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 606 Obsolete 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 615 Upgrading 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 623 Upgrading 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 631 Generating 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 638 Using an Autotest Test Suite 639 640 * testsuite Scripts:: The concepts of Autotest 641 * Autotest Logs:: Their contents 642 643 Frequent 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 655 History 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 663 Indices 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 685 A physicist, an engineer, and a computer scientist were discussing the 686 nature of God. ``Surely a Physicist,'' said the physicist, ``because 687 early in the Creation, God made Light; and you know, Maxwell's 688 equations, the dual nature of electromagnetic waves, the relativistic 689 consequences@enddots{}'' ``An Engineer!,'' said the engineer, ``because 690 before making Light, God split the Chaos into Land and Water; it takes a 691 hell of an engineer to handle that big amount of mud, and orderly 692 separation of solids from liquids@enddots{}'' The computer scientist 693 shouted: ``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 699 Autoconf is a tool for producing shell scripts that automatically 700 configure software source code packages to adapt to many kinds of 701 Posix-like systems. The configuration scripts produced by Autoconf 702 are independent of Autoconf when they are run, so their users do not 703 need to have Autoconf. 704 705 The configuration scripts produced by Autoconf require no manual user 706 intervention when run; they do not normally even need an argument 707 specifying the system type. Instead, they individually test for the 708 presence 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 710 checking for, so the user doesn't get too bored while waiting for the 711 script to finish.) As a result, they deal well with systems that are 712 hybrids or customized from the more common Posix variants. There is 713 no need to maintain files that list the features supported by each 714 release of each variant of Posix. 715 716 For each software package that Autoconf is used with, it creates a 717 configuration script from a template file that lists the system features 718 that the package needs or can use. After the shell code to recognize 719 and respond to a system feature has been written, Autoconf allows it to 720 be shared by many software packages that can use (or need) that feature. 721 If it later turns out that the shell code needs adjustment for some 722 reason, it needs to be changed in only one place; all of the 723 configuration scripts can be regenerated automatically to take advantage 724 of 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) 728 Those who do not understand Autoconf are condemned to reinvent it, poorly. 729 The primary goal of Autoconf is making the @emph{user's} life easier; 730 making the @emph{maintainer's} life easier is only a secondary goal. 731 Put another way, the primary goal is not to make the generation of 732 @file{configure} automatic for package maintainers (although patches 733 along that front are welcome, since package maintainers form the user 734 base of Autoconf); rather, the goal is to make @file{configure} 735 painless, portable, and predictable for the end user of each 736 @dfn{autoconfiscated} package. And to this degree, Autoconf is highly 737 successful at its goal --- most complaints to the Autoconf list are 738 about difficulties in writing Autoconf input, and not in the behavior of 739 the resulting @file{configure}. Even packages that don't use Autoconf 740 will generally provide a @file{configure} script, and the most common 741 complaint about these alternative home-grown scripts is that they fail 742 to meet one or more of the GNU Coding Standards (@pxref{Configuration, , , 743 standards, The GNU Coding Standards}) that users 744 have come to expect from Autoconf-generated @file{configure} scripts. 745 746 The Metaconfig package is similar in purpose to Autoconf, but the 747 scripts it produces require manual user intervention, which is quite 748 inconvenient when configuring large source trees. Unlike Metaconfig 749 scripts, Autoconf scripts can support cross-compiling, if some care is 750 taken in writing them. 751 752 Autoconf does not solve all problems related to making portable 753 software packages---for a more complete solution, it should be used in 754 concert with other GNU build tools like Automake and 755 Libtool. These other tools take on jobs like the creation of a 756 portable, recursive makefile with all of the standard targets, 757 linking of shared libraries, and so on. @xref{The GNU Build System}, 758 for more information. 759 760 Autoconf imposes some restrictions on the names of macros used with 761 @code{#if} in C programs (@pxref{Preprocessor Symbol Index}). 762 763 Autoconf requires GNU M4 version 1.4.6 or later in order to 764 generate the scripts. It uses features that some versions of M4, 765 including GNU M4 1.3, do not have. Autoconf works better 766 with GNU M4 version 1.4.14 or later, though this is not 767 required. 768 769 @xref{Autoconf 1}, for information about upgrading from version 1. 770 @xref{History}, for the story of Autoconf's development. @xref{FAQ}, 771 for answers to some common questions about Autoconf. 772 773 See the @uref{http://@/www.gnu.org/@/software/@/autoconf/, 774 Autoconf web page} for up-to-date information, details on the mailing 775 lists, pointers to a list of known bugs, etc. 776 777 Mail suggestions to @email{autoconf@@gnu.org, the Autoconf mailing 778 list}. Past suggestions are 779 @uref{http://@/lists.gnu.org/@/archive/@/html/@/autoconf/, archived}. 780 781 Mail bug reports to @email{bug-autoconf@@gnu.org, the 782 Autoconf Bugs mailing list}. Past bug reports are 783 @uref{http://@/lists.gnu.org/@/archive/@/html/@/bug-autoconf/, archived}. 784 785 If possible, first check that your bug is 786 not already solved in current development versions, and that it has not 787 been reported yet. Be sure to include all the needed information and a 788 short @file{configure.ac} that demonstrates the problem. 789 790 Autoconf's development tree is accessible via @command{git}; see the 791 @uref{http://@/savannah.gnu.org/@/projects/@/autoconf/, Autoconf 792 Summary} for details, or view 793 @uref{http://@/git.sv.gnu.org/@/gitweb/@/?p=autoconf.git, the actual 794 repository}. Anonymous CVS access is also available, see 795 @file{README} for more details. Patches relative to the 796 current @command{git} version can be sent for review to the 797 @email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}, with 798 discussion on prior patches 799 @uref{http://@/lists.gnu.org/@/archive/@/html/@/autoconf-@/patches/, 800 archived}; and all commits are posted in the read-only 801 @email{autoconf-commit@@gnu.org, Autoconf Commit mailing list}, which is 802 also @uref{http://@/lists.gnu.org/@/archive/@/html/@/autoconf-commit/, 803 archived}. 804 805 Because of its mission, the Autoconf package itself 806 includes only a set of often-used 807 macros that have already demonstrated their usefulness. Nevertheless, 808 if you wish to share your macros, or find existing ones, see the 809 @uref{http://@/www.gnu.org/@/software/@/autoconf-archive/, Autoconf Macro 810 Archive}, which is kindly run by @email{simons@@cryp.to, 811 Peter 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 820 Autoconf solves an important problem---reliable discovery of 821 system-specific build and runtime information---but this is only one 822 piece of the puzzle for the development of portable software. To this 823 end, the GNU project has developed a suite of integrated 824 utilities to finish the job Autoconf started: the GNU build 825 system, whose most important components are Autoconf, Automake, and 826 Libtool. In this chapter, we introduce you to those tools, point you 827 to sources of more information, and try to convince you to use the 828 entire 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 840 The ubiquity of @command{make} means that a makefile is almost the 841 only viable way to distribute automatic build rules for software, but 842 one quickly runs into its numerous limitations. Its lack of 843 support for automatic dependency tracking, recursive builds in 844 subdirectories, reliable timestamps (e.g., for network file systems), and 845 so on, mean that developers must painfully (and often incorrectly) 846 reinvent the wheel for each project. Portability is non-trivial, thanks 847 to the quirks of @command{make} on many systems. On top of all this is the 848 manual labor required to implement the many standard targets that users 849 have come to expect (@code{make install}, @code{make distclean}, 850 @code{make uninstall}, etc.). Since you are, of course, using Autoconf, 851 you also have to insert repetitive code in your @file{Makefile.in} to 852 recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions 853 provided by @command{configure}. Into this mess steps @dfn{Automake}. 854 @cindex Automake 855 856 Automake allows you to specify your build needs in a @file{Makefile.am} 857 file with a vastly simpler and more powerful syntax than that of a plain 858 makefile, and then generates a portable @file{Makefile.in} for 859 use with Autoconf. For example, the @file{Makefile.am} to build and 860 install a simple ``Hello world'' program might look like: 861 862 @example 863 bin_PROGRAMS = hello 864 hello_SOURCES = hello.c 865 @end example 866 867 @noindent 868 The resulting @file{Makefile.in} (~400 lines) automatically supports all 869 the standard targets, the substitutions provided by Autoconf, automatic 870 dependency tracking, @code{VPATH} building, and so on. @command{make} 871 builds the @code{hello} program, and @code{make install} installs it 872 in @file{/usr/local/bin} (or whatever prefix was given to 873 @command{configure}, if not @file{/usr/local}). 874 875 The benefits of Automake increase for larger packages (especially ones 876 with subdirectories), but even for small programs the added convenience 877 and portability can be substantial. And that's not all@enddots{} 878 879 @node Gnulib 880 @section Gnulib 881 882 GNU software has a well-deserved reputation for running on 883 many different types of systems. While our primary goal is to write 884 software for the GNU system, many users and developers have 885 been introduced to us through the systems that they were already using. 886 887 @cindex Gnulib 888 Gnulib is a central location for common GNU code, intended to 889 be shared among free software packages. Its components are typically 890 shared at the source level, rather than being a library that gets built, 891 installed, and linked against. The idea is to copy files from Gnulib 892 into your own source tree. There is no distribution tarball; developers 893 should just grab source modules from the repository. The source files 894 are available online, under various licenses, mostly GNU 895 GPL or GNU LGPL. 896 897 Gnulib modules typically contain C source code along with Autoconf 898 macros used to configure the source code. For example, the Gnulib 899 @code{stdbool} module implements a @file{stdbool.h} header that nearly 900 conforms to C99, even on old-fashioned hosts that lack @file{stdbool.h}. 901 This module contains a source file for the replacement header, along 902 with an Autoconf macro that arranges to use the replacement header on 903 old-fashioned systems. 904 905 @node Libtool 906 @section Libtool 907 908 Often, one wants to build not only programs, but libraries, so that 909 other programs can benefit from the fruits of your labor. Ideally, one 910 would like to produce @emph{shared} (dynamically linked) libraries, 911 which can be used by multiple programs without duplication on disk or in 912 memory and can be updated independently of the linked programs. 913 Producing shared libraries portably, however, is the stuff of 914 nightmares---each system has its own incompatible tools, compiler flags, 915 and magic incantations. Fortunately, GNU provides a solution: 916 @dfn{Libtool}. 917 @cindex Libtool 918 919 Libtool handles all the requirements of building shared libraries for 920 you, and at this time seems to be the @emph{only} way to do so with any 921 portability. It also handles many other headaches, such as: the 922 interaction of Make rules with the variable suffixes of 923 shared libraries, linking reliably with shared libraries before they are 924 installed by the superuser, and supplying a consistent versioning system 925 (so that different versions of a library can be installed or upgraded 926 without breaking binary compatibility). Although Libtool, like 927 Autoconf, can be used without Automake, it is most simply utilized in 928 conjunction with Automake---there, Libtool is used automatically 929 whenever shared libraries are needed, and you need not know its syntax. 930 931 @node Pointers 932 @section Pointers 933 934 Developers who are used to the simplicity of @command{make} for small 935 projects on a single system might be daunted at the prospect of 936 learning to use Automake and Autoconf. As your software is 937 distributed to more and more users, however, you otherwise 938 quickly find yourself putting lots of effort into reinventing the 939 services that the GNU build tools provide, and making the 940 same mistakes that they once made and overcame. (Besides, since 941 you're already learning Autoconf, Automake is a piece of cake.) 942 943 There are a number of places that you can go to for more information on 944 the GNU build tools. 945 946 @itemize @minus 947 948 @item Web 949 950 The 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 959 information on Automake. 960 961 @item Books 962 963 The book @cite{GNU Autoconf, Automake and 964 Libtool}@footnote{@cite{GNU Autoconf, Automake and Libtool}, 965 by G. V. Vaughan, B. Elliston, T. Tromey, and I. L. Taylor. SAMS (originally 966 New Riders), 2000, ISBN 1578701902.} describes the complete GNU 967 build 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 979 The configuration scripts that Autoconf produces are by convention 980 called @command{configure}. When run, @command{configure} creates several 981 files, replacing configuration parameters in them with appropriate 982 values. The files that @command{configure} creates are: 983 984 @itemize @minus 985 @item 986 one or more @file{Makefile} files, usually one in each subdirectory of the 987 package (@pxref{Makefile Substitutions}); 988 989 @item 990 optionally, a C header file, the name of which is configurable, 991 containing @code{#define} directives (@pxref{Configuration Headers}); 992 993 @item 994 a shell script called @file{config.status} that, when run, recreates 995 the files listed above (@pxref{config.status Invocation}); 996 997 @item 998 an optional shell script normally called @file{config.cache} 999 (created when using @samp{configure --config-cache}) that 1000 saves the results of running many of the tests (@pxref{Cache Files}); 1001 1002 @item 1003 a file called @file{config.log} containing any messages produced by 1004 compilers, to help debugging if @command{configure} makes a mistake. 1005 @end itemize 1006 1007 @cindex @file{configure.in} 1008 @cindex @file{configure.ac} 1009 To create a @command{configure} script with Autoconf, you need to write an 1010 Autoconf input file @file{configure.ac} (or @file{configure.in}) and run 1011 @command{autoconf} on it. If you write your own feature tests to 1012 supplement those that come with Autoconf, you might also write files 1013 called @file{aclocal.m4} and @file{acsite.m4}. If you use a C header 1014 file 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 1018 Here is a diagram showing how the files that can be used in 1019 configuration 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 1022 macro files (by reading @file{autoconf.m4}). 1023 1024 @noindent 1025 Files used in preparing a software package for distribution, when using 1026 just Autoconf: 1027 @example 1028 your source files --> [autoscan*] --> [configure.scan] --> configure.ac 1029 1030 @group 1031 configure.ac --. 1032 | .------> autoconf* -----> configure 1033 [aclocal.m4] --+---+ 1034 | `-----> [autoheader*] --> [config.h.in] 1035 [acsite.m4] ---' 1036 @end group 1037 1038 Makefile.in 1039 @end example 1040 1041 @noindent 1042 Additionally, if you use Automake, the following additional productions 1043 come into play: 1044 1045 @example 1046 @group 1047 [acinclude.m4] --. 1048 | 1049 [local macros] --+--> aclocal* --> aclocal.m4 1050 | 1051 configure.ac ----' 1052 @end group 1053 1054 @group 1055 configure.ac --. 1056 +--> automake* --> Makefile.in 1057 Makefile.am ---' 1058 @end group 1059 @end example 1060 1061 @noindent 1062 Files used in configuring a software package: 1063 @example 1064 @group 1065 .-------------> [config.cache] 1066 configure* ------------+-------------> config.log 1067 | 1068 [config.h.in] -. v .-> [config.h] -. 1069 +--> config.status* -+ +--> make* 1070 Makefile.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 1085 To produce a @command{configure} script for a software package, create a 1086 file called @file{configure.ac} that contains invocations of the 1087 Autoconf macros that test the system features your package needs or can 1088 use. Autoconf macros already exist to check for many features; see 1089 @ref{Existing Tests}, for their descriptions. For most other features, 1090 you can use Autoconf template macros to produce custom checks; see 1091 @ref{Writing Tests}, for information about them. For especially tricky 1092 or specialized features, @file{configure.ac} might need to contain some 1093 hand-crafted shell commands; see @ref{Portable Shell, , Portable Shell 1094 Programming}. The @command{autoscan} program can give you a good start 1095 in writing @file{configure.ac} (@pxref{autoscan Invocation}, for more 1096 information). 1097 1098 Previous versions of Autoconf promoted the name @file{configure.in}, 1099 which is somewhat ambiguous (the tool needed to process this file is not 1100 described by its extension), and introduces a slight confusion with 1101 @file{config.h.in} and so on (for which @samp{.in} means ``to be 1102 processed by @command{configure}''). Using @file{configure.ac} is now 1103 preferred. 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 1114 Just as for any other computer language, in order to properly program 1115 @file{configure.ac} in Autoconf you must understand @emph{what} problem 1116 the language tries to address and @emph{how} it does so. 1117 1118 The problem Autoconf addresses is that the world is a mess. After all, 1119 you are using Autoconf in order to have your package compile easily on 1120 all sorts of different systems, some of them being extremely hostile. 1121 Autoconf itself bears the price for these differences: @command{configure} 1122 must run on all those systems, and thus @command{configure} must limit itself 1123 to their lowest common denominator of features. 1124 1125 Naturally, you might then think of shell scripts; who needs 1126 @command{autoconf}? A set of properly written shell functions is enough to 1127 make it easy to write @command{configure} scripts by hand. Sigh! 1128 Unfortunately, even in 2008, where shells without any function support are 1129 far and few between, there are pitfalls to avoid when making use of them. 1130 Also, finding a Bourne shell that accepts shell functions is not trivial, 1131 even though there is almost always one on interesting porting targets. 1132 1133 So, what is really needed is some kind of compiler, @command{autoconf}, 1134 that takes an Autoconf program, @file{configure.ac}, and transforms it 1135 into a portable shell script, @command{configure}. 1136 1137 How does @command{autoconf} perform this task? 1138 1139 There are two obvious possibilities: creating a brand new language or 1140 extending an existing one. The former option is attractive: all 1141 sorts of optimizations could easily be implemented in the compiler and 1142 many rigorous checks could be performed on the Autoconf program 1143 (e.g., rejecting any non-portable construct). Alternatively, you can 1144 extend an existing language, such as the @code{sh} (Bourne shell) 1145 language. 1146 1147 Autoconf does the latter: it is a layer on top of @code{sh}. It was 1148 therefore most convenient to implement @command{autoconf} as a macro 1149 expander: a program that repeatedly performs @dfn{macro expansions} on 1150 text input, replacing macro calls with macro bodies and producing a pure 1151 @code{sh} script in the end. Instead of implementing a dedicated 1152 Autoconf macro expander, it is natural to use an existing 1153 general-purpose macro language, such as M4, and implement the extensions 1154 as a set of M4 macros. 1155 1156 1157 @node Autoconf Language 1158 @subsection The Autoconf Language 1159 @cindex quotation 1160 1161 The Autoconf language differs from many other computer 1162 languages because it treats actual code the same as plain text. Whereas 1163 in C, for instance, data and instructions have different syntactic 1164 status, in Autoconf their status is rigorously the same. Therefore, we 1165 need a means to distinguish literal strings from text to be expanded: 1166 quotation. 1167 1168 When calling macros that take arguments, there must not be any white 1169 space between the macro name and the open parenthesis. 1170 1171 @example 1172 AC_INIT ([oops], [1.0]) # incorrect 1173 AC_INIT([hello], [1.0]) # good 1174 @end example 1175 1176 Arguments should 1177 be enclosed within the quote characters @samp{[} and @samp{]}, and be 1178 separated by commas. Any leading blanks or newlines in arguments are ignored, 1179 unless they are quoted. You should always quote an argument that 1180 might contain a macro name, comma, parenthesis, or a leading blank or 1181 newline. This rule applies recursively for every macro 1182 call, including macros called from other macros. For more details on 1183 quoting rules, see @ref{Programming in M4}. 1184 1185 For instance: 1186 1187 @example 1188 AC_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 1195 is quoted properly. You may safely simplify its quotation to: 1196 1197 @example 1198 AC_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 1205 because @samp{1} cannot contain a macro call. Here, the argument of 1206 @code{AC_MSG_ERROR} must be quoted; otherwise, its comma would be 1207 interpreted as an argument separator. Also, the second and third arguments 1208 of @samp{AC_CHECK_HEADER} must be quoted, since they contain 1209 macro calls. The three arguments @samp{HAVE_STDIO_H}, @samp{stdio.h}, 1210 and @samp{Define to 1 if you have <stdio.h>.} do not need quoting, but 1211 if you unwisely defined a macro with a name like @samp{Define} or 1212 @samp{stdio} then they would need quoting. Cautious Autoconf users 1213 would keep the quotes, but many Autoconf users find such precautions 1214 annoying, and would rewrite the example as follows: 1215 1216 @example 1217 AC_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 1224 This is safe, so long as you adopt good naming conventions and do not 1225 define 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 1228 message strings are more likely to inadvertently contain commas. 1229 1230 The following example is wrong and dangerous, as it is underquoted: 1231 1232 @example 1233 AC_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 1239 In other cases, you may have to use text that also resembles a macro 1240 call. You must quote that text even when it is not passed as a macro 1241 argument. For example, these two approaches in @file{configure.ac} 1242 (quoting just the potential problems, or quoting the entire line) will 1243 protect your script in case autoconf ever adds a macro @code{AC_DC}: 1244 1245 @example 1246 echo "Hard rock was here! --[AC_DC]" 1247 [echo "Hard rock was here! --AC_DC"] 1248 @end example 1249 1250 @noindent 1251 which results in this text in @file{configure}: 1252 1253 @example 1254 echo "Hard rock was here! --AC_DC" 1255 echo "Hard rock was here! --AC_DC" 1256 @end example 1257 1258 @noindent 1259 When you use the same text in a macro argument, you must therefore have 1260 an extra quotation level (since one is stripped away by the macro 1261 substitution). In general, then, it is a good idea to @emph{use double 1262 quoting for all literal string arguments}, either around just the 1263 problematic portions, or over the entire argument: 1264 1265 @example 1266 AC_MSG_WARN([[AC_DC] stinks --Iron Maiden]) 1267 AC_MSG_WARN([[AC_DC stinks --Iron Maiden]]) 1268 @end example 1269 1270 However, the above example triggers a warning about a possibly 1271 unexpanded macro when running @command{autoconf}, because it collides 1272 with the namespace of macros reserved for the Autoconf language. To be 1273 really safe, you can use additional escaping (either a quadrigraph, or 1274 creative shell constructs) to silence that particular warning: 1275 1276 @example 1277 echo "Hard rock was here! --AC""_DC" 1278 AC_MSG_WARN([[AC@@&t@@_DC stinks --Iron Maiden]]) 1279 @end example 1280 1281 You are now able to understand one of the constructs of Autoconf that 1282 has been continually misunderstood@enddots{} The rule of thumb is that 1283 @emph{whenever you expect macro expansion, expect quote expansion}; 1284 i.e., expect one level of quotes to be lost. For instance: 1285 1286 @example 1287 AC_COMPILE_IFELSE(AC_LANG_SOURCE([char b[10];]), [], 1288 [AC_MSG_ERROR([you lose])]) 1289 @end example 1290 1291 @noindent 1292 is 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 1295 to being passed to @code{AC_COMPILE_IFELSE}. (There was an idiom common 1296 in Autoconf's past to 1297 address this issue via the M4 @code{changequote} primitive, but do not 1298 use it!) Let's take a closer look: the author meant the first argument 1299 to be understood as a literal, and therefore it must be quoted twice; 1300 likewise, the intermediate @code{AC_LANG_SOURCE} macro should be quoted 1301 once so that it is only expanded after the rest of the body of 1302 @code{AC_COMPILE_IFELSE} is in place: 1303 1304 @example 1305 AC_COMPILE_IFELSE([AC_LANG_SOURCE([[char b[10];]])], [], 1306 [AC_MSG_ERROR([you lose])]) 1307 @end example 1308 1309 @noindent 1310 Voil@`a, you actually produce @samp{char b[10];} this time! 1311 1312 On the other hand, descriptions (e.g., the last parameter of 1313 @code{AC_DEFINE} or @code{AS_HELP_STRING}) are not literals---they 1314 are subject to line breaking, for example---and should not be double quoted. 1315 Even if these descriptions are short and are not actually broken, double 1316 quoting them yields weird results. 1317 1318 Some macros take optional arguments, which this documentation represents 1319 as @ovar{arg} (not to be confused with the quote characters). You may 1320 just leave them empty, or use @samp{[]} to make the emptiness of the 1321 argument explicit, or you may simply omit the trailing commas. The 1322 three lines below are equivalent: 1323 1324 @example 1325 AC_CHECK_HEADERS([stdio.h], [], [], []) 1326 AC_CHECK_HEADERS([stdio.h],,,) 1327 AC_CHECK_HEADERS([stdio.h]) 1328 @end example 1329 1330 It 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 1332 rely on the newline after the macro call to terminate the commands. 1333 This approach makes the generated @command{configure} script a little 1334 easier to read by not inserting lots of blank lines. It is generally 1335 safe to set shell variables on the same line as a macro call, because 1336 the shell allows assignments without intervening newlines. 1337 1338 You can include comments in @file{configure.ac} files by starting them 1339 with 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 1349 The order in which @file{configure.ac} calls the Autoconf macros is not 1350 important, with a few exceptions. Every @file{configure.ac} must 1351 contain 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 1353 rely on other macros having been called first, because they check 1354 previously set values of some variables to decide what to do. These 1355 macros are noted in the individual descriptions (@pxref{Existing 1356 Tests}), and they also warn you when @command{configure} is created if they 1357 are called out of order. 1358 1359 To encourage consistency, here is a suggested order for calling the 1360 Autoconf macros. Generally speaking, the things near the end of this 1361 list are those that could depend on things earlier in it. For example, 1362 library functions could be affected by types and libraries. 1363 1364 @display 1365 @group 1366 Autoconf requirements 1367 @code{AC_INIT(@var{package}, @var{version}, @var{bug-report-address})} 1368 information on the package 1369 checks for programs 1370 checks for libraries 1371 checks for header files 1372 checks for types 1373 checks for structures 1374 checks for compiler characteristics 1375 checks for library functions 1376 checks 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 1387 The @command{autoscan} program can help you create and/or maintain a 1388 @file{configure.ac} file for a software package. @command{autoscan} 1389 examines source files in the directory tree rooted at a directory given 1390 as a command line argument, or the current directory if none is given. 1391 It searches the source files for common portability problems and creates 1392 a file @file{configure.scan} which is a preliminary @file{configure.ac} 1393 for that package, and checks a possibly existing @file{configure.ac} for 1394 completeness. 1395 1396 When using @command{autoscan} to create a @file{configure.ac}, you 1397 should manually examine @file{configure.scan} before renaming it to 1398 @file{configure.ac}; it probably needs some adjustments. 1399 Occasionally, @command{autoscan} outputs a macro in the wrong order 1400 relative to another macro, so that @command{autoconf} produces a warning; 1401 you need to move such macros manually. Also, if you want the package to 1402 use a configuration header file, you must add a call to 1403 @code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}). You might 1404 also have to change or add some @code{#if} directives to your program in 1405 order to make it work with Autoconf (@pxref{ifnames Invocation}, for 1406 information about a program that can help with that job). 1407 1408 When using @command{autoscan} to maintain a @file{configure.ac}, simply 1409 consider adding its suggestions. The file @file{autoscan.log} 1410 contains detailed information on why a macro is requested. 1411 1412 @command{autoscan} uses several data files (installed along with Autoconf) 1413 to determine which macros to output when it finds particular symbols in 1414 a package's source files. These data files all have the same format: 1415 each line consists of a symbol, one or more blanks, and the Autoconf macro to 1416 output if that symbol is encountered. Lines starting with @samp{#} are 1417 comments. 1418 1419 @command{autoscan} accepts the following options: 1420 1421 @table @option 1422 @item --help 1423 @itemx -h 1424 Print a summary of the command line options and exit. 1425 1426 @item --version 1427 @itemx -V 1428 Print the version number of Autoconf and exit. 1429 1430 @item --verbose 1431 @itemx -v 1432 Print the names of the files it examines and the potentially interesting 1433 symbols it finds in them. This output can be voluminous. 1434 1435 @item --debug 1436 @itemx -d 1437 Don't remove temporary files. 1438 1439 @item --include=@var{dir} 1440 @itemx -I @var{dir} 1441 Append @var{dir} to the include path. Multiple invocations accumulate. 1442 1443 @item --prepend-include=@var{dir} 1444 @itemx -B @var{dir} 1445 Prepend @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 1453 package. It prints the identifiers that the package already uses in C 1454 preprocessor conditionals. If a package has already been set up to have 1455 some 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 1458 Invocation}). 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 1462 output a sorted list of all the identifiers that appear in those files 1463 in @code{#if}, @code{#elif}, @code{#ifdef}, or @code{#ifndef} 1464 directives. It prints each identifier on a line, followed by a 1465 space-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 1473 Print a summary of the command line options and exit. 1474 1475 @item --version 1476 @itemx -V 1477 Print 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 1484 To 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 1487 Autoconf macros. If you give @command{autoconf} an argument, it reads that 1488 file instead of @file{configure.ac} and writes the configuration script 1489 to the standard output instead of to @command{configure}. If you give 1490 @command{autoconf} the argument @option{-}, it reads from the standard 1491 input instead of @file{configure.ac} and writes the configuration script 1492 to the standard output. 1493 1494 The Autoconf macros are defined in several files. Some of the files are 1495 distributed with Autoconf; @command{autoconf} reads them first. Then it 1496 looks for the optional file @file{acsite.m4} in the directory that 1497 contains the distributed Autoconf macro files, and for the optional file 1498 @file{aclocal.m4} in the current directory. Those files can contain 1499 your site's or the package's own Autoconf macro definitions 1500 (@pxref{Writing Autoconf Macros}, for more information). If a macro is 1501 defined in more than one of the files that @command{autoconf} reads, the 1502 last 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 1509 Print a summary of the command line options and exit. 1510 1511 @item --version 1512 @itemx -V 1513 Print the version number of Autoconf and exit. 1514 1515 @item --verbose 1516 @itemx -v 1517 Report processing steps. 1518 1519 @item --debug 1520 @itemx -d 1521 Don't remove the temporary files. 1522 1523 @item --force 1524 @itemx -f 1525 Remake @file{configure} even if newer than its input files. 1526 1527 @item --include=@var{dir} 1528 @itemx -I @var{dir} 1529 Append @var{dir} to the include path. Multiple invocations accumulate. 1530 1531 @item --prepend-include=@var{dir} 1532 @itemx -B @var{dir} 1533 Prepend @var{dir} to the include path. Multiple invocations accumulate. 1534 1535 @item --output=@var{file} 1536 @itemx -o @var{file} 1537 Save output (script or trace) to @var{file}. The file @option{-} stands 1538 for the standard output. 1539 1540 @item --warnings=@var{category} 1541 @itemx -W @var{category} 1542 @evindex WARNINGS 1543 Report the warnings related to @var{category} (which can actually be a 1544 comma separated list). @xref{Reporting Messages}, macro 1545 @code{AC_DIAGNOSE}, for a comprehensive list of categories. Special 1546 values include: 1547 1548 @table @samp 1549 @item all 1550 report all the warnings 1551 1552 @item none 1553 report none 1554 1555 @item error 1556 treats warnings as errors 1557 1558 @item no-@var{category} 1559 disable warnings falling into @var{category} 1560 @end table 1561 1562 Warnings about @samp{syntax} are enabled by default, and the environment 1563 variable @env{WARNINGS}, a comma separated list of categories, is 1564 honored as well. Passing @option{-W @var{category}} actually behaves as if 1565 you had passed @option{--warnings syntax,$WARNINGS,@var{category}}. To 1566 disable the defaults and @env{WARNINGS}, and then 1567 enable warnings about obsolete constructs, use @option{-W 1568 none,obsolete}. 1569 1570 @cindex Back trace 1571 @cindex Macro invocation stack 1572 Because @command{autoconf} uses @command{autom4te} behind the scenes, it 1573 displays a back trace for errors, but not for warnings; if you want 1574 them, just pass @option{-W error}. @xref{autom4te Invocation}, for some 1575 examples. 1576 1577 @item --trace=@var{macro}[:@var{format}] 1578 @itemx -t @var{macro}[:@var{format}] 1579 Do not create the @command{configure} script, but list the calls to 1580 @var{macro} according to the @var{format}. Multiple @option{--trace} 1581 arguments can be used to list several macros. Multiple @option{--trace} 1582 arguments for a single macro are not cumulative; instead, you should 1583 just make @var{format} as long as needed. 1584 1585 The @var{format} is a regular string, with newlines if desired, and 1586 several 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 1591 By default, @option{--trace} does not trace the initialization of the 1592 Autoconf macros (typically the @code{AC_DEFUN} definitions). This 1593 results in a noticeable speedup, but can be disabled by this option. 1594 @end table 1595 1596 1597 It is often necessary to check the content of a @file{configure.ac} 1598 file, but parsing it yourself is extremely fragile and error-prone. It 1599 is suggested that you rely upon @option{--trace} to scan 1600 @file{configure.ac}. For instance, to find the list of variables that 1601 are substituted, use: 1602 1603 @example 1604 @group 1605 $ @kbd{autoconf -t AC_SUBST} 1606 configure.ac:2:AC_SUBST:ECHO_C 1607 configure.ac:2:AC_SUBST:ECHO_N 1608 configure.ac:2:AC_SUBST:ECHO_T 1609 @i{More traces deleted} 1610 @end group 1611 @end example 1612 1613 @noindent 1614 The example below highlights the difference between @samp{$@@}, 1615 @samp{$*}, and @samp{$%}. 1616 1617 @example 1618 @group 1619 $ @kbd{cat configure.ac} 1620 AC_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 1634 The @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 1647 A long @var{separator} can be used to improve the readability of complex 1648 structures, and to ease their parsing (for instance when no single 1649 character is suitable as a separator): 1650 1651 @example 1652 @group 1653 $ @kbd{autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*'} 1654 ACLOCAL|:::::|aclocal|:::::|$missing_dir 1655 AUTOCONF|:::::|autoconf|:::::|$missing_dir 1656 AUTOMAKE|:::::|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 1665 Installing the various components of the GNU Build System can be 1666 tedious: running @command{autopoint} for Gettext, @command{automake} for 1667 @file{Makefile.in} etc.@: in each directory. It may be needed either 1668 because some tools such as @command{automake} have been updated on your 1669 system, or because some of the sources such as @file{configure.ac} have 1670 been updated, or finally, simply in order to install the GNU Build 1671 System 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 1676 GNU Build System in the specified directories and their 1677 subdirectories (@pxref{Subdirectories}). By default, it only remakes 1678 those 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} 1681 may be used to override the invocation of the respective tools. 1682 1683 If 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 1688 rebuild @command{configure} scripts when their source files change. That 1689 method handles the timestamps of configuration header templates 1690 properly, but does not pass @option{--autoconf-dir=@var{dir}} or 1691 @option{--localdir=@var{dir}}. 1692 1693 @cindex Gettext 1694 @cindex @command{autopoint} 1695 Gettext supplies the @command{autopoint} command to add translation 1696 infrastructure to a source package. If you use @command{autopoint}, 1697 your @file{configure.ac} should invoke both @code{AM_GNU_GETTEXT} and 1698 @code{AM_GNU_GETTEXT_VERSION(@var{gettext-version})}. @xref{autopoint 1699 Invocation, , Invoking the @code{autopoint} Program, gettext, 1700 GNU @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 1708 Print a summary of the command line options and exit. 1709 1710 @item --version 1711 @itemx -V 1712 Print the version number of Autoconf and exit. 1713 1714 @item --verbose 1715 @itemx -v 1716 Print the name of each directory @command{autoreconf} examines and the 1717 commands it runs. If given two or more times, pass @option{--verbose} 1718 to subordinate tools that support it. 1719 1720 @item --debug 1721 @itemx -d 1722 Don't remove the temporary files. 1723 1724 @item --force 1725 @itemx -f 1726 Remake even @file{configure} scripts and configuration headers that are 1727 newer than their input files (@file{configure.ac} and, if present, 1728 @file{aclocal.m4}). 1729 1730 @item --install 1731 @itemx -i 1732 Install the missing auxiliary files in the package. By default, files 1733 are copied; this can be changed with @option{--symlink}. 1734 1735 If deemed appropriate, this option triggers calls to 1736 @samp{automake --add-missing}, 1737 @samp{libtoolize}, @samp{autopoint}, etc. 1738 1739 @item --no-recursive 1740 Do not rebuild files in subdirectories to configure (see @ref{Subdirectories}, 1741 macro @code{AC_CONFIG_SUBDIRS}). 1742 1743 @item --symlink 1744 @itemx -s 1745 When used with @option{--install}, install symbolic links to the missing 1746 auxiliary files instead of copying them. 1747 1748 @item --make 1749 @itemx -m 1750 When the directories were configured, update the configuration by 1751 running @samp{./config.status --recheck && ./config.status}, and then 1752 run @samp{make}. 1753 1754 @item --include=@var{dir} 1755 @itemx -I @var{dir} 1756 Append @var{dir} to the include path. Multiple invocations accumulate. 1757 Passed on to @command{aclocal}, @command{autoconf} and 1758 @command{autoheader} internally. 1759 1760 @item --prepend-include=@var{dir} 1761 @itemx -B @var{dir} 1762 Prepend @var{dir} to the include path. Multiple invocations accumulate. 1763 Passed on to @command{autoconf} and @command{autoheader} internally. 1764 1765 @item --warnings=@var{category} 1766 @itemx -W @var{category} 1767 @evindex WARNINGS 1768 Report the warnings related to @var{category} (which can actually be a 1769 comma separated list). 1770 1771 @table @samp 1772 @item cross 1773 related to cross compilation issues. 1774 1775 @item obsolete 1776 report the uses of obsolete constructs. 1777 1778 @item portability 1779 portability issues 1780 1781 @item syntax 1782 dubious syntactic constructs. 1783 1784 @item all 1785 report all the warnings 1786 1787 @item none 1788 report none 1789 1790 @item error 1791 treats warnings as errors 1792 1793 @item no-@var{category} 1794 disable warnings falling into @var{category} 1795 @end table 1796 1797 Warnings about @samp{syntax} are enabled by default, and the environment 1798 variable @env{WARNINGS}, a comma separated list of categories, is 1799 honored as well. Passing @option{-W @var{category}} actually behaves as if 1800 you had passed @option{--warnings syntax,$WARNINGS,@var{category}}. To 1801 disable the defaults and @env{WARNINGS}, and then 1802 enable warnings about obsolete constructs, use @option{-W 1803 none,obsolete}. 1804 @end table 1805 1806 If you want @command{autoreconf} to pass flags that are not listed here 1807 on to @command{aclocal}, set @code{ACLOCAL_AMFLAGS} in your @file{Makefile.am}. 1808 Due to a limitation in the Autoconf implementation these flags currently 1809 must be set on a single line in @file{Makefile.am}, without any 1810 backslash-newlines. 1811 1812 @c ========================================= Initialization and Output Files. 1813 1814 @node Setup 1815 @chapter Initialization and Output Files 1816 1817 Autoconf-generated @command{configure} scripts need some information about 1818 how to initialize, such as how to find the package's source files and 1819 about the output files to produce. The following sections describe the 1820 initialization 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 1841 Every @command{configure} script must call @code{AC_INIT} before doing 1842 anything else that produces output. Calls to silent macros, such as 1843 @code{AC_DEFUN}, may also occur prior to @code{AC_INIT}, although these 1844 are generally used via @file{aclocal.m4}, since that is implicitly 1845 included before the start of @file{configure.ac}. The only other 1846 required 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} 1852 Process any command-line arguments and perform initialization 1853 and verification. 1854 1855 Set the name of the @var{package} and its @var{version}. These are 1856 typically used in @option{--version} support, including that of 1857 @command{configure}. The optional argument @var{bug-report} should be 1858 the email to which users should send bug reports. The package 1859 @var{tarname} differs from @var{package}: the latter designates the full 1860 package name (e.g., @samp{GNU Autoconf}), while the former is meant for 1861 distribution tar ball names (e.g., @samp{autoconf}). It defaults to 1862 @var{package} with @samp{GNU } stripped, lower-cased, and all characters 1863 other than alphanumerics and underscores are changed to @samp{-}. If 1864 provided, @var{url} should be the home page for the package. 1865 1866 The arguments of @code{AC_INIT} must be static, i.e., there should not 1867 be any shell computation, quotes, or newlines, but they can be computed 1868 by M4. This is because the package information strings are expanded at 1869 M4 time into several contexts, and must give the same text at shell time 1870 whether used in single-quoted strings, double-quoted strings, quoted 1871 here-documents, or unquoted here-documents. It is permissible to use 1872 @code{m4_esyscmd} or @code{m4_esyscmd_s} for computing a version string 1873 that changes with every commit to a version control system (in fact, 1874 Autoconf does just that, for all builds of the development tree made 1875 between releases). 1876 1877 The 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 1886 Exactly @var{package}. 1887 1888 @item @code{AC_PACKAGE_TARNAME}, @code{PACKAGE_TARNAME} 1889 @acindex{PACKAGE_TARNAME} 1890 @ovindex PACKAGE_TARNAME 1891 @cvindex PACKAGE_TARNAME 1892 Exactly @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 1898 Exactly @var{version}. 1899 1900 @item @code{AC_PACKAGE_STRING}, @code{PACKAGE_STRING} 1901 @acindex{PACKAGE_STRING} 1902 @ovindex PACKAGE_STRING 1903 @cvindex PACKAGE_STRING 1904 Exactly @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 1910 Exactly @var{bug-report}, if one was provided. Typically an email 1911 address, 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 1917 Exactly @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 1920 assumed. 1921 @end table 1922 @end defmac 1923 1924 If your @command{configure} script does its own option processing, it 1925 should 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 1928 of updating @samp{$@@} and @samp{$*}. However, we suggest that you use 1929 standard macros like @code{AC_ARG_ENABLE} instead of attempting to 1930 implement 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 1937 The following optional macros can be used to help choose the minimum 1938 version 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 1944 Ensure that a recent enough version of Autoconf is being used. If the 1945 version of Autoconf being used to create @command{configure} is 1946 earlier than @var{version}, print an error message to the standard 1947 error output and exit with failure (exit status is 63). For example: 1948 1949 @example 1950 AC_PREREQ([@value{VERSION}]) 1951 @end example 1952 1953 This macro may be used before @code{AC_INIT}. 1954 @end defmac 1955 1956 @defmac AC_AUTOCONF_VERSION 1957 @acindex{AUTOCONF_VERSION} 1958 This macro was introduced in Autoconf 2.62. It identifies the version 1959 of Autoconf that is currently parsing the input file, in a format 1960 suitable for @code{m4_version_compare} (@pxref{m4_version_compare}); in 1961 other words, for this release of Autoconf, its value is 1962 @samp{@value{VERSION}}. One potential use of this macro is for writing 1963 conditional fallbacks based on when a feature was added to Autoconf, 1964 rather than using @code{AC_PREREQ} to require the newer version of 1965 Autoconf. However, remember that the Autoconf philosophy favors feature 1966 checks over version checks. 1967 1968 You should not expand this macro directly; use 1969 @samp{m4_defn([AC_AUTOCONF_VERSION])} instead. This is because some 1970 users might 1971 have a beta version of Autoconf installed, with arbitrary letters 1972 included in its version string. This means it is possible for the 1973 version string to contain the name of a defined macro, such that 1974 expanding @code{AC_AUTOCONF_VERSION} would trigger the expansion of that 1975 macro during rescanning, and change the version string to be different 1976 than 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 1983 The following macros manage version numbers for @command{configure} 1984 scripts. Using them is optional. 1985 1986 @defmac AC_COPYRIGHT (@var{copyright-notice}) 1987 @acindex{COPYRIGHT} 1988 @cindex Copyright Notice 1989 State that, in addition to the Free Software Foundation's copyright on 1990 the Autoconf macros, parts of your @command{configure} are covered by the 1991 @var{copyright-notice}. 1992 1993 The @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 2001 Copy revision stamp @var{revision-info} into the @command{configure} 2002 script, with any dollar signs or double-quotes removed. This macro lets 2003 you put a revision stamp from @file{configure.ac} into @command{configure} 2004 without 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 2008 For example, this line in @file{configure.ac}: 2009 2010 @c The @w prevents RCS from changing the example in the manual. 2011 @example 2012 AC_REVISION([@w{$}Revision: 1.30 $]) 2013 @end example 2014 2015 @noindent 2016 produces 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 2032 source directory; @command{configure} checks for this file's existence to 2033 make sure that the directory that it is told contains the source code in 2034 fact does. Occasionally people accidentally specify the wrong directory 2035 with @option{--srcdir}; this is a safety check. @xref{configure 2036 Invocation}, 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 2064 Packages that do manual configuration or use the @command{install} program 2065 might need to tell @command{configure} where to find some other shell 2066 scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places 2067 it looks are correct for most cases. 2068 2069 @defmac AC_CONFIG_AUX_DIR (@var{dir}) 2070 @acindex{CONFIG_AUX_DIR} 2071 Use the auxiliary build tools (e.g., @file{install-sh}, 2072 @file{config.sub}, @file{config.guess}, Cygnus @command{configure}, 2073 Automake and Libtool scripts, etc.)@: that are in directory @var{dir}. 2074 These are auxiliary files used in configuration. @var{dir} can be 2075 either 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 2080 other auxiliary files. It checks for @file{install.sh} also, but that 2081 name is obsolete because some @command{make} have a rule that creates 2082 @file{install} from it if there is no makefile. 2083 2084 The auxiliary directory is commonly named @file{build-aux}. 2085 If you need portability to DOS variants, do not name the 2086 auxiliary directory @file{aux}. @xref{File System Conventions}. 2087 @end defmac 2088 2089 @defmac AC_REQUIRE_AUX_FILE (@var{file}) 2090 @acindex{REQUIRE_AUX_FILE} 2091 Declares that @var{file} is expected in the directory defined above. In 2092 Autoconf proper, this macro does nothing: its sole purpose is to be 2093 traced by third-party tools to produce a list of expected auxiliary 2094 files. 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 2099 Similarly, packages that use @command{aclocal} should declare where 2100 local macros can be found using @code{AC_CONFIG_MACRO_DIR}. 2101 2102 @defmac AC_CONFIG_MACRO_DIR (@var{dir}) 2103 @acindex{CONFIG_MACRO_DIR} 2104 Specify @var{dir} as the location of additional local Autoconf macros. 2105 This macro is intended for use by future versions of commands like 2106 @command{autoreconf} that trace macro calls. It should be called 2107 directly from @file{configure.ac} so that tools that install macros for 2108 @command{aclocal} can find the macros' declarations. 2109 2110 Note 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 2113 the Autoconf implementation of @command{autoreconf}, these include 2114 directives currently must be set on a single line in @file{Makefile.am}, 2115 without any backslash-newlines. 2116 @end defmac 2117 2118 2119 @node Output 2120 @section Outputting Files 2121 @cindex Outputting files 2122 2123 Every Autoconf script, e.g., @file{configure.ac}, should finish by 2124 calling @code{AC_OUTPUT}. That is the macro that generates and runs 2125 @file{config.status}, which in turn creates the makefiles and any 2126 other files resulting from configuration. This is the only required 2127 macro besides @code{AC_INIT} (@pxref{Input}). 2128 2129 @anchor{AC_OUTPUT} 2130 @defmac AC_OUTPUT 2131 @acindex{OUTPUT} 2132 @cindex Instantiation 2133 Generate @file{config.status} and launch it. Call this macro once, at 2134 the end of @file{configure.ac}. 2135 2136 @file{config.status} performs all the configuration actions: all the 2137 output files (see @ref{Configuration Files}, macro 2138 @code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers}, 2139 macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration 2140 Commands}, macro @code{AC_CONFIG_COMMANDS}), links (see 2141 @ref{Configuration Links}, macro @code{AC_CONFIG_LINKS}), subdirectories 2142 to configure (see @ref{Subdirectories}, macro @code{AC_CONFIG_SUBDIRS}) 2143 are honored. 2144 2145 The location of your @code{AC_OUTPUT} invocation is the exact point 2146 where configuration actions are taken: any code afterwards is 2147 executed by @command{configure} once @command{config.status} was run. If 2148 you 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 2151 Commands}. 2152 @end defmac 2153 2154 Historically, 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 2159 If 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 2162 was given. (But many do not include in it the values of any variables 2163 set on the command line, so those are not passed on automatically.) 2164 Some old versions of @command{make} do not set this variable. The 2165 following 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 2171 If the Make command, @code{$MAKE} if set or else @samp{make}, predefines 2172 @code{$(MAKE)}, define output variable @code{SET_MAKE} to be empty. 2173 Otherwise, 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 2178 If you use this macro, place a line like this in each @file{Makefile.in} 2179 that 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, 2192 but 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 2195 results of @file{configure}. The most typical task of 2196 @file{config.status} is to @emph{instantiate} files. 2197 2198 @acindex{CONFIG_@var{ITEMS}} 2199 This section describes the common behavior of the four standard 2200 instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS}, 2201 @code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}. They all 2202 have this prototype: 2203 2204 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something 2205 @c awful. 2206 @example 2207 AC_CONFIG_@var{ITEMS}(@var{tag}@dots{}, @r{[}@var{commands}@r{]}, @r{[}@var{init-cmds}@r{]}) 2208 @end example 2209 2210 @noindent 2211 where the arguments are: 2212 2213 @table @var 2214 @item tag@dots{} 2215 A blank-or-newline-separated list of tags, which are typically the names of 2216 the files to instantiate. 2217 2218 You are encouraged to use literals as @var{tags}. In particular, you 2219 should avoid 2220 2221 @example 2222 @dots{} && my_foos="$my_foos fooo" 2223 @dots{} && my_foos="$my_foos foooo" 2224 AC_CONFIG_@var{ITEMS}([$my_foos]) 2225 @end example 2226 2227 @noindent 2228 and use this instead: 2229 2230 @example 2231 @dots{} && AC_CONFIG_@var{ITEMS}([fooo]) 2232 @dots{} && AC_CONFIG_@var{ITEMS}([foooo]) 2233 @end example 2234 2235 The macros @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use 2236 special @var{tag} values: they may have the form @samp{@var{output}} or 2237 @samp{@var{output}:@var{inputs}}. The file @var{output} is instantiated 2238 from its templates, @var{inputs} (defaulting to @samp{@var{output}.in}). 2239 2240 @samp{AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk])}, 2241 for example, asks for 2242 the creation of the file @file{Makefile} that contains the expansion of the 2243 output variables in the concatenation of @file{boiler/top.mk} and 2244 @file{boiler/bot.mk}. 2245 2246 The special value @samp{-} might be used to denote the standard output 2247 when 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 2250 interface of @file{./config.status}, see @ref{config.status Invocation}, 2251 for more details. 2252 2253 The @var{inputs} may be absolute or relative file names. In the latter 2254 case they are first looked for in the build tree, and then in the source 2255 tree. Input files should be text files, and a line length below 2000 2256 bytes should be safe. 2257 2258 @item commands 2259 Shell commands output literally into @file{config.status}, and 2260 associated with a tag that the user can use to tell @file{config.status} 2261 which commands to run. The commands are run each time a @var{tag} 2262 request is given to @file{config.status}, typically each time the file 2263 @file{@var{tag}} is created. 2264 2265 The 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 2272 The name of the top source directory, assuming that the working 2273 directory is the top build directory. This 2274 is what the @command{configure} option @option{--srcdir} sets. 2275 2276 @item ac_top_srcdir 2277 @vrindex ac_top_srcdir 2278 The name of the top source directory, assuming that the working 2279 directory is the current build directory. 2280 2281 @item ac_top_build_prefix 2282 @vrindex ac_top_build_prefix 2283 The name of the top build directory, assuming that the working 2284 directory is the current build directory. 2285 It can be empty, or else ends with a slash, so that you may concatenate 2286 it. 2287 2288 @item ac_srcdir 2289 @vrindex ac_srcdir 2290 The name of the corresponding source directory, assuming that the 2291 working directory is the current build directory. 2292 2293 @item tmp 2294 @vrindex tmp 2295 The name of a temporary directory within the build tree, which you 2296 can use if you need to create additional temporary files. The 2297 directory is cleaned up when @command{config.status} is done or 2298 interrupted. Please use package-specific file name prefixes to 2299 avoid clashing with files that @command{config.status} may use 2300 internally. 2301 @end table 2302 2303 @noindent 2304 The @dfn{current} directory refers to the directory (or 2305 pseudo-directory) containing the input part of @var{tags}. For 2306 instance, running 2307 2308 @example 2309 AC_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 2317 srcdir='../package' 2318 # Reversing deep/dir 2319 ac_top_build_prefix='../../' 2320 # Concatenation of $ac_top_build_prefix and srcdir 2321 ac_top_srcdir='../../../package' 2322 # Concatenation of $ac_top_srcdir and deep/dir 2323 ac_srcdir='../../../package/deep/dir' 2324 @end example 2325 2326 @noindent 2327 independently of @samp{in/in.in}. 2328 2329 @item init-cmds 2330 Shell 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} 2334 is typically used by @file{configure} to give @file{config.status} some 2335 variables it needs to run the @var{commands}. 2336 2337 You should be extremely cautious in your variable names: all the 2338 @var{init-cmds} share the same name space and may overwrite each other 2339 in unpredictable ways. Sorry@enddots{} 2340 @end table 2341 2342 All 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 2351 Be 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} 2356 Make @code{AC_OUTPUT} create each @file{@var{file}} by copying an input 2357 file (by default @file{@var{file}.in}), substituting the output variable 2358 values. 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. 2363 This macro is one of the instantiating macros; see @ref{Configuration 2364 Actions}. @xref{Makefile Substitutions}, for more information on using 2365 output variables. @xref{Setting Output Variables}, for more information 2366 on creating them. This macro creates the directory that the file is in 2367 if it doesn't exist. Usually, makefiles are created this way, 2368 but other files, such as @file{.gdbinit}, can be specified as well. 2369 2370 Typical calls to @code{AC_CONFIG_FILES} look like this: 2371 2372 @example 2373 AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile]) 2374 AC_CONFIG_FILES([autoconf], [chmod +x autoconf]) 2375 @end example 2376 2377 You can override an input file name by appending to @var{file} a 2378 colon-separated list of input files. Examples: 2379 2380 @example 2381 AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk] 2382 [lib/Makefile:boiler/lib.mk]) 2383 @end example 2384 2385 @noindent 2386 Doing this allows you to keep your file names acceptable to 2387 DOS variants, or 2388 to 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 2398 Each subdirectory in a distribution that contains something to be 2399 compiled or installed should come with a file @file{Makefile.in}, from 2400 which @command{configure} creates a file @file{Makefile} in that directory. 2401 To create @file{Makefile}, @command{configure} performs a simple variable 2402 substitution, replacing occurrences of @samp{@@@var{variable}@@} in 2403 @file{Makefile.in} with the value that @command{configure} has determined 2404 for that variable. Variables that are substituted into output files in 2405 this way are called @dfn{output variables}. They are ordinary shell 2406 variables that are set in @command{configure}. To make @command{configure} 2407 substitute a particular variable into the output files, the macro 2408 @code{AC_SUBST} must be called with that variable name as an argument. 2409 Any occurrences of @samp{@@@var{variable}@@} for other variables are 2410 left unchanged. @xref{Setting Output Variables}, for more information 2411 on creating output variables with @code{AC_SUBST}. 2412 2413 A software package that uses a @command{configure} script should be 2414 distributed with a file @file{Makefile.in}, but no makefile; that 2415 way, the user has to properly configure the package for the local system 2416 before compiling it. 2417 2418 @xref{Makefile Conventions, , Makefile Conventions, standards, The 2419 GNU Coding Standards}, for more information on what to put in 2420 makefiles. 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 2434 Some output variables are preset by the Autoconf macros. Some of the 2435 Autoconf macros set additional output variables, which are mentioned in 2436 the descriptions for those macros. @xref{Output Variable Index}, for a 2437 complete list of output variables. @xref{Installation Directory 2438 Variables}, for the list of the preset ones related to installation 2439 directories. Below are listed the other preset ones, many of which are 2440 precious variables (@pxref{Setting Output Variables}, 2441 @code{AC_ARG_VAR}). 2442 2443 The 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 2447 option @option{-I} during a compiler feature check. When used in this 2448 manner, coupled with the fact that @command{configure} is always run 2449 from 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 2461 Debugging and optimization options for the C compiler. If it is not set 2462 in the environment when @command{configure} runs, the default value is set 2463 when you call @code{AC_PROG_CC} (or empty if you don't). @command{configure} 2464 uses this variable when compiling or linking programs to test for C features. 2465 2466 If a compiler option affects only the behavior of the preprocessor 2467 (e.g., @option{-D@var{name}}), it should be put into @code{CPPFLAGS} 2468 instead. If it affects only the linker (e.g., @option{-L@var{directory}}), 2469 it should be put into @code{LDFLAGS} instead. If it 2470 affects only the compiler proper, @code{CFLAGS} is the natural home for 2471 it. If an option affects multiple phases of the compiler, though, 2472 matters 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 2476 However, remember that some @file{Makefile} variables are reserved by 2477 the GNU Coding Standards for the use of the ``user''---the person 2478 building the package. For instance, @code{CFLAGS} is one such variable. 2479 2480 Sometimes package developers are tempted to set user variables such as 2481 @code{CFLAGS} because it appears to make their job easier. However, the 2482 package itself should never set a user variable, particularly not to 2483 include switches that are required for proper compilation of the 2484 package. Since these variables are documented as being for the package 2485 builder, that person rightfully expects to be able to override any of 2486 these variables at build time. If the package developer needs to add 2487 switches without interfering with the user, the proper way to do that is 2488 to introduce an additional variable. Automake makes this easy by 2489 introducing @code{AM_CFLAGS} (@pxref{Flag Variables Ordering, , , 2490 automake, GNU Automake}), but the concept is the same even if 2491 Automake is not used. 2492 @end defvar 2493 2494 @defvar configure_input 2495 @ovindex configure_input 2496 A 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 2499 of every makefile it creates. For other files, you should 2500 reference this variable in a comment at the top of each input file. For 2501 example, an input shell script should begin like this: 2502 2503 @example 2504 #!/bin/sh 2505 # @@configure_input@@ 2506 @end example 2507 2508 @noindent 2509 The presence of that line also reminds people editing the file that it 2510 needs to be processed by @command{configure} in order to be used. 2511 @end defvar 2512 2513 @defvar CPPFLAGS 2514 @evindex CPPFLAGS 2515 @ovindex CPPFLAGS 2516 Preprocessor options for the C, C++, Objective C, and Objective C++ 2517 preprocessors and compilers. If 2518 it is not set in the environment when @command{configure} runs, the default 2519 value is empty. @command{configure} uses this variable when preprocessing 2520 or compiling programs to test for C, C++, Objective C, and Objective C++ 2521 features. 2522 2523 This variable's contents should contain options like @option{-I}, 2524 @option{-D}, and @option{-U} that affect only the behavior of the 2525 preprocessor. Please see the explanation of @code{CFLAGS} for what you 2526 can do if an option affects other phases of the compiler as well. 2527 2528 Currently, @command{configure} always links as part of a single 2529 invocation of the compiler that also preprocesses and compiles, so it 2530 uses this variable also when linking programs. However, it is unwise to 2531 depend on this behavior because the GNU Coding Standards do 2532 not require it and many packages do not use @code{CPPFLAGS} when linking 2533 programs. 2534 2535 @xref{Special Chars in Variables}, for limitations that @code{CPPFLAGS} 2536 might run into. 2537 @end defvar 2538 2539 @defvar CXXFLAGS 2540 @evindex CXXFLAGS 2541 @ovindex CXXFLAGS 2542 Debugging 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} 2549 is called, @command{configure} replaces @samp{@@DEFS@@} with 2550 @option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}). This 2551 variable is not defined while @command{configure} is performing its tests, 2552 only when creating the output files. @xref{Setting Output Variables}, for 2553 how 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 2562 How does one suppress the trailing newline from @command{echo} for 2563 question-answer message pairs? These variables provide a way: 2564 2565 @example 2566 echo $ECHO_N "And the winner is... $ECHO_C" 2567 sleep 100000000000 2568 echo "$@{ECHO_T@}dead." 2569 @end example 2570 2571 @noindent 2572 Some old and uncommon @command{echo} implementations offer no means to 2573 achieve this, in which case @code{ECHO_T} is set to tab. You might not 2574 want to use it. 2575 @end defvar 2576 2577 @defvar ERLCFLAGS 2578 @evindex ERLCFLAGS 2579 @ovindex ERLCFLAGS 2580 Debugging and optimization options for the Erlang compiler. If it is not set 2581 in the environment when @command{configure} runs, the default value is empty. 2582 @command{configure} uses this variable when compiling 2583 programs to test for Erlang features. 2584 @end defvar 2585 2586 @defvar FCFLAGS 2587 @evindex FCFLAGS 2588 @ovindex FCFLAGS 2589 Debugging and optimization options for the Fortran compiler. If it 2590 is not set in the environment when @command{configure} runs, the default 2591 value 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 2593 programs to test for Fortran features. 2594 @end defvar 2595 2596 @defvar FFLAGS 2597 @evindex FFLAGS 2598 @ovindex FFLAGS 2599 Debugging and optimization options for the Fortran 77 compiler. If it 2600 is not set in the environment when @command{configure} runs, the default 2601 value 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 2603 programs to test for Fortran 77 features. 2604 @end defvar 2605 2606 @defvar LDFLAGS 2607 @evindex LDFLAGS 2608 @ovindex LDFLAGS 2609 Options for the linker. If it is not set 2610 in the environment when @command{configure} runs, the default value is empty. 2611 @command{configure} uses this variable when linking programs to test for 2612 C, C++, Objective C, Objective C++, Fortran, and Go features. 2613 2614 This variable's contents should contain options like @option{-s} and 2615 @option{-L} that affect only the behavior of the linker. Please see the 2616 explanation of @code{CFLAGS} for what you can do if an option also 2617 affects other phases of the compiler. 2618 2619 Don'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, 2627 but some Autoconf macros may prepend extra libraries to this variable if 2628 those libraries are found and provide necessary functions, see 2629 @ref{Libraries}. @command{configure} uses this variable when linking 2630 programs to test for C, C++, Objective C, Objective C++, Fortran, and Go 2631 features. 2632 @end defvar 2633 2634 @defvar OBJCFLAGS 2635 @evindex OBJCFLAGS 2636 @ovindex OBJCFLAGS 2637 Debugging and optimization options for the Objective C compiler. It 2638 acts like @code{CFLAGS}, but for Objective C instead of C. 2639 @end defvar 2640 2641 @defvar OBJCXXFLAGS 2642 @evindex OBJCXXFLAGS 2643 @ovindex OBJCXXFLAGS 2644 Debugging and optimization options for the Objective C++ compiler. It 2645 acts like @code{CXXFLAGS}, but for Objective C++ instead of C++. 2646 @end defvar 2647 2648 @defvar GOFLAGS 2649 @evindex GOFLAGS 2650 @ovindex GOFLAGS 2651 Debugging 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 2657 Rigorously equal to @samp{.}. Added for symmetry only. 2658 @end defvar 2659 2660 @defvar abs_builddir 2661 @ovindex abs_builddir 2662 Absolute name of @code{builddir}. 2663 @end defvar 2664 2665 @defvar top_builddir 2666 @ovindex top_builddir 2667 The relative name of the top level of the current build tree. In the 2668 top-level directory, this is the same as @code{builddir}. 2669 @end defvar 2670 2671 @defvar top_build_prefix 2672 @ovindex top_build_prefix 2673 The relative name of the top level of the current build tree with final 2674 slash if nonempty. This is the same as @code{top_builddir}, except that 2675 it contains zero or more runs of @code{../}, so it should not be 2676 appended with a slash for concatenation. This helps for @command{make} 2677 implementations that otherwise do not treat @file{./file} and @file{file} 2678 as equal in the toplevel build directory. 2679 @end defvar 2680 2681 @defvar abs_top_builddir 2682 @ovindex abs_top_builddir 2683 Absolute name of @code{top_builddir}. 2684 @end defvar 2685 2686 @defvar srcdir 2687 @ovindex srcdir 2688 The name of the directory that contains the source code for 2689 that makefile. 2690 @end defvar 2691 2692 @defvar abs_srcdir 2693 @ovindex abs_srcdir 2694 Absolute name of @code{srcdir}. 2695 @end defvar 2696 2697 @defvar top_srcdir 2698 @ovindex top_srcdir 2699 The name of the top-level source code directory for the 2700 package. 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 2705 Absolute 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 2713 The following variables specify the directories for 2714 package installation, see @ref{Directory Variables, , Variables for 2715 Installation Directories, standards, The GNU Coding 2716 Standards}, for more information. Each variable corresponds to an 2717 argument of @command{configure}; trailing slashes are stripped so that 2718 expressions such as @samp{$@{prefix@}/lib} expand with only one slash 2719 between directory names. See the end of this section for 2720 details on when and how to use these variables. 2721 2722 @defvar bindir 2723 @ovindex bindir 2724 The directory for installing executables that users run. 2725 @end defvar 2726 2727 @defvar datadir 2728 @ovindex datadir 2729 The directory for installing idiosyncratic read-only 2730 architecture-independent data. 2731 @end defvar 2732 2733 @defvar datarootdir 2734 @ovindex datarootdir 2735 The root of the directory tree for read-only architecture-independent 2736 data files. 2737 @end defvar 2738 2739 @defvar docdir 2740 @ovindex docdir 2741 The directory for installing documentation files (other than Info and 2742 man). 2743 @end defvar 2744 2745 @defvar dvidir 2746 @ovindex dvidir 2747 The directory for installing documentation files in DVI format. 2748 @end defvar 2749 2750 @defvar exec_prefix 2751 @ovindex exec_prefix 2752 The installation prefix for architecture-dependent files. By default 2753 it's the same as @code{prefix}. You should avoid installing anything 2754 directly to @code{exec_prefix}. However, the default value for 2755 directories containing architecture-dependent files should be relative 2756 to @code{exec_prefix}. 2757 @end defvar 2758 2759 @defvar htmldir 2760 @ovindex htmldir 2761 The directory for installing HTML documentation. 2762 @end defvar 2763 2764 @defvar includedir 2765 @ovindex includedir 2766 The directory for installing C header files. 2767 @end defvar 2768 2769 @defvar infodir 2770 @ovindex infodir 2771 The directory for installing documentation in Info format. 2772 @end defvar 2773 2774 @defvar libdir 2775 @ovindex libdir 2776 The directory for installing object code libraries. 2777 @end defvar 2778 2779 @defvar libexecdir 2780 @ovindex libexecdir 2781 The directory for installing executables that other programs run. 2782 @end defvar 2783 2784 @defvar localedir 2785 @ovindex localedir 2786 The directory for installing locale-dependent but 2787 architecture-independent data, such as message catalogs. This directory 2788 usually has a subdirectory per locale. 2789 @end defvar 2790 2791 @defvar localstatedir 2792 @ovindex localstatedir 2793 The directory for installing modifiable single-machine data. 2794 @end defvar 2795 2796 @defvar mandir 2797 @ovindex mandir 2798 The top-level directory for installing documentation in man format. 2799 @end defvar 2800 2801 @defvar oldincludedir 2802 @ovindex oldincludedir 2803 The directory for installing C header files for non-GCC compilers. 2804 @end defvar 2805 2806 @defvar pdfdir 2807 @ovindex pdfdir 2808 The directory for installing PDF documentation. 2809 @end defvar 2810 2811 @defvar prefix 2812 @ovindex prefix 2813 The common installation prefix for all files. If @code{exec_prefix} 2814 is defined to a different value, @code{prefix} is used only for 2815 architecture-independent files. 2816 @end defvar 2817 2818 @defvar psdir 2819 @ovindex psdir 2820 The directory for installing PostScript documentation. 2821 @end defvar 2822 2823 @defvar sbindir 2824 @ovindex sbindir 2825 The directory for installing executables that system 2826 administrators run. 2827 @end defvar 2828 2829 @defvar sharedstatedir 2830 @ovindex sharedstatedir 2831 The directory for installing modifiable architecture-independent data. 2832 @end defvar 2833 2834 @defvar sysconfdir 2835 @ovindex sysconfdir 2836 The directory for installing read-only single-machine data. 2837 @end defvar 2838 2839 2840 Most of these variables have values that rely on @code{prefix} or 2841 @code{exec_prefix}. It is deliberate that the directory output 2842 variables keep them unexpanded: typically @samp{@@datarootdir@@} is 2843 replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}, and 2844 @samp{@@datadir@@} is replaced by @samp{$@{datarootdir@}}. 2845 2846 This behavior is mandated by the GNU Coding Standards, so that when 2847 the user runs: 2848 2849 @table @samp 2850 @item make 2851 she can still specify a different prefix from the one specified to 2852 @command{configure}, in which case, if needed, the package should hard 2853 code dependencies corresponding to the make-specified prefix. 2854 2855 @item make install 2856 she can specify a different installation location, in which case the 2857 package @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 2859 extremely important feature, as many people may decide to install all 2860 the files of a package grouped together, and then install links from 2861 the final locations to there. 2862 @end table 2863 2864 In order to support these features, it is essential that 2865 @code{datarootdir} remains defined as @samp{$@{prefix@}/share}, 2866 so that its value can be expanded based 2867 on the current value of @code{prefix}. 2868 2869 A corollary is that you should not use these variables except in 2870 makefiles. For instance, instead of trying to evaluate @code{datadir} 2871 in @file{configure} and hard-coding it in makefiles using 2872 e.g., @samp{AC_DEFINE_UNQUOTED([DATADIR], ["$datadir"], [Data directory.])}, 2873 you 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 2877 Similarly, you should not rely on @code{AC_CONFIG_FILES} to replace 2878 @code{bindir} and friends in your shell scripts and other files; instead, 2879 let @command{make} manage their replacement. For instance Autoconf 2880 ships templates of its shell scripts ending with @samp{.in}, and uses a 2881 makefile snippet similar to the following to build scripts like 2882 @command{autoheader} and @command{autom4te}: 2883 2884 @example 2885 @group 2886 edit = 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 2893 autoheader 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 2905 autoheader: $(srcdir)/autoheader.in 2906 autom4te: $(srcdir)/autom4te.in 2907 @end group 2908 @end example 2909 2910 Some details are noteworthy: 2911 2912 @table @asis 2913 @item @samp{@@bindir[@@]} 2914 The brackets prevent @command{configure} from replacing 2915 @samp{@@bindir@@} in the Sed expression itself. 2916 Brackets are preferable to a backslash here, since 2917 Posix says @samp{\@@} is not portable. 2918 2919 @item @samp{$(bindir)} 2920 Don't use @samp{@@bindir@@}! Use the matching makefile variable 2921 instead. 2922 2923 @item @samp{$(pkgdatadir)} 2924 The example takes advantage of the variable @samp{$(pkgdatadir)} 2925 provided by Automake; it is equivalent to @samp{$(datadir)/$(PACKAGE)}. 2926 2927 @item @samp{/} 2928 Don't use @samp{/} in the Sed expressions that replace file names since 2929 most likely the 2930 variables you use, such as @samp{$(bindir)}, contain @samp{/}. 2931 Use a shell metacharacter instead, such as @samp{|}. 2932 2933 @item special characters 2934 File names, file name components, and the value of @code{VPATH} should 2935 not contain shell metacharacters or white 2936 space. @xref{Special Chars in Variables}. 2937 2938 @item dependency on @file{Makefile} 2939 Since @code{edit} uses values that depend on the configuration specific 2940 values (@code{prefix}, etc.)@: and not only on @code{VERSION} and so forth, 2941 the output depends on @file{Makefile}, not @file{configure.ac}. 2942 2943 @item @samp{$@@} 2944 The main rule is generic, and uses @samp{$@@} extensively to 2945 avoid the need for multiple copies of the rule. 2946 2947 @item Separated dependencies and single suffix rules 2948 You can't use them! The above snippet cannot be (portably) rewritten 2949 as: 2950 2951 @example 2952 autoconf 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)} 2965 Be sure to specify the name of the source directory, 2966 otherwise the package won't support separated builds. 2967 @end table 2968 2969 For the more specific installation of Erlang libraries, the following variables 2970 are defined: 2971 2972 @defvar ERLANG_INSTALL_LIB_DIR 2973 @ovindex ERLANG_INSTALL_LIB_DIR 2974 @acindex{ERLANG_SUBST_INSTALL_LIB_DIR} 2975 The common parent directory of Erlang library installation directories. 2976 This variable is set by calling the @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR} 2977 macro 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} 2983 The installation directory for Erlang library @var{library}. 2984 This variable is set by using the 2985 @samp{AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR} 2986 macro 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 2996 In Autoconf 2.60, the set of directory variables has changed, and the 2997 defaults of some variables have been adjusted 2998 (@pxref{Installation Directory Variables}) to changes in the 2999 GNU Coding Standards. Notably, @file{datadir}, @file{infodir}, and 3000 @file{mandir} are now expressed in terms of @file{datarootdir}. If you are 3001 upgrading from an earlier Autoconf version, you may need to adjust your files 3002 to ensure that the directory variables are substituted correctly 3003 (@pxref{Defining Directories}), and that a definition of @file{datarootdir} is 3004 in place. For example, in a @file{Makefile.in}, adding 3005 3006 @example 3007 datarootdir = @@datarootdir@@ 3008 @end example 3009 3010 @noindent 3011 is usually sufficient. If you use Automake to create @file{Makefile.in}, 3012 it will add this for you. 3013 3014 To help with the transition, Autoconf warns about files that seem to use 3015 @code{datarootdir} without defining it. In some cases, it then expands 3016 the value of @code{$datarootdir} in substitutions of the directory 3017 variables. The following example shows such a warning: 3018 3019 @example 3020 $ @kbd{cat configure.ac} 3021 AC_INIT 3022 AC_CONFIG_FILES([Makefile]) 3023 AC_OUTPUT 3024 $ @kbd{cat Makefile.in} 3025 prefix = @@prefix@@ 3026 datadir = @@datadir@@ 3027 $ @kbd{autoconf} 3028 $ @kbd{configure} 3029 configure: creating ./config.status 3030 config.status: creating Makefile 3031 config.status: WARNING: 3032 Makefile.in seems to ignore the --datarootdir setting 3033 $ @kbd{cat Makefile} 3034 prefix = /usr/local 3035 datadir = $@{prefix@}/share 3036 @end example 3037 3038 Usually one can easily change the file to accommodate both older and newer 3039 Autoconf releases: 3040 3041 @example 3042 $ @kbd{cat Makefile.in} 3043 prefix = @@prefix@@ 3044 datarootdir = @@datarootdir@@ 3045 datadir = @@datadir@@ 3046 $ @kbd{configure} 3047 configure: creating ./config.status 3048 config.status: creating Makefile 3049 $ @kbd{cat Makefile} 3050 prefix = /usr/local 3051 datarootdir = $@{prefix@}/share 3052 datadir = $@{datarootdir@} 3053 @end example 3054 3055 @acindex{DATAROOTDIR_CHECKED} 3056 In some cases, however, the checks may not be able to detect that a suitable 3057 initialization of @code{datarootdir} is in place, or they may fail to detect 3058 that such an initialization is necessary in the output file. If, after 3059 auditing your package, there are still spurious @file{configure} warnings about 3060 @code{datarootdir}, you may add the line 3061 3062 @example 3063 AC_DEFUN([AC_DATAROOTDIR_CHECKED]) 3064 @end example 3065 3066 @noindent 3067 to your @file{configure.ac} to disable the warnings. This is an exception 3068 to 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 3078 You can support compiling a software package for several architectures 3079 simultaneously from the same copy of the source code. The object files 3080 for each architecture are kept in their own directory. 3081 3082 To support doing this, @command{make} uses the @code{VPATH} variable to 3083 find the files that are in the source directory. GNU Make 3084 can do this. Most other recent @command{make} programs can do this as 3085 well, though they may have difficulties and it is often simpler to 3086 recommend GNU @command{make} (@pxref{VPATH and Make}). Older 3087 @command{make} programs do not support @code{VPATH}; when using them, the 3088 source code must be in the same directory as the object files. 3089 3090 If you are using GNU Automake, the remaining details in this 3091 section are already covered for you, based on the contents of your 3092 @file{Makefile.am}. But if you are using Autoconf in isolation, then 3093 supporting @code{VPATH} requires the following in your 3094 @file{Makefile.in}: 3095 3096 @example 3097 srcdir = @@srcdir@@ 3098 VPATH = @@srcdir@@ 3099 @end example 3100 3101 Do not set @code{VPATH} to the value of another variable (@pxref{Variables 3102 listed in VPATH}. 3103 3104 @command{configure} substitutes the correct value for @code{srcdir} when 3105 it produces @file{Makefile}. 3106 3107 Do not use the @command{make} variable @code{$<}, which expands to the 3108 file name of the file in the source directory (found with @code{VPATH}), 3109 except in implicit rules. (An implicit rule is one such as @samp{.c.o}, 3110 which tells how to create a @file{.o} file from a @file{.c} file.) Some 3111 versions of @command{make} do not set @code{$<} in explicit rules; they 3112 expand it to an empty value. 3113 3114 Instead, Make command lines should always refer to source 3115 files by prefixing them with @samp{$(srcdir)/}. For example: 3116 3117 @example 3118 time.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 3127 You can put rules like the following in the top-level @file{Makefile.in} 3128 for a package to automatically update the configuration information when 3129 you change the configuration files. This example includes all of the 3130 optional files, such as @file{aclocal.m4} and those related to 3131 configuration header files. Omit from the @file{Makefile.in} rules for 3132 any of these files that your package does not use. 3133 3134 The @samp{$(srcdir)/} prefix is included because of limitations in the 3135 @code{VPATH} mechanism. 3136 3137 The @file{stamp-} files are necessary because the timestamps of 3138 @file{config.h.in} and @file{config.h} are not changed if remaking 3139 them does not change their contents. This feature avoids unnecessary 3140 recompilation. You should include the file @file{stamp-h.in} in your 3141 package'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 3146 conflicts, 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 3159 config.h: stamp-h 3160 stamp-h: config.h.in config.status 3161 ./config.status 3162 3163 Makefile: Makefile.in config.status 3164 ./config.status 3165 3166 config.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 3173 need to convert the indented lines to start with the tab character.) 3174 3175 In addition, you should use 3176 3177 @example 3178 AC_CONFIG_FILES([stamp-h], [echo timestamp > stamp-h]) 3179 @end example 3180 3181 @noindent 3182 so @file{config.status} ensures that @file{config.h} is considered up to 3183 date. @xref{Output}, for more information about @code{AC_OUTPUT}. 3184 3185 @xref{config.status Invocation}, for more examples of handling 3186 configuration-related dependencies. 3187 3188 @node Configuration Headers 3189 @section Configuration Header Files 3190 @cindex Configuration Header 3191 @cindex @file{config.h} 3192 3193 When a package contains more than a few tests that define C preprocessor 3194 symbols, the command lines to pass @option{-D} options to the compiler 3195 can get quite long. This causes two problems. One is that the 3196 @command{make} output is hard to visually scan for errors. More 3197 seriously, the command lines can exceed the length limits of some 3198 operating systems. As an alternative to passing @option{-D} options to 3199 the compiler, @command{configure} scripts can create a C header file 3200 containing @samp{#define} directives. The @code{AC_CONFIG_HEADERS} 3201 macro selects this kind of output. Though it can be called anywhere 3202 between @code{AC_INIT} and @code{AC_OUTPUT}, it is customary to call 3203 it right after @code{AC_INIT}. 3204 3205 The package should @samp{#include} the configuration header file before 3206 any other header files, to prevent inconsistencies in declarations (for 3207 example, if it redefines @code{const}). 3208 3209 To provide for VPATH builds, remember to pass the C compiler a @option{-I.} 3210 option (or @option{-I..}; whichever directory contains @file{config.h}). 3211 Even if you use @samp{#include "config.h"}, the preprocessor searches only 3212 the directory of the currently read file, i.e., the source directory, not 3213 the build directory. 3214 3215 With the appropriate @option{-I} option, you can use 3216 @samp{#include <config.h>}. Actually, it's a good habit to use it, 3217 because 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 3224 This macro is one of the instantiating macros; see @ref{Configuration 3225 Actions}. Make @code{AC_OUTPUT} create the file(s) in the 3226 blank-or-newline-separated list @var{header} containing C preprocessor 3227 @code{#define} statements, and replace @samp{@@DEFS@@} in generated 3228 files with @option{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}. 3229 The usual name for @var{header} is @file{config.h}. 3230 3231 If @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 3233 making some changes in the configuration without needlessly causing 3234 object files that depend on the header file to be recompiled. 3235 3236 Usually the input file is named @file{@var{header}.in}; however, you can 3237 override the input file name by appending to @var{header} a 3238 colon-separated list of input files. For example, you might need to make 3239 the input file name acceptable to DOS variants: 3240 3241 @example 3242 AC_CONFIG_HEADERS([config.h:config.hin]) 3243 @end example 3244 3245 @end defmac 3246 3247 @defmac AH_HEADER 3248 @ahindex{HEADER} 3249 This macro is defined as the name of the first declared config header 3250 and undefined if no config headers have been declared up to this point. 3251 A third-party macro may, for example, require use of a config header 3252 without invoking AC_CONFIG_HEADERS twice, like this: 3253 3254 @example 3255 AC_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 3275 Your distribution should contain a template file that looks as you want 3276 the final header file to look, including comments, with @code{#undef} 3277 statements which are used as hooks. For example, suppose your 3278 @file{configure.ac} makes these calls: 3279 3280 @example 3281 AC_CONFIG_HEADERS([conf.h]) 3282 AC_CHECK_HEADERS([unistd.h]) 3283 @end example 3284 3285 @noindent 3286 Then you could have code like the following in @file{conf.h.in}. 3287 The @file{conf.h} created by @command{configure} defines @samp{HAVE_UNISTD_H} 3288 to 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 3297 The format of the template file is stricter than what the C preprocessor 3298 is required to accept. A directive line should contain only whitespace, 3299 @samp{#undef}, and @samp{HAVE_UNISTD_H}. The use of @samp{#define} 3300 instead of @samp{#undef}, or of comments on the same line as 3301 @samp{#undef}, is strongly discouraged. Each hook should only be listed 3302 once. Other preprocessor lines, such as @samp{#ifdef} or 3303 @samp{#include}, are copied verbatim from the template into the 3304 generated header. 3305 3306 Since it is a tedious task to keep a template header up to date, you may 3307 use @command{autoheader} to generate it, see @ref{autoheader Invocation}. 3308 3309 During the instantiation of the header, each @samp{#undef} line in the 3310 template file for each symbol defined by @samp{AC_DEFINE} is changed to an 3311 appropriate @samp{#define}. If the corresponding @samp{AC_DEFINE} has not 3312 been executed during the @command{configure} run, the @samp{#undef} line is 3313 commented out. (This is important, e.g., for @samp{_POSIX_SOURCE}: 3314 on many systems, it can be implicitly defined by the compiler, and 3315 undefining it in the header would then break compilation of subsequent 3316 headers.) 3317 3318 Currently, @emph{all} remaining @samp{#undef} lines in the header 3319 template are commented out, whether or not there was a corresponding 3320 @samp{AC_DEFINE} for the macro name; but this behavior is not guaranteed 3321 for future releases of Autoconf. 3322 3323 Generally speaking, since you should not use @samp{#define}, and you 3324 cannot guarantee whether a @samp{#undef} directive in the header 3325 template will be converted to a @samp{#define} or commented out in the 3326 generated header file, the template file cannot be used for conditional 3327 definition 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 3338 you must place it outside of the template. 3339 If you absolutely need to hook it to the config header itself, please put 3340 the directives to a separate file, and @samp{#include} that file from the 3341 config header template. If you are using @command{autoheader}, you would 3342 probably 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 3349 The @command{autoheader} program can create a template file of C 3350 @samp{#define} statements for @command{configure} to use. 3351 It 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 3354 input file name, @command{autoheader} uses the first one.) 3355 3356 It is recommended that only one input file is used. If you want to append 3357 a boilerplate code, it is preferable to use 3358 @samp{AH_BOTTOM([#include <conf_post.h>])}. 3359 File @file{conf_post.h} is not processed during the configuration then, 3360 which make things clearer. Analogically, @code{AH_TOP} can be used to 3361 prepend a boilerplate code. 3362 3363 In order to do its job, @command{autoheader} needs you to document all 3364 of 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 3366 is 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 3369 suitable input file for a subsequent configuration header file. 3370 Symbols defined by Autoconf's builtin tests are already documented properly; 3371 you need to document only those that you 3372 define yourself. 3373 3374 You might wonder why @command{autoheader} is needed: after all, why 3375 would @command{configure} need to ``patch'' a @file{config.h.in} to 3376 produce a @file{config.h} instead of just creating @file{config.h} from 3377 scratch? Well, when everything rocks, the answer is just that we are 3378 wasting our time maintaining @command{autoheader}: generating 3379 @file{config.h} directly is all that is needed. When things go wrong, 3380 however, you'll be thankful for the existence of @command{autoheader}. 3381 3382 The 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 3384 well-defined list of symbols that should be defined (or not) is 3385 also important for people who are porting packages to environments where 3386 @command{configure} cannot be run: they just have to @emph{fill in the 3387 blanks}. 3388 3389 But let's come back to the point: the invocation of @command{autoheader}@dots{} 3390 3391 If you give @command{autoheader} an argument, it uses that file instead 3392 of @file{configure.ac} and writes the header file to the standard output 3393 instead of to @file{config.h.in}. If you give @command{autoheader} an 3394 argument 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 3402 Print a summary of the command line options and exit. 3403 3404 @item --version 3405 @itemx -V 3406 Print the version number of Autoconf and exit. 3407 3408 @item --verbose 3409 @itemx -v 3410 Report processing steps. 3411 3412 @item --debug 3413 @itemx -d 3414 Don't remove the temporary files. 3415 3416 @item --force 3417 @itemx -f 3418 Remake the template file even if newer than its input files. 3419 3420 @item --include=@var{dir} 3421 @itemx -I @var{dir} 3422 Append @var{dir} to the include path. Multiple invocations accumulate. 3423 3424 @item --prepend-include=@var{dir} 3425 @itemx -B @var{dir} 3426 Prepend @var{dir} to the include path. Multiple invocations accumulate. 3427 3428 @item --warnings=@var{category} 3429 @itemx -W @var{category} 3430 @evindex WARNINGS 3431 Report the warnings related to @var{category} (which can actually be a 3432 comma separated list). Current categories include: 3433 3434 @table @samp 3435 @item obsolete 3436 report the uses of obsolete constructs 3437 3438 @item all 3439 report all the warnings 3440 3441 @item none 3442 report none 3443 3444 @item error 3445 treats warnings as errors 3446 3447 @item no-@var{category} 3448 disable 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 3460 preprocessor symbols it might define. It knows how to generate 3461 templates for symbols defined by @code{AC_CHECK_HEADERS}, 3462 @code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional 3463 symbol, you must define a template for it. If there are missing 3464 templates, @command{autoheader} fails with an error message. 3465 3466 The template for a @var{symbol} is created 3467 by @command{autoheader} from 3468 the @var{description} argument to an @code{AC_DEFINE}; 3469 see @ref{Defining Symbols}. 3470 3471 For special needs, you can use the following macros. 3472 3473 3474 @defmac AH_TEMPLATE (@var{key}, @var{description}) 3475 @ahindex{TEMPLATE} 3476 Tell @command{autoheader} to generate a template for @var{key}. This macro 3477 generates standard templates just like @code{AC_DEFINE} when a 3478 @var{description} is given. 3479 3480 For example: 3481 3482 @example 3483 AH_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 3491 generates the following template, with the description properly 3492 justified. 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} 3505 Tell @command{autoheader} to include the @var{template} as-is in the header 3506 template file. This @var{template} is associated with the @var{key}, 3507 which is used to sort all the different templates and guarantee their 3508 uniqueness. 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} 3514 Include @var{text} at the top of the header template file. 3515 @end defmac 3516 3517 3518 @defmac AH_BOTTOM (@var{text}) 3519 @ahindex{BOTTOM} 3520 Include @var{text} at the bottom of the header template file. 3521 @end defmac 3522 3523 3524 Please note that @var{text} gets included ``verbatim'' to the template file, 3525 not to the resulting config header, so it can easily get mangled when the 3526 template is processed. There is rarely a need for something other than 3527 3528 @example 3529 AH_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 3539 You can execute arbitrary commands before, during, and after 3540 @file{config.status} is run. The three following macros accumulate the 3541 commands 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} 3548 Specify additional shell commands to run at the end of 3549 @file{config.status}, and shell commands to initialize any variables 3550 from @command{configure}. Associate the commands with @var{tag}. 3551 Since typically the @var{cmds} create a file, @var{tag} should 3552 naturally be the name of that file. If needed, the directory hosting 3553 @var{tag} is created. This macro is one of the instantiating macros; 3554 see @ref{Configuration Actions}. 3555 3556 Here is an unrealistic example: 3557 @example 3558 fubar=42 3559 AC_CONFIG_COMMANDS([fubar], 3560 [echo this is extra $fubar, and so on.], 3561 [fubar=$fubar]) 3562 @end example 3563 3564 Here is a better one: 3565 @example 3566 AC_CONFIG_COMMANDS([timestamp], [date >timestamp]) 3567 @end example 3568 @end defmac 3569 3570 The following two macros look similar, but in fact they are not of the same 3571 breed: 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} 3579 Execute the @var{cmds} right before creating @file{config.status}. 3580 3581 This 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} 3587 Execute 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 3598 You may find it convenient to create links whose destinations depend upon 3599 results of tests. One can use @code{AC_CONFIG_COMMANDS} but the 3600 creation of relative symbolic links can be delicate when the package is 3601 built 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 3608 Make @code{AC_OUTPUT} link each of the existing files @var{source} to 3609 the corresponding link name @var{dest}. Makes a symbolic link if 3610 possible, otherwise a hard link if possible, otherwise a copy. The 3611 @var{dest} and @var{source} names should be relative to the top level 3612 source or build directory. This macro is one of the instantiating 3613 macros; see @ref{Configuration Actions}. 3614 3615 For example, this call: 3616 3617 @example 3618 AC_CONFIG_LINKS([host.h:config/$machine.h 3619 object.h:config/$obj_format.h]) 3620 @end example 3621 3622 @noindent 3623 creates in the current directory @file{host.h} as a link to 3624 @file{@var{srcdir}/config/$machine.h}, and @file{object.h} as a 3625 link to @file{@var{srcdir}/config/$obj_format.h}. 3626 3627 The tempting value @samp{.} for @var{dest} is invalid: it makes it 3628 impossible for @samp{config.status} to guess the links to establish. 3629 3630 One can then run: 3631 @example 3632 ./config.status host.h object.h 3633 @end example 3634 @noindent 3635 to 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 3645 In most situations, calling @code{AC_OUTPUT} is sufficient to produce 3646 makefiles in subdirectories. However, @command{configure} scripts 3647 that control more than one independent package can use 3648 @code{AC_CONFIG_SUBDIRS} to run @command{configure} scripts for other 3649 packages in subdirectories. 3650 3651 @defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{}) 3652 @acindex{CONFIG_SUBDIRS} 3653 @ovindex subdirs 3654 Make @code{AC_OUTPUT} run @command{configure} in each subdirectory 3655 @var{dir} in the given blank-or-newline-separated list. Each @var{dir} should 3656 be 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. 3660 if test "x$package_foo_enabled" = xyes; then 3661 my_subdirs="$my_subdirs foo" 3662 fi 3663 AC_CONFIG_SUBDIRS([$my_subdirs]) 3664 @end example 3665 3666 @noindent 3667 because this prevents @samp{./configure --help=recursive} from 3668 displaying the options of the package @code{foo}. Instead, you should 3669 write: 3670 3671 @example 3672 if test "x$package_foo_enabled" = xyes; then 3673 AC_CONFIG_SUBDIRS([foo]) 3674 fi 3675 @end example 3676 3677 If a given @var{dir} is not found at @command{configure} run time, a 3678 warning is reported; if the subdirectory is optional, write: 3679 3680 @example 3681 if test -d "$srcdir/foo"; then 3682 AC_CONFIG_SUBDIRS([foo]) 3683 fi 3684 @end example 3685 3686 @c NB: Yes, below we mean configure.in, not configure.ac. 3687 If a given @var{dir} contains @command{configure.gnu}, it is run instead 3688 of @command{configure}. This is for packages that might use a 3689 non-Autoconf script @command{Configure}, which can't be called through a 3690 wrapper @command{configure} since it would be the same file on 3691 case-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 3695 The subdirectory @command{configure} scripts are given the same command 3696 line options that were given to this @command{configure} script, with minor 3697 changes if needed, which include: 3698 3699 @itemize @minus 3700 @item 3701 adjusting a relative name for the cache file; 3702 3703 @item 3704 adjusting a relative name for the source directory; 3705 3706 @item 3707 propagating the current value of @code{$prefix}, including if it was 3708 defaulted, and if the default values of the top level and of the subdirectory 3709 @file{configure} differ. 3710 @end itemize 3711 3712 This macro also sets the output variable @code{subdirs} to the list of 3713 directories @samp{@var{dir} @dots{}}. Make rules can use 3714 this variable to determine which subdirectories to recurse into. 3715 3716 This 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 3724 By default, @command{configure} sets the prefix for files it installs to 3725 @file{/usr/local}. The user of @command{configure} can select a different 3726 prefix using the @option{--prefix} and @option{--exec-prefix} options. 3727 There are two ways to change the default: when creating 3728 @command{configure}, and when running it. 3729 3730 Some 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} 3736 Set the default installation prefix to @var{prefix} instead of 3737 @file{/usr/local}. 3738 @end defmac 3739 3740 It may be convenient for users to have @command{configure} guess the 3741 installation prefix from the location of a related program that they 3742 have 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} 3748 If 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} 3751 is 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 3765 These macros test for particular system features that packages might 3766 need or want to use. If you need to test for a kind of feature that 3767 none of these macros check for, you can probably do it by calling 3768 primitive test macros with appropriate arguments (@pxref{Writing 3769 Tests}). 3770 3771 These tests print messages telling the user which feature they're 3772 checking for, and what they find. They cache their results for future 3773 @command{configure} runs (@pxref{Caching Results}). 3774 3775 Some of these macros set output variables. @xref{Makefile 3776 Substitutions}, for how to get their values. The phrase ``define 3777 @var{name}'' is used below as a shorthand to mean ``define the C 3778 preprocessor symbol @var{name} to the value 1''. @xref{Defining 3779 Symbols}, 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 3801 Much effort has been expended to make Autoconf easy to learn. The most 3802 obvious way to reach this goal is simply to enforce standard interfaces 3803 and behaviors, avoiding exceptions as much as possible. Because of 3804 history and inertia, unfortunately, there are still too many exceptions 3805 in Autoconf; nevertheless, this section describes some of the common 3806 rules. 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 3817 All the generic macros that @code{AC_DEFINE} a symbol as a result of 3818 their test transform their @var{argument} values to a standard alphabet. 3819 First, @var{argument} is converted to upper case and any asterisks 3820 (@samp{*}) are each converted to @samp{P}. Any remaining characters 3821 that are not alphanumeric are converted to underscores. 3822 3823 For instance, 3824 3825 @example 3826 AC_CHECK_TYPES([struct $Expensive*]) 3827 @end example 3828 3829 @noindent 3830 defines the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check 3831 succeeds. 3832 3833 3834 @node Default Includes 3835 @subsection Default Includes 3836 @cindex Default includes 3837 @cindex Includes, default 3838 3839 Several tests depend upon a set of header files. Since these headers 3840 are not universally available, tests actually have to provide a set of 3841 protected 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 3859 Unless you know exactly what you are doing, you should avoid using 3860 unconditional includes, and check the existence of the headers you 3861 include beforehand (@pxref{Header Files}). 3862 3863 Most generic macros use the following macro to provide the default set 3864 of includes: 3865 3866 @defmac AC_INCLUDES_DEFAULT (@ovar{include-directives}) 3867 @acindex{INCLUDES_DEFAULT} 3868 Expand 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 3908 If the default includes are used, then check for the presence of these 3909 headers and their compatibility, i.e., you don't need to run 3910 @code{AC_HEADER_STDC}, nor check for @file{stdlib.h} etc. 3911 3912 These headers are checked for in the same order as they are included. 3913 For instance, on some systems @file{string.h} and @file{strings.h} both 3914 exist, 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 3922 These macros check for the presence or behavior of particular programs. 3923 They are used to choose between several alternative programs and to 3924 decide what to do once one has been chosen. If there is no macro 3925 specifically defined to check for a program you need, and you don't need 3926 to check for any special properties of it, then you can use one of the 3927 general 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 3937 These macros check for particular programs---whether they exist, and 3938 in some cases whether they support certain features. 3939 3940 @defmac AC_PROG_AWK 3941 @acindex{PROG_AWK} 3942 @ovindex AWK 3943 @caindex prog_AWK 3944 Check for @code{gawk}, @code{mawk}, @code{nawk}, and @code{awk}, in that 3945 order, and set output variable @code{AWK} to the first one that is found. 3946 It tries @code{gawk} first because that is reported to be the 3947 best implementation. The result can be overridden by setting the 3948 variable @code{AWK} or the cache variable @code{ac_cv_prog_AWK}. 3949 3950 Using 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 3958 Look for the best available @code{grep} or @code{ggrep} that accepts the 3959 longest input lines possible, and that supports multiple @option{-e} options. 3960 Set the output variable @code{GREP} to whatever is chosen. 3961 @xref{grep, , Limitations of Usual Tools}, for more information about 3962 portability problems with the @command{grep} command family. The result 3963 can 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 3971 Check 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. 3973 Set the output variable @code{EGREP} to whatever is chosen. The result 3974 can 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 3982 Check 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. 3984 Set the output variable @code{FGREP} to whatever is chosen. The result 3985 can 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 3996 Set output variable @code{INSTALL} to the name of a BSD-compatible 3997 @command{install} program, if one is found in the current @env{PATH}. 3998 Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c}, 3999 checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its 4000 default directories) to determine @var{dir} (@pxref{Output}). Also set 4001 the 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 4005 configuration files. 4006 4007 This macro screens out various instances of @command{install} known not to 4008 work. It prefers to find a C program rather than a shell script, for 4009 speed. Instead of @file{install-sh}, it can also use @file{install.sh}, 4010 but that name is obsolete because some @command{make} programs have a rule 4011 that creates @file{install} from it if there is no makefile. Further, this 4012 macro requires @command{install} to be able to install multiple files into a 4013 target directory in a single invocation. 4014 4015 Autoconf comes with a copy of @file{install-sh} that you can use. If 4016 you 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 4019 them---even if the system you're on has a good @command{install} program. 4020 This check is a safety measure to prevent you from accidentally leaving 4021 that file out, which would prevent your package from installing on 4022 systems that don't have a BSD-compatible @command{install} program. 4023 4024 If you need to use your own installation program because it has features 4025 not 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 4029 The 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 4037 Set output variable @code{MKDIR_P} to a program that ensures that for 4038 each argument, a directory named by this argument exists, creating it 4039 and its parent directories if needed, and without race conditions when 4040 two instances of the program attempt to make the same directory at 4041 nearly the same time. 4042 4043 This macro uses the @samp{mkdir -p} command if possible. Otherwise, it 4044 falls back on invoking @command{install-sh} with the @option{-d} option, 4045 so your package should 4046 contain @file{install-sh} as described under @code{AC_PROG_INSTALL}. 4047 An @file{install-sh} file that predates Autoconf 2.60 or Automake 1.10 4048 is vulnerable to race conditions, so if you want to support parallel 4049 installs from 4050 different packages into the same directory you need to make sure you 4051 have an up-to-date @file{install-sh}. In particular, be careful about 4052 using @samp{autoreconf -if} if your Automake predates Automake 1.10. 4053 4054 This macro is related to the @code{AS_MKDIR_P} macro (@pxref{Programming 4055 in M4sh}), but it sets an output variable intended for use in other 4056 files, whereas @code{AS_MKDIR_P} is intended for use in scripts like 4057 @command{configure}. Also, @code{AS_MKDIR_P} does not accept options, 4058 but @code{MKDIR_P} supports the @option{-m} option, e.g., a makefile 4059 might invoke @code{$(MKDIR_P) -m 0 dir} to create an inaccessible 4060 directory, and conversely a makefile should use @code{$(MKDIR_P) -- 4061 $(FOO)} if @var{FOO} might yield a value that begins with @samp{-}. 4062 Finally, @code{AS_MKDIR_P} does not check for race condition 4063 vulnerability, whereas @code{AC_PROG_MKDIR_P} does. 4064 4065 @samp{@@MKDIR_P@@} is special, as its value may vary for different 4066 configuration files. 4067 4068 The 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 4080 If @code{flex} is found, set output variable @code{LEX} to @samp{flex} 4081 and @code{LEXLIB} to @option{-lfl}, if that library is in a standard 4082 place. Otherwise set @code{LEX} to @samp{lex} and @code{LEXLIB} to 4083 @option{-ll}, if found. If neither variant is available, set @code{LEX} 4084 to @samp{:}; for packages that ship the generated @file{file.yy.c} 4085 alongside the source @file{file.l}, this default allows users without a 4086 lexer generator to still build the package even if the timestamp for 4087 @file{file.l} is inadvertently changed. 4088 4089 Define @code{YYTEXT_POINTER} if @code{yytext} defaults to @samp{char *} instead 4090 of to @samp{char []}. Also set output variable @code{LEX_OUTPUT_ROOT} to 4091 the base of the file name that the lexer generates; usually 4092 @file{lex.yy}, but sometimes something else. These results vary 4093 according to whether @code{lex} or @code{flex} is being used. 4094 4095 You are encouraged to use Flex in your sources, since it is both more 4096 pleasant to use than plain Lex and the C source it produces is portable. 4097 In order to ensure portability, however, you must either provide a 4098 function @code{yywrap} or, if you don't use it (e.g., your scanner has 4099 no @samp{#include}-like feature), simply include a @samp{%noyywrap} 4100 statement in the scanner's source. Once this done, the scanner is 4101 portable (unless @emph{you} felt free to use nonportable constructs) and 4102 does not depend on any library. In this case, and in this case only, it 4103 is suggested that you use this Autoconf snippet: 4104 4105 @example 4106 AC_PROG_LEX 4107 if test "x$LEX" != xflex; then 4108 LEX="$SHELL $missing_dir/missing flex" 4109 AC_SUBST([LEX_OUTPUT_ROOT], [lex.yy]) 4110 AC_SUBST([LEXLIB], ['']) 4111 fi 4112 @end example 4113 4114 The shell script @command{missing} can be found in the Automake 4115 distribution. 4116 4117 Remember 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 4119 provided something sufficient by parsing the output of @samp{$LEX 4120 --version} than by simply relying on @code{test "x$LEX" = xflex}. 4121 4122 To 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 4125 of Automake will fix this issue; meanwhile, just ignore this message. 4126 4127 As part of running the test, this macro may delete any file in the 4128 configuration directory named @file{lex.yy.c} or @file{lexyy.c}. 4129 4130 The 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 4138 If @samp{ln -s} works on the current file system (the operating system 4139 and 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 4143 If you make a link in a directory other than the current directory, its 4144 meaning depends on whether @samp{ln} or @samp{ln -s} is used. To safely 4145 create links using @samp{$(LN_S)}, either find out which form is used 4146 and adjust the arguments, or always invoke @code{ln} in the directory 4147 where the link is to be created. 4148 4149 In other words, it does not work to do: 4150 @example 4151 $(LN_S) foo /x/bar 4152 @end example 4153 4154 Instead, 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 4166 Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib} 4167 is 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 4174 Set output variable @code{SED} to a Sed implementation that conforms to 4175 Posix and does not have arbitrary length limits. Report an error if no 4176 acceptable Sed is found. @xref{sed, , Limitations of Usual Tools}, for more 4177 information about portability problems with Sed. 4178 4179 The result of this test can be overridden by setting the @code{SED} variable 4180 and 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 4189 If @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}. 4192 The 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 4199 These macros are used to find programs not covered by the ``particular'' 4200 test macros. If you need to check the behavior of a program as well as 4201 find 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 4203 variable @env{PATH}. If you need to check for a program that might not 4204 be in the user's @env{PATH}, you can pass a modified path to use 4205 instead, like this: 4206 4207 @example 4208 AC_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 4213 You 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} 4223 Check whether program @var{prog-to-check-for} exists in @var{path}. If 4224 it 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 4226 absolute file name) even if it is the first found in the search path; in 4227 that 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} 4240 Check 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 4243 checking the next program in the list. If none of the programs in the 4244 list 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} 4246 is not changed. Calls @code{AC_SUBST} for @var{variable}. The result of 4247 this test can be overridden by setting the @var{variable} variable or the 4248 cache 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} 4254 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for} 4255 with a prefix of the target type as determined by 4256 @code{AC_CANONICAL_TARGET}, followed by a dash (@pxref{Canonicalizing}). 4257 If the tool cannot be found with a prefix, and if the build and target 4258 types are equal, then it is also searched for without a prefix. 4259 4260 As noted in @ref{Specifying Target Triplets}, the 4261 target is rarely specified, because most of the time it is the same 4262 as the host: it is the type of system for which any compiler tool in 4263 the package produces code. What this macro looks for is, 4264 for example, @emph{a tool @r{(assembler, linker, etc.)}@: that the 4265 compiler driver @r{(@command{gcc} for the GNU C Compiler)} 4266 uses 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} 4274 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for} 4275 with a prefix of the host type as specified by @option{--host}, followed by a 4276 dash. For example, if the user runs 4277 @samp{configure --build=x86_64-gnu --host=i386-gnu}, then this call: 4278 @example 4279 AC_CHECK_TOOL([RANLIB], [ranlib], [:]) 4280 @end example 4281 @noindent 4282 sets @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 4286 When cross-compiling, this macro will issue a warning if no program 4287 prefixed with the host type could be found. 4288 For 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} 4294 Like @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 4296 determined by @code{AC_CANONICAL_TARGET}, followed by a dash 4297 (@pxref{Canonicalizing}). If none of the tools can be found with a 4298 prefix, and if the build and target types are equal, then the first one 4299 without a prefix is used. If a tool is found, set @var{variable} to 4300 the name of that program. If none of the tools in the list are found, 4301 set @var{variable} to @var{value-if-not-found}; if @var{value-if-not-found} 4302 is 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} 4309 Like @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 4311 determined by @code{AC_CANONICAL_HOST}, followed by a dash 4312 (@pxref{Canonicalizing}). If none of the tools can be found with a 4313 prefix, then the first one without a prefix is used. If a tool is found, 4314 set @var{variable} to the name of that program. If none of the tools in 4315 the 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} 4317 is not changed. Calls @code{AC_SUBST} for @var{variable}. 4318 4319 When cross-compiling, this macro will issue a warning if no program 4320 prefixed with the host type could be found. 4321 For 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} 4329 Like @code{AC_CHECK_PROG}, but set @var{variable} to the absolute 4330 name of @var{prog-to-check-for} if found. The result of this test 4331 can be overridden by setting the @var{variable} variable. A positive 4332 result of this test is cached in the @code{ac_cv_path_@var{variable}} 4333 variable. 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} 4341 Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for} 4342 are found, set @var{variable} to the absolute name of the program 4343 found. The result of this test can be overridden by setting the 4344 @var{variable} variable. A positive result of this test is cached in 4345 the @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 4355 This macro was introduced in Autoconf 2.62. If @var{variable} is not 4356 empty, then set the cache variable @code{ac_cv_path_@var{variable}} to 4357 its value. Otherwise, check for each program in the blank-separated 4358 list @var{progs-to-check-for} existing in @var{path}. For each program 4359 found, execute @var{feature-test} with @code{ac_path_@var{variable}} 4360 set 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 4363 executed. @var{feature-test} will be run even when 4364 @code{ac_cv_path_@var{variable}} is set, to provide the ability to 4365 choose a better candidate found later in @var{path}; to accept the 4366 current setting and bypass all further checks, @var{feature-test} can 4367 execute @code{ac_path_@var{variable}_found=:}. 4368 4369 Note 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 4372 particular, @var{variable} is not set to the final value of 4373 @code{ac_cv_path_@var{variable}}, nor is @code{AC_SUBST} automatically 4374 run. 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 4378 Here is an example, similar to what Autoconf uses in its own configure 4379 script. It will search for an implementation of @command{m4} that 4380 supports 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 4384 AC_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])])]) 4390 AC_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} 4397 Like @code{AC_CHECK_TARGET_TOOL}, but set @var{variable} to the absolute 4398 name 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} 4404 Like @code{AC_CHECK_TOOL}, but set @var{variable} to the absolute 4405 name of the program if it is found. 4406 4407 When cross-compiling, this macro will issue a warning if no program 4408 prefixed with the host type could be found. 4409 For more information, see @ref{Specifying Target Triplets}. 4410 @end defmac 4411 4412 4413 @node Files 4414 @section Files 4415 @cindex File, checking 4416 4417 You might also need to check for the existence of files. Before using 4418 these macros, ask yourself whether a runtime test might not be a better 4419 solution. Be aware that, like most Autoconf macros, they test a feature 4420 of 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} 4426 Check whether file @var{file} exists on the native system. If it is 4427 found, execute @var{action-if-found}, otherwise do 4428 @var{action-if-not-found}, if given. The result of this test is cached 4429 in the @code{ac_cv_file_@var{file}} variable, with characters not 4430 suitable 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} 4437 Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}. 4438 Additionally, defines @samp{HAVE_@var{file}} (@pxref{Standard Symbols}) 4439 for 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 4441 a variable name mapped to underscores. 4442 @end defmac 4443 4444 4445 @node Libraries 4446 @section Library Files 4447 @cindex Library, checking 4448 4449 The following macros check for the presence of certain C, C++, Fortran, 4450 or 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} 4457 Test whether the library @var{library} is available by trying to link 4458 a test program that calls function @var{function} with the library. 4459 @var{function} should be a function provided by the library. 4460 Use the base 4461 name of the library; e.g., to check for @option{-lmp}, use @samp{mp} as 4462 the @var{library} argument. 4463 4464 @var{action-if-found} is a list of shell commands to run if the link 4465 with the library succeeds; @var{action-if-not-found} is a list of shell 4466 commands to run if the link fails. If @var{action-if-found} is not 4467 specified, the default action prepends @option{-l@var{library}} to 4468 @code{LIBS} and defines @samp{HAVE_LIB@var{library}} (in all 4469 capitals). This macro is intended to support building @code{LIBS} in 4470 a right-to-left (least-dependent to most-dependent) fashion such that 4471 library dependencies are satisfied as a natural side effect of 4472 consecutive tests. Linkers are sensitive to library ordering 4473 so the order in which @code{LIBS} is generated is important to reliable 4474 detection of libraries. 4475 4476 If linking with @var{library} results in unresolved symbols that would 4477 be resolved by linking with additional libraries, give those libraries 4478 as the @var{other-libraries} argument, separated by spaces: 4479 e.g., @option{-lXt -lX11}. Otherwise, this macro may fail to detect 4480 that @var{library} is present, because linking the test program can 4481 fail with unresolved symbols. The @var{other-libraries} argument 4482 should be limited to cases where it is desirable to test for one library 4483 in 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 4486 in some common cases. Many standard functions like @code{gethostbyname} 4487 appear in the standard C library on some hosts, and in special libraries 4488 like @code{nsl} on other hosts. On some hosts the special libraries 4489 contain variant implementations that you may not want to use. These 4490 days it is normally better to use @code{AC_SEARCH_LIBS([gethostbyname], 4491 [nsl])} instead of @code{AC_CHECK_LIB([nsl], [gethostbyname])}. 4492 4493 The 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} 4502 Search for a library defining @var{function} if it's not already 4503 available. This equates to calling 4504 @samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])])} first with 4505 no libraries, then for each library listed in @var{search-libs}. 4506 4507 Prepend @option{-l@var{library}} to @code{LIBS} for the first library found 4508 to contain @var{function}, and run @var{action-if-found}. If the 4509 function is not found, run @var{action-if-not-found}. 4510 4511 If linking with @var{library} results in unresolved symbols that would 4512 be resolved by linking with additional libraries, give those libraries 4513 as the @var{other-libraries} argument, separated by spaces: 4514 e.g., @option{-lXt -lX11}. Otherwise, this macro fails to detect 4515 that @var{function} is present, because linking the test program 4516 always fails with unresolved symbols. 4517 4518 The 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 4521 containing @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 4530 The following macros check for particular C library functions. 4531 If there is no macro specifically defined to check for a function you need, 4532 and you don't need to check for any special properties of 4533 it, 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 4546 Most usual functions can either be missing, or be buggy, or be limited 4547 on some architectures. This section tries to make an inventory of these 4548 portability issues. By definition, this list always requires 4549 additions. A much more complete list is maintained by the Gnulib 4550 project (@pxref{Gnulib}), covering @ref{Function Substitutes, , 4551 Current Posix Functions, gnulib, GNU gnulib}, @ref{Legacy Function 4552 Substitutes, , Legacy Functions, gnulib, GNU gnulib}, and @ref{Glibc 4553 Function Substitutes, , Glibc Functions, gnulib, GNU gnulib}. Please 4554 help 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} 4560 On ancient hosts, @code{exit} returned @code{int}. 4561 This is because @code{exit} predates @code{void}, and there was a long 4562 tradition of it returning @code{int}. 4563 4564 On current hosts, the problem more likely is that @code{exit} is not 4565 declared, due to C++ problems of some sort or another. For this reason 4566 we 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} 4572 The C standard says a call @code{free (NULL)} does nothing, but 4573 some 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} 4581 The C99 standard says that @code{isinf} and @code{isnan} are 4582 macros. On some systems just macros are available 4583 (e.g., HP-UX and Solaris 10), on 4584 some systems both macros and functions (e.g., glibc 2.3.2), and on some 4585 systems only functions (e.g., IRIX 6 and Solaris 9). In some cases 4586 these 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 4590 The C99 @code{isinf} and @code{isnan} macros work correctly with 4591 @code{long double} arguments, but pre-C99 systems that use functions 4592 typically assume @code{double} arguments. On such a system, 4593 @code{isinf} incorrectly returns true for a finite @code{long double} 4594 argument that is outside the range of @code{double}. 4595 4596 The best workaround for these issues is to use gnulib modules 4597 @code{isinf} and @code{isnan} (@pxref{Gnulib}). But a lighter weight 4598 solution 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)) 4608 static inline int isnan_f (float x) @{ return x != x; @} 4609 static inline int isnan_d (double x) @{ return x != x; @} 4610 static 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)) 4618 static inline int isinf_f (float x) 4619 @{ return !isnan (x) && isnan (x - x); @} 4620 static inline int isinf_d (double x) 4621 @{ return !isnan (x) && isnan (x - x); @} 4622 static inline int isinf_ld (long double x) 4623 @{ return !isnan (x) && isnan (x - x); @} 4624 #endif 4625 @end smallexample 4626 4627 Use @code{AC_C_INLINE} (@pxref{C Compiler}) so that this code works on 4628 compilers that lack the @code{inline} keyword. Some optimizing 4629 compilers mishandle these definitions, but systems with that bug 4630 typically have many other floating point corner-case compliance problems 4631 anyway, so it's probably not worth worrying about. 4632 4633 @item @code{malloc} 4634 @c @fuindex malloc 4635 @prindex @code{malloc} 4636 The C standard says a call @code{malloc (0)} is implementation 4637 dependent. It can return either @code{NULL} or a new non-null pointer. 4638 The latter is more common (e.g., the GNU C Library) but is by 4639 no means universal. @code{AC_FUNC_MALLOC} 4640 can be used to insist on non-@code{NULL} (@pxref{Particular Functions}). 4641 4642 @item @code{putenv} 4643 @c @fuindex putenv 4644 @prindex @code{putenv} 4645 Posix 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 4649 Posix specifies that @code{putenv} puts the given string directly in 4650 @code{environ}, but some systems make a copy of it instead (e.g., 4651 glibc 2.0, or BSD). And when a copy is made, @code{unsetenv} might 4652 not free it, causing a memory leak (e.g., FreeBSD 4). 4653 4654 On some systems @code{putenv ("FOO")} removes @samp{FOO} from the 4655 environment, but this is not standard usage and it dumps core 4656 on some systems (e.g., AIX). 4657 4658 On MinGW, a call @code{putenv ("FOO=")} removes @samp{FOO} from the 4659 environment, rather than inserting it with an empty value. 4660 4661 @item @code{realloc} 4662 @c @fuindex realloc 4663 @prindex @code{realloc} 4664 The C standard says a call @code{realloc (NULL, size)} is equivalent 4665 to @code{malloc (size)}, but some old systems don't support this (e.g., 4666 NextStep). 4667 4668 @item @code{signal} handler 4669 @c @fuindex signal 4670 @prindex @code{signal} 4671 @prindex @code{sigaction} 4672 Normally @code{signal} takes a handler function with a return type of 4673 @code{void}, but some old systems required @code{int} instead. Any 4674 actual @code{int} value returned is not used; this is only a 4675 difference in the function prototype demanded. 4676 4677 All 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 4679 available. The obsolete macro @code{AC_TYPE_SIGNAL} 4680 (@pxref{AC_TYPE_SIGNAL}) can be used to establish the correct type in 4681 all cases. 4682 4683 In most cases, it is more robust to use @code{sigaction} when it is 4684 available, 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} 4691 The C99 standard says that if the output array isn't big enough 4692 and if no other errors occur, @code{snprintf} and @code{vsnprintf} 4693 truncate the output and return the number of bytes that ought to have 4694 been produced. Some older systems return the truncated length (e.g., 4695 GNU 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 4697 length without truncation (e.g., 32-bit Solaris 7). Also, some buggy 4698 older systems ignore the length and overrun the buffer (e.g., 64-bit 4699 Solaris 7). 4700 4701 @item @code{sprintf} 4702 @c @fuindex sprintf 4703 @prindex @code{sprintf} 4704 @c @fuindex vsprintf 4705 @prindex @code{vsprintf} 4706 The C standard says @code{sprintf} and @code{vsprintf} return the 4707 number of bytes written. On some ancient systems (SunOS 4 for 4708 instance) they return the buffer pointer instead, but these no 4709 longer need to be worried about. 4710 4711 @item @code{sscanf} 4712 @c @fuindex sscanf 4713 @prindex @code{sscanf} 4714 On various old systems, e.g., HP-UX 9, @code{sscanf} requires 4715 that its 4716 input string be writable (though it doesn't actually change it). This 4717 can be a problem when using @command{gcc} since it normally puts 4718 constant strings in read-only memory (@pxref{Incompatibilities, 4719 Incompatibilities of GCC, , gcc, Using and 4720 Porting the GNU Compiler Collection}). Apparently in some cases even 4721 having format strings read-only can be a problem. 4722 4723 @item @code{strerror_r} 4724 @c @fuindex strerror_r 4725 @prindex @code{strerror_r} 4726 Posix specifies that @code{strerror_r} returns an @code{int}, but many 4727 systems (e.g., GNU C Library version 2.2.4) provide a 4728 different version returning a @code{char *}. @code{AC_FUNC_STRERROR_R} 4729 can detect which is in use (@pxref{Particular Functions}). 4730 4731 @item @code{strnlen} 4732 @c @fuindex strnlen 4733 @prindex @code{strnlen} 4734 AIX 4.3 provides a broken version which produces the 4735 following results: 4736 4737 @example 4738 strnlen ("foobar", 0) = 0 4739 strnlen ("foobar", 1) = 3 4740 strnlen ("foobar", 2) = 2 4741 strnlen ("foobar", 3) = 1 4742 strnlen ("foobar", 4) = 0 4743 strnlen ("foobar", 5) = 6 4744 strnlen ("foobar", 6) = 6 4745 strnlen ("foobar", 7) = 6 4746 strnlen ("foobar", 8) = 6 4747 strnlen ("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 4754 9) 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} 4760 The Posix spec says that @code{unlink} causes the given file to be 4761 removed only after there are no more open file handles for it. Some 4762 non-Posix hosts have trouble with this requirement, though, 4763 and some DOS variants even corrupt the file system. 4764 4765 @item @code{unsetenv} 4766 @c @fuindex unsetenv 4767 @prindex @code{unsetenv} 4768 On MinGW, @code{unsetenv} is not available, but a variable @samp{FOO} 4769 can 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} 4775 The C99 standard provides @code{va_copy} for copying 4776 @code{va_list} variables. It may be available in older environments 4777 too, though possibly as @code{__va_copy} (e.g., @command{gcc} in strict 4778 pre-C99 mode). These can be tested with @code{#ifdef}. A fallback to 4779 @code{memcpy (&dst, &src, sizeof (va_list))} gives maximum 4780 portability. 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 4787 not portable. Or it can be an array (e.g., @command{gcc} in some 4788 PowerPC configurations), which means as a function parameter it can be 4789 effectively call-by-reference and library routines might modify the 4790 value back in the caller (e.g., @code{vsnprintf} in the GNU C Library 4791 2.1). 4792 4793 @item Signed @code{>>} 4794 Normally the C @code{>>} right shift of a signed type replicates the 4795 high bit, giving a so-called ``arithmetic'' shift. But care should be 4796 taken since Standard C doesn't require that behavior. On those 4797 few processors without a native arithmetic shift (for instance Cray 4798 vector systems) zero bits may be shifted in, the same as a shift of an 4799 unsigned type. 4800 4801 @item Integer @code{/} 4802 C divides signed integers by truncating their quotient toward zero, 4803 yielding the same result as Fortran. However, before C99 the standard 4804 allowed C implementations to take the floor or ceiling of the quotient 4805 in some cases. Hardly any implementations took advantage of this 4806 freedom, though, and it's probably not worth worrying about this issue 4807 nowadays. 4808 @end table 4809 4810 4811 @node Particular Functions 4812 @subsection Particular Function Checks 4813 @cindex Function, checking 4814 4815 These macros check for particular C functions---whether they exist, and 4816 in 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 4828 Check how to get @code{alloca}. Tries to get a builtin version by 4829 checking for @file{alloca.h} or the predefined C preprocessor macros 4830 @code{__GNUC__} and @code{_AIX}. If this macro finds @file{alloca.h}, 4831 it defines @code{HAVE_ALLOCA_H}. 4832 4833 If those attempts fail, it looks for the function in the standard C 4834 library. 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 4838 garbage collect). This variable is separate from @code{LIBOBJS} so 4839 multiple programs can share the value of @code{ALLOCA} without needing 4840 to create an actual library, in case only some of them use the code in 4841 @code{LIBOBJS}. The @samp{$@{LIBOBJDIR@}} prefix serves the same 4842 purpose as in @code{LIBOBJS} (@pxref{AC_LIBOBJ vs LIBOBJS}). 4843 4844 This 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 4846 contain some incompatible functions that cause trouble. Some versions 4847 do not even contain @code{alloca} or contain a buggy version. If you 4848 still want to use their @code{alloca}, use @code{ar} to extract 4849 @file{alloca.o} from them instead of compiling @file{alloca.c}. 4850 4851 Source files that use @code{alloca} should start with a piece of code 4852 like 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 4876 extern "C" 4877 # endif 4878 void *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 4891 If the @code{chown} function is available and works (in particular, it 4892 should 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 4904 If the @code{closedir} function does not return a meaningful value, 4905 define @code{CLOSEDIR_VOID}. Otherwise, callers ought to check its 4906 return value for an error indicator. 4907 4908 Currently this test is implemented by running a test program. When 4909 cross compiling the pessimistic assumption that @code{closedir} does not 4910 return a meaningful value is made. 4911 4912 The result of this macro is cached in the @code{ac_cv_func_closedir_void} 4913 variable. 4914 4915 This macro is obsolescent, as @code{closedir} returns a meaningful value 4916 on 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 4924 If the @code{error_at_line} function is not found, require an 4925 @code{AC_LIBOBJ} replacement of @samp{error}. 4926 4927 The result of this macro is cached in the @code{ac_cv_lib_error_at_line} 4928 variable. 4929 4930 The @code{AC_FUNC_ERROR_AT_LINE} macro is obsolescent. New programs 4931 should 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 4939 If the @code{fnmatch} function conforms to Posix, define 4940 @code{HAVE_FNMATCH}. Detect common implementation bugs, for example, 4941 the bugs in Solaris 2.4. 4942 4943 Unlike the other specific 4944 @code{AC_FUNC} macros, @code{AC_FUNC_FNMATCH} does not replace a 4945 broken/missing @code{fnmatch}. This is for historical reasons. 4946 See @code{AC_REPLACE_FNMATCH} below. 4947 4948 The result of this macro is cached in the @code{ac_cv_func_fnmatch_works} 4949 variable. 4950 4951 This 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 4960 Behave like @code{AC_REPLACE_FNMATCH} (@emph{replace}) but also test 4961 whether @code{fnmatch} supports GNU extensions. Detect common 4962 implementation bugs, for example, the bugs in the GNU C 4963 Library 2.1. 4964 4965 The result of this macro is cached in the @code{ac_cv_func_fnmatch_gnu} 4966 variable. 4967 4968 This 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 4986 This macro checks for the @code{fork} and @code{vfork} functions. If a 4987 working @code{fork} is found, define @code{HAVE_WORKING_FORK}. This macro 4988 checks whether @code{fork} is just a stub by trying to run it. 4989 4990 If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working 4991 @code{vfork} is found, define @code{HAVE_WORKING_VFORK}. Otherwise, 4992 define @code{vfork} to be @code{fork} for backward compatibility with 4993 previous versions of @command{autoconf}. This macro checks for several known 4994 errors in implementations of @code{vfork} and considers the system to not 4995 have a working @code{vfork} if it detects any of them. It is not considered 4996 to be an implementation error if a child's invocation of @code{signal} 4997 modifies the parent's signal handler, since child processes rarely change 4998 their signal handlers. 4999 5000 Since this macro defines @code{vfork} only for backward compatibility with 5001 previous versions of @command{autoconf} you're encouraged to define it 5002 yourself 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 5011 The results of this macro are cached in the @code{ac_cv_func_fork_works} 5012 and @code{ac_cv_func_vfork_works} variables. In order to override the 5013 test, 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 5026 If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}. 5027 Define @code{_LARGEFILE_SOURCE} if necessary to make the prototype 5028 visible on some systems (e.g., glibc 2.2). Otherwise linkage problems 5029 may occur when compiling with @code{AC_SYS_LARGEFILE} on 5030 largefile-sensitive systems where @code{off_t} does not default to a 5031 64bit 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 5041 If the @code{getgroups} function is available and works (unlike on 5042 Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define 5043 @code{HAVE_GETGROUPS}. Set @code{GETGROUPS_LIBS} to any libraries 5044 needed 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} 5065 Check how to get the system load averages. To perform its tests 5066 properly, this macro needs the file @file{getloadavg.c}; therefore, be 5067 sure to set the @code{AC_LIBOBJ} replacement directory properly (see 5068 @ref{Generic Functions}, @code{AC_CONFIG_LIBOBJ_DIR}). 5069 5070 If the system has the @code{getloadavg} function, define 5071 @code{HAVE_GETLOADAVG}, and set @code{GETLOADAVG_LIBS} to any libraries 5072 necessary 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 5075 possibly define several other C preprocessor macros and output 5076 variables: 5077 5078 @enumerate 5079 @item 5080 Define @code{C_GETLOADAVG}. 5081 5082 @item 5083 Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on 5084 those systems. 5085 5086 @item 5087 @hdrindex{nlist.h} 5088 If @file{nlist.h} is found, define @code{HAVE_NLIST_H}. 5089 5090 @item 5091 If @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 5096 Programs 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} 5099 to @samp{true} (and otherwise to @samp{false}), and set 5100 @code{KMEM_GROUP} to the name of the group that should own the installed 5101 program. 5102 @end enumerate 5103 5104 The @code{AC_FUNC_GETLOADAVG} macro is obsolescent. New programs should 5105 use 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 5115 Check for @code{getmntent} in the standard C library, and then in the 5116 @file{sun}, @file{seq}, and @file{gen} libraries, for UNICOS, 5117 IRIX 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 5122 The 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 5134 Define @code{GETPGRP_VOID} if it is an error to pass 0 to 5135 @code{getpgrp}; this is the Posix behavior. On older BSD 5136 systems, you must pass 0 to @code{getpgrp}, as it takes an argument and 5137 behaves 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 5147 This macro does not check whether 5148 @code{getpgrp} exists at all; if you need to work in that situation, 5149 first call @code{AC_CHECK_FUNC} for @code{getpgrp}. 5150 5151 The result of this macro is cached in the @code{ac_cv_func_getpgrp_void} 5152 variable. 5153 5154 This macro is obsolescent, as current systems have a @code{getpgrp} 5155 whose 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 5164 If @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 5168 It is safe to assume that if @code{lstat} incorrectly ignores 5169 trailing slashes, then other symbolic-link-aware functions like 5170 @code{unlink} also incorrectly ignore trailing slashes. 5171 5172 If @code{lstat} behaves properly, define 5173 @code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an 5174 @code{AC_LIBOBJ} replacement of @code{lstat}. 5175 5176 The result of this macro is cached in the 5177 @code{ac_cv_func_lstat_dereferences_slashed_symlink} variable. 5178 5179 The @code{AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK} macro is obsolescent. 5180 New 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 5190 If the @code{malloc} function is compatible with the GNU C 5191 library @code{malloc} (i.e., @samp{malloc (0)} returns a valid 5192 pointer), 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 5195 native @code{malloc} is not used in the main project. 5196 5197 Typically, the replacement file @file{malloc.c} should look like (note 5198 the @samp{#undef malloc}): 5199 5200 @verbatim 5201 #include <config.h> 5202 #undef malloc 5203 5204 #include <sys/types.h> 5205 5206 void *malloc (); 5207 5208 /* Allocate an N-byte block of memory from the heap. 5209 If N is zero, allocate a 1-byte block. */ 5210 5211 void * 5212 rpl_malloc (size_t n) 5213 { 5214 if (n == 0) 5215 n = 1; 5216 return malloc (n); 5217 } 5218 @end verbatim 5219 5220 The 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 5230 Define @code{HAVE_MBRTOWC} to 1 if the function @code{mbrtowc} and the 5231 type @code{mbstate_t} are properly declared. 5232 5233 The result of this macro is cached in the @code{ac_cv_func_mbrtowc} 5234 variable. 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 5243 If the @code{memcmp} function is not available, or does not work on 5244 8-bit data (like the one on SunOS 4.1.3), or fails when comparing 16 5245 bytes or more and with at least one buffer not starting on a 4-byte 5246 boundary (such as the one on NeXT x86 OpenStep), require an 5247 @code{AC_LIBOBJ} replacement for @samp{memcmp}. 5248 5249 The result of this macro is cached in the 5250 @code{ac_cv_func_memcmp_working} variable. 5251 5252 This 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 5262 If the @code{mktime} function is not available, or does not work 5263 correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}. 5264 For the purposes of this test, @code{mktime} should conform to the 5265 Posix standard and should be the inverse of 5266 @code{localtime}. 5267 5268 The result of this macro is cached in the 5269 @code{ac_cv_func_working_mktime} variable. 5270 5271 The @code{AC_FUNC_MKTIME} macro is obsolescent. New programs should 5272 use 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 5282 If the @code{mmap} function exists and works correctly, define 5283 @code{HAVE_MMAP}. This checks only private fixed mapping of already-mapped 5284 memory. 5285 5286 The 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 5295 If the obstacks are found, define @code{HAVE_OBSTACK}, else require an 5296 @code{AC_LIBOBJ} replacement for @samp{obstack}. 5297 5298 The result of this macro is cached in the @code{ac_cv_func_obstack} 5299 variable. 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 5309 If the @code{realloc} function is compatible with the GNU C 5310 library @code{realloc} (i.e., @samp{realloc (NULL, 0)} returns a 5311 valid 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 5314 the native @code{realloc} is not used in the main project. See 5315 @code{AC_FUNC_MALLOC} for details. 5316 5317 The 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 5329 Determines the correct type to be passed for each of the 5330 @code{select} function's arguments, and defines those types 5331 in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and 5332 @code{SELECT_TYPE_ARG5} respectively. @code{SELECT_TYPE_ARG1} defaults 5333 to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *}, 5334 and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}. 5335 5336 This macro is obsolescent, as current systems have a @code{select} whose 5337 signature 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 5346 If @code{setpgrp} takes no argument (the Posix version), define 5347 @code{SETPGRP_VOID}. Otherwise, it is the BSD version, which takes 5348 two process IDs as arguments. This macro does not check whether 5349 @code{setpgrp} exists at all; if you need to work in that situation, 5350 first call @code{AC_CHECK_FUNC} for @code{setpgrp}. 5351 5352 The result of this macro is cached in the @code{ac_cv_func_setpgrp_void} 5353 variable. 5354 5355 This macro is obsolescent, as current systems have a @code{setpgrp} 5356 whose 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 5371 Determine whether @code{stat} or @code{lstat} have the bug that it 5372 succeeds when given the zero-length file name as argument. The @code{stat} 5373 and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do 5374 this. 5375 5376 If 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} 5378 replacement of it. 5379 5380 The 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 5384 These macros are obsolescent, as no current systems have the bug. 5385 New 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 5395 If 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 5398 definitions of @code{strcoll} that should not be used. 5399 5400 The result of this macro is cached in the @code{ac_cv_func_strcoll_works} 5401 variable. 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} 5412 If @code{strerror_r} is available, define @code{HAVE_STRERROR_R}, and if 5413 it is declared, define @code{HAVE_DECL_STRERROR_R}. If it returns a 5414 @code{char *} message, define @code{STRERROR_R_CHAR_P}; otherwise it 5415 returns an @code{int} error number. The Thread-Safe Functions option of 5416 Posix requires @code{strerror_r} to return @code{int}, but 5417 many systems (including, for example, version 2.2.4 of the GNU C 5418 Library) return a @code{char *} value that is not necessarily equal to 5419 the buffer argument. 5420 5421 The 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} 5431 Check for @code{strftime} in the @file{intl} library, for SCO Unix. 5432 Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}. 5433 5434 This macro is obsolescent, as no current systems require the @file{intl} 5435 library 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 5445 If the @code{strtod} function does not exist or doesn't work correctly, 5446 ask for an @code{AC_LIBOBJ} replacement of @samp{strtod}. In this case, 5447 because @file{strtod.c} is likely to need @samp{pow}, set the output 5448 variable @code{POW_LIB} to the extra library needed. 5449 5450 This macro caches its result in the @code{ac_cv_func_strtod} variable 5451 and depends upon the result in the @code{ac_cv_func_pow} variable. 5452 5453 The @code{AC_FUNC_STRTOD} macro is obsolescent. New programs should 5454 use 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 5462 If the @code{strtold} function exists and conforms to C99, define 5463 @code{HAVE_STRTOLD}. 5464 5465 This 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 5474 If the @code{strnlen} function is not available, or is buggy (like the one 5475 from AIX 4.3), require an @code{AC_LIBOBJ} replacement for it. 5476 5477 This macro caches its result in the @code{ac_cv_func_strnlen_working} 5478 variable. 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 5488 If @samp{utime (@var{file}, NULL)} sets @var{file}'s timestamp to 5489 the present, define @code{HAVE_UTIME_NULL}. 5490 5491 This macro caches its result in the @code{ac_cv_func_utime_null} 5492 variable. 5493 5494 This macro is obsolescent, as all current systems have a @code{utime} 5495 that 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} 5507 If @code{vprintf} is found, define @code{HAVE_VPRINTF}. Otherwise, if 5508 @code{_doprnt} is found, define @code{HAVE_DOPRNT}. (If @code{vprintf} 5509 is available, you may assume that @code{vfprintf} and @code{vsprintf} 5510 are also available.) 5511 5512 This macro is obsolescent, as all current systems have @code{vprintf}. 5513 New 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 5522 If the @code{fnmatch} function does not conform to Posix (see 5523 @code{AC_FUNC_FNMATCH}), ask for its @code{AC_LIBOBJ} replacement. 5524 5525 The files @file{fnmatch.c}, @file{fnmatch_loop.c}, and @file{fnmatch_.h} 5526 in the @code{AC_LIBOBJ} replacement directory are assumed to contain a 5527 copy of the source code of GNU @code{fnmatch}. If necessary, 5528 this 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 5530 included in place of the system @code{<fnmatch.h>}. 5531 5532 This macro caches its result in the @code{ac_cv_func_fnmatch_works} 5533 variable. 5534 5535 This macro is obsolescent, as it assumes the use of particular source 5536 files. New programs should use Gnulib's @code{fnmatch-posix} module, 5537 which 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 5545 These macros are used to find functions not covered by the ``particular'' 5546 test macros. If the functions might be in libraries other than the 5547 default C library, first call @code{AC_CHECK_LIB} for those libraries. 5548 If you need to check the behavior of a function as well as find out 5549 whether it is present, you have to write your own test for 5550 it (@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} 5557 If C function @var{function} is available, run shell commands 5558 @var{action-if-found}, otherwise @var{action-if-not-found}. If you just 5559 want to define a symbol if the function is available, consider using 5560 @code{AC_CHECK_FUNCS} instead. This macro checks for functions with C 5561 linkage even when @code{AC_LANG(C++)} has been called, since C is more 5562 standardized than C++. (@pxref{Language Choice}, for more information 5563 about selecting the language for checks.) 5564 5565 This macro caches its result in the @code{ac_cv_func_@var{function}} 5566 variable. 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} 5574 For each @var{function} enumerated in the blank-or-newline-separated argument 5575 list, define @code{HAVE_@var{function}} (in all capitals) if it is available. 5576 If @var{action-if-found} is given, it is additional shell code to 5577 execute 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 5580 functions is not found. 5581 5582 Results 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} 5588 For each @var{function} enumerated in the blank-or-newline-separated argument 5589 list, define @code{HAVE_@var{function}} (in all capitals) if it is available. 5590 This is a once-only variant of @code{AC_CHECK_FUNCS}. It generates the 5591 checking code at most once, so that @command{configure} is smaller and 5592 faster; but the checks cannot be conditionalized and are always done once, 5593 early during the @command{configure} run. 5594 @end defmac 5595 5596 @sp 1 5597 5598 Autoconf follows a philosophy that was formed over the years by those 5599 who have struggled for portability: isolate the portability issues in 5600 specific files, and then program as if you were in a Posix 5601 environment. Some functions may be missing or unfixable, and your 5602 package must be ready to replace them. 5603 5604 Suitable replacements for many such problem functions are available from 5605 Gnulib (@pxref{Gnulib}). 5606 5607 @defmac AC_LIBOBJ (@var{function}) 5608 @acindex{LIBOBJ} 5609 @ovindex LIBOBJS 5610 Specify that @samp{@var{function}.c} must be included in the executables 5611 to replace a missing or broken implementation of @var{function}. 5612 5613 @vrindex ac_objext 5614 Technically, it adds @samp{@var{function}.$ac_objext} to the output 5615 variable @code{LIBOBJS} if it is not already in, and calls 5616 @code{AC_LIBSOURCE} for @samp{@var{function}.c}. You should not 5617 directly change @code{LIBOBJS}, since this is not traceable. 5618 @end defmac 5619 5620 @defmac AC_LIBSOURCE (@var{file}) 5621 @acindex{LIBSOURCE} 5622 Specify that @var{file} might be needed to compile the project. If you 5623 need to know what files might be needed by a @file{configure.ac}, you 5624 should trace @code{AC_LIBSOURCE}. @var{file} must be a literal. 5625 5626 This macro is called automatically from @code{AC_LIBOBJ}, but you must 5627 call it explicitly if you pass a shell variable to @code{AC_LIBOBJ}. In 5628 that case, since shell variables cannot be traced statically, you must 5629 pass to @code{AC_LIBSOURCE} any possible files that the shell variable 5630 might cause @code{AC_LIBOBJ} to need. For example, if you want to pass 5631 a variable @code{$foo_or_bar} to @code{AC_LIBOBJ} that holds either 5632 @code{"foo"} or @code{"bar"}, you should do: 5633 5634 @example 5635 AC_LIBSOURCE([foo.c]) 5636 AC_LIBSOURCE([bar.c]) 5637 AC_LIBOBJ([$foo_or_bar]) 5638 @end example 5639 5640 @noindent 5641 There is usually a way to avoid this, however, and you are encouraged to 5642 simply call @code{AC_LIBOBJ} with literal arguments. 5643 5644 Note that this macro replaces the obsolete @code{AC_LIBOBJ_DECL}, with 5645 slightly different semantics: the old macro took the function name, 5646 e.g., @code{foo}, as its argument rather than the file name. 5647 @end defmac 5648 5649 @defmac AC_LIBSOURCES (@var{files}) 5650 @acindex{LIBSOURCES} 5651 Like @code{AC_LIBSOURCE}, but accepts one or more @var{files} in a 5652 comma-separated M4 list. Thus, the above example might be rewritten: 5653 5654 @example 5655 AC_LIBSOURCES([foo.c, bar.c]) 5656 AC_LIBOBJ([$foo_or_bar]) 5657 @end example 5658 @end defmac 5659 5660 @defmac AC_CONFIG_LIBOBJ_DIR (@var{directory}) 5661 @acindex{CONFIG_LIBOBJ_DIR} 5662 Specify that @code{AC_LIBOBJ} replacement files are to be found in 5663 @var{directory}, a name relative to the top level of the 5664 source tree. The replacement directory defaults to @file{.}, the top 5665 level directory, and the most typical value is @file{lib}, corresponding 5666 to @samp{AC_CONFIG_LIBOBJ_DIR([lib])}. 5667 5668 @command{configure} might need to know the replacement directory for the 5669 following reasons: (i) some checks use the replacement files, (ii) some 5670 macros bypass broken system headers by installing links to the 5671 replacement headers (iii) when used in conjunction with Automake, 5672 within each makefile, @var{directory} is used as a relative path 5673 from @code{$(top_srcdir)} to each object named in @code{LIBOBJS} and 5674 @code{LTLIBOBJS}, etc. 5675 @end defmac 5676 5677 @sp 1 5678 5679 It is common to merely check for the existence of a function, and ask 5680 for its @code{AC_LIBOBJ} replacement if missing. The following macro is 5681 a convenient shorthand. 5682 5683 @defmac AC_REPLACE_FUNCS (@var{function}@dots{}) 5684 @acindex{REPLACE_FUNCS} 5685 @cvindex HAVE_@var{function} 5686 @ovindex LIBOBJS 5687 Like @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 5689 enclosing the prototype in @samp{#ifndef HAVE_@var{function}}. If the 5690 system has the function, it probably declares it in a header file you 5691 should be including, so you shouldn't redeclare it lest your declaration 5692 conflict. 5693 @end defmac 5694 5695 @node Header Files 5696 @section Header Files 5697 @cindex Header, checking 5698 5699 The following macros check for the presence of certain C header files. 5700 If there is no macro specifically defined to check for a header file you need, 5701 and you don't need to check for any special properties of 5702 it, 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 5715 This section documents some collected knowledge about common headers, 5716 and the problems they cause. By definition, this list always requires 5717 additions. A much more complete list is maintained by the Gnulib 5718 project (@pxref{Gnulib}), covering @ref{Header File Substitutes, , 5719 Posix Headers, gnulib, GNU gnulib} and @ref{Glibc Header File 5720 Substitutes, , Glibc Headers, gnulib, GNU gnulib}. Please help us keep 5721 the gnulib list as complete as possible. 5722 5723 @table @asis 5724 5725 @item @file{limits.h} 5726 C99 says that @file{limits.h} defines @code{LLONG_MIN}, 5727 @code{LLONG_MAX}, and @code{ULLONG_MAX}, but many almost-C99 5728 environments (e.g., default GCC 4.0.2 + glibc 2.4) do not 5729 define them. 5730 5731 @item @file{inttypes.h} vs.@: @file{stdint.h} 5732 @hdrindex{inttypes.h} 5733 @hdrindex{stdint.h} 5734 The C99 standard says that @file{inttypes.h} includes 5735 @file{stdint.h}, so there's no need to include @file{stdint.h} 5736 separately in a standard environment. Some implementations have 5737 @file{inttypes.h} but not @file{stdint.h} (e.g., Solaris 7), but we don't 5738 know 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} 5743 It requires @file{linux/types.h} and @file{sys/socket.h}. 5744 5745 @item @file{linux/random.h} 5746 @hdrindex{linux/random.h} 5747 It requires @file{linux/types.h}. 5748 5749 @item @file{net/if.h} 5750 @hdrindex{net/if.h} 5751 On Darwin, this file requires that @file{sys/socket.h} be included 5752 beforehand. One should run: 5753 5754 @example 5755 AC_CHECK_HEADERS([sys/socket.h]) 5756 AC_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} 5774 On Darwin, this file requires that @file{stdio.h} and 5775 @file{sys/socket.h} be included beforehand. One should run: 5776 5777 @example 5778 AC_CHECK_HEADERS([sys/socket.h]) 5779 AC_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} 5796 See above, item @file{inttypes.h} vs.@: @file{stdint.h}. 5797 5798 @item @file{stdlib.h} 5799 @hdrindex{stdlib.h} 5800 On many systems (e.g., Darwin), @file{stdio.h} is a prerequisite. 5801 5802 @item @file{sys/mount.h} 5803 @hdrindex{sys/mount.h} 5804 On 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} 5809 On Solaris 8, @file{sys/stream.h} is a prerequisite. 5810 5811 @item @file{sys/socket.h} 5812 @hdrindex{sys/socket.h} 5813 On Darwin, @file{stdlib.h} is a prerequisite. 5814 5815 @item @file{sys/ucred.h} 5816 @hdrindex{sys/ucred.h} 5817 On Tru64 5.1, @file{sys/types.h} is a prerequisite. 5818 5819 @item @file{X11/extensions/scrnsaver.h} 5820 @hdrindex{X11/extensions/scrnsaver.h} 5821 Using XFree86, this header requires @file{X11/Xlib.h}, which is probably 5822 so required that you might not even consider looking for it. 5823 5824 @example 5825 AC_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 5835 These macros check for particular system header files---whether they 5836 exist, 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 5843 Check whether @file{stdbool.h} exists and conforms to C99, and cache the 5844 result in the @code{ac_cv_header_stdbool_h} variable. If the type 5845 @code{_Bool} is defined, define @code{HAVE__BOOL} to 1. 5846 5847 This macro is intended for use by Gnulib (@pxref{Gnulib}) and other 5848 packages that supply a substitute @file{stdbool.h} on platforms lacking 5849 a conforming one. The @code{AC_HEADER_STDBOOL} macro is better for code 5850 that 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} 5857 Check whether to enable assertions in the style of @file{assert.h}. 5858 Assertions are enabled by default, but the user can override this by 5859 invoking @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} 5873 Check for the following header files. For the first one that is 5874 found 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 5883 The directory-library declarations in your source code should look 5884 something 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 5908 Using the above declarations, the program would declare variables to be 5909 of type @code{struct dirent}, not @code{struct direct}, and would access 5910 the length of a directory entry name by passing a pointer to a 5911 @code{struct dirent} to the @code{NAMLEN} macro. 5912 5913 This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries. 5914 5915 This macro is obsolescent, as all current systems with directory 5916 libraries have @code{<dirent.h>}. New programs need not use this macro. 5917 5918 Also 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} 5929 If @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} 5939 Checks for header @file{resolv.h}, checking for prerequisites first. 5940 To properly use @file{resolv.h}, your code should contain something like 5941 the 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} 5965 If the macros @code{S_ISDIR}, @code{S_ISREG}, etc.@: defined in 5966 @file{sys/stat.h} do not work properly (returning false positives), 5967 define @code{STAT_MACROS_BROKEN}. This is the case on Tektronix UTekV, 5968 Amdahl UTS and Motorola System V/88. 5969 5970 This macro is obsolescent, as no current systems have the bug. 5971 New 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 5980 If @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 5983 program 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 5992 typedef 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 6005 Alternatively 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 6008 platforms. 6009 6010 This macro caches its result in the @code{ac_cv_header_stdbool_h} 6011 variable. 6012 6013 This macro differs from @code{AC_CHECK_HEADER_STDBOOL} only in that it 6014 defines @code{HAVE_STDBOOL_H} whereas @code{AC_CHECK_HEADER_STDBOOL} 6015 does 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 6028 Define @code{STDC_HEADERS} if the system has C header files 6029 conforming to ANSI C89 (ISO C90). 6030 Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h}, 6031 @file{string.h}, and @file{float.h}; if the system has those, it 6032 probably has the rest of the C89 header files. This macro also 6033 checks whether @file{string.h} declares @code{memchr} (and thus 6034 presumably the other @code{mem} functions), whether @file{stdlib.h} 6035 declare @code{free} (and thus presumably @code{malloc} and other related 6036 functions), and whether the @file{ctype.h} macros work on characters 6037 with the high bit set, as the C standard requires. 6038 6039 If you use this macro, your code can refer to @code{STDC_HEADERS} to 6040 determine whether the system has conforming header files (and probably C 6041 library functions). 6042 6043 This macro caches its result in the @code{ac_cv_header_stdc} variable. 6044 6045 This macro is obsolescent, as current systems have conforming header 6046 files. New programs need not use this macro. 6047 6048 @hdrindex{string.h} 6049 @hdrindex{strings.h} 6050 Nowadays @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 6052 BSD functions like @code{bcopy}; but 6053 historically, string functions were a major sticking point in this area. 6054 If you still want to worry about portability to ancient systems without 6055 standard headers, there is so much variation 6056 that it is probably easier to declare the functions you use than to 6057 figure out exactly what the system header files declare. Some ancient systems 6058 contained a mix of functions from the C standard and from BSD; 6059 some were mostly standard but lacked @samp{memmove}; some defined the 6060 BSD 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}, 6063 some in @file{string.h}; etc. It is probably sufficient to check for 6064 one string function and one memory function; if the library had the 6065 standard versions of those then it probably had most of the others. 6066 If you put the following in @file{configure.ac}: 6067 6068 @example 6069 # This example is obsolescent. 6070 # Nowadays you can omit these macro calls. 6071 AC_HEADER_STDC 6072 AC_CHECK_FUNCS([strchr memcpy]) 6073 @end example 6074 6075 @noindent 6076 then, 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 6089 char *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 6099 If you use a function like @code{memchr}, @code{memset}, @code{strtok}, 6100 or @code{strspn}, which have no BSD equivalent, then macros don't 6101 suffice to port to ancient hosts; you must provide an implementation of 6102 each function. An easy 6103 way to incorporate your implementations only when needed (since the ones 6104 in system C libraries may be hand optimized) is to, taking @code{memchr} 6105 for 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 6114 If @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} 6116 does not exist, or if it uses the old BSD @code{union wait} instead 6117 of @code{int} to store a status value. If @file{sys/wait.h} is not 6118 Posix compatible, then instead of including it, define the 6119 Posix macros with their usual interpretations. Here is an 6120 example: 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 6138 This macro caches its result in the @code{ac_cv_header_sys_wait_h} 6139 variable. 6140 6141 This macro is obsolescent, as current systems are compatible with Posix. 6142 New 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 6148 Posix systems. If there is no @file{unistd.h}, it is definitely 6149 not a Posix system. However, some non-Posix systems do 6150 have @file{unistd.h}. 6151 6152 The 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 6174 If a program may include both @file{time.h} and @file{sys/time.h}, 6175 define @code{TIME_WITH_SYS_TIME}. On some ancient systems, 6176 @file{sys/time.h} included @file{time.h}, but @file{time.h} was not 6177 protected against multiple inclusion, so programs could not explicitly 6178 include both files. This macro is useful in programs that use, for 6179 example, @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 6200 This macro caches its result in the @code{ac_cv_header_time} variable. 6201 6202 This macro is obsolescent, as current systems can include both files 6203 when 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. 6213 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then 6214 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be 6215 found in @file{<termios.h>}. 6216 6217 Use: 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 6235 These 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 6237 as well as find out whether it is present, you have to write your own 6238 test 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} 6245 If the system header file @var{header-file} is compilable, execute shell 6246 commands @var{action-if-found}, otherwise execute 6247 @var{action-if-not-found}. If you just want to define a symbol if the 6248 header file is available, consider using @code{AC_CHECK_HEADERS} 6249 instead. 6250 6251 @var{includes} is decoded to determine the appropriate include 6252 directives. If omitted or empty, @file{configure} will check for both header 6253 existence (with the preprocessor) and usability (with the compiler), 6254 using @code{AC_INCLUDES_DEFAULT} for the compile test. If 6255 there is a discrepancy between the results, a warning is issued to the 6256 user, and the compiler results are favored (@pxref{Present But 6257 Cannot Be Compiled}). In general, favoring the compiler results means 6258 that a header will be treated as not found even though the file exists, 6259 because you did not provide enough prerequisites. 6260 6261 Providing a non-empty @var{includes} argument allows the code to provide 6262 any prerequisites prior to including the header under test; it is common 6263 to use the argument @code{AC_INCLUDES_DEFAULT} (@pxref{Default 6264 Includes}). With an explicit fourth argument, no preprocessor test is 6265 needed. As a special case, an @var{includes} of exactly @samp{-} 6266 triggers the older preprocessor check, which merely determines existence 6267 of the file in the preprocessor search path; this should only be used as 6268 a last resort (it is safer to determine the actual prerequisites and 6269 perform a compiler check, or else use @code{AC_PREPROC_IFELSE} to make 6270 it obvious that only a preprocessor check is desired). 6271 6272 This macro caches its result in the @code{ac_cv_header_@var{header-file}} 6273 variable, with characters not suitable for a variable name mapped to 6274 underscores. 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} 6284 For each given system header file @var{header-file} in the 6285 blank-separated argument list that exists, define 6286 @code{HAVE_@var{header-file}} (in all capitals). If @var{action-if-found} 6287 is given, it is additional shell code to execute when one of the header 6288 files is found. You can give it a value of @samp{break} to break out of 6289 the loop on the first match. If @var{action-if-not-found} is given, it 6290 is 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 6293 choose the set of preprocessor directives supplied before the header 6294 under test. 6295 6296 This macro caches its result in the @code{ac_cv_header_@var{header-file}} 6297 variable, with characters not suitable for a variable name mapped to 6298 underscores. 6299 @end defmac 6300 6301 Previous versions of Autoconf merely checked whether the header was 6302 accepted by the preprocessor. This was changed because the old test was 6303 inappropriate for typical uses. Headers are typically used to compile, 6304 not merely to preprocess, and the old behavior sometimes accepted 6305 headers that clashed at compile-time (@pxref{Present But Cannot Be 6306 Compiled}). If you need to check whether a header is preprocessable, 6307 you can use @code{AC_PREPROC_IFELSE} (@pxref{Running the Preprocessor}). 6308 6309 Actually requiring a header to compile improves the robustness of the 6310 test, but it also requires 6311 that you make sure that headers that must be included before the 6312 @var{header-file} be part of the @var{includes}, (@pxref{Default 6313 Includes}). If looking for @file{bar.h}, which requires that 6314 @file{foo.h} be included before if it exists, we suggest the following 6315 scheme: 6316 6317 @verbatim 6318 AC_CHECK_HEADERS([foo.h]) 6319 AC_CHECK_HEADERS([bar.h], [], [], 6320 [#ifdef HAVE_FOO_H 6321 # include <foo.h> 6322 #endif 6323 ]) 6324 @end verbatim 6325 6326 The following variant generates smaller, faster @command{configure} 6327 files 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} 6332 For each given system header file @var{header-file} in the 6333 blank-separated argument list that exists, define 6334 @code{HAVE_@var{header-file}} (in all capitals). 6335 This is a once-only variant of @code{AC_CHECK_HEADERS}. It generates the 6336 checking code at most once, so that @command{configure} is smaller and 6337 faster; but the checks cannot be conditionalized and are always done once, 6338 early during the @command{configure} run. Thus, this macro is only safe 6339 for 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 6347 The following macros check for the declaration of variables and 6348 functions. If there is no macro specifically defined to check for a 6349 symbol you need, then you can use the general macros (@pxref{Generic 6350 Declarations}) 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 6361 There are no specific macros for declarations. 6362 6363 @node Generic Declarations 6364 @subsection Generic Declaration Checks 6365 6366 These macros are used to find declarations not covered by the ``particular'' 6367 test 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} 6373 If @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 6378 prior to the declaration under test. 6379 6380 This macro actually tests whether @var{symbol} is defined as a macro or 6381 can be used as an r-value, not whether it is really declared, because it 6382 is much safer to avoid introducing extra declarations when they are not 6383 needed. In order to facilitate use of C++ and overloaded function 6384 declarations, it is possible to specify function argument types in 6385 parentheses for types which can be zero-initialized: 6386 6387 @example 6388 AC_CHECK_DECL([basename(char *)]) 6389 @end example 6390 6391 This macro caches its result in the @code{ac_cv_have_decl_@var{symbol}} 6392 variable, with characters not suitable for a variable name mapped to 6393 underscores. 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} 6402 For each of the @var{symbols} (@emph{comma}-separated list with optional 6403 function 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 6407 execute 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 6412 prior to the declarations under test. 6413 6414 This macro uses an M4 list as first argument: 6415 @example 6416 AC_CHECK_DECLS([strdup]) 6417 AC_CHECK_DECLS([strlen]) 6418 AC_CHECK_DECLS([malloc, realloc, calloc, free]) 6419 AC_CHECK_DECLS([j0], [], [], [[#include <math.h>]]) 6420 AC_CHECK_DECLS([[basename(char *)], [dirname(char *)]]) 6421 @end example 6422 6423 Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not 6424 declared, @code{HAVE_DECL_@var{symbol}} is defined to @samp{0} instead 6425 of 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 6431 extern char *symbol; 6432 #endif 6433 @end example 6434 6435 @noindent 6436 If 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 6438 with the system's one, you should use: 6439 6440 @example 6441 #if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC 6442 void *malloc (size_t *s); 6443 #endif 6444 @end example 6445 6446 @noindent 6447 You fall into the second category only in extreme situations: either 6448 your files may be used without being configured, or they are used during 6449 the configuration. In most cases the traditional approach is enough. 6450 6451 This macro caches its results in @code{ac_cv_have_decl_@var{symbol}} 6452 variables, with characters not suitable for a variable name mapped to 6453 underscores. 6454 @end defmac 6455 6456 @defmac AC_CHECK_DECLS_ONCE (@var{symbols}) 6457 @acindex{CHECK_DECLS_ONCE} 6458 @cvindex HAVE_DECL_@var{symbol} 6459 For 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 6463 generates the checking code at most once, so that @command{configure} is 6464 smaller and faster; but the checks cannot be conditionalized and are 6465 always done once, early during the @command{configure} run. 6466 @end defmac 6467 6468 6469 @node Structures 6470 @section Structures 6471 @cindex Structure, checking 6472 6473 The following macros check for the presence of certain members in C 6474 structures. If there is no macro specifically defined to check for a 6475 member 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 6487 The 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 6494 Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular 6495 Headers}). Then, if @code{struct dirent} contains a @code{d_ino} 6496 member, 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. 6500 Traditionally, a zero @code{d_ino} indicated a deleted directory entry, 6501 though current systems hide this detail from the user and never return 6502 zero @code{d_ino} values. 6503 Many current systems report an incorrect @code{d_ino} for a directory 6504 entry 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 6512 Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular 6513 Headers}). Then, if @code{struct dirent} contains a @code{d_type} 6514 member, 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 6524 If @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 6528 future. 6529 6530 This macro caches its result in the @code{ac_cv_member_struct_stat_st_blocks} 6531 variable. 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} 6539 If @file{time.h} does not define @code{struct tm}, define 6540 @code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h} 6541 had better define @code{struct tm}. 6542 6543 This macro is obsolescent, as @file{time.h} defines @code{struct tm} in 6544 current 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 6556 Figure 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 6558 obsoleted @code{HAVE_TM_ZONE}). Otherwise, if the external array 6559 @code{tzname} is found, define @code{HAVE_TZNAME}; if it is declared, 6560 define @code{HAVE_DECL_TZNAME}. 6561 @end defmac 6562 6563 @node Generic Structures 6564 @subsection Generic Structure Checks 6565 6566 These 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} 6574 Check whether @var{member} is a member of the aggregate @var{aggregate}. 6575 If no @var{includes} are specified, the default includes are used 6576 (@pxref{Default Includes}). 6577 6578 @example 6579 AC_CHECK_MEMBER([struct passwd.pw_gecos], [], 6580 [AC_MSG_ERROR([we need `passwd.pw_gecos'])], 6581 [[#include <pwd.h>]]) 6582 @end example 6583 6584 You can use this macro for submembers: 6585 6586 @example 6587 AC_CHECK_MEMBER(struct top.middle.bot) 6588 @end example 6589 6590 This macro caches its result in the 6591 @code{ac_cv_member_@var{aggregate}_@var{member}} variable, with 6592 characters 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} 6600 Check 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 6603 capitals, with spaces and dots replaced by underscores). If 6604 @var{action-if-found} is given, it is executed for each of the found 6605 members. If @var{action-if-not-found} is given, it is executed for each 6606 of 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 6610 prior to the members under test. 6611 6612 This macro uses M4 lists: 6613 @example 6614 AC_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 6624 The following macros check for C types, either builtin or typedefs. If 6625 there is no macro specifically defined to check for a type you need, and 6626 you don't need to check for any special properties of it, then you can 6627 use 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} 6641 These 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 6643 exist. 6644 6645 The Gnulib @code{stdint} module is an alternate way to define many of 6646 these symbols; it is useful if you prefer your code to assume a 6647 C99-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 6654 Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int} 6655 is the base type of the array argument to @code{getgroups}. 6656 6657 This macro caches the base type in the @code{ac_cv_type_getgroups} 6658 variable. 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 6666 If @file{stdint.h} or @file{inttypes.h} does not define the type 6667 @code{int8_t}, define @code{int8_t} to a signed 6668 integer type that is exactly 8 bits wide and that uses two's complement 6669 representation, if such a type exists. 6670 If you are worried about porting to hosts that lack such a type, you can 6671 use 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 6684 This 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 6692 This 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 6700 This 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 6708 This 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 6716 If @file{stdint.h} or @file{inttypes.h} defines the type @code{intmax_t}, 6717 define @code{HAVE_INTMAX_T}. Otherwise, define @code{intmax_t} to the 6718 widest 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 6726 If @file{stdint.h} or @file{inttypes.h} defines the type @code{intptr_t}, 6727 define @code{HAVE_INTPTR_T}. Otherwise, define @code{intptr_t} to a 6728 signed integer type wide enough to hold a pointer, if such a type 6729 exists. 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 6736 If the C compiler supports a working @code{long double} type, define 6737 @code{HAVE_LONG_DOUBLE}. The @code{long double} type might have the 6738 same range and precision as @code{double}. 6739 6740 This macro caches its result in the @code{ac_cv_type_long_double} 6741 variable. 6742 6743 This macro is obsolescent, as current C compilers support @code{long 6744 double}. 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 6751 If the C compiler supports a working @code{long double} type with more 6752 range or precision than the @code{double} type, define 6753 @code{HAVE_LONG_DOUBLE_WIDER}. 6754 6755 This macro caches its result in the @code{ac_cv_type_long_double_wider} 6756 variable. 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 6763 If 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, 6766 because too many compilers mishandle such expressions. 6767 @xref{Preprocessor Arithmetic}. 6768 6769 This macro caches its result in the @code{ac_cv_type_long_long_int} 6770 variable. 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 6778 Define @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 6782 This macro caches its result in the @code{ac_cv_type_mbstate_t} 6783 variable. 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 6791 Define @code{mode_t} to a suitable type, if standard headers do not 6792 define it. 6793 6794 This 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 6802 Define @code{off_t} to a suitable type, if standard headers do not 6803 define it. 6804 6805 This 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 6813 Define @code{pid_t} to a suitable type, if standard headers do not 6814 define it. 6815 6816 This 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 6824 Define @code{size_t} to a suitable type, if standard headers do not 6825 define it. 6826 6827 This 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 6834 Define @code{ssize_t} to a suitable type, if standard headers do not 6835 define it. 6836 6837 This 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 6846 Define @code{uid_t} and @code{gid_t} to suitable types, if standard 6847 headers do not define them. 6848 6849 This 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 6857 If @file{stdint.h} or @file{inttypes.h} does not define the type 6858 @code{uint8_t}, define @code{uint8_t} to an 6859 unsigned integer type that is exactly 8 bits wide, if such a type 6860 exists. 6861 This 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 6869 This 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 6877 This 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 6885 This 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 6893 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintmax_t}, 6894 define @code{HAVE_UINTMAX_T}. Otherwise, define @code{uintmax_t} to the 6895 widest 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 6903 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintptr_t}, 6904 define @code{HAVE_UINTPTR_T}. Otherwise, define @code{uintptr_t} to an 6905 unsigned integer type wide enough to hold a pointer, if such a type 6906 exists. 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 6913 If the C compiler supports a working @code{unsigned long long int} type, 6914 define @code{HAVE_UNSIGNED_LONG_LONG_INT}. However, this test does not test 6915 @code{unsigned long long int} values in preprocessor @code{#if} expressions, 6916 because too many compilers mishandle such expressions. 6917 @xref{Preprocessor Arithmetic}. 6918 6919 This macro caches its result in the @code{ac_cv_type_unsigned_long_long_int} 6920 variable. 6921 @end defmac 6922 6923 @node Generic Types 6924 @subsection Generic Type Checks 6925 6926 These macros are used to check for types not covered by the ``particular'' 6927 test 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} 6933 Check whether @var{type} is defined. It may be a compiler builtin type 6934 or defined by the @var{includes}. @var{includes} is a series of include 6935 directives, defaulting to @code{AC_INCLUDES_DEFAULT} (@pxref{Default 6936 Includes}), which are used prior to the type under test. 6937 6938 In 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 6940 same 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 6944 This macro caches its result in the @code{ac_cv_type_@var{type}} 6945 variable, with @samp{*} mapped to @samp{p} and other characters not 6946 suitable 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} 6954 For each @var{type} of the @var{types} that is defined, define 6955 @code{HAVE_@var{type}} (in all capitals). Each @var{type} must follow 6956 the rules of @code{AC_CHECK_TYPE}. If no @var{includes} are 6957 specified, the default includes are used (@pxref{Default Includes}). If 6958 @var{action-if-found} is given, it is additional shell code to execute 6959 when one of the types is found. If @var{action-if-not-found} is given, 6960 it is executed when one of the types is not found. 6961 6962 This macro uses M4 lists: 6963 @example 6964 AC_CHECK_TYPES([ptrdiff_t]) 6965 AC_CHECK_TYPES([unsigned long long int, uintmax_t]) 6966 AC_CHECK_TYPES([float_t], [], [], [[#include <math.h>]]) 6967 @end example 6968 6969 @end defmac 6970 6971 Autoconf, up to 2.13, used to provide to another version of 6972 @code{AC_CHECK_TYPE}, broken by design. In order to keep backward 6973 compatibility, a simple heuristic, quite safe but not totally, is 6974 implemented. 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 6984 All 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 6986 the output of the compiler, typically to the empty string if 6987 Posix and @samp{.exe} if a DOS variant. 6988 6989 @ovindex OBJEXT 6990 They also define the output variable @code{OBJEXT} based on the 6991 output of the compiler, after @file{.c} files have been excluded, typically 6992 to @samp{o} if Posix, @samp{obj} if a DOS variant. 6993 6994 If the compiler being used does not produce executables, the tests fail. If 6995 the executables can't be run, and cross-compilation is not enabled, they 6996 fail too. @xref{Manual Configuration}, for more on support for cross 6997 compiling. 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 7014 Some compilers exhibit different behaviors. 7015 7016 @table @asis 7017 @item Static/Dynamic Expressions 7018 Autoconf relies on a trick to extract one bit of information from the C 7019 compiler: using negative array sizes. For instance the following 7020 excerpt of a C source demonstrates how to test whether @samp{int} objects are 4 7021 bytes wide: 7022 7023 @example 7024 static int test_array[sizeof (int) == 4 ? 1 : -1]; 7025 @end example 7026 7027 @noindent 7028 To our knowledge, there is a single compiler that does not support this 7029 trick: the HP C compilers (the real ones, not only the 7030 ``bundled'') on HP-UX 11.00. 7031 They incorrectly reject the above program with the diagnostic 7032 ``Variable-length arrays cannot have static storage.'' 7033 This bug comes from HP compilers' mishandling of @code{sizeof (int)}, 7034 not from the @code{? 1 : -1}, and 7035 Autoconf 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} 7048 Define @code{SIZEOF_@var{type-or-expr}} (@pxref{Standard Symbols}) to be 7049 the size in bytes of @var{type-or-expr}, which may be either a type or 7050 an 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 7054 prior to the expression under test. 7055 7056 This macro now works even when cross-compiling. The @var{unused} 7057 argument was used when cross-compiling. 7058 7059 For example, the call 7060 7061 @example 7062 @c If you change this example, adjust tests/semantics.at:AC_CHECK_SIZEOF struct. 7063 AC_CHECK_SIZEOF([int *]) 7064 @end example 7065 7066 @noindent 7067 defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems. 7068 7069 This macro caches its result in the @code{ac_cv_sizeof_@var{type-or-expr}} 7070 variable, with @samp{*} mapped to @samp{p} and other characters not 7071 suitable 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} 7078 Define @code{ALIGNOF_@var{type}} (@pxref{Standard Symbols}) to be the 7079 alignment in bytes of @var{type}. @samp{@var{type} y;} must be valid as 7080 a structure member declaration. If @samp{type} is unknown, the result 7081 is 0. If no @var{includes} are specified, the default includes are used 7082 (@pxref{Default Includes}). 7083 7084 This macro caches its result in the @code{ac_cv_alignof_@var{type-or-expr}} 7085 variable, with @samp{*} mapped to @samp{p} and other characters not 7086 suitable 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} 7092 Store into the shell variable @var{var} the value of the integer 7093 @var{expression}. The 7094 value should fit in an initializer in a C variable of type @code{signed 7095 long}. To support cross compilation (in which case, the macro only works on 7096 hosts that use twos-complement arithmetic), it should be possible to evaluate 7097 the expression at compile-time. If no @var{includes} are specified, the 7098 default includes are used (@pxref{Default Includes}). 7099 7100 Execute @var{action-if-fails} if the value cannot be determined correctly. 7101 @end defmac 7102 7103 @defmac AC_LANG_WERROR 7104 @acindex{LANG_WERROR} 7105 Normally Autoconf ignores warnings generated by the compiler, linker, and 7106 preprocessor. If this macro is used, warnings count as fatal 7107 errors for the current language. This macro is useful when the 7108 results of configuration are used where warnings are unacceptable; for 7109 instance, if parts of a program are built with the GCC 7110 @option{-Werror} 7111 option. If the whole program is built using @option{-Werror} it is 7112 often simpler to put @option{-Werror} in the compiler flags (@code{CFLAGS}, 7113 etc.). 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++, 7128 and Fortran that simplify optimization of shared memory parallelism, 7129 which is a common problem on multicore CPUs. 7130 7131 If the current language is C, the macro @code{AC_OPENMP} sets the 7132 variable @code{OPENMP_CFLAGS} to the C compiler flags needed for 7133 supporting OpenMP@. @code{OPENMP_CFLAGS} is set to empty if the 7134 compiler already supports OpenMP, if it has no way to activate OpenMP 7135 support, 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 7139 preprocessing program source, and when linking programs. Therefore you 7140 need to add @code{$(OPENMP_CFLAGS)} to the @code{CFLAGS} of C programs 7141 that use OpenMP@. If you preprocess OpenMP-specific C code, you also 7142 need to add @code{$(OPENMP_CFLAGS)} to @code{CPPFLAGS}. The presence of 7143 OpenMP support is revealed at compile time by the preprocessor macro 7144 @code{_OPENMP}. 7145 7146 Linking a program with @code{OPENMP_CFLAGS} typically adds one more 7147 shared library to the program's dependencies, so its use is recommended 7148 only on programs that actually require OpenMP. 7149 7150 If the current language is C++, @code{AC_OPENMP} sets the variable 7151 @code{OPENMP_CXXFLAGS}, suitably for the C++ compiler. The same remarks 7152 hold as for C. 7153 7154 If the current language is Fortran 77 or Fortran, @code{AC_OPENMP} sets 7155 the variable @code{OPENMP_FFLAGS} or @code{OPENMP_FCFLAGS}, 7156 respectively. Similar remarks as for C hold, except that 7157 @code{CPPFLAGS} is not used for Fortran, and no preprocessor macro 7158 signals OpenMP support. 7159 7160 For 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 7163 latter. 7164 7165 This 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 7173 The following macros provide ways to find and exercise a C Compiler. 7174 There are a few constructs that ought to be avoided, but do not deserve 7175 being checked for, since they can easily be worked around. 7176 7177 @table @asis 7178 @item Don't use lines containing solitary backslashes 7179 They tickle a bug in the HP-UX C compiler (checked on 7180 HP-UX 10.20, 7181 11.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 / 7189 char str[] = "\\ 7190 " A string with backslash-newlines in it %@{ %@} \\ 7191 ""; 7192 char apostrophe = '\\ 7193 \ 7194 '\ 7195 '; 7196 #endif 7197 @end example 7198 7199 @noindent 7200 the compiler incorrectly fails with the diagnostics ``Non-terminating 7201 comment at end of file'' and ``Missing @samp{#endif} at end of file.'' 7202 Removing the lines with solitary backslashes solves the problem. 7203 7204 @item Don't compile several files at once if output matters to you 7205 Some compilers, such as HP's, report names of files being 7206 compiled when given more than one file operand. For instance: 7207 7208 @example 7209 $ @kbd{cc a.c b.c} 7210 a.c: 7211 b.c: 7212 @end example 7213 7214 @noindent 7215 This can cause problems if you observe the output of the compiler to 7216 detect failures. Invoking @samp{cc -c a.c && cc -c b.c && cc -o c a.o 7217 b.o} solves the issue. 7218 7219 @item Don't rely on @code{#error} failing 7220 The IRIX C compiler does not fail when #error is preprocessed; it 7221 simply emits a diagnostic and continues, exiting successfully. So, 7222 instead of an error directive like @code{#error "Unsupported word size"} 7223 it is more portable to use an invalid directive like @code{#Unsupported 7224 word size} in Autoconf tests. In ordinary source code, @code{#error} is 7225 OK, since installers with inadequate compilers like IRIX can simply 7226 examine these compilers' diagnostic output. 7227 7228 @item Don't rely on correct @code{#line} support 7229 On Solaris, @command{c89} (at least Sun C 5.3 through 5.8) 7230 diagnoses @code{#line} directives whose line 7231 numbers are greater than 32767. Nothing in Posix 7232 makes 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 7243 Determine a C compiler to use. If @code{CC} is not already set in the 7244 environment, check for @code{gcc} and @code{cc}, then for other C 7245 compilers. Set output variable @code{CC} to the name of the compiler 7246 found. 7247 7248 This macro may, however, be invoked with an optional first argument 7249 which, if specified, must be a blank-separated list of C compilers to 7250 search for. This just gives the user an opportunity to specify an 7251 alternative search list for the C compiler. For example, if you didn't 7252 like the default order, then you could invoke @code{AC_PROG_CC} like 7253 this: 7254 7255 @example 7256 AC_PROG_CC([gcc cl cc]) 7257 @end example 7258 7259 If the C compiler does not handle function prototypes correctly by 7260 default, try to add an option to output variable @code{CC} to make it 7261 so. This macro tries various options that select standard-conformance 7262 modes on various systems. 7263 7264 After calling this macro you can check whether the C compiler has been 7265 set to accept ANSI C89 (ISO C90); if not, the shell 7266 variable 7267 @code{ac_cv_prog_cc_c89} is set to @samp{no}. See also 7268 @code{AC_C_PROTOTYPES} below. 7269 7270 If using the GNU C compiler, set shell variable @code{GCC} to 7271 @samp{yes}. If output variable @code{CFLAGS} was not already set, set 7272 it to @option{-g -O2} for the GNU C compiler (@option{-O2} on systems 7273 where GCC does not accept @option{-g}), or @option{-g} for 7274 other compilers. If your package does not like this default, then it is 7275 acceptable to insert the line @samp{: $@{CFLAGS=""@}} after @code{AC_INIT} 7276 and before @code{AC_PROG_CC} to select an empty default instead. 7277 7278 Many Autoconf macros use a compiler, and thus call 7279 @samp{AC_REQUIRE([AC_PROG_CC])} to ensure that the compiler has been 7280 determined before the body of the outermost @code{AC_DEFUN} macro. 7281 Although @code{AC_PROG_CC} is safe to directly expand multiple times, it 7282 performs certain checks (such as the proper value of @env{EXEEXT}) only 7283 on the first invocation. Therefore, care must be used when invoking 7284 this 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 7293 If the C compiler does not accept the @option{-c} and @option{-o} options 7294 simultaneously, define @code{NO_MINUS_C_MINUS_O}. This macro actually 7295 tests both the compiler found by @code{AC_PROG_CC}, and, if different, 7296 the first @code{cc} in the path. The test fails if one fails. This 7297 macro was created for GNU Make to choose the default C compilation 7298 rule. 7299 7300 For 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 7309 Set output variable @code{CPP} to a command that runs the 7310 C preprocessor. If @samp{$CC -E} doesn't work, @file{/lib/cpp} is used. 7311 It is only portable to run @code{CPP} on files with a @file{.c} 7312 extension. 7313 7314 Some preprocessors don't indicate missing include files by the error 7315 status. For such preprocessors an internal variable is set that causes 7316 other macros to check the standard error from the preprocessor and 7317 consider the test failed if any warnings have been reported. 7318 For most preprocessors, though, warnings do not cause include-file 7319 tests 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 7325 This acts like @code{AC_PROG_CPP}, except it treats warnings from the 7326 preprocessor as errors even if the preprocessor exit status indicates 7327 success. This is useful for avoiding headers that generate mandatory 7328 warnings, such as deprecation notices. 7329 @end defmac 7330 7331 7332 The following macros check for C compiler or machine architecture 7333 features. 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 7340 If the C compiler cannot compile ISO Standard C (currently 7341 C99), try to add an option to output variable @code{CC} to make it work. 7342 If the compiler does not support C99, fall back to supporting 7343 ANSI C89 (ISO C90). 7344 7345 After calling this macro you can check whether the C compiler has been 7346 set 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 7353 If the C compiler is not in ANSI C89 (ISO C90) mode by 7354 default, try to add an option to output variable @code{CC} to make it 7355 so. This macro tries various options that select ANSI C89 on 7356 some system or another, preferring extended functionality modes over 7357 strict conformance modes. It considers the compiler to be in 7358 ANSI C89 mode if it handles function prototypes correctly. 7359 7360 After calling this macro you can check whether the C compiler has been 7361 set to accept ANSI C89; if not, the shell variable 7362 @code{ac_cv_prog_cc_c89} is set to @samp{no}. 7363 7364 This 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 7370 If the C compiler is not in C99 mode by default, try to add an 7371 option to output variable @code{CC} to make it so. This macro tries 7372 various options that select C99 on some system or another, preferring 7373 extended functionality modes over strict conformance modes. It 7374 considers the compiler to be in C99 mode if it handles @code{_Bool}, 7375 @code{//} comments, flexible array members, @code{inline}, signed and 7376 unsigned @code{long long int}, mixed code and declarations, named 7377 initialization of structs, 7378 @code{restrict}, @code{va_copy}, varargs macros, variable declarations 7379 in @code{for} loops, and variable length arrays. 7380 7381 After calling this macro you can check whether the C compiler has been 7382 set 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 7389 Define @samp{HAVE_C_BACKSLASH_A} to 1 if the C compiler understands 7390 @samp{\a}. 7391 7392 This macro is obsolescent, as current C compilers understand @samp{\a}. 7393 New 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 7402 If words are stored with the most significant byte first (like Motorola 7403 and SPARC CPUs), execute @var{action-if-true}. If words are stored with 7404 the least significant byte first (like Intel and VAX CPUs), execute 7405 @var{action-if-false}. 7406 7407 This macro runs a test-case if endianness cannot be determined from the 7408 system header files. When cross-compiling, the test-case is not run but 7409 grep'ed for some magic values. @var{action-if-unknown} is executed if 7410 the latter case fails to determine the byte sex of the host system. 7411 7412 In some cases a single run of a compiler can generate code for multiple 7413 architectures. This can happen, for example, when generating Mac OS X 7414 universal binary files, which work on both PowerPC and Intel 7415 architectures. In this case, the different variants might be for 7416 different architectures whose endiannesses differ. If 7417 @command{configure} detects this, it executes @var{action-if-universal} 7418 instead of @var{action-if-unknown}. 7419 7420 The default for @var{action-if-true} is to define 7421 @samp{WORDS_BIGENDIAN}. The default for @var{action-if-false} is to do 7422 nothing. The default for @var{action-if-unknown} is to 7423 abort configure and tell the installer how to bypass this test. 7424 And 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 7426 detected and the current code is big-endian; this default works only if 7427 @command{autoheader} is used (@pxref{autoheader Invocation}). 7428 7429 If you use this macro without specifying @var{action-if-universal}, you 7430 should also use @code{AC_CONFIG_HEADERS}; otherwise 7431 @samp{WORDS_BIGENDIAN} may be set incorrectly for Mac OS X universal 7432 binary 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 7440 If the C compiler does not fully support the @code{const} keyword, 7441 define @code{const} to be empty. Some C compilers that do 7442 not define @code{__STDC__} do support @code{const}; some compilers that 7443 define @code{__STDC__} do not completely support @code{const}. Programs 7444 can simply use @code{const} as if every C compiler supported it; for 7445 those that don't, the makefile or configuration header file 7446 defines it as empty. 7447 7448 Occasionally installers use a C++ compiler to compile C code, typically 7449 because they lack a C compiler. This causes problems with @code{const}, 7450 because C and C++ treat @code{const} differently. For example: 7451 7452 @example 7453 const int foo; 7454 @end example 7455 7456 @noindent 7457 is valid in C but not in C++. These differences unfortunately cannot be 7458 papered over by defining @code{const} to be empty. 7459 7460 If @command{autoconf} detects this situation, it leaves @code{const} alone, 7461 as this generally yields better results in practice. However, using a 7462 C++ compiler to compile C code is not recommended or supported, and 7463 installers who run into trouble in this area should get a C compiler 7464 like GCC to compile their C code. 7465 7466 This macro caches its result in the @code{ac_cv_c_const} variable. 7467 7468 This macro is obsolescent, as current C compilers support @code{const}. 7469 New 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 7476 If the C compiler recognizes a variant spelling for the @code{restrict} 7477 keyword (@code{__restrict}, @code{__restrict__}, or @code{_Restrict}), 7478 then define @code{restrict} to that; this is more likely to do the right 7479 thing with compilers that support language variants where plain 7480 @code{restrict} is not a keyword. Otherwise, if the C compiler 7481 recognizes the @code{restrict} keyword, don't do anything. 7482 Otherwise, define @code{restrict} to be empty. 7483 Thus, programs may simply use @code{restrict} as if every C compiler 7484 supported it; for those that do not, the makefile 7485 or configuration header defines it away. 7486 7487 Although support in C++ for the @code{restrict} keyword is not 7488 required, several C++ compilers do accept the keyword. 7489 This macro works for them, too. 7490 7491 This macro caches @samp{no} in the @code{ac_cv_c_restrict} variable 7492 if @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 7498 If the C compiler does not understand the keyword @code{volatile}, 7499 define @code{volatile} to be empty. Programs can simply use 7500 @code{volatile} as if every C compiler supported it; for those that do 7501 not, the makefile or configuration header defines it as 7502 empty. 7503 7504 If the correctness of your program depends on the semantics of 7505 @code{volatile}, simply defining it to be empty does, in a sense, break 7506 your code. However, given that the compiler does not support 7507 @code{volatile}, you are at its mercy anyway. At least your 7508 program compiles, when it wouldn't before. 7509 @xref{Volatile Objects}, for more about @code{volatile}. 7510 7511 In general, the @code{volatile} keyword is a standard C feature, so 7512 you might expect that @code{volatile} is available only when 7513 @code{__STDC__} is defined. However, Ultrix 4.3's native compiler does 7514 support volatile, but does not define @code{__STDC__}. 7515 7516 This macro is obsolescent, as current C compilers support @code{volatile}. 7517 New 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 7524 If the C compiler supports the keyword @code{inline}, do nothing. 7525 Otherwise define @code{inline} to @code{__inline__} or @code{__inline} 7526 if 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__ 7533 If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__}, 7534 unless the C compiler predefines it. 7535 7536 These days, using this macro is not necessary. The same information can 7537 be determined by this portable alternative, thus avoiding the use of 7538 preprocessor 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 7551 If the C preprocessor supports the stringizing operator, define 7552 @code{HAVE_STRINGIZE}. The stringizing operator is @samp{#} and is 7553 found in macros such as this: 7554 7555 @example 7556 #define x(y) #y 7557 @end example 7558 7559 This macro is obsolescent, as current C compilers support the 7560 stringizing 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 7566 If the C compiler supports flexible array members, define 7567 @code{FLEXIBLE_ARRAY_MEMBER} to nothing; otherwise define it to 1. 7568 That way, a declaration like this: 7569 7570 @example 7571 struct s 7572 @{ 7573 size_t n_vals; 7574 double val[FLEXIBLE_ARRAY_MEMBER]; 7575 @}; 7576 @end example 7577 7578 @noindent 7579 will let applications use the ``struct hack'' even with compilers that 7580 do not support flexible array members. To allocate and use such an 7581 object, you can use code like this: 7582 7583 @example 7584 size_t i; 7585 size_t n = compute_value_count (); 7586 struct s *p = 7587 malloc (offsetof (struct s, val) 7588 + n * sizeof (double)); 7589 p->n_vals = n; 7590 for (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 7598 If the C compiler supports variable-length arrays, define 7599 @code{HAVE_C_VARARRAYS}. A variable-length array is an array of automatic 7600 storage duration whose length is determined at run time, when the array 7601 is declared. 7602 @end defmac 7603 7604 @defmac AC_C_TYPEOF 7605 @acindex{C_TYPEOF} 7606 @cvindex HAVE_TYPEOF 7607 @cvindex typeof 7608 If the C compiler supports GCC's @code{typeof} syntax either 7609 directly or 7610 through a different spelling of the keyword (e.g., @code{__typeof__}), 7611 define @code{HAVE_TYPEOF}. If the support is available only through a 7612 different 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 7620 If function prototypes are understood by the compiler (as determined by 7621 @code{AC_PROG_CC}), define @code{PROTOTYPES} and @code{__PROTOTYPES}. 7622 Defining @code{__PROTOTYPES} is for the benefit of 7623 header files that cannot use macros that infringe on user name space. 7624 7625 This macro is obsolescent, as current C compilers support prototypes. 7626 New 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 7633 Add @option{-traditional} to output variable @code{CC} if using the 7634 GNU C compiler and @code{ioctl} does not work properly without 7635 @option{-traditional}. That usually happens when the fixed header files 7636 have not been installed on an old system. 7637 7638 This macro is obsolescent, since current versions of the GNU C 7639 compiler 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 7653 Determine 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 7655 variable @code{CXX} to its value. 7656 7657 Otherwise, if the macro is invoked without an argument, then search for 7658 a C++ compiler under the likely names (first @code{g++} and @code{c++} 7659 then other names). If none of those checks succeed, then as a last 7660 resort set @code{CXX} to @code{g++}. 7661 7662 This macro may, however, be invoked with an optional first argument 7663 which, if specified, must be a blank-separated list of C++ compilers to 7664 search for. This just gives the user an opportunity to specify an 7665 alternative search list for the C++ compiler. For example, if you 7666 didn't like the default order, then you could invoke @code{AC_PROG_CXX} 7667 like this: 7668 7669 @example 7670 AC_PROG_CXX([gcc cl KCC CC cxx cc++ xlC aCC c++ g++]) 7671 @end example 7672 7673 If using the GNU C++ compiler, set shell variable @code{GXX} to 7674 @samp{yes}. If output variable @code{CXXFLAGS} was not already set, set 7675 it to @option{-g -O2} for the GNU C++ compiler (@option{-O2} on 7676 systems where G++ does not accept @option{-g}), or @option{-g} for other 7677 compilers. If your package does not like this default, then it is 7678 acceptable to insert the line @samp{: $@{CXXFLAGS=""@}} after @code{AC_INIT} 7679 and 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 7687 Set output variable @code{CXXCPP} to a command that runs the C++ 7688 preprocessor. If @samp{$CXX -E} doesn't work, @file{/lib/cpp} is used. 7689 It is portable to run @code{CXXCPP} only on files with a @file{.c}, 7690 @file{.C}, @file{.cc}, or @file{.cpp} extension. 7691 7692 Some preprocessors don't indicate missing include files by the error 7693 status. For such preprocessors an internal variable is set that causes 7694 other macros to check the standard error from the preprocessor and 7695 consider the test failed if any warnings have been reported. However, 7696 it 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 7702 Test whether the C++ compiler accepts the options @option{-c} and 7703 @option{-o} simultaneously, and define @code{CXX_NO_MINUS_C_MINUS_O}, 7704 if 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 7718 Determine an Objective C compiler to use. If @code{OBJC} is not already 7719 set in the environment, check for Objective C compilers. Set output 7720 variable @code{OBJC} to the name of the compiler found. 7721 7722 This macro may, however, be invoked with an optional first argument 7723 which, if specified, must be a blank-separated list of Objective C compilers to 7724 search for. This just gives the user an opportunity to specify an 7725 alternative search list for the Objective C compiler. For example, if you 7726 didn't like the default order, then you could invoke @code{AC_PROG_OBJC} 7727 like this: 7728 7729 @example 7730 AC_PROG_OBJC([gcc objcc objc]) 7731 @end example 7732 7733 If using the GNU Objective C compiler, set shell variable 7734 @code{GOBJC} to @samp{yes}. If output variable @code{OBJCFLAGS} was not 7735 already set, set it to @option{-g -O2} for the GNU Objective C 7736 compiler (@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 7744 Set output variable @code{OBJCPP} to a command that runs the Objective C 7745 preprocessor. 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 7759 Determine an Objective C++ compiler to use. If @code{OBJCXX} is not already 7760 set in the environment, check for Objective C++ compilers. Set output 7761 variable @code{OBJCXX} to the name of the compiler found. 7762 7763 This macro may, however, be invoked with an optional first argument 7764 which, if specified, must be a blank-separated list of Objective C++ compilers 7765 to search for. This just gives the user an opportunity to specify an 7766 alternative search list for the Objective C++ compiler. For example, if you 7767 didn't like the default order, then you could invoke @code{AC_PROG_OBJCXX} 7768 like this: 7769 7770 @example 7771 AC_PROG_OBJCXX([gcc g++ objcc++ objcxx]) 7772 @end example 7773 7774 If using the GNU Objective C++ compiler, set shell variable 7775 @code{GOBJCXX} to @samp{yes}. If output variable @code{OBJCXXFLAGS} was not 7776 already set, set it to @option{-g -O2} for the GNU Objective C++ 7777 compiler (@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 7785 Set output variable @code{OBJCXXCPP} to a command that runs the Objective C++ 7786 preprocessor. 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 7794 Autoconf defines the following macros for determining paths to the essential 7795 Erlang/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 7803 Determine an Erlang compiler to use. If @code{ERLC} is not already set in the 7804 environment, check for @command{erlc}. Set output variable @code{ERLC} to the 7805 complete path of the compiler command found. In addition, if @code{ERLCFLAGS} 7806 is not set in the environment, set it to an empty value. 7807 7808 The two optional arguments have the same meaning as the two last arguments of 7809 macro @code{AC_PATH_PROG} for looking for the @command{erlc} program. For 7810 example, to look for @command{erlc} only in the @file{/usr/lib/erlang/bin} 7811 directory: 7812 7813 @example 7814 AC_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} 7820 A simplified variant of the @code{AC_ERLANG_PATH_ERLC} macro, that prints an 7821 error message and exits the @command{configure} script if the @command{erlc} 7822 program 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 7829 Determine an Erlang interpreter to use. If @code{ERL} is not already 7830 set in the 7831 environment, check for @command{erl}. Set output variable @code{ERL} to the 7832 complete path of the interpreter command found. 7833 7834 The two optional arguments have the same meaning as the two last arguments of 7835 macro @code{AC_PATH_PROG} for looking for the @command{erl} program. For 7836 example, to look for @command{erl} only in the @file{/usr/lib/erlang/bin} 7837 directory: 7838 7839 @example 7840 AC_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} 7846 A simplified variant of the @code{AC_ERLANG_PATH_ERL} macro, that prints an 7847 error message and exits the @command{configure} script if the @command{erl} 7848 program is not found. 7849 @end defmac 7850 7851 7852 @node Fortran Compiler 7853 @subsection Fortran Compiler Characteristics 7854 @cindex Fortran 7855 @cindex F77 7856 7857 The Autoconf Fortran support is divided into two categories: legacy 7858 Fortran 77 macros (@code{F77}), and modern Fortran macros (@code{FC}). 7859 The former are intended for traditional Fortran 77 code, and have output 7860 variables like @code{F77}, @code{FFLAGS}, and @code{FLIBS}. The latter 7861 are for newer programs that can (or must) compile under the newer 7862 Fortran standards, and have output variables like @code{FC}, 7863 @code{FCFLAGS}, and @code{FCLIBS}. 7864 7865 Except 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 7868 are 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 7879 Determine a Fortran 77 compiler to use. If @code{F77} is not already 7880 set in the environment, then check for @code{g77} and @code{f77}, and 7881 then some other names. Set the output variable @code{F77} to the name 7882 of the compiler found. 7883 7884 This macro may, however, be invoked with an optional first argument 7885 which, if specified, must be a blank-separated list of Fortran 77 7886 compilers to search for. This just gives the user an opportunity to 7887 specify an alternative search list for the Fortran 77 compiler. For 7888 example, if you didn't like the default order, then you could invoke 7889 @code{AC_PROG_F77} like this: 7890 7891 @example 7892 AC_PROG_F77([fl32 f77 fort77 xlf g77 f90 xlf90]) 7893 @end example 7894 7895 If using @code{g77} (the GNU Fortran 77 compiler), then 7896 set the shell variable @code{G77} to @samp{yes}. 7897 If the output variable @code{FFLAGS} was not already set in the 7898 environment, then set it to @option{-g -02} for @code{g77} (or @option{-O2} 7899 where @code{g77} does not accept @option{-g}). Otherwise, set 7900 @code{FFLAGS} to @option{-g} for all other Fortran 77 compilers. 7901 7902 The 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 7915 Determine a Fortran compiler to use. If @code{FC} is not already set in 7916 the environment, then @code{dialect} is a hint to indicate what Fortran 7917 dialect to search for; the default is to search for the newest available 7918 dialect. Set the output variable @code{FC} to the name of the compiler 7919 found. 7920 7921 By default, newer dialects are preferred over older dialects, but if 7922 @code{dialect} is specified then older dialects are preferred starting 7923 with the specified dialect. @code{dialect} can currently be one of 7924 Fortran 77, Fortran 90, or Fortran 95. However, this is only a hint of 7925 which compiler @emph{name} to prefer (e.g., @code{f90} or @code{f95}), 7926 and no attempt is made to guarantee that a particular language standard 7927 is actually supported. Thus, it is preferable that you avoid the 7928 @code{dialect} option, and use AC_PROG_FC only for code compatible with 7929 the latest Fortran standard. 7930 7931 This macro may, alternatively, be invoked with an optional first argument 7932 which, if specified, must be a blank-separated list of Fortran 7933 compilers to search for, just as in @code{AC_PROG_F77}. 7934 7935 If using @code{gfortran} or @code{g77} (the GNU Fortran compilers), then 7936 set the shell variable @code{GFC} to @samp{yes}. 7937 If the output variable @code{FCFLAGS} was not already set in the 7938 environment, then set it to @option{-g -02} for GNU @code{g77} (or 7939 @option{-O2} where @code{g77} does not accept @option{-g}). Otherwise, 7940 set @code{FCFLAGS} to @option{-g} for all other Fortran compilers. 7941 7942 The result of the GNU test is cached in the @code{ac_cv_fc_compiler_gnu} 7943 variable, acceptance of @option{-g} in the @code{ac_cv_prog_fc_g} 7944 variable. 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 7955 Test 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 7959 The 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 7963 The following macros check for Fortran compiler characteristics. 7964 To 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 7967 current language to Fortran 77 or Fortran via @code{AC_LANG([Fortran 77])} 7968 or @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 7981 Determine the linker flags (e.g., @option{-L} and @option{-l}) for the 7982 @dfn{Fortran intrinsic and runtime libraries} that are required to 7983 successfully link a Fortran program or shared library. The output 7984 variable @code{FLIBS} or @code{FCLIBS} is set to these flags (which 7985 should be included after @code{LIBS} when linking). 7986 7987 This macro is intended to be used in those situations when it is 7988 necessary to mix, e.g., C++ and Fortran source code in a single 7989 program or shared library (@pxref{Mixing Fortran 77 With C and C++, , , 7990 automake, GNU Automake}). 7991 7992 For example, if object files from a C++ and Fortran compiler must be 7993 linked 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 7995 global constructors, instantiating templates, enabling exception 7996 support, etc.). 7997 7998 However, the Fortran intrinsic and runtime libraries must be linked in 7999 as well, but the C++ compiler/linker doesn't know by default how to add 8000 these Fortran 77 libraries. Hence, this macro was created to determine 8001 these Fortran libraries. 8002 8003 The 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 8005 link C/C++ with Fortran; see below. Further, it is highly recommended 8006 that you use @code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}) 8007 because the complex defines that the function wrapper macros create 8008 may not work with C/C++ compiler drivers. 8009 8010 These macros internally compute the flag needed to verbose linking 8011 output and cache it in @code{ac_cv_prog_f77_v} or @code{ac_cv_prog_fc_v} 8012 variables, 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 8026 With many compilers, the Fortran libraries detected by 8027 @code{AC_F77_LIBRARY_LDFLAGS} or @code{AC_FC_LIBRARY_LDFLAGS} provide 8028 their own @code{main} entry function that initializes things like 8029 Fortran 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 8033 this interaction. 8034 8035 When using Fortran for purely numerical functions (no I/O, etc.)@: often 8036 one prefers to provide one's own @code{main} and skip the Fortran 8037 library initializations. In this case, however, one may still need to 8038 provide a dummy @code{MAIN__} routine in order to prevent linking errors 8039 on some systems. @code{AC_F77_DUMMY_MAIN} or @code{AC_FC_DUMMY_MAIN} 8040 detects whether any such routine is @emph{required} for linking, and 8041 what its name is; the shell variable @code{F77_DUMMY_MAIN} or 8042 @code{FC_DUMMY_MAIN} holds this name, @code{unknown} when no solution 8043 was found, and @code{none} when no such dummy main is needed. 8044 8045 By 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 8048 exiting with an error. 8049 8050 In order to link with Fortran routines, the user's C/C++ program should 8051 then include the following code to define the dummy main if it is 8052 needed: 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 8066 Note that this macro is called automatically from @code{AC_F77_WRAPPERS} 8067 or @code{AC_FC_WRAPPERS}; there is generally no need to call it 8068 explicitly unless one wants to change the default actions. 8069 8070 The 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 8082 As discussed above, many Fortran libraries allow you to provide an entry 8083 point called (say) @code{MAIN__} instead of the usual @code{main}, which 8084 is then called by a @code{main} function in the Fortran libraries that 8085 initializes 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 8089 alternate main function name is found, @code{F77_MAIN} and @code{FC_MAIN} are 8090 simply defined to @code{main}.) 8091 8092 Thus, when calling Fortran routines from C that perform things like I/O, 8093 one 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 8100 int 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 8105 The 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 8119 Defines 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 8121 mangle the names of C/C++ identifiers, and identifiers with underscores, 8122 respectively, so that they match the name-mangling scheme used by the 8123 Fortran compiler. 8124 8125 Fortran is case-insensitive, and in order to achieve this the Fortran 8126 compiler converts all identifiers into a canonical case and format. To 8127 call a Fortran subroutine from C or to write a C function that is 8128 callable from Fortran, the C program must explicitly use identifiers in 8129 the format expected by the Fortran compiler. In order to do this, one 8130 simply wraps all C identifiers in one of the macros provided by 8131 @code{AC_F77_WRAPPERS} or @code{AC_FC_WRAPPERS}. For example, suppose 8132 you 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 8143 You 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 8149 extern "C" /* prevent C++ name mangling */ 8150 #endif 8151 void FOOBAR_F77 (double *x, double *y); 8152 @end example 8153 8154 Note that we pass both the lowercase and uppercase versions of the 8155 function name to @code{F77_FUNC} so that it can select the right one. 8156 Note also that all parameters to Fortran 77 routines are passed as 8157 pointers (@pxref{Mixing Fortran 77 With C and C++, , , automake, GNU 8158 Automake}). 8159 8160 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.) 8161 8162 Although Autoconf tries to be intelligent about detecting the 8163 name-mangling scheme of the Fortran compiler, there may be Fortran 8164 compilers that it doesn't support yet. In this case, the above code 8165 generates a compile-time error, but some other behavior 8166 (e.g., disabling Fortran-related features) can be induced by checking 8167 whether @code{F77_FUNC} or @code{FC_FUNC} is defined. 8168 8169 Now, 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 8179 If the Fortran identifier contains an underscore (e.g., @code{foo_bar}), 8180 you 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 8182 because some Fortran compilers mangle names differently if they contain 8183 an underscore. 8184 8185 The 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 8187 the @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} 8194 Given an identifier @var{name}, set the shell variable @var{shellvar} to 8195 hold the mangled version @var{name} according to the rules of the 8196 Fortran linker (see also @code{AC_F77_WRAPPERS} or 8197 @code{AC_FC_WRAPPERS}). @var{shellvar} is optional; if it is not 8198 supplied, the shell variable is simply @var{name}. The purpose of 8199 this macro is to give the caller a way to access the name-mangling 8200 information other than through the C preprocessor as above, for example, 8201 to 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} 8212 By default, the @code{FC} macros perform their tests using a @file{.f} 8213 extension for source-code files. Some compilers, however, only enable 8214 newer language features for appropriately named files, e.g., Fortran 90 8215 features only for @file{.f90} files, or preprocessing only with 8216 @file{.F} files or maybe other upper-case extensions. On the other 8217 hand, some other compilers expect all source files to end in @file{.f} 8218 and 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 8220 issues. 8221 8222 The @code{AC_FC_SRCEXT} macro tries to get the @code{FC} compiler to 8223 accept files ending with the extension @file{.@var{ext}} (i.e., 8224 @var{ext} does @emph{not} contain the dot). If any special compiler 8225 flags are needed for this, it stores them in the output variable 8226 @code{FCFLAGS_@var{ext}}. This extension and these flags are then used 8227 for all subsequent @code{FC} tests (until @code{AC_FC_SRCEXT} or 8228 @code{AC_FC_PP_SRCEXT} is called another time). 8229 8230 For 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 8233 to compile such files. 8234 8235 Similarly, the @code{AC_FC_PP_SRCEXT} macro tries to get the @code{FC} 8236 compiler to preprocess and compile files with the extension 8237 @file{.@var{ext}}. When both @command{fpp} and @command{cpp} style 8238 preprocessing are provided, the former is preferred, as the latter may 8239 treat continuation lines, @code{//} tokens, and white space differently 8240 from what some Fortran dialects expect. Conversely, if you do not want 8241 files to be preprocessed, use only lower-case characters in the file 8242 name extension. Like with @code{AC_FC_SRCEXT(f90)}, any needed flags 8243 are stored in the @code{FCFLAGS_@var{ext}} variable. 8244 8245 The @code{FCFLAGS_@var{ext}} flags can @emph{not} be simply absorbed 8246 into @code{FCFLAGS}, for two reasons based on the limitations of some 8247 compilers. First, only one @code{FCFLAGS_@var{ext}} can be used at a 8248 time, so files with different extensions must be compiled separately. 8249 Second, @code{FCFLAGS_@var{ext}} must appear @emph{immediately} before 8250 the source-code file name when compiling. So, continuing the example 8251 above, you might compile a @file{foo.f90} file in your makefile with the 8252 command: 8253 8254 @example 8255 foo.o: foo.f90 8256 $(FC) -c $(FCFLAGS) $(FCFLAGS_f90) '$(srcdir)/foo.f90' 8257 @end example 8258 8259 If @code{AC_FC_SRCEXT} or @code{AC_FC_PP_SRCEXT} succeeds in compiling 8260 files 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 8265 The @code{AC_FC_SRCEXT} and @code{AC_FC_PP_SRCEXT} macros cache their 8266 results 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 8275 Find a flag to specify defines for preprocessed Fortran. Not all 8276 Fortran compilers use @option{-D}. Substitute @code{FC_DEFINE} with 8277 the result and call @var{action-if-success} (defaults to nothing) if 8278 successful, and @var{action-if-failure} (defaults to failing with an 8279 error message) if not. 8280 8281 This macro calls @code{AC_FC_PP_SRCEXT([F])} in order to learn how to 8282 preprocess a @file{conftest.F} file, but restores a previously used 8283 Fortran source file extension afterwards again. 8284 8285 The result of this test is cached in the @code{ac_cv_fc_pp_define} 8286 variable. 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 8294 Try to ensure that the Fortran compiler (@code{$FC}) allows free-format 8295 source code (as opposed to the older fixed-format style from Fortran 8296 77). If necessary, it may add some additional flags to @code{FCFLAGS}. 8297 8298 This macro is most important if you are using the default @file{.f} 8299 extension, since many compilers interpret this extension as indicating 8300 fixed-format source unless an additional flag is supplied. If you 8301 specify a different extension with @code{AC_FC_SRCEXT}, such as 8302 @file{.f90}, then @code{AC_FC_FREEFORM} ordinarily succeeds without 8303 modifying @code{FCFLAGS}. For extensions which the compiler does not 8304 know about, the flag set by the @code{AC_FC_SRCEXT} macro might let 8305 the compiler assume Fortran 77 by default, however. 8306 8307 If @code{AC_FC_FREEFORM} succeeds in compiling free-form source, it 8308 calls @var{action-if-success} (defaults to nothing). If it fails, it 8309 calls @var{action-if-failure} (defaults to exiting with an error 8310 message). 8311 8312 The result of this test, or @samp{none} or @samp{unknown}, is cached in 8313 the @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 8321 Try to ensure that the Fortran compiler (@code{$FC}) allows the old 8322 fixed-format source code (as opposed to free-format style). If 8323 necessary, it may add some additional flags to @code{FCFLAGS}. 8324 8325 This macro is needed for some compilers alias names like @command{xlf95} 8326 which assume free-form source code by default, and in case you want to 8327 use fixed-form source with an extension like @file{.f90} which many 8328 compilers interpret as free-form by default. If you specify a different 8329 extension with @code{AC_FC_SRCEXT}, such as @file{.f}, then 8330 @code{AC_FC_FIXEDFORM} ordinarily succeeds without modifying 8331 @code{FCFLAGS}. 8332 8333 If @code{AC_FC_FIXEDFORM} succeeds in compiling fixed-form source, it 8334 calls @var{action-if-success} (defaults to nothing). If it fails, it 8335 calls @var{action-if-failure} (defaults to exiting with an error 8336 message). 8337 8338 The result of this test, or @samp{none} or @samp{unknown}, is cached in 8339 the @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 8347 Try to ensure that the Fortran compiler (@code{$FC}) accepts long source 8348 code lines. The @var{length} argument may be given as 80, 132, or 8349 unlimited, and defaults to 132. Note that line lengths above 254 8350 columns are not portable, and some compilers do not accept more than 132 8351 columns at least for fixed format source. If necessary, it may add some 8352 additional flags to @code{FCFLAGS}. 8353 8354 If @code{AC_FC_LINE_LENGTH} succeeds in compiling fixed-form source, it 8355 calls @var{action-if-success} (defaults to nothing). If it fails, it 8356 calls @var{action-if-failure} (defaults to exiting with an error 8357 message). 8358 8359 The result of this test, or @samp{none} or @samp{unknown}, is cached in 8360 the @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 8368 The @code{AC_FC_CHECK_BOUNDS} macro tries to enable array bounds checking 8369 in the Fortran compiler. If successful, the @var{action-if-success} 8370 is 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 8372 message. The macro currently requires Fortran 90 or a newer dialect. 8373 8374 The result of the macro is cached in the @code{ac_cv_fc_check_bounds} 8375 variable. 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 8387 Try to disallow implicit declarations in the Fortran compiler. If 8388 successful, @var{action-if-success} is called and any needed flags 8389 are added to @code{FFLAGS} or @code{FCFLAGS}, respectively. Otherwise, 8390 @var{action-if-failure} is called, which defaults to failing with an error 8391 message. 8392 8393 The result of these macros are cached in the 8394 @code{ac_cv_f77_implicit_none} and @code{ac_cv_fc_implicit_none} 8395 variables, 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 8403 Find the Fortran 90 module file name extension. Most Fortran 90 8404 compilers store module information in files separate from the object 8405 files. The module files are usually named after the name of the module 8406 rather than the source file name, with characters possibly turned to 8407 upper case, plus an extension, often @file{.mod}. 8408 8409 Not all compilers use module files at all, or by default. The Cray 8410 Fortran compiler requires @option{-e m} in order to store and search 8411 module information in @file{.mod} files rather than in object files. 8412 Likewise, the Fujitsu Fortran compilers uses the @option{-Am} option to 8413 indicate how module information is stored. 8414 8415 The @code{AC_FC_MODULE_EXTENSION} macro computes the module extension 8416 without the leading dot, and stores that in the @code{FC_MODEXT} 8417 variable. If the compiler does not produce module files, or the 8418 extension cannot be determined, @code{FC_MODEXT} is empty. Typically, 8419 the result of this macro may be used in cleanup @command{make} rules as 8420 follows: 8421 8422 @example 8423 clean-modules: 8424 -test -z "$(FC_MODEXT)" || rm -f *.$(FC_MODEXT) 8425 @end example 8426 8427 The 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 8438 Find the compiler flag to include Fortran 90 module information from 8439 another directory, and store that in the @code{FC_MODINC} variable. 8440 Call @var{action-if-success} (defaults to nothing) if successful, and 8441 set @code{FC_MODINC} to empty and call @var{action-if-failure} (defaults 8442 to exiting with an error message) if not. 8443 8444 Most Fortran 90 compilers provide a way to specify module directories. 8445 Some have separate flags for the directory to write module files to, 8446 and directories to search them in, whereas others only allow writing to 8447 the current directory or to the first directory specified in the include 8448 path. Further, with some compilers, the module search path and the 8449 preprocessor search path can only be modified with the same flag. Thus, 8450 for portability, write module files to the current directory only and 8451 list that as first directory in the search path. 8452 8453 There may be no whitespace between @code{FC_MODINC} and the following 8454 directory name, but @code{FC_MODINC} may contain trailing white space. 8455 For example, if you use Automake and would like to search @file{../lib} 8456 for module files, you can use the following: 8457 8458 @example 8459 AM_FCFLAGS = $(FC_MODINC). $(FC_MODINC)../lib 8460 @end example 8461 8462 Inside @command{configure} tests, you can use: 8463 8464 @example 8465 if test -n "$FC_MODINC"; then 8466 FCFLAGS="$FCFLAGS $FC_MODINC. $FC_MODINC../lib" 8467 fi 8468 @end example 8469 8470 The flag is cached in the @code{ac_cv_fc_module_flag} variable. 8471 The substituted value of @code{FC_MODINC} may refer to the 8472 @code{ac_empty} dummy placeholder empty variable, to avoid losing 8473 the 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 8482 Find the compiler flag to write Fortran 90 module information to 8483 another directory, and store that in the @code{FC_MODOUT} variable. 8484 Call @var{action-if-success} (defaults to nothing) if successful, and 8485 set @code{FC_MODOUT} to empty and call @var{action-if-failure} (defaults 8486 to exiting with an error message) if not. 8487 8488 Not all Fortran 90 compilers write module files, and of those that do, 8489 not all allow writing to a directory other than the current one, nor 8490 do all have separate flags for writing and reading; see the description 8491 of @code{AC_FC_MODULE_FLAG} above. If you need to be able to write to 8492 another directory, for maximum portability use @code{FC_MODOUT} before 8493 any @code{FC_MODINC} and include both the current directory and the one 8494 you write to in the search path: 8495 8496 @example 8497 AM_FCFLAGS = $(FC_MODOUT)../mod $(FC_MODINC)../mod $(FC_MODINC). @dots{} 8498 @end example 8499 8500 The flag is cached in the @code{ac_cv_fc_module_output_flag} variable. 8501 The substituted value of @code{FC_MODOUT} may refer to the 8502 @code{ac_empty} dummy placeholder empty variable, to avoid losing 8503 the 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 8511 Autoconf provides basic support for the Go programming language when 8512 using 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}) 8516 Find 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 8518 value. 8519 8520 Otherwise, if the macro is invoked without an argument, then search for 8521 a Go compiler named @code{gccgo}. If it is not found, then as a last 8522 resort set @code{GOC} to @code{gccgo}. 8523 8524 This macro may be invoked with an optional first argument which, if 8525 specified, must be a blank-separated list of Go compilers to search for. 8526 8527 If 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 8536 The 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 8543 Try to locate the X Window System include files and libraries. If the 8544 user gave the command line options @option{--x-includes=@var{dir}} and 8545 @option{--x-libraries=@var{dir}}, use those directories. 8546 8547 If either or both were not given, get the missing values by running 8548 @code{xmkmf} (or an executable pointed to by the @code{XMKMF} 8549 environment variable) on a trivial @file{Imakefile} and examining the 8550 makefile that it produces. Setting @code{XMKMF} to @samp{false} 8551 disables this method. 8552 8553 If this method fails to find the X Window System, @command{configure} 8554 looks for the files in several directories where they often reside. 8555 If either method is successful, set the shell variables 8556 @code{x_includes} and @code{x_libraries} to their locations, unless they 8557 are in directories the compiler searches by default. 8558 8559 If 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}; 8561 otherwise 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 8572 An enhanced version of @code{AC_PATH_X}. It adds the C compiler flags 8573 that X needs to output variable @code{X_CFLAGS}, and the X linker flags 8574 to @code{X_LIBS}. Define @code{X_DISPLAY_MISSING} if X is not 8575 available. 8576 8577 This macro also checks for special libraries that some systems need in 8578 order to compile X programs. It adds any that the system needs to 8579 output variable @code{X_EXTRA_LIBS}. And it checks for special X11R6 8580 libraries that need to be linked with before @option{-lX11}, and adds 8581 any 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} 8592 Check whether the system supports starting scripts with a line of the 8593 form @samp{#!/bin/sh} to select the interpreter to use for the script. 8594 After running this macro, shell code in @file{configure.ac} can check 8595 the shell variable @code{interpval}; it is set to @samp{yes} 8596 if 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 8606 Arrange for 64-bit file offsets, known as 8607 @uref{http://@/www.unix-systems@/.org/@/version2/@/whatsnew/@/lfs20mar.html, 8608 large-file support}. On some hosts, one must use special compiler 8609 options to build programs that can access large files. Append any such 8610 options to the output variable @code{CC}. Define 8611 @code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary. 8612 8613 Large-file support can be disabled by configuring with the 8614 @option{--disable-largefile} option. 8615 8616 If 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 8618 large-file support is enabled. For example, it is not correct to print 8619 an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld", 8620 (long int) X)}. 8621 8622 The LFS introduced the @code{fseeko} and @code{ftello} functions to 8623 replace their C counterparts @code{fseek} and @code{ftell} that do not 8624 use @code{off_t}. Take care to use @code{AC_FUNC_FSEEKO} to make their 8625 prototypes available when using them and large-file support is 8626 enabled. 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 8633 If 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 8642 Check to see if the Posix termios headers and functions are available on the 8643 system. 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 8650 The following macro makes it possible to use features of Posix that are 8651 extensions 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__ 8664 This macro was introduced in Autoconf 2.60. If possible, enable 8665 extensions to C or Posix on hosts that normally disable the extensions, 8666 typically due to standards-conformance namespace issues. This should be 8667 called before any macros that run the C compiler. The following 8668 preprocessor macros are defined where appropriate: 8669 8670 @table @code 8671 @item _GNU_SOURCE 8672 Enable extensions on GNU/Linux. 8673 @item __EXTENSIONS__ 8674 Enable general extensions on Solaris. 8675 @item _POSIX_PTHREAD_SEMANTICS 8676 Enable threading extensions on Solaris. 8677 @item _TANDEM_SOURCE 8678 Enable extensions for the HP NonStop platform. 8679 @item _ALL_SOURCE 8680 Enable extensions for AIX 3, and for Interix. 8681 @item _POSIX_SOURCE 8682 Enable Posix functions for Minix. 8683 @item _POSIX_1_SOURCE 8684 Enable additional Posix functions for Minix. 8685 @item _MINIX 8686 Identify Minix platform. This particular preprocessor macro is 8687 obsolescent, 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 8696 The following macros check for an installation of Erlang/OTP, and for the 8697 presence of certain Erlang libraries. All those macros require the 8698 configuration 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 8704 Set the output variable @code{ERLANG_ERTS_VER} to the version of the 8705 Erlang runtime system (as returned by Erlang's 8706 @code{erlang:system_info(version)} function). The result of this test 8707 is cached if caching is enabled when running @command{configure}. The 8708 @code{ERLANG_ERTS_VER} variable is not intended to be used for testing 8709 for features of specific ERTS versions, but to be used for substituting 8710 the ERTS version in Erlang/OTP release resource files (@code{.rel} 8711 files), 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 8717 Set the output variable @code{ERLANG_ROOT_DIR} to the path to the base 8718 directory 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 8720 caching 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 8726 Set the output variable @code{ERLANG_LIB_DIR} to the path of the library 8727 directory of Erlang/OTP (as returned by Erlang's 8728 @code{code:lib_dir/0} function), which subdirectories each contain an installed 8729 Erlang/OTP library. The result of this test is cached if caching is enabled 8730 when 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} 8738 Test whether the Erlang/OTP library @var{library} is installed by 8739 calling Erlang's @code{code:lib_dir/1} function. The result of this 8740 test 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 8742 is installed; @var{action-if-not-found} is a list of shell commands to 8743 run if it is not. Additionally, if the library is installed, the output 8744 variable @samp{ERLANG_LIB_DIR_@var{library}} is set to the path to the 8745 library installation directory, and the output variable 8746 @samp{ERLANG_LIB_VER_@var{library}} is set to the version number that is 8747 part of the subdirectory name, if it is in the standard form 8748 (@code{@var{library}-@var{version}}). If the directory name does not 8749 have a version part, @samp{ERLANG_LIB_VER_@var{library}} is set to the 8750 empty 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 8753 example, to check if library @code{stdlib} is installed: 8754 8755 @example 8756 AC_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 8762 The @samp{ERLANG_LIB_VER_@var{library}} variables (set by 8763 @code{AC_ERLANG_CHECK_LIB}) and the @code{ERLANG_ERTS_VER} variable (set 8764 by @code{AC_ERLANG_SUBST_ERTS_VER}) are not intended to be used for 8765 testing for features of specific versions of libraries or of the Erlang 8766 runtime system. Those variables are intended to be substituted in 8767 Erlang release resource files (@code{.rel} files). For instance, to 8768 generate a @file{example.rel} file for an application depending on the 8769 @code{stdlib} library, @file{configure.ac} could contain: 8770 8771 @example 8772 AC_ERLANG_SUBST_ERTS_VER 8773 AC_ERLANG_CHECK_LIB([stdlib], 8774 [], 8775 [AC_MSG_ERROR([stdlib was not found!])]) 8776 AC_CONFIG_FILES([example.rel]) 8777 @end example 8778 8779 @noindent 8780 The @file{example.rel.in} file used to generate @file{example.rel} 8781 should 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 8792 In addition to the above macros, which test installed Erlang libraries, the 8793 following macros determine the paths to the directories into which newly built 8794 Erlang 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 8800 Set the @code{ERLANG_INSTALL_LIB_DIR} output variable to the directory into 8801 which every built Erlang library should be installed in a separate 8802 subdirectory. 8803 If this variable is not set in the environment when @command{configure} runs, 8804 its 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 8811 Set the @samp{ERLANG_INSTALL_LIB_DIR_@var{library}} output variable to the 8812 directory into which the built Erlang library @var{library} version 8813 @var{version} should be installed. If this variable is not set in the 8814 environment 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 8829 If the existing feature tests don't do something you need, you have to 8830 write new ones. These macros are the building blocks. They provide 8831 ways for other macros to check whether various kinds of features are 8832 available and report the results. 8833 8834 This chapter contains some suggestions and some of the reasons why the 8835 existing tests are written the way they are. You can also learn a lot 8836 about how to write Autoconf tests by looking at the existing ones. If 8837 something goes wrong in one or more of the Autoconf tests, this 8838 information can help you understand the assumptions behind them, which 8839 might help you figure out how to best solve the problem. 8840 8841 These macros check the output of the compiler system of the current 8842 language (@pxref{Language Choice}). They do not cache the results of 8843 their tests for future use (@pxref{Caching Results}), because they don't 8844 know enough about the information they are checking for to generate a 8845 cache variable name. They also do not print any messages, for the same 8846 reason. The checks for particular kinds of features call these macros 8847 and do cache their results and print messages about what they're 8848 checking for. 8849 8850 When you write a feature test that could be applicable to more than one 8851 software 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 8869 Autoconf-generated @command{configure} scripts check for the C compiler and 8870 its 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 8872 compilers for the respective languages. The following macros determine 8873 which 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} 8879 Do compilation tests using the compiler, preprocessor, and file 8880 extensions for the specified @var{language}. 8881 8882 Supported languages are: 8883 8884 @table @samp 8885 @item C 8886 Do 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++ 8891 Do compilation tests using @code{CXX} and @code{CXXCPP} and use 8892 extension @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 8897 Do compilation tests using @code{F77} and use extension @file{.f} for 8898 test programs. Use compilation flags: @code{FFLAGS}. 8899 8900 @item Fortran 8901 Do compilation tests using @code{FC} and use extension @file{.f} (or 8902 whatever has been set by @code{AC_FC_SRCEXT}) for test programs. Use 8903 compilation flags: @code{FCFLAGS}. 8904 8905 @item Erlang 8906 @ovindex ERLC 8907 @ovindex ERL 8908 @ovindex ERLCFLAGS 8909 Compile 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 8913 Do compilation tests using @code{OBJC} and @code{OBJCPP} and use 8914 extension @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++ 8919 Do compilation tests using @code{OBJCXX} and @code{OBJCXXCPP} and use 8920 extension @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 8925 Do compilation tests using @code{GOC} and use extension @file{.go} for 8926 test 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} 8933 Remember the current language (as set by @code{AC_LANG}) on a stack, and 8934 then select the @var{language}. Use this macro and @code{AC_LANG_POP} 8935 in 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} 8940 Select 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 8943 If given, @var{language} specifies the language we just @emph{quit}. It 8944 is a good idea to specify it when it's known (which should be the 8945 case@dots{}), since Autoconf detects inconsistencies. 8946 8947 @example 8948 AC_LANG_PUSH([Fortran 77]) 8949 # Perform some tests on Fortran 77. 8950 # @dots{} 8951 AC_LANG_POP([Fortran 77]) 8952 @end example 8953 @end defmac 8954 8955 @defmac AC_LANG_ASSERT (@var{language}) 8956 @acindex{LANG_ASSERT} 8957 Check statically that the current language is @var{language}. 8958 You should use this in your language specific macros 8959 to avoid that they be called with an inappropriate language. 8960 8961 This macro runs only at @command{autoconf} time, and incurs no cost at 8962 @command{configure} time. Sadly enough and because Autoconf is a two 8963 layer language @footnote{Because M4 is not aware of Sh code, 8964 especially conditionals, some optimizations that look nice statically 8965 may produce incorrect results at runtime.}, the macros 8966 @code{AC_LANG_PUSH} and @code{AC_LANG_POP} cannot be ``optimizing'', 8967 therefore as much as possible you ought to avoid using them to wrap 8968 your code, rather, require from the user to run the macro with a 8969 correct current language, and check it with @code{AC_LANG_ASSERT}. 8970 And anyway, that may help the user understand she is running a Fortran 8971 macro while expecting a result about her Fortran 77 compiler@enddots{} 8972 @end defmac 8973 8974 8975 @defmac AC_REQUIRE_CPP 8976 @acindex{REQUIRE_CPP} 8977 Ensure that whichever preprocessor would currently be used for tests has 8978 been found. Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an 8979 argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP}, 8980 depending on which language is current. 8981 @end defmac 8982 8983 8984 @node Writing Test Programs 8985 @section Writing Test Programs 8986 8987 Autoconf tests follow a common scheme: feed some program with some 8988 input, and most of the time, feed a compiler with some source file. 8989 This 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 9000 The most important rule to follow when writing testing samples is: 9001 9002 @center @emph{Look for realism.} 9003 9004 This motto means that testing samples must be written with the same 9005 strictness as real programs are written. In particular, you should 9006 avoid ``shortcuts'' and simplifications. 9007 9008 Don't just play with the preprocessor if you want to prepare a 9009 compilation. For instance, using @command{cpp} to check whether a header is 9010 functional might let your @command{configure} accept a header which 9011 causes some @emph{compiler} error. Do not hesitate to check a header with 9012 other headers included before, especially required headers. 9013 9014 Make sure the symbols you use are properly defined, i.e., refrain from 9015 simply declaring a function yourself instead of including the proper 9016 header. 9017 9018 Test programs should not write to standard output. They 9019 should exit with status 0 if the test succeeds, and with status 1 9020 otherwise, so that success 9021 can be distinguished easily from a core dump or other failure; 9022 segmentation violations and other failures produce a nonzero exit 9023 status. Unless you arrange for @code{exit} to be declared, test 9024 programs should @code{return}, not @code{exit}, from @code{main}, 9025 because on many systems @code{exit} is not declared by default. 9026 9027 Test programs can use @code{#if} or @code{#ifdef} to check the values of 9028 preprocessor macros defined by tests that have already run. For 9029 example, 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 9041 Both @code{#if HAVE_STDBOOL_H} and @code{#ifdef HAVE_STDBOOL_H} will 9042 work with any standard C compiler. Some developers prefer @code{#if} 9043 because it is easier to read, while others prefer @code{#ifdef} because 9044 it avoids diagnostics with picky compilers like GCC with the 9045 @option{-Wundef} option. 9046 9047 If a test program needs to use or create a data file, give it a name 9048 that starts with @file{conftest}, such as @file{conftest.data}. The 9049 @command{configure} script cleans up by running @samp{rm -f -r conftest*} 9050 after running test programs and if the script is interrupted. 9051 9052 @node Test Functions 9053 @subsection Test Functions 9054 9055 These days it's safe to assume support for function prototypes 9056 (introduced in C89). 9057 9058 Functions that test programs declare should also be conditionalized for 9059 C++, which requires @samp{extern "C"} prototypes. Make sure to not 9060 include any header files containing clashing prototypes. 9061 9062 @example 9063 #ifdef __cplusplus 9064 extern "C" 9065 #endif 9066 void *valloc (size_t); 9067 @end example 9068 9069 If a test program calls a function with invalid parameters (just to see 9070 whether it exists), organize the program to ensure that it never invokes 9071 that function. You can do this by calling it in another function that is 9072 never invoked. You can't do it by putting it after a call to 9073 @code{exit}, because GCC version 2 knows that @code{exit} 9074 never returns 9075 and optimizes out any code that follows it in the same block. 9076 9077 If you include any header files, be sure to call the functions 9078 relevant to them with the correct number of arguments, even if they are 9079 just 0, to avoid compilation errors due to prototypes. GCC 9080 version 2 9081 has internal prototypes for several functions that it automatically 9082 inlines; for example, @code{memcpy}. To avoid errors when checking for 9083 them, either pass them the correct number of arguments or redeclare them 9084 with a different return type (such as @code{char}). 9085 9086 9087 @node Generating Sources 9088 @subsection Generating Sources 9089 9090 Autoconf provides a set of macros that can be used to generate test 9091 source files. They are written to be language generic, i.e., they 9092 actually 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} 9098 Save the @var{source} text in the current test source file: 9099 @file{conftest.@var{extension}} where the @var{extension} depends on the 9100 current language. As of Autoconf 2.63b, the source file also contains 9101 the results of all of the @code{AC_DEFINE} performed so far. 9102 9103 Note that the @var{source} is evaluated exactly once, like regular 9104 Autoconf macro arguments, and therefore (i) you may pass a macro 9105 invocation, (ii) if not, be sure to double quote if needed. 9106 9107 This 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 9112 This macro is seldom called directly, but is used under the hood by more 9113 common 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} 9118 This macro is called as a witness that the file 9119 @file{conftest.@var{extension}} appropriate for the current language is 9120 complete, including all previously determined results from 9121 @code{AC_DEFINE}. This macro is seldom called directly, but exists if 9122 you 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} 9129 Expands into the @var{source}, with the definition of 9130 all the @code{AC_DEFINE} performed so far. This macro includes an 9131 expansion of @code{AC_LANG_DEFINES_PROVIDED}. 9132 9133 In many cases, you may find it more convenient to use the wrapper 9134 @code{AC_LANG_PROGRAM}. 9135 @end defmac 9136 9137 For instance, executing (observe the double quotation!): 9138 9139 @example 9140 @c If you change this example, adjust tests/compile.at:AC_LANG_SOURCE example. 9141 AC_INIT([Hello], [1.0], [bug-hello@@example.org], [], 9142 [http://www.example.org/]) 9143 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"], 9144 [Greetings string.]) 9145 AC_LANG([C]) 9146 AC_LANG_CONFTEST( 9147 [AC_LANG_SOURCE([[const char hw[] = "Hello, World\n";]])]) 9148 gcc -E -dD conftest.c 9149 @end example 9150 9151 @noindent 9152 on 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 9167 const char hw[] = "Hello, World\n"; 9168 @end example 9169 9170 When the test language is Fortran, Erlang, or Go, the @code{AC_DEFINE} 9171 definitions are not automatically translated into constants in the 9172 source code by this macro. 9173 9174 @defmac AC_LANG_PROGRAM (@var{prologue}, @var{body}) 9175 @acindex{LANG_PROGRAM} 9176 Expands into a source file which consists of the @var{prologue}, and 9177 then @var{body} as body of the main function (e.g., @code{main} in 9178 C). Since it uses @code{AC_LANG_SOURCE}, the features of the latter are 9179 available. 9180 @end defmac 9181 9182 For instance: 9183 9184 @example 9185 @c If you change this example, adjust tests/compile.at:AC_LANG_PROGRAM example. 9186 AC_INIT([Hello], [1.0], [bug-hello@@example.org], [], 9187 [http://www.example.org/]) 9188 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"], 9189 [Greetings string.]) 9190 AC_LANG_CONFTEST( 9191 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]], 9192 [[fputs (hw, stdout);]])]) 9193 gcc -E -dD conftest.c 9194 @end example 9195 9196 @noindent 9197 on 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 9212 const char hw[] = "Hello, World\n"; 9213 int 9214 main () 9215 @{ 9216 fputs (hw, stdout); 9217 ; 9218 return 0; 9219 @} 9220 @end example 9221 9222 In Erlang tests, the created source file is that of an Erlang module called 9223 @code{conftest} (@file{conftest.erl}). This module defines and exports 9224 at least 9225 one @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 9227 the @code{start/0} function definition. @var{body} is the body of the 9228 @code{start/0} function without the final period (@pxref{Runtime}, about 9229 constraints on this function's behavior). 9230 9231 For instance: 9232 9233 @example 9234 AC_INIT([Hello], [1.0], [bug-hello@@example.org]) 9235 AC_LANG(Erlang) 9236 AC_LANG_CONFTEST( 9237 [AC_LANG_PROGRAM([[-define(HELLO_WORLD, "Hello, world!").]], 9238 [[io:format("~s~n", [?HELLO_WORLD])]])]) 9239 cat conftest.erl 9240 @end example 9241 9242 @noindent 9243 results in: 9244 9245 @example 9246 -module(conftest). 9247 -export([start/0]). 9248 -define(HELLO_WORLD, "Hello, world!"). 9249 start() -> 9250 io:format("~s~n", [?HELLO_WORLD]) 9251 . 9252 @end example 9253 9254 @defmac AC_LANG_CALL (@var{prologue}, @var{function}) 9255 @acindex{LANG_CALL} 9256 Expands into a source file which consists of the @var{prologue}, and 9257 then 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 9259 of the latter are available. 9260 9261 This function will probably be replaced in the future by a version 9262 which would enable specifying the arguments. The use of this macro is 9263 not encouraged, as it violates strongly the typing system. 9264 9265 This 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} 9270 Expands into a source file which uses the @var{function} in the body of 9271 the main function (e.g., @code{main} in C). Since it uses 9272 @code{AC_LANG_PROGRAM}, the features of the latter are available. 9273 9274 As @code{AC_LANG_CALL}, this macro is documented only for completeness. 9275 It is considered to be severely broken, and in the future will be 9276 removed in favor of actual function calls (with properly typed 9277 arguments). 9278 9279 This macro cannot be used for Erlang tests. 9280 @end defmac 9281 9282 @node Running the Preprocessor 9283 @section Running the Preprocessor 9284 9285 Sometimes 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} 9287 your project, not merely run the preprocessor on it; therefore you 9288 certainly want to run the compiler, not the preprocessor. Resist the 9289 temptation of following the easiest path. 9290 9291 Nevertheless, if you need to run the preprocessor, then use 9292 @code{AC_PREPROC_IFELSE}. 9293 9294 The macros described in this section cannot be used for tests in Erlang, 9295 Fortran, 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} 9301 Run the preprocessor of the current language (@pxref{Language Choice}) 9302 on the @var{input}, run the shell commands @var{action-if-true} on 9303 success, @var{action-if-false} otherwise. The @var{input} can be made 9304 by @code{AC_LANG_PROGRAM} and friends. 9305 9306 This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because 9307 @option{-g}, @option{-O}, etc.@: are not valid options to many C 9308 preprocessors. 9309 9310 It is customary to report unexpected failures with 9311 @code{AC_MSG_FAILURE}. If needed, @var{action-if-true} can further access 9312 the preprocessed output in the file @file{conftest.i}. 9313 @end defmac 9314 9315 For instance: 9316 9317 @example 9318 AC_INIT([Hello], [1.0], [bug-hello@@example.org]) 9319 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"], 9320 [Greetings string.]) 9321 AC_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 9329 results in: 9330 9331 @example 9332 checking for gcc... gcc 9333 checking for C compiler default output file name... a.out 9334 checking whether the C compiler works... yes 9335 checking whether we are cross compiling... no 9336 checking for suffix of executables... 9337 checking for suffix of object files... o 9338 checking whether we are using the GNU C compiler... yes 9339 checking whether gcc accepts -g... yes 9340 checking for gcc option to accept ISO C89... none needed 9341 checking how to run the C preprocessor... gcc -E 9342 OK 9343 @end example 9344 9345 @sp 1 9346 9347 The macro @code{AC_TRY_CPP} (@pxref{Obsolete Macros}) used to play the 9348 role of @code{AC_PREPROC_IFELSE}, but double quotes its argument, making 9349 it impossible to use it to elaborate sources. You are encouraged to 9350 get 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 9352 to 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} 9358 If 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 9361 execute @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 9369 variable, back quote, and backslash substitutions are performed. If the 9370 output of running the preprocessor on @var{program} matches the 9371 extended 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 9380 To check for a syntax feature of the current language's (@pxref{Language 9381 Choice}) compiler, such as whether it recognizes a certain keyword, or 9382 simply to try some library feature, use @code{AC_COMPILE_IFELSE} to try 9383 to 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} 9388 Run 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 9393 It 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 9396 Linker}). If needed, @var{action-if-true} can further access the 9397 just-compiled object file @file{conftest.$OBJEXT}. 9398 9399 This macro uses @code{AC_REQUIRE} for the compiler associated with the 9400 current language, which means that if the compiler has not yet been 9401 determined, the compiler determination will be made prior to the body of 9402 the outermost @code{AC_DEFUN} macro that triggered this macro to 9403 expand (@pxref{Expanded Before Required}). 9404 @end defmac 9405 9406 @ovindex ERL 9407 For 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} 9409 file that can be interpreted by the Erlang virtual machine (@code{ERL}). It is 9410 recommended to use @code{AC_LANG_PROGRAM} to specify the test program, 9411 to ensure that the Erlang module has the right name. 9412 9413 @node Running the Linker 9414 @section Running the Linker 9415 9416 To check for a library, a function, or a global variable, Autoconf 9417 @command{configure} scripts try to compile and link a small program that 9418 uses 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 9420 available. Trying to link with the function is usually a more reliable 9421 approach because it avoids dealing with the variations in the options 9422 and output formats of @code{nm} and @code{ar} and in the location of the 9423 standard libraries. It also allows configuring for cross-compilation or 9424 checking a function's runtime behavior if needed. On the other hand, 9425 it can be slower than scanning the libraries once, but accuracy is more 9426 important than speed. 9427 9428 @code{AC_LINK_IFELSE} is used to compile test programs to test for 9429 functions and global variables. It is also used by @code{AC_CHECK_LIB} 9430 to check for libraries (@pxref{Libraries}), by adding the library being 9431 checked for to @code{LIBS} temporarily and trying to link a small 9432 program. 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} 9438 Run the compiler (and compilation flags) and the linker of the current 9439 language (@pxref{Language Choice}) on the @var{input}, run the shell 9440 commands @var{action-if-true} on success, @var{action-if-false} 9441 otherwise. The @var{input} can be made by @code{AC_LANG_PROGRAM} and 9442 friends. If needed, @var{action-if-true} can further access the 9443 just-linked program file @file{conftest$EXEEXT}. 9444 9445 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the 9446 current compilation flags. 9447 9448 It is customary to report unexpected failures with 9449 @code{AC_MSG_FAILURE}. This macro does not try to execute the program; 9450 use @code{AC_RUN_IFELSE} if you need to do that (@pxref{Runtime}). 9451 @end defmac 9452 9453 The @code{AC_LINK_IFELSE} macro cannot be used for Erlang tests, since Erlang 9454 programs are interpreted and do not require linking. 9455 9456 9457 9458 @node Runtime 9459 @section Checking Runtime Behavior 9460 9461 Sometimes you need to find out how a system performs at runtime, such 9462 as whether a given function has a certain capability or bug. If you 9463 can, make such checks when your program runs instead of when it is 9464 configured. You can check for things like the machine's endianness when 9465 your program initializes itself. 9466 9467 If you really need to test for a runtime behavior while configuring, 9468 you can write a test program to determine the result, and compile and 9469 run it using @code{AC_RUN_IFELSE}. Avoid running test programs if 9470 possible, because this prevents people from configuring your package for 9471 cross-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} 9477 Run the compiler (and compilation flags) and the linker of the current 9478 language (@pxref{Language Choice}) on the @var{input}, then execute the 9479 resulting program. If the program returns an exit 9480 status of 0 when executed, run shell commands @var{action-if-true}. 9481 Otherwise, run shell commands @var{action-if-false}. 9482 9483 The @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 9485 compilation flags of the current language (@pxref{Language Choice}). 9486 Additionally, @var{action-if-true} can run @command{./conftest$EXEEXT} 9487 for further testing. 9488 9489 In the @var{action-if-false} section, the failing exit status is 9490 available in the shell variable @samp{$?}. This exit status might be 9491 that of a failed compilation, or it might be that of a failed program 9492 execution. 9493 9494 If cross-compilation mode is enabled (this is the case if either the 9495 compiler being used does not produce executables that run on the system 9496 where @command{configure} is being run, or if the options @code{--build} 9497 and @code{--host} were both specified and their values are different), 9498 then the test program is 9499 not run. If the optional shell commands @var{action-if-cross-compiling} 9500 are given, those commands are run instead; typically these commands 9501 provide pessimistic defaults that allow cross-compilation to work even 9502 if the guess was wrong. If the fourth argument is empty or omitted, but 9503 cross-compilation is detected, then @command{configure} prints an error 9504 message and exits. If you want your package to be useful in a 9505 cross-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 9509 pessimistic default if needed. 9510 9511 It 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 9518 given. If you are not concerned about users configuring your package 9519 for cross-compilation, you may ignore the warning. A few of the macros 9520 distributed with Autoconf produce this warning message; but if this is a 9521 problem for you, please report it as a bug, along with an appropriate 9522 pessimistic guess to use instead. 9523 9524 To configure for cross-compiling you can also choose a value for those 9525 parameters based on the canonical system name (@pxref{Manual 9526 Configuration}). Alternatively, set up a test results cache file with 9527 the correct values for the host system (@pxref{Caching Results}). 9528 9529 @ovindex cross_compiling 9530 To provide a default for calls of @code{AC_RUN_IFELSE} that are embedded 9531 in other macros, including a few of the ones that come with Autoconf, 9532 you 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 9534 of calling the macros. 9535 9536 It is also permissible to temporarily assign to @code{cross_compiling} 9537 in order to force tests to behave as though they are in a 9538 cross-compilation environment, particularly since this provides a way to 9539 test your @var{action-if-cross-compiling} even when you are not using a 9540 cross-compiler. 9541 9542 @example 9543 # We temporarily set cross-compile mode to force AC_COMPUTE_INT 9544 # to use the slow link-only method 9545 save_cross_compiling=$cross_compiling 9546 cross_compiling=yes 9547 AC_COMPUTE_INT([@dots{}]) 9548 cross_compiling=$save_cross_compiling 9549 @end example 9550 9551 A C or C++ runtime test should be portable. 9552 @xref{Portable C and C++}. 9553 9554 Erlang tests must exit themselves the Erlang VM by calling the @code{halt/1} 9555 function: 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 9557 explained 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. 9559 Therefore, if a test must output configuration information, it is recommended 9560 to create and to output data into the temporary file named @file{conftest.out}, 9561 using the functions of module @code{file}. The @code{conftest.out} file is 9562 automatically deleted by the @code{AC_RUN_IFELSE} macro. For instance, a 9563 simplified implementation of Autoconf's @code{AC_ERLANG_SUBST_LIB_DIR} 9564 macro is: 9565 9566 @example 9567 AC_INIT([LibdirTest], [1.0], [bug-libdirtest@@example.org]) 9568 AC_ERLANG_NEED_ERL 9569 AC_LANG(Erlang) 9570 AC_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 9583 This section aims at presenting some systems and pointers to 9584 documentation. It may help you addressing particular problems reported 9585 by users. 9586 9587 @uref{http://@/www.opengroup.org/@/susv3, Posix-conforming systems} are 9588 derived from the @uref{http://@/www.bell-labs.com/@/history/@/unix/, Unix 9589 operating system}. 9590 9591 The @uref{http://@/bhami.com/@/rosetta.html, Rosetta Stone for Unix} 9592 contains a table correlating the features of various Posix-conforming 9593 systems. @uref{http://@/www.levenez.com/@/unix/, Unix History} is a 9594 simplified diagram of how many Unix systems were derived from each 9595 other. 9596 9597 @uref{http://@/heirloom.sourceforge.net/, The Heirloom Project} 9598 provides some variants of traditional implementations of Unix utilities. 9599 9600 @table @asis 9601 @item Darwin 9602 @cindex Darwin 9603 Darwin is also known as Mac OS X@. Beware that the file system @emph{can} be 9604 case-preserving, but case insensitive. This can cause nasty problems, 9605 since for instance the installation attempt for a package having an 9606 @file{INSTALL} file can result in @samp{make install} report that 9607 nothing was to be done! 9608 9609 That's all dependent on whether the file system is a UFS (case 9610 sensitive) or HFS+ (case preserving). By default Apple wants you to 9611 install the OS on HFS+. Unfortunately, there are some pieces of 9612 software which really need to be built on UFS@. We may want to rebuild 9613 Darwin to have both UFS and HFS+ available (and put the /local/build 9614 tree 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. 9621 QNX is a realtime operating system running on Intel architecture 9622 meant to be scalable from the small embedded systems to the hundred 9623 processor super-computer. It claims to be Posix certified. More 9624 information 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/, 9630 Documentation of several versions of Tru64} is available in different 9631 formats. 9632 9633 @item Unix version 7 9634 @cindex Unix version 7 9635 @cindex V7 9636 Officially this was called the ``Seventh Edition'' of ``the UNIX 9637 time-sharing system'' but we use the more-common name ``Unix version 7''. 9638 Documentation is available in the 9639 @uref{http://@/plan9.bell-labs.com/@/7thEdMan/, Unix Seventh Edition Manual}. 9640 Previous versions of Unix are called ``Unix version 6'', etc., but 9641 they were not as widely used. 9642 @end table 9643 9644 9645 @node Multiple Cases 9646 @section Multiple Cases 9647 9648 Some operations are accomplished in several possible ways, depending on 9649 the OS variant. Checking for them essentially requires a ``case 9650 statement''. Autoconf does not directly provide one; however, it is 9651 easy to simulate by using a shell variable to keep track of whether a 9652 way to perform the operation has been found yet. 9653 9654 Here is an example that uses the shell variable @code{fstype} to keep 9655 track of whether the remaining cases need to be checked. Note that 9656 since the value of @code{fstype} is under our control, we don't have to 9657 use the longer @samp{test "x$fstype" = xno}. 9658 9659 @example 9660 @group 9661 AC_MSG_CHECKING([how to get file system type]) 9662 fstype=no 9663 # The order of these tests is important. 9664 AC_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]) 9669 if 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]) 9675 fi 9676 if 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]) 9682 fi 9683 # (more cases omitted here) 9684 AC_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 9693 Once @command{configure} has determined whether a feature exists, what can 9694 it do to record that information? There are four sorts of things it can 9695 do: define a C preprocessor symbol, set a variable in the output files, 9696 save the result in a cache file for future @command{configure} runs, and 9697 print 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 9710 A common action to take in response to a feature test is to define a C 9711 preprocessor symbol indicating the results of the test. That is done by 9712 calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}. 9713 9714 By default, @code{AC_OUTPUT} places the symbols defined by these macros 9715 into the output variable @code{DEFS}, which contains an option 9716 @option{-D@var{symbol}=@var{value}} for each symbol defined. Unlike in 9717 Autoconf version 1, there is no variable @code{DEFS} defined while 9718 @command{configure} is running. To check whether Autoconf macros have 9719 already defined a certain C preprocessor symbol, test the value of the 9720 appropriate cache variable, as in this example: 9721 9722 @example 9723 AC_CHECK_FUNC([vprintf], [AC_DEFINE([HAVE_VPRINTF], [1], 9724 [Define if vprintf exists.])]) 9725 if test "x$ac_cv_func_vprintf" != xyes; then 9726 AC_CHECK_FUNC([_doprnt], [AC_DEFINE([HAVE_DOPRNT], [1], 9727 [Define if _doprnt exists.])]) 9728 fi 9729 @end example 9730 9731 If @code{AC_CONFIG_HEADERS} has been called, then instead of creating 9732 @code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the 9733 correct values into @code{#define} statements in a template file. 9734 @xref{Configuration Headers}, for more information about this kind of 9735 output. 9736 9737 @defmac AC_DEFINE (@var{variable}, @var{value}, @ovar{description}) 9738 @defmacx AC_DEFINE (@var{variable}) 9739 @cvindex @var{variable} 9740 @acindex{DEFINE} 9741 Define @var{variable} to @var{value} (verbatim), by defining a C 9742 preprocessor macro for @var{variable}. @var{variable} should be a C 9743 identifier, optionally suffixed by a parenthesized argument list to 9744 define a C preprocessor macro with arguments. The macro argument list, 9745 if present, should be a comma-separated list of C identifiers, possibly 9746 terminated by an ellipsis @samp{...} if C99 syntax is employed. 9747 @var{variable} should not contain comments, white space, trigraphs, 9748 backslash-newlines, universal character names, or non-ASCII 9749 characters. 9750 9751 @var{value} may contain backslash-escaped newlines, which will be 9752 preserved if you use @code{AC_CONFIG_HEADERS} but flattened if passed 9753 via @code{@@DEFS@@} (with no effect on the compilation, since the 9754 preprocessor sees only one line in the first place). @var{value} should 9755 not contain raw newlines. If you are not using 9756 @code{AC_CONFIG_HEADERS}, @var{value} should not contain any @samp{#} 9757 characters, as @command{make} tends to eat them. To use a shell 9758 variable, 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 9762 the generated @file{config.h.in} as the comment before the macro define. 9763 The following example defines the C preprocessor variable 9764 @code{EQUATION} to be the string constant @samp{"$a > $b"}: 9765 9766 @example 9767 AC_DEFINE([EQUATION], ["$a > $b"], 9768 [Equation string.]) 9769 @end example 9770 9771 If neither @var{value} nor @var{description} are given, then 9772 @var{value} defaults to 1 instead of to the empty string. This is for 9773 backwards compatibility with older versions of Autoconf, but this usage 9774 is obsolescent and may be withdrawn in future versions of Autoconf. 9775 9776 If the @var{variable} is a literal string, it is passed to 9777 @code{m4_pattern_allow} (@pxref{Forbidden Patterns}). 9778 9779 If multiple @code{AC_DEFINE} statements are executed for the same 9780 @var{variable} name (not counting any parenthesized argument list), 9781 the 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} 9788 Like @code{AC_DEFINE}, but three shell expansions are 9789 performed---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 9792 characters in the value have no 9793 special meaning. Use this macro instead of @code{AC_DEFINE} when 9794 @var{variable} or @var{value} is a shell variable. Examples: 9795 9796 @example 9797 AC_DEFINE_UNQUOTED([config_machfile], ["$machfile"], 9798 [Configuration machine file.]) 9799 AC_DEFINE_UNQUOTED([GETGROUPS_T], [$ac_cv_type_getgroups], 9800 [getgroups return type.]) 9801 AC_DEFINE_UNQUOTED([$ac_tr_hdr], [1], 9802 [Translated header name.]) 9803 @end example 9804 @end defmac 9805 9806 Due to a syntactical bizarreness of the Bourne shell, do not use 9807 semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED} 9808 calls from other macro calls or shell code; that can cause syntax errors 9809 in the resulting @command{configure} script. Use either blanks or 9810 newlines. That is, do this: 9811 9812 @example 9813 AC_CHECK_HEADER([elf.h], 9814 [AC_DEFINE([SVR4], [1], [System V Release 4]) LIBS="-lelf $LIBS"]) 9815 @end example 9816 9817 @noindent 9818 or this: 9819 9820 @example 9821 AC_CHECK_HEADER([elf.h], 9822 [AC_DEFINE([SVR4], [1], [System V Release 4]) 9823 LIBS="-lelf $LIBS"]) 9824 @end example 9825 9826 @noindent 9827 instead of this: 9828 9829 @example 9830 AC_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 9838 Another way to record the results of tests is to set @dfn{output 9839 variables}, which are shell variables whose values are substituted into 9840 files that @command{configure} outputs. The two macros below create new 9841 output variables. @xref{Preset Output Variables}, for a list of output 9842 variables that are always available. 9843 9844 @defmac AC_SUBST (@var{variable}, @ovar{value}) 9845 @acindex{SUBST} 9846 Create an output variable from a shell variable. Make @code{AC_OUTPUT} 9847 substitute the variable @var{variable} into output files (typically one 9848 or more makefiles). This means that @code{AC_OUTPUT} 9849 replaces instances of @samp{@@@var{variable}@@} in input files with the 9850 value that the shell variable @var{variable} has when @code{AC_OUTPUT} 9851 is called. The value can contain any non-@code{NUL} character, including 9852 newline. If you are using Automake 1.11 or newer, for newlines in values 9853 you 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, , 9856 Automake, automake, Other things Automake recognizes}). 9857 9858 Variable occurrences should not overlap: e.g., an input file should 9859 not contain @samp{@@@var{var1}@@@var{var2}@@} if @var{var1} and @var{var2} 9860 are variable names. 9861 The substituted value is not rescanned for more output variables; 9862 occurrences of @samp{@@@var{variable}@@} in the value are inserted 9863 literally into the output file. (The algorithm uses the special marker 9864 @code{|#_!!_#|} internally, so neither the substituted value nor the 9865 output file may contain @code{|#_!!_#|}.) 9866 9867 If @var{value} is given, in addition assign it to @var{variable}. 9868 9869 The 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} 9875 Another way to create an output variable from a shell variable. Make 9876 @code{AC_OUTPUT} insert (without substitutions) the contents of the file 9877 named by shell variable @var{variable} into output files. This means 9878 that @code{AC_OUTPUT} replaces instances of 9879 @samp{@@@var{variable}@@} in output files (such as @file{Makefile.in}) 9880 with the contents of the file that the shell variable @var{variable} 9881 names when @code{AC_OUTPUT} is called. Set the variable to 9882 @file{/dev/null} for cases that do not have a file to insert. 9883 This substitution occurs only when the @samp{@@@var{variable}@@} is on a 9884 line by itself, optionally surrounded by spaces and tabs. The 9885 substitution replaces the whole line, including the spaces, tabs, and 9886 the terminating newline. 9887 9888 This macro is useful for inserting makefile fragments containing 9889 special dependencies or other @command{make} directives for particular host 9890 or target types into makefiles. For example, @file{configure.ac} 9891 could contain: 9892 9893 @example 9894 AC_SUBST_FILE([host_frag]) 9895 host_frag=$srcdir/conf/sun4.mh 9896 @end example 9897 9898 @noindent 9899 and then a @file{Makefile.in} could contain: 9900 9901 @example 9902 @@host_frag@@ 9903 @end example 9904 9905 The 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 9911 Running @command{configure} in varying environments can be extremely 9912 dangerous. If for instance the user runs @samp{CC=bizarre-cc 9913 ./configure}, then the cache, @file{config.h}, and many other output 9914 files depend upon @command{bizarre-cc} being the C compiler. If 9915 for some reason the user runs @command{./configure} again, or if it is 9916 run via @samp{./config.status --recheck}, (@xref{Automatic Remaking}, 9917 and @pxref{config.status Invocation}), then the configuration can be 9918 inconsistent, composed of results depending upon two different 9919 compilers. 9920 9921 Environment variables that affect this situation, such as @samp{CC} 9922 above, are called @dfn{precious variables}, and can be declared as such 9923 by @code{AC_ARG_VAR}. 9924 9925 @defmac AC_ARG_VAR (@var{variable}, @var{description}) 9926 @acindex{ARG_VAR} 9927 Declare @var{variable} is a precious variable, and include its 9928 @var{description} in the variable section of @samp{./configure --help}. 9929 9930 Being precious means that 9931 @itemize @minus 9932 @item 9933 @var{variable} is substituted via @code{AC_SUBST}. 9934 9935 @item 9936 The value of @var{variable} when @command{configure} was launched is 9937 saved in the cache, including if it was not specified on the command 9938 line but via the environment. Indeed, while @command{configure} can 9939 notice the definition of @code{CC} in @samp{./configure CC=bizarre-cc}, 9940 it is impossible to notice it in @samp{CC=bizarre-cc ./configure}, 9941 which, unfortunately, is what most users do. 9942 9943 We emphasize that it is the @emph{initial} value of @var{variable} which 9944 is saved, not that found during the execution of @command{configure}. 9945 Indeed, specifying @samp{./configure FOO=foo} and letting 9946 @samp{./configure} guess that @code{FOO} is @code{foo} can be two 9947 different 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} 9956 configure: error: `CC' was not set in the previous run 9957 configure: error: changes in the environment can compromise \ 9958 the build 9959 configure: error: run `make distclean' and/or \ 9960 `rm config.cache' and start over 9961 @end example 9962 9963 @noindent 9964 and similarly if the variable is unset, or if its content is changed. 9965 If the content has white space changes only, then the error is degraded 9966 to 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 9971 line 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} 9976 running 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 9986 Many output variables are intended to be evaluated both by 9987 @command{make} and by the shell. Some characters are expanded 9988 differently in these two contexts, so to avoid confusion these 9989 variables' values should not contain any of the following characters: 9990 9991 @example 9992 " # $ & ' ( ) * ; < > ? [ \ ^ ` | 9993 @end example 9994 9995 Also, these variables' values should neither contain newlines, nor start 9996 with @samp{~}, nor contain white space or @samp{:} immediately followed 9997 by @samp{~}. The values can contain nonempty sequences of white space 9998 characters like tabs and spaces, but each such sequence might 9999 arbitrarily be replaced by a single space during substitution. 10000 10001 These restrictions apply both to the values that @command{configure} 10002 computes, and to the values set directly by the user. For example, the 10003 following invocations of @command{configure} are problematic, since they 10004 attempt to use special characters within @code{CPPFLAGS} and white space 10005 within @code{$(srcdir)}: 10006 10007 @example 10008 CPPFLAGS='-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 10017 To 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 10021 runs with caching enabled and finds a cache file, it reads the results 10022 of previous runs from the cache and avoids rerunning those checks. As a 10023 result, @command{configure} can then run much faster than if it had to 10024 perform all of the checks every time. 10025 10026 @defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it}) 10027 @acindex{CACHE_VAL} 10028 Ensure that the results of the check identified by @var{cache-id} are 10029 available. If the results of the check were in the cache file that was 10030 read, and @command{configure} was not given the @option{--quiet} or 10031 @option{--silent} option, print a message saying that the result was 10032 cached; otherwise, run the shell commands @var{commands-to-set-it}. If 10033 the shell commands are run to determine the value, the value is 10034 saved in the cache file just before @command{configure} creates its output 10035 files. @xref{Cache Variable Names}, for how to choose the name of the 10036 @var{cache-id} variable. 10037 10038 The @var{commands-to-set-it} @emph{must have no side effects} except for 10039 setting 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} 10045 A wrapper for @code{AC_CACHE_VAL} that takes care of printing the 10046 messages. This macro provides a convenient shorthand for the most 10047 common 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 10051 The @var{commands-to-set-it} @emph{must have no side effects} except for 10052 setting the variable @var{cache-id}, see below. 10053 @end defmac 10054 10055 It 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 10060 instance, the following macro is broken: 10061 10062 @example 10063 @c If you change this example, adjust tests/base.at:AC_CACHE_CHECK. 10064 @group 10065 AC_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 10078 This 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 10080 is: 10081 10082 @example 10083 @c If you change this example, adjust tests/base.at:AC_CACHE_CHECK. 10084 @group 10085 AC_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 10097 Also, @var{commands-to-set-it} should not print any messages, for 10098 example with @code{AC_MSG_CHECKING}; do that before calling 10099 @code{AC_CACHE_VAL}, so the messages are printed regardless of whether 10100 the results of the check are retrieved from the cache or determined by 10101 running 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 10113 The 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 10120 for 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} 10125 An abbreviation for your package or organization; the same prefix you 10126 begin local Autoconf macros with, except lowercase by convention. 10127 For cache values used by the distributed Autoconf macros, this value is 10128 @samp{ac}. 10129 10130 @item @code{_cv_} 10131 Indicates that this shell variable is a cache value. This string 10132 @emph{must} be present in the variable name, including the leading 10133 underscore. 10134 10135 @item @var{value-type} 10136 A convention for classifying cache values, to produce a rational naming 10137 system. The values used in Autoconf are listed in @ref{Macro Names}. 10138 10139 @item @var{specific-value} 10140 Which member of the class of cache values this test applies to. 10141 For example, which function (@samp{alloca}), program (@samp{gcc}), or 10142 output variable (@samp{INSTALL}). 10143 10144 @item @var{additional-options} 10145 Any particular behavior of the specific member that this test applies to. 10146 For example, @samp{broken} or @samp{set}. This part of the name may 10147 be omitted if it does not apply. 10148 @end table 10149 10150 The values assigned to cache variables may not contain newlines. 10151 Usually, their values are Boolean (@samp{yes} or @samp{no}) or the 10152 names of files or functions; so this is not an important restriction. 10153 @ref{Cache Variable Index} for an index of cache variables with 10154 documented semantics. 10155 10156 10157 @node Cache Files 10158 @subsection Cache Files 10159 10160 A cache file is a shell script that caches the results of configure 10161 tests run on one system so they can be shared between configure scripts 10162 and configure runs. It is not useful on other systems. If its contents 10163 are invalid for some reason, the user may delete or edit it, or override 10164 documented cache variables on the @command{configure} command line. 10165 10166 By default, @command{configure} uses no cache file, 10167 to avoid problems caused by accidental 10168 use of stale cache files. 10169 10170 To enable caching, @command{configure} accepts @option{--config-cache} (or 10171 @option{-C}) to cache results in the file @file{config.cache}. 10172 Alternatively, @option{--cache-file=@var{file}} specifies that 10173 @var{file} be the cache file. The cache file is created if it does not 10174 exist already. When @command{configure} calls @command{configure} scripts in 10175 subdirectories, it uses the @option{--cache-file} argument so that they 10176 share the same cache. @xref{Subdirectories}, for information on 10177 configuring subdirectories with the @code{AC_CONFIG_SUBDIRS} macro. 10178 10179 @file{config.status} only pays attention to the cache file if it is 10180 given the @option{--recheck} option, which makes it rerun 10181 @command{configure}. 10182 10183 It is wrong to try to distribute cache files for particular system types. 10184 There is too much room for error in doing that, and too much 10185 administrative overhead in maintaining them. For any features that 10186 can't be guessed automatically, use the standard method of the canonical 10187 system type and linking files (@pxref{Manual Configuration}). 10188 10189 The site initialization script can specify a site-wide cache file to 10190 use, instead of the usual per-program cache. In this case, the cache 10191 file gradually accumulates information whenever someone runs a new 10192 @command{configure} script. (Running @command{configure} merges the new cache 10193 results with the existing cache file.) This may cause problems, 10194 however, if the system configuration (e.g., the installed libraries or 10195 compilers) changes and the stale cache file is not deleted. 10196 10197 If @command{configure} is interrupted at the right time when it updates 10198 a cache file outside of the build directory where the @command{configure} 10199 script is run, it may leave behind a temporary file named after the 10200 cache file with digits following it. You may safely delete such a file. 10201 10202 10203 @node Cache Checkpointing 10204 @subsection Cache Checkpointing 10205 10206 If your configure script, or a macro called from @file{configure.ac}, happens 10207 to abort the configure process, it may be useful to checkpoint the cache 10208 a few times at key points using @code{AC_CACHE_SAVE}. Doing so 10209 reduces 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} 10215 Loads values from existing cache file, or creates a new cache file if a 10216 cache file is not found. Called automatically from @code{AC_INIT}. 10217 @end defmac 10218 10219 @defmac AC_CACHE_SAVE 10220 @acindex{CACHE_SAVE} 10221 Flushes 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 10226 For instance: 10227 10228 @example 10229 @r{ @dots{} AC_INIT, etc. @dots{}} 10230 @group 10231 # Checks for programs. 10232 AC_PROG_CC 10233 AC_PROG_AWK 10234 @r{ @dots{} more program checks @dots{}} 10235 AC_CACHE_SAVE 10236 @end group 10237 10238 @group 10239 # Checks for libraries. 10240 AC_CHECK_LIB([nsl], [gethostbyname]) 10241 AC_CHECK_LIB([socket], [connect]) 10242 @r{ @dots{} more lib checks @dots{}} 10243 AC_CACHE_SAVE 10244 @end group 10245 10246 @group 10247 # Might abort@dots{} 10248 AM_PATH_GTK([1.0.2], [], [AC_MSG_ERROR([GTK not in path])]) 10249 AM_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 10259 of information. The following macros print messages in ways appropriate 10260 for each kind. The arguments to all of them get enclosed in shell 10261 double quotes, so the shell performs variable and back-quote 10262 substitution on them. 10263 10264 These macros are all wrappers around the @command{echo} shell command. 10265 They direct output to the appropriate file descriptor (@pxref{File 10266 Descriptor Macros}). 10267 @command{configure} scripts should rarely need to run @command{echo} directly 10268 to print messages for the user. Using these macros makes it easy to 10269 change how and when each kind of message is printed; such changes need 10270 only be made to the macro definitions and all the callers change 10271 automatically. 10272 10273 To 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} 10278 Notify the user that @command{configure} is checking for a particular 10279 feature. This macro prints a message that starts with @samp{checking } 10280 and ends with @samp{...} and no newline. It must be followed by a call 10281 to @code{AC_MSG_RESULT} to print the result of the check and the 10282 newline. The @var{feature-description} should be something like 10283 @samp{whether the Fortran compiler accepts C++ comments} or @samp{for 10284 c89}. 10285 10286 This 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} 10293 Notify the user of the results of a check. @var{result-description} is 10294 almost 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 10296 to @code{AC_MSG_CHECKING}, and the @var{result-description} should be 10297 the completion of the message printed by the call to 10298 @code{AC_MSG_CHECKING}. 10299 10300 This 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} 10307 Deliver the @var{message} to the user. It is useful mainly to print a 10308 general description of the overall purpose of a group of feature checks, 10309 e.g., 10310 10311 @example 10312 AC_MSG_NOTICE([checking if stack overflow is detectable]) 10313 @end example 10314 10315 This 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} 10322 Notify the user of an error that prevents @command{configure} from 10323 completing. This macro prints an error message to the standard error 10324 output and exits @command{configure} with @var{exit-status} (@samp{$?} 10325 by 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 10329 The @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} 10335 This @code{AC_MSG_ERROR} wrapper notifies the user of an error that 10336 prevents @command{configure} from completing @emph{and} that additional 10337 details are provided in @file{config.log}. This is typically used when 10338 abnormal 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} 10344 Notify the @command{configure} user of a possible problem. This macro 10345 prints the message to the standard error output; @command{configure} 10346 continues running afterward, so macros that call @code{AC_MSG_WARN} should 10347 provide a default (back-up) behavior for the situations they warn about. 10348 @var{problem-description} should be something like @samp{ln -s seems to 10349 make 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 10360 Autoconf is written on top of two layers: @dfn{M4sugar}, which provides 10361 convenient macros for pure M4 programming, and @dfn{M4sh}, which 10362 provides macros dedicated to shell script generation. 10363 10364 As of this version of Autoconf, these two layers still contain 10365 experimental macros, whose interface might change in the future. As a 10366 matter 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 10380 The most common problem with existing macros is an improper quotation. 10381 This section, which users of Autoconf can skip, but which macro writers 10382 @emph{must} read, first justifies the quotation scheme that was chosen 10383 for Autoconf and then ends with a rule of thumb. Understanding the 10384 former 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 10400 To fully understand where proper quotation is important, you first need 10401 to know what the special characters are in Autoconf: @samp{#} introduces 10402 a comment inside which no macro expansion is performed, @samp{,} 10403 separates arguments, @samp{[} and @samp{]} are the quotes 10404 themselves@footnote{By itself, M4 uses @samp{`} and @samp{'}; it is the 10405 M4sugar 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 10409 In order to understand the delicate case of macro calls, we first have 10410 to present some obvious failures. Below they are ``obvious-ified'', 10411 but when you find them in real life, they are usually in disguise. 10412 10413 Comments, introduced by a hash and running up to the newline, are opaque 10414 tokens to the top level: active characters are turned off, and there is 10415 no macro expansion: 10416 10417 @example 10418 # define([def], ine) 10419 @result{}# define([def], ine) 10420 @end example 10421 10422 Each time there can be a macro expansion, there is a quotation 10423 expansion, i.e., one level of quotes is stripped: 10424 10425 @example 10426 int tab[10]; 10427 @result{}int tab10; 10428 [int tab[10];] 10429 @result{}int tab[10]; 10430 @end example 10431 10432 Without this in mind, the reader might try hopelessly to use her macro 10433 @code{array}: 10434 10435 @example 10436 define([array], [int tab[10];]) 10437 array 10438 @result{}int tab10; 10439 [array] 10440 @result{}array 10441 @end example 10442 10443 @noindent 10444 How 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 10451 Let's proceed on the interaction between active characters and macros 10452 with this small macro, which just returns its first argument: 10453 10454 @example 10455 define([car], [$1]) 10456 @end example 10457 10458 @noindent 10459 The 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 10461 tries to find the arguments of @code{define}. Therefore, assuming 10462 @code{car} is not already defined, it is equivalent to write: 10463 10464 @example 10465 define(car, $1) 10466 @end example 10467 10468 @noindent 10469 But, while it is acceptable for a @file{configure.ac} to avoid unnecessary 10470 quotes, it is bad practice for Autoconf macros which must both be more 10471 robust and also advocate perfect style. 10472 10473 At the top level, there are only two possibilities: either you 10474 quote or you don't: 10475 10476 @example 10477 car(foo, bar, baz) 10478 @result{}foo 10479 [car(foo, bar, baz)] 10480 @result{}car(foo, bar, baz) 10481 @end example 10482 10483 Let's pay attention to the special characters: 10484 10485 @example 10486 car(#) 10487 @error{}EOF in argument list 10488 @end example 10489 10490 The closing parenthesis is hidden in the comment; with a hypothetical 10491 quoting, the top level understood it this way: 10492 10493 @example 10494 car([#)] 10495 @end example 10496 10497 @noindent 10498 Proper quotation, of course, fixes the problem: 10499 10500 @example 10501 car([#]) 10502 @result{}# 10503 @end example 10504 10505 Here are more examples: 10506 10507 @example 10508 car(foo, bar) 10509 @result{}foo 10510 car([foo, bar]) 10511 @result{}foo, bar 10512 car((foo, bar)) 10513 @result{}(foo, bar) 10514 car([(foo], [bar)]) 10515 @result{}(foo 10516 define([a], [b]) 10517 @result{} 10518 car(a) 10519 @result{}b 10520 car([a]) 10521 @result{}b 10522 car([[a]]) 10523 @result{}a 10524 car([[[a]]]) 10525 @result{}[a] 10526 @end example 10527 10528 @node Quoting and Parameters 10529 @subsection Quoting and Parameters 10530 10531 When M4 encounters @samp{$} within a macro definition, followed 10532 immediately by a character it recognizes (@samp{0}@dots{}@samp{9}, 10533 @samp{#}, @samp{@@}, or @samp{*}), it will perform M4 parameter 10534 expansion. This happens regardless of how many layers of quotes the 10535 parameter expansion is nested within, or even if it occurs in text that 10536 will be rescanned as a comment. 10537 10538 @example 10539 define([none], [$1]) 10540 @result{} 10541 define([one], [[$1]]) 10542 @result{} 10543 define([two], [[[$1]]]) 10544 @result{} 10545 define([comment], [# $1]) 10546 @result{} 10547 define([active], [ACTIVE]) 10548 @result{} 10549 none([active]) 10550 @result{}ACTIVE 10551 one([active]) 10552 @result{}active 10553 two([active]) 10554 @result{}[active] 10555 comment([active]) 10556 @result{}# active 10557 @end example 10558 10559 On the other hand, since autoconf generates shell code, you often want 10560 to output shell variable expansion, rather than performing M4 parameter 10561 expansion. To do this, you must use M4 quoting to separate the @samp{$} 10562 from the next character in the definition of your macro. If the macro 10563 definition occurs in single-quoted text, then insert another level of 10564 quoting; if the usage is already inside a double-quoted string, then 10565 split it into concatenated strings. 10566 10567 @example 10568 define([single], [a single-quoted $[]1 definition]) 10569 @result{} 10570 define([double], [[a double-quoted $][1 definition]]) 10571 @result{} 10572 single 10573 @result{}a single-quoted $1 definition 10574 double 10575 @result{}a double-quoted $1 definition 10576 @end example 10577 10578 Posix states that M4 implementations are free to provide implementation 10579 extensions when @samp{$@{} is encountered in a macro definition. 10580 Autoconf reserves the longer sequence @samp{$@{@{} for use with planned 10581 extensions that will be available in the future GNU M4 2.0, 10582 but guarantees that all other instances of @samp{$@{} will be output 10583 literally. Therefore, this idiom can also be used to output shell code 10584 parameter references: 10585 10586 @example 10587 define([first], [$@{1@}])first 10588 @result{}$@{1@} 10589 @end example 10590 10591 Posix also states that @samp{$11} should expand to the first parameter 10592 concatenated with a literal @samp{1}, although some versions of 10593 GNU M4 expand the eleventh parameter instead. For 10594 portability, you should only use single-digit M4 parameter expansion. 10595 10596 With this in mind, we can explore the cases where macros invoke 10597 macros@enddots{} 10598 10599 @node Quotation and Nested Macros 10600 @subsection Quotation and Nested Macros 10601 10602 The examples below use the following macros: 10603 10604 @example 10605 define([car], [$1]) 10606 define([active], [ACT, IVE]) 10607 define([array], [int tab[10]]) 10608 @end example 10609 10610 Each additional embedded macro call introduces other possible 10611 interesting quotations: 10612 10613 @example 10614 car(active) 10615 @result{}ACT 10616 car([active]) 10617 @result{}ACT, IVE 10618 car([[active]]) 10619 @result{}active 10620 @end example 10621 10622 In the first case, the top level looks for the arguments of @code{car}, 10623 and finds @samp{active}. Because M4 evaluates its arguments 10624 before applying the macro, @samp{active} is expanded, which results in: 10625 10626 @example 10627 car(ACT, IVE) 10628 @result{}ACT 10629 @end example 10630 10631 @noindent 10632 In the second case, the top level gives @samp{active} as first and only 10633 argument of @code{car}, which results in: 10634 10635 @example 10636 active 10637 @result{}ACT, IVE 10638 @end example 10639 10640 @noindent 10641 i.e., the argument is evaluated @emph{after} the macro that invokes it. 10642 In 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 10650 exactly as we already saw above. 10651 10652 The example above, applied to a more realistic example, gives: 10653 10654 @example 10655 car(int tab[10];) 10656 @result{}int tab10; 10657 car([int tab[10];]) 10658 @result{}int tab10; 10659 car([[int tab[10];]]) 10660 @result{}int tab[10]; 10661 @end example 10662 10663 @noindent 10664 Huh? The first case is easily understood, but why is the second wrong, 10665 and the third right? To understand that, you must know that after 10666 M4 expands a macro, the resulting text is immediately subjected 10667 to macro expansion and quote removal. This means that the quote removal 10668 occurs twice---first before the argument is passed to the @code{car} 10669 macro, and second after the @code{car} macro expands to the first 10670 argument. 10671 10672 As the author of the Autoconf macro @code{car}, you then consider it to 10673 be 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 10675 quoted car: 10676 10677 @example 10678 define([qar], [[$1]]) 10679 @end example 10680 10681 @noindent 10682 and check that @code{qar} is properly fixed: 10683 10684 @example 10685 qar([int tab[10];]) 10686 @result{}int tab[10]; 10687 @end example 10688 10689 @noindent 10690 Ahhh! That's much better. 10691 10692 But note what you've done: now that the result of @code{qar} is always 10693 a literal string, the only time a user can use nested macros is if she 10694 relies on an @emph{unquoted} macro call: 10695 10696 @example 10697 qar(active) 10698 @result{}ACT 10699 qar([active]) 10700 @result{}active 10701 @end example 10702 10703 @noindent 10704 leaving no way for her to reproduce what she used to do with @code{car}: 10705 10706 @example 10707 car([active]) 10708 @result{}ACT, IVE 10709 @end example 10710 10711 @noindent 10712 Worse yet: she wants to use a macro that produces a set of @code{cpp} 10713 macros: 10714 10715 @example 10716 define([my_includes], [#include <stdio.h>]) 10717 car([my_includes]) 10718 @result{}#include <stdio.h> 10719 qar(my_includes) 10720 @error{}EOF in argument list 10721 @end example 10722 10723 This macro, @code{qar}, because it double quotes its arguments, forces 10724 its users to leave their macro calls unquoted, which is dangerous. 10725 Commas and other active symbols are interpreted by M4 before 10726 they are given to the macro, often not in the way the users expect. 10727 Also, because @code{qar} behaves differently from the other macros, 10728 it'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 10734 The temptation is often high to bypass proper quotation, in particular 10735 when it's late at night. Then, many experienced Autoconf hackers 10736 finally surrender to the dark side of the force and use the ultimate 10737 weapon: @code{changequote}. 10738 10739 The M4 builtin @code{changequote} belongs to a set of primitives that 10740 allow one to adjust the syntax of the language to adjust it to one's 10741 needs. For instance, by default M4 uses @samp{`} and @samp{'} as 10742 quotes, but in the context of shell programming (and actually of most 10743 programming languages), that's about the worst choice one can make: 10744 because of strings and back-quoted expressions in shell code (such as 10745 @samp{'this'} and @samp{`that`}), and because of literal characters in usual 10746 programming languages (as in @samp{'0'}), there are many unbalanced 10747 @samp{`} and @samp{'}. Proper M4 quotation then becomes a nightmare, if 10748 not impossible. In order to make M4 useful in such a context, its 10749 designers have equipped it with @code{changequote}, which makes it 10750 possible to choose another pair of quotes. M4sugar, M4sh, Autoconf, and 10751 Autotest all have chosen to use @samp{[} and @samp{]}. Not especially 10752 because they are unlikely characters, but @emph{because they are 10753 characters unlikely to be unbalanced}. 10754 10755 There are other magic primitives, such as @code{changecom} to specify 10756 what 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 10759 details (such as the character to denote the @var{n}th argument, @samp{$} by 10760 default, the parentheses around arguments, etc.). 10761 10762 These primitives are really meant to make M4 more useful for specific 10763 domains: 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 10766 it makes M4 libraries self contained (no need for additional options). 10767 10768 There lies the problem@enddots{} 10769 10770 @sp 1 10771 10772 The problem is that it is then tempting to use them in the middle of an 10773 M4 script, as opposed to its initialization. This, if not carefully 10774 thought out, can lead to disastrous effects: @emph{you are changing the 10775 language in the middle of the execution}. Changing and restoring the 10776 syntax is often not enough: if you happened to invoke macros in between, 10777 these macros are lost, as the current syntax is probably not 10778 the 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 10798 When writing an Autoconf macro you may occasionally need to generate 10799 special characters that are difficult to express with the standard 10800 Autoconf quoting rules. For example, you may need to output the regular 10801 expression @samp{[^[]}, which matches any character other than @samp{[}. 10802 This expression contains unbalanced brackets so it cannot be put easily 10803 into an M4 macro. 10804 10805 Additionally, there are a few m4sugar macros (such as @code{m4_split} 10806 and @code{m4_expand}) which internally use special markers in addition 10807 to the regular quoting characters. If the arguments to these macros 10808 contain the literal strings @samp{-=<@{(} or @samp{)@}>=-}, the macros 10809 might behave incorrectly. 10810 10811 You 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@@ 10828 Expands to nothing. 10829 @end table 10830 10831 Quadrigraphs are replaced at a late stage of the translation process, 10832 after @command{m4} is run, so they do not get in the way of M4 quoting. 10833 For example, the string @samp{^@@<:@@}, independently of its quotation, 10834 appears as @samp{^[} in the output. 10835 10836 The empty quadrigraph can be used: 10837 10838 @itemize @minus 10839 @item to mark trailing spaces explicitly 10840 10841 Trailing spaces are smashed by @command{autom4te}. This is a feature. 10842 10843 @item to produce quadrigraphs and other strings reserved by m4sugar 10844 10845 For instance @samp{@@<@@&t@@:@@} produces @samp{@@<:@@}. For a more 10846 contrived example: 10847 10848 @example 10849 m4_define([a], [A])m4_define([b], [B])m4_define([c], [C])dnl 10850 m4_split([a )@}>=- b -=<@{( c]) 10851 @result{}[a], [], [B], [], [c] 10852 m4_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 10858 For instance you might want to mention @code{AC_FOO} in a comment, while 10859 still being sure that @command{autom4te} still catches unexpanded 10860 @samp{AC_*}. Then write @samp{AC@@&t@@_FOO}. 10861 @end itemize 10862 10863 The name @samp{@@&t@@} was suggested by Paul Eggert: 10864 10865 @quotation 10866 I should give some credit to the @samp{@@&t@@} pun. The @samp{&} is my 10867 own invention, but the @samp{t} came from the source code of the 10868 ALGOL68C compiler, written by Steve Bourne (of Bourne shell fame), 10869 and which used @samp{mt} to denote the empty string. In C, it would 10870 have looked like something like: 10871 10872 @example 10873 char const mt[] = ""; 10874 @end example 10875 10876 @noindent 10877 but of course the source code was written in Algol 68. 10878 10879 I don't know where he got @samp{mt} from: it could have been his own 10880 invention, and I suppose it could have been a common pun around the 10881 Cambridge 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 10891 One of the pitfalls of portable shell programming is that @command{case} 10892 statements require unbalanced parentheses (@pxref{case, , Limitations of 10893 Shell Builtins}). With syntax highlighting 10894 editors, the presence of unbalanced @samp{)} can interfere with editors 10895 that perform syntax highlighting of macro contents based on finding the 10896 matching @samp{(}. Another concern is how much editing must be done 10897 when transferring code snippets between shell scripts and macro 10898 definitions. But most importantly, the presence of unbalanced 10899 parentheses can introduce expansion bugs. 10900 10901 For an example, here is an underquoted attempt to use the macro 10902 @code{my_case}, which happens to expand to a portable @command{case} 10903 statement: 10904 10905 @example 10906 AC_DEFUN([my_case], 10907 [case $file_name in 10908 *.c) echo "C source code";; 10909 esac]) 10910 AS_IF(:, my_case) 10911 @end example 10912 10913 @noindent 10914 In the above example, the @code{AS_IF} call underquotes its arguments. 10915 As a result, the unbalanced @samp{)} generated by the premature 10916 expansion of @code{my_case} results in expanding @code{AS_IF} with a 10917 truncated parameter, and the expansion is syntactically invalid: 10918 10919 @example 10920 if :; then 10921 case $file_name in 10922 *.c 10923 fi echo "C source code";; 10924 esac) 10925 @end example 10926 10927 If nothing else, this should emphasize the importance of the quoting 10928 arguments to macro calls. On the other hand, there are several 10929 variations for defining @code{my_case} to be more robust, even when used 10930 without proper quoting, each with some benefits and some drawbacks. 10931 10932 @itemize @w{} 10933 @item Creative literal shell comment 10934 @example 10935 AC_DEFUN([my_case], 10936 [case $file_name in #( 10937 *.c) echo "C source code";; 10938 esac]) 10939 @end example 10940 @noindent 10941 This version provides balanced parentheses to several editors, and can 10942 be copied and pasted into a terminal as is. Unfortunately, it is still 10943 unbalanced as an Autoconf argument, since @samp{#(} is an M4 comment 10944 that masks the normal properties of @samp{(}. 10945 10946 @item Quadrigraph shell comment 10947 @example 10948 AC_DEFUN([my_case], 10949 [case $file_name in @@%:@@( 10950 *.c) echo "C source code";; 10951 esac]) 10952 @end example 10953 @noindent 10954 This version provides balanced parentheses to even more editors, and can 10955 be used as a balanced Autoconf argument. Unfortunately, it requires 10956 some editing before it can be copied and pasted into a terminal, and the 10957 use of the quadrigraph @samp{@@%:@@} for @samp{#} reduces readability. 10958 10959 @item Quoting just the parenthesis 10960 @example 10961 AC_DEFUN([my_case], 10962 [case $file_name in 10963 *.c[)] echo "C source code";; 10964 esac]) 10965 @end example 10966 @noindent 10967 This version quotes the @samp{)}, so that it can be used as a balanced 10968 Autoconf argument. As written, this is not balanced to an editor, but 10969 it can be coupled with @samp{[#(]} to meet that need, too. However, it 10970 still requires some edits before it can be copied and pasted into a 10971 terminal. 10972 10973 @item Double-quoting the entire statement 10974 @example 10975 AC_DEFUN([my_case], 10976 [[case $file_name in #( 10977 *.c) echo "C source code";; 10978 esac]]) 10979 @end example 10980 @noindent 10981 Since the entire macro is double-quoted, there is no problem with using 10982 this as an Autoconf argument; and since the double-quoting is over the 10983 entire statement, this code can be easily copied and pasted into a 10984 terminal. However, the double quoting prevents the expansion of any 10985 macros inside the case statement, which may cause its own set of 10986 problems. 10987 10988 @item Using @code{AS_CASE} 10989 @example 10990 AC_DEFUN([my_case], 10991 [AS_CASE([$file_name], 10992 [*.c], [echo "C source code"])]) 10993 @end example 10994 @noindent 10995 This version avoids the balancing issue altogether, by relying on 10996 @code{AS_CASE} (@pxref{Common Shell Constructs}); it also allows for the 10997 expansion of @code{AC_REQUIRE} to occur prior to the entire case 10998 statement, rather than within a branch of the case statement that might 10999 not be taken. However, the abstraction comes with a penalty that it is 11000 no 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 11007 To conclude, the quotation rule of thumb is: 11008 11009 @center @emph{One pair of quotes per pair of parentheses.} 11010 11011 Never over-quote, never under-quote, in particular in the definition of 11012 macros. 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 11016 It is common to read Autoconf programs with snippets like: 11017 11018 @example 11019 AC_TRY_LINK( 11020 changequote(<<, >>)dnl 11021 <<#include <time.h> 11022 #ifndef tzname /* For SGI. */ 11023 extern char *tzname[]; /* RS6000 and others reject char **tzname. */ 11024 #endif>>, 11025 changequote([, ])dnl 11026 [atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no) 11027 @end example 11028 11029 @noindent 11030 which is incredibly useless since @code{AC_TRY_LINK} is @emph{already} 11031 double quoting, so you just need: 11032 11033 @example 11034 AC_TRY_LINK( 11035 [#include <time.h> 11036 #ifndef tzname /* For SGI. */ 11037 extern 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 11045 The M4-fluent reader might note that these two examples are rigorously 11046 equivalent, since M4 swallows both the @samp{changequote(<<, >>)} 11047 and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these 11048 quotes are not part of the arguments! 11049 11050 Simplified, the example above is just doing this: 11051 11052 @example 11053 changequote(<<, >>)dnl 11054 <<[]>> 11055 changequote([, ])dnl 11056 @end example 11057 11058 @noindent 11059 instead of simply: 11060 11061 @example 11062 [[]] 11063 @end example 11064 11065 With macros that do not double quote their arguments (which is the 11066 rule), double-quote the (risky) literals: 11067 11068 @example 11069 AC_LINK_IFELSE([AC_LANG_PROGRAM( 11070 [[#include <time.h> 11071 #ifndef tzname /* For SGI. */ 11072 extern 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 11079 Please note that the macro @code{AC_TRY_LINK} is obsolete, so you really 11080 should be using @code{AC_LINK_IFELSE} instead. 11081 11082 @xref{Quadrigraphs}, for what to do if you run into a hopeless case 11083 where quoting does not suffice. 11084 11085 When you create a @command{configure} script using newly written macros, 11086 examine it carefully to check whether you need to add more quotes in 11087 your macros. If one or more words have disappeared in the M4 11088 output, you need more quotes. When in doubt, quote. 11089 11090 However, it's also possible to put on too many layers of quotes. If 11091 this happens, the resulting @command{configure} script may contain 11092 unexpanded macros. The @command{autoconf} program checks for this problem 11093 by looking for the string @samp{AC_} in @file{configure}. However, this 11094 heuristic does not work in general: for example, it does not catch 11095 overquoting in @code{AC_DEFINE} descriptions. 11096 11097 11098 @c ---------------------------------------- Using autom4te 11099 11100 @node Using autom4te 11101 @section Using @command{autom4te} 11102 11103 The Autoconf suite, including M4sugar, M4sh, and Autotest, in addition 11104 to Autoconf per se, heavily rely on M4. All these different uses 11105 revealed common needs factored into a layer over M4: 11106 @command{autom4te}@footnote{ 11107 @c 11108 Yet another great name from Lars J. Aas. 11109 @c 11110 }. 11111 11112 @command{autom4te} is a preprocessor that is like @command{m4}. 11113 It 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 11123 The command line arguments are modeled after M4's: 11124 11125 @example 11126 autom4te @var{options} @var{files} 11127 @end example 11128 11129 @noindent 11130 @evindex M4 11131 where the @var{files} are directly passed to @command{m4}. By default, 11132 GNU M4 is found during configuration, but the environment 11133 variable 11134 @env{M4} can be set to tell @command{autom4te} where to look. In addition 11135 to the regular expansion, it handles the replacement of the quadrigraphs 11136 (@pxref{Quadrigraphs}), and of @samp{__oline__}, the current line in the 11137 output. It supports an extended syntax for the @var{files}: 11138 11139 @table @file 11140 @item @var{file}.m4f 11141 This file is an M4 frozen file. Note that @emph{all the previous files 11142 are ignored}. See the option @option{--melt} for the rationale. 11143 11144 @item @var{file}? 11145 If found in the library path, the @var{file} is included for expansion, 11146 otherwise it is ignored instead of triggering a failure. 11147 @end table 11148 11149 @sp 1 11150 11151 Of course, it supports the Autoconf common subset of options: 11152 11153 @table @option 11154 @item --help 11155 @itemx -h 11156 Print a summary of the command line options and exit. 11157 11158 @item --version 11159 @itemx -V 11160 Print the version number of Autoconf and exit. 11161 11162 @item --verbose 11163 @itemx -v 11164 Report processing steps. 11165 11166 @item --debug 11167 @itemx -d 11168 Don't remove the temporary files and be even more verbose. 11169 11170 @item --include=@var{dir} 11171 @itemx -I @var{dir} 11172 Also look for input files in @var{dir}. Multiple invocations 11173 accumulate. 11174 11175 @item --output=@var{file} 11176 @itemx -o @var{file} 11177 Save output (script or trace) to @var{file}. The file @option{-} stands 11178 for the standard output. 11179 @end table 11180 11181 @sp 1 11182 11183 As 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. 11190 Report the warnings related to @var{category} (which can actually be a 11191 comma separated list). @xref{Reporting Messages}, macro 11192 @code{AC_DIAGNOSE}, for a comprehensive list of categories. Special 11193 values include: 11194 11195 @table @samp 11196 @item all 11197 report all the warnings 11198 11199 @item none 11200 report none 11201 11202 @item error 11203 treats warnings as errors 11204 11205 @item no-@var{category} 11206 disable warnings falling into @var{category} 11207 @end table 11208 11209 Warnings about @samp{syntax} are enabled by default, and the environment 11210 variable @env{WARNINGS}, a comma separated list of categories, is 11211 honored. @samp{autom4te -W @var{category}} actually 11212 behaves as if you had run: 11213 11214 @example 11215 autom4te --warnings=syntax,$WARNINGS,@var{category} 11216 @end example 11217 11218 @noindent 11219 For example, if you want to disable defaults and @env{WARNINGS} 11220 of @command{autom4te}, but enable the warnings about obsolete 11221 constructs, 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 11226 warnings; if you want them, just pass @option{-W error}. 11227 11228 @item --melt 11229 @itemx -M 11230 Do not use frozen files. Any argument @code{@var{file}.m4f} is 11231 replaced by @code{@var{file}.m4}. This helps tracing the macros which 11232 are executed only when the files are frozen, typically 11233 @code{m4_define}. For instance, running: 11234 11235 @example 11236 autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4 11237 @end example 11238 11239 @noindent 11240 is roughly equivalent to running: 11241 11242 @example 11243 m4 1.m4 2.m4 3.m4 4.m4 input.m4 11244 @end example 11245 11246 @noindent 11247 while 11248 11249 @example 11250 autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4 11251 @end example 11252 11253 @noindent 11254 is equivalent to: 11255 11256 @example 11257 m4 --reload-state=4.m4f input.m4 11258 @end example 11259 11260 @item --freeze 11261 @itemx -F 11262 Produce a frozen state file. @command{autom4te} freezing is stricter 11263 than M4's: it must produce no warnings, and no output other than empty 11264 lines (a line with white space is @emph{not} empty) and comments 11265 (starting with @samp{#}). Unlike @command{m4}'s similarly-named option, 11266 this option takes no argument: 11267 11268 @example 11269 autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f 11270 @end example 11271 11272 @noindent 11273 corresponds to 11274 11275 @example 11276 m4 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} 11281 Set 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} 11288 As another additional feature over @command{m4}, @command{autom4te} 11289 caches its results. GNU M4 is able to produce a regular 11290 output and traces at the same time. Traces are heavily used in the 11291 GNU Build System: @command{autoheader} uses them to build 11292 @file{config.h.in}, @command{autoreconf} to determine what 11293 GNU Build System components are used, @command{automake} to 11294 ``parse'' @file{configure.ac} etc. To avoid recomputation, 11295 traces are cached while performing regular expansion, 11296 and conversely. This cache is (actually, the caches are) stored in 11297 the directory @file{autom4te.cache}. @emph{It can safely be removed} 11298 at any moment (especially if for some reason @command{autom4te} 11299 considers it trashed). 11300 11301 @table @option 11302 @item --cache=@var{directory} 11303 @itemx -C @var{directory} 11304 Specify the name of the directory where the result should be cached. 11305 Passing an empty value disables caching. Be sure to pass a relative 11306 file name, as for the time being, global caches are not supported. 11307 11308 @item --no-cache 11309 Don't cache the results. 11310 11311 @item --force 11312 @itemx -f 11313 If a cache is used, consider it obsolete (but update it anyway). 11314 @end table 11315 11316 @sp 1 11317 11318 Because traces are so important to the GNU Build System, 11319 @command{autom4te} provides high level tracing features as compared to 11320 M4, and helps exploiting the cache: 11321 11322 @table @option 11323 @item --trace=@var{macro}[:@var{format}] 11324 @itemx -t @var{macro}[:@var{format}] 11325 Trace the invocations of @var{macro} according to the @var{format}. 11326 Multiple @option{--trace} arguments can be used to list several macros. 11327 Multiple @option{--trace} arguments for a single macro are not 11328 cumulative; instead, you should just make @var{format} as long as 11329 needed. 11330 11331 The @var{format} is a regular string, with newlines if desired, and 11332 several special escape codes. It defaults to @samp{$f:$l:$n:$%}. It can 11333 use the following special escapes: 11334 11335 @table @samp 11336 @item $$ 11337 @c $$ restore font-lock 11338 The character @samp{$}. 11339 11340 @item $f 11341 The file name from which @var{macro} is called. 11342 11343 @item $l 11344 The line number from which @var{macro} is called. 11345 11346 @item $d 11347 The depth of the @var{macro} call. This is an M4 technical detail that 11348 you probably don't want to know about. 11349 11350 @item $n 11351 The name of the @var{macro}. 11352 11353 @item $@var{num} 11354 The @var{num}th argument of the call to @var{macro}. 11355 11356 @item $@@ 11357 @itemx $@var{sep}@@ 11358 @itemx $@{@var{separator}@}@@ 11359 All the arguments passed to @var{macro}, separated by the character 11360 @var{sep} or the string @var{separator} (@samp{,} by default). Each 11361 argument is quoted, i.e., enclosed in a pair of square brackets. 11362 11363 @item $* 11364 @itemx $@var{sep}* 11365 @itemx $@{@var{separator}@}* 11366 As above, but the arguments are not quoted. 11367 11368 @item $% 11369 @itemx $@var{sep}% 11370 @itemx $@{@var{separator}@}% 11371 As above, but the arguments are not quoted, all new line characters in 11372 the arguments are smashed, and the default separator is @samp{:}. 11373 11374 The escape @samp{$%} produces single-line trace outputs (unless you put 11375 newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do 11376 not. 11377 @end table 11378 11379 @xref{autoconf Invocation}, for examples of trace uses. 11380 11381 @item --preselect=@var{macro} 11382 @itemx -p @var{macro} 11383 Cache the traces of @var{macro}, but do not enable traces. This is 11384 especially important to save CPU cycles in the future. For instance, 11385 when invoked, @command{autoconf} preselects all the macros that 11386 @command{autoheader}, @command{automake}, @command{autoreconf}, etc., 11387 trace, so that running @command{m4} is not needed to trace them: the 11388 cache suffices. This results in a huge speed-up. 11389 @end table 11390 11391 @sp 1 11392 11393 @cindex Autom4te Library 11394 Finally, @command{autom4te} introduces the concept of @dfn{Autom4te 11395 libraries}. They consists in a powerful yet extremely simple feature: 11396 sets of combined command line arguments: 11397 11398 @table @option 11399 @item --language=@var{language} 11400 @itemx -l @var{language} 11401 Use the @var{language} Autom4te library. Current languages include: 11402 11403 @table @code 11404 @item M4sugar 11405 create M4sugar output. 11406 11407 @item M4sh 11408 create M4sh executable shell scripts. 11409 11410 @item Autotest 11411 create Autotest executable test suites. 11412 11413 @item Autoconf-without-aclocal-m4 11414 create Autoconf executable configure scripts without 11415 reading @file{aclocal.m4}. 11416 11417 @item Autoconf 11418 create Autoconf executable configure scripts. This language inherits 11419 all the characteristics of @code{Autoconf-without-aclocal-m4} and 11420 additionally reads @file{aclocal.m4}. 11421 @end table 11422 11423 @item --prepend-include=@var{dir} 11424 @itemx -B @var{dir} 11425 Prepend directory @var{dir} to the search path. This is used to include 11426 the language-specific files before any third-party macros. 11427 11428 @end table 11429 11430 @cindex @file{autom4te.cfg} 11431 As an example, if Autoconf is installed in its default location, 11432 @file{/usr/local}, the command @samp{autom4te -l m4sugar foo.m4} is 11433 strictly equivalent to the command: 11434 11435 @example 11436 autom4te --prepend-include /usr/local/share/autoconf \ 11437 m4sugar/m4sugar.m4f --warnings syntax foo.m4 11438 @end example 11439 11440 @noindent 11441 Recursive expansion applies here: the command @samp{autom4te -l m4sh foo.m4} 11442 is the same as @samp{autom4te --language M4sugar m4sugar/m4sh.m4f 11443 foo.m4}, i.e.: 11444 11445 @example 11446 autom4te --prepend-include /usr/local/share/autoconf \ 11447 m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4 11448 @end example 11449 11450 @noindent 11451 The definition of the languages is stored in @file{autom4te.cfg}. 11452 11453 @node Customizing autom4te 11454 @subsection Customizing @command{autom4te} 11455 11456 One can customize @command{autom4te} via @file{~/.autom4te.cfg} (i.e., 11457 as found in the user home directory), and @file{./.autom4te.cfg} (i.e., 11458 as found in the directory from which @command{autom4te} is run). The 11459 order is first reading @file{autom4te.cfg}, then @file{~/.autom4te.cfg}, 11460 then @file{./.autom4te.cfg}, and finally the command line arguments. 11461 11462 In these text files, comments are introduced with @code{#}, and empty 11463 lines are ignored. Customization is performed on a per-language basis, 11464 wrapped in between a @samp{begin-language: "@var{language}"}, 11465 @samp{end-language: "@var{language}"} pair. 11466 11467 Customizing a language stands for appending options (@pxref{autom4te 11468 Invocation}) to the current definition of the language. Options, and 11469 more generally arguments, are introduced by @samp{args: 11470 @var{arguments}}. You may use the traditional shell syntax to quote the 11471 @var{arguments}. 11472 11473 As an example, to disable Autoconf caches (@file{autom4te.cache}) 11474 globally, include the following lines in @file{~/.autom4te.cfg}: 11475 11476 @verbatim 11477 ## ------------------ ## 11478 ## User Preferences. ## 11479 ## ------------------ ## 11480 11481 begin-language: "Autoconf-without-aclocal-m4" 11482 args: --no-cache 11483 end-language: "Autoconf-without-aclocal-m4" 11484 @end verbatim 11485 11486 11487 @node Programming in M4sugar 11488 @section Programming in M4sugar 11489 11490 @cindex M4sugar 11491 M4 by itself provides only a small, but sufficient, set of all-purpose 11492 macros. M4sugar introduces additional generic macros. Its name was 11493 coined by Lars J. Aas: ``Readability And Greater Understanding Stands 4 11494 M4sugar''. 11495 11496 M4sugar reserves the macro namespace @samp{^_m4_} for internal use, and 11497 the macro namespace @samp{^m4_} for M4sugar macros. You should not 11498 define 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} 11541 With 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 11545 The 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 11574 Some M4 macros are redefined, and are slightly incompatible with their 11575 native equivalent. 11576 11577 @defmac __file__ 11578 @defmacx __line__ 11579 @MSindex __file__ 11580 @MSindex __line__ 11581 All M4 macros starting with @samp{__} retain their original name: for 11582 example, no @code{m4__file__} is defined. 11583 @end defmac 11584 11585 @defmac __oline__ 11586 @MSindex __oline__ 11587 This is not technically a macro, but a feature of Autom4te. The 11588 sequence @code{__oline__} can be used similarly to the other m4sugar 11589 location macros, but rather than expanding to the location of the input 11590 file, it is translated to the line number where it appears in the output 11591 file after all other M4 expansions. 11592 @end defmac 11593 11594 @defmac dnl 11595 @MSindex dnl 11596 This 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} 11601 This macro corresponds to @code{patsubst}. The name @code{m4_patsubst} 11602 is kept for future versions of M4sugar, once GNU M4 2.0 is 11603 released and supports extended regular expression syntax. 11604 @end defmac 11605 11606 @defmac m4_bregexp (@var{string}, @var{regexp}, @ovar{replacement}) 11607 @msindex{bregexp} 11608 This macro corresponds to @code{regexp}. The name @code{m4_regexp} 11609 is kept for future versions of M4sugar, once GNU M4 2.0 is 11610 released 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} 11621 These 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 11625 definition. All four macros then proceed to copy the entire pushdef 11626 stack of definitions of @var{source} over to @var{dest}. @code{m4_copy} 11627 and @code{m4_copy_force} preserve the source (including in the special 11628 case where @var{source} is undefined), while @code{m4_rename} and 11629 @code{m4_rename_force} undefine the original macro name (making it an 11630 error to rename an undefined @var{source}). 11631 11632 Note that attempting to invoke a renamed macro might not work, since the 11633 macro may have a dependence on helper macros accessed via composition of 11634 @samp{$0} but that were not also renamed; likewise, other macros may 11635 have 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 11637 rename a macro to temporarily move it out of the way, then rename it 11638 back later to restore original semantics. 11639 @end defmac 11640 11641 @defmac m4_defn (@var{macro}@dots{}) 11642 @msindex{defn} 11643 This macro fails if @var{macro} is not defined, even when using older 11644 versions of M4 that did not warn. See @code{m4_undefine}. 11645 Unfortunately, in order to support these older versions of M4, there are 11646 some situations involving unbalanced quotes where concatenating multiple 11647 macros together will work in newer M4 but not in m4sugar; use 11648 quadrigraphs to work around this. 11649 @end defmac 11650 11651 @defmac m4_divert (@var{diversion}) 11652 @msindex{divert} 11653 M4sugar relies heavily on diversions, so rather than behaving as a 11654 primitive, @code{m4_divert} behaves like: 11655 @example 11656 m4_divert_pop()m4_divert_push([@var{diversion}]) 11657 @end example 11658 @noindent 11659 @xref{Diversion support}, for more details about the use of the 11660 diversion stack. In particular, this implies that @var{diversion} 11661 should be a named diversion rather than a raw number. But be aware that 11662 it is seldom necessary to explicitly change the diversion stack, and 11663 that when done incorrectly, it can lead to syntactically invalid 11664 scripts. 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 11672 requires at least one argument, output always goes to standard error 11673 rather than the current debug file, no sorting is done on multiple 11674 arguments, and an error is issued if any 11675 @var{name} is undefined. @code{m4_dumpdefs} is a convenience macro that 11676 calls @code{m4_dumpdef} for all of the 11677 @code{m4_pushdef} stack of definitions, starting with the current, and 11678 silently does nothing if @var{name} is undefined. 11679 11680 Unfortunately, due to a limitation in M4 1.4.x, any macro defined as a 11681 builtin is output as the empty string. This behavior is rectified by 11682 using M4 1.6 or newer. However, this behavior difference means that 11683 @code{m4_dumpdef} should only be used while developing m4sugar macros, 11684 and never in the final published form of a macro. 11685 @end defmac 11686 11687 @defmac m4_esyscmd_s (@var{command}) 11688 @msindex{esyscmd_s} 11689 Like @code{m4_esyscmd}, this macro expands to the result of running 11690 @var{command} in a shell. The difference is that any trailing newlines 11691 are removed, so that the output behaves more like shell command 11692 substitution. 11693 @end defmac 11694 11695 @defmac m4_exit (@var{exit-status}) 11696 @msindex{exit} 11697 This 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} 11705 This macro corresponds to @code{ifelse}. @var{string-1} and 11706 @var{string-2} are compared literally, so usually one of the two 11707 arguments is passed unquoted. @xref{Conditional constructs}, for more 11708 conditional idioms. 11709 @end defmac 11710 11711 @defmac m4_include (@var{file}) 11712 @defmacx m4_sinclude (@var{file}) 11713 @msindex{include} 11714 @msindex{sinclude} 11715 Like 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} 11722 Posix requires @code{maketemp} to replace the trailing @samp{X} 11723 characters in @var{template} with the process id, without regards to the 11724 existence of a file by that name, but this a security hole. When this 11725 was 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 11727 versions of GNU M4 support the new macro. In M4sugar, 11728 @code{m4_maketemp} and @code{m4_mkstemp} are synonyms for each other, 11729 and both have the secure semantics regardless of which macro the 11730 underlying M4 provides. 11731 @end defmac 11732 11733 @defmac m4_popdef (@var{macro}@dots{}) 11734 @msindex{popdef} 11735 This macro fails if @var{macro} is not defined, even when using older 11736 versions of M4 that did not warn. See @code{m4_undefine}. 11737 @end defmac 11738 11739 @defmac m4_undefine (@var{macro}@dots{}) 11740 @msindex{undefine} 11741 This macro fails if @var{macro} is not defined, even when using older 11742 versions of M4 that did not warn. Use 11743 11744 @example 11745 m4_ifdef([@var{macro}], [m4_undefine([@var{macro}])]) 11746 @end example 11747 11748 @noindent 11749 if you are not sure whether @var{macro} is defined. 11750 @end defmac 11751 11752 @defmac m4_undivert (@var{diversion}@dots{}) 11753 @msindex{undivert} 11754 Unlike the M4 builtin, at least one @var{diversion} must be specified. 11755 Also, since the M4sugar diversion stack prefers named 11756 diversions, the use of @code{m4_undivert} to include files is risky. 11757 @xref{Diversion support}, for more details about the use of the 11758 diversion stack. But be aware that it is seldom necessary to explicitly 11759 change the diversion stack, and that when done incorrectly, it can lead 11760 to 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} 11767 These macros correspond to @code{m4wrap}. Posix requires arguments of 11768 multiple wrap calls to be reprocessed at EOF in the same order 11769 as the original calls (first-in, first-out). GNU M4 versions 11770 through 1.4.10, however, reprocess them in reverse order (last-in, 11771 first-out). Both orders are useful, therefore, you can rely on 11772 @code{m4_wrap} to provide FIFO semantics and @code{m4_wrap_lifo} for 11773 LIFO semantics, regardless of the underlying GNU M4 version. 11774 11775 Unlike the GNU M4 builtin, these macros only recognize one 11776 argument, and avoid token pasting between consecutive invocations. On 11777 the other hand, nested calls to @code{m4_wrap} from within wrapped text 11778 work 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 11786 When macros statically diagnose abnormal situations, benign or fatal, 11787 they should report them using these macros. For issuing dynamic issues, 11788 i.e., when @command{configure} is run, see @ref{Printing Messages}. 11789 11790 @defmac m4_assert (@var{expression}, @dvar{exit-status, 1}) 11791 @msindex{assert} 11792 Assert that the arithmetic @var{expression} evaluates to non-zero. 11793 Otherwise, 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} 11799 Similar to the builtin @code{m4_errprint}, except that a newline is 11800 guaranteed after @var{message}. 11801 @end defmac 11802 11803 @anchor{m4_fatal} 11804 @defmac m4_fatal (@var{message}) 11805 @msindex{fatal} 11806 Report a severe error @var{message} prefixed with the current location, 11807 and have @command{autom4te} die. 11808 @end defmac 11809 11810 @defmac m4_location 11811 @msindex{location} 11812 Useful 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} 11821 Report @var{message} as a warning (or as an error if requested by the 11822 user) if warnings of the @var{category} are turned on. If the message 11823 is emitted, it is prefixed with the current location, and followed by a 11824 call trace of all macros defined via @code{AC_DEFUN} used to get to the 11825 current expansion. You are encouraged to use standard categories, which 11826 currently include: 11827 11828 @table @samp 11829 @item all 11830 messages that don't fall into one of the following categories. Use of an 11831 empty @var{category} is equivalent. 11832 11833 @item cross 11834 related to cross compilation issues. 11835 11836 @item obsolete 11837 use of an obsolete construct. 11838 11839 @item syntax 11840 dubious syntactic constructs, incorrectly ordered macro calls. 11841 @end table 11842 @end defmac 11843 11844 11845 @node Diversion support 11846 @subsection Diversion support 11847 11848 M4sugar makes heavy use of diversions under the hood, because it is 11849 often the case that 11850 text that must appear early in the output is not discovered until late 11851 in the input. Additionally, some of the topological sorting algorithms 11852 used in resolving macro dependencies use diversions. However, most 11853 macros should not need to change diversions directly, but rather rely on 11854 higher-level M4sugar macros to manage diversions transparently. If you 11855 change diversions improperly, you risk generating a syntactically 11856 invalid script, because an incorrect diversion will violate assumptions 11857 made by many macros about whether prerequisite text has been previously 11858 output. In short, if you manually change the diversion, you should not 11859 expect any macros provided by the Autoconf package to work until you 11860 have restored the diversion stack back to its original state. 11861 11862 In the rare case that it is necessary to write a macro that explicitly 11863 outputs text to a different diversion, it is important to be aware of an 11864 M4 limitation regarding diversions: text only goes to a diversion if it 11865 is not part of argument collection. Therefore, any macro that changes 11866 the current diversion cannot be used as an unquoted argument to another 11867 macro, but must be expanded at the top level. The macro 11868 @code{m4_expand} will diagnose any attempt to change diversions, since 11869 it is generally useful only as an argument to another macro. The 11870 following example shows what happens when diversion manipulation is 11871 attempted within macro arguments: 11872 11873 @example 11874 m4_do([normal text] 11875 m4_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 11882 Notice that the unquoted text @code{unwanted} is output, even though it 11883 was processed while the current diversion was @code{KILL}, because it 11884 was collected as part of the argument to @code{m4_do}. However, the 11885 text @code{discarded} disappeared as desired, because the diversion 11886 changes were single-quoted, and were not expanded until the top-level 11887 rescan of the output of @code{m4_do}. 11888 11889 To make diversion management easier, M4sugar uses the concept of named 11890 diversions. Rather than using diversion numbers directly, it is nicer 11891 to associate a name with each diversion. The diversion number associated 11892 with a particular diversion name is an implementation detail, and a 11893 syntax warning is issued if a diversion number is used instead of a 11894 name. In general, you should not output text 11895 to a named diversion until after calling the appropriate initialization 11896 routine for your language (@code{m4_init}, @code{AS_INIT}, 11897 @code{AT_INIT}, @dots{}), although there are some exceptions documented 11898 below. 11899 11900 M4sugar defines two named diversions. 11901 @table @code 11902 @item KILL 11903 Text written to this diversion is discarded. This is the default 11904 diversion once M4sugar is initialized. 11905 @item GROW 11906 This diversion is used behind the scenes by topological sorting macros, 11907 such as @code{AC_REQUIRE}. 11908 @end table 11909 11910 M4sh adds several more named diversions. 11911 @table @code 11912 @item BINSH 11913 This diversion is reserved for the @samp{#!} interpreter line. 11914 @item HEADER-REVISION 11915 This diversion holds text from @code{AC_REVISION}. 11916 @item HEADER-COMMENT 11917 This diversion holds comments about the purpose of a file. 11918 @item HEADER-COPYRIGHT 11919 This diversion is managed by @code{AC_COPYRIGHT}. 11920 @item M4SH-SANITIZE 11921 This diversion contains M4sh sanitization code, used to ensure M4sh is 11922 executing in a reasonable shell environment. 11923 @item M4SH-INIT 11924 This diversion contains M4sh initialization code, initializing variables 11925 that are required by other M4sh macros. 11926 @item BODY 11927 This diversion contains the body of the shell code, and is the default 11928 diversion once M4sh is initialized. 11929 @end table 11930 11931 Autotest inherits diversions from M4sh, and changes the default 11932 diversion from @code{BODY} back to @code{KILL}. It also adds several 11933 more named diversions, with the following subset designed for developer 11934 use. 11935 @table @code 11936 @item PREPARE_TESTS 11937 This diversion contains initialization sequences which are executed 11938 after @file{atconfig} and @file{atlocal}, and after all command line 11939 arguments have been parsed, but prior to running any tests. It can be 11940 used to set up state that is required across all tests. This diversion 11941 will work even before @code{AT_INIT}. 11942 @end table 11943 11944 Autoconf inherits diversions from M4sh, and adds the following named 11945 diversions which developers can utilize. 11946 @table @code 11947 @item DEFAULTS 11948 This diversion contains shell variable assignments to set defaults that 11949 must be in place before arguments are parsed. This diversion is placed 11950 early enough in @file{configure} that it is unsafe to expand any 11951 autoconf macros into this diversion. 11952 @item HELP_ENABLE 11953 If @code{AC_PRESERVE_HELP_ORDER} was used, then text placed in this 11954 diversion will be included as part of a quoted here-doc providing all of 11955 the @option{--help} output of @file{configure} related to options 11956 created by @code{AC_ARG_WITH} and @code{AC_ARG_ENABLE}. 11957 @item INIT_PREPARE 11958 This diversion occurs after all command line options have been parsed, 11959 but prior to the main body of the @file{configure} script. This 11960 diversion is the last chance to insert shell code such as variable 11961 assignments or shell function declarations that will used by the 11962 expansion of other macros. 11963 @end table 11964 11965 For now, the remaining named diversions of Autoconf, Autoheader, and 11966 Autotest are not documented. In other words, 11967 intentionally outputting text into an undocumented diversion is subject 11968 to breakage in a future release of Autoconf. 11969 11970 @defmac m4_cleardivert (@var{diversion}@dots{}) 11971 @msindex{cleardivert} 11972 Permanently 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} 11978 Similar to @code{m4_divert_text}, except that @var{content} is only 11979 output 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} 11985 If provided, check that the current diversion is indeed @var{diversion}. 11986 Then change to the diversion located earlier on the stack, giving an 11987 error if an attempt is made to pop beyond the initial m4sugar diversion 11988 of @code{KILL}. 11989 @end defmac 11990 11991 @defmac m4_divert_push (@var{diversion}) 11992 @msindex{divert_push} 11993 Remember the former diversion on the diversion stack, and output 11994 subsequent text into @var{diversion}. M4sugar maintains a diversion 11995 stack, and issues an error if there is not a matching pop for every 11996 push. 11997 @end defmac 11998 11999 @defmac m4_divert_text (@var{diversion}, @ovar{content}) 12000 @msindex{divert_text} 12001 Output @var{content} and a newline into @var{diversion}, without 12002 affecting the current diversion. Shorthand for: 12003 @example 12004 m4_divert_push([@var{diversion}])@var{content} 12005 m4_divert_pop([@var{diversion}])dnl 12006 @end example 12007 12008 One use of @code{m4_divert_text} is to develop two related macros, where 12009 macro @samp{MY_A} does the work, but adjusts what work is performed 12010 based on whether the optional macro @samp{MY_B} has also been expanded. 12011 Of course, it is possible to use @code{AC_BEFORE} within @code{MY_A} to 12012 require that @samp{MY_B} occurs first, if it occurs at all. But this 12013 imposes 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 12015 is 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 12017 expanded. 12018 12019 @example 12020 AC_DEFUN([MY_A], 12021 [# various actions 12022 if test -n "$b_was_used"; then 12023 # extra action 12024 fi]) 12025 AC_DEFUN([MY_B], 12026 [AC_REQUIRE([MY_A])dnl 12027 m4_divert_text([INIT_PREPARE], [b_was_used=true])]) 12028 @end example 12029 12030 @end defmac 12031 12032 @defmac m4_init 12033 @msindex{init} 12034 Initialize the M4sugar environment, setting up the default named 12035 diversion to be @code{KILL}. 12036 @end defmac 12037 12038 @node Conditional constructs 12039 @subsection Conditional constructs 12040 12041 The following macros provide additional conditional constructs as 12042 convenience 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} 12047 The string @var{string} is repeatedly compared against a series of 12048 @var{regex} arguments; if a match is found, the expansion is the 12049 corresponding @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} 12057 The string @var{string} is altered by @var{regex-1} and @var{subst-1}, 12058 as if by: 12059 @example 12060 m4_bpatsubst([[@var{string}]], [@var{regex}], [@var{subst}]) 12061 @end example 12062 12063 @noindent 12064 The 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 12066 deletion of any matched portions in the current string. Note that this 12067 macro over-quotes @var{string}; this behavior is intentional, so that 12068 the result of each step of the recursion remains as a quoted string. 12069 However, it means that anchors (@samp{^} and @samp{$} in the @var{regex} 12070 will line up with the extra quotations, and not the characters of the 12071 original string. The overquoting is removed after the final 12072 substitution. 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} 12078 Test @var{string} against multiple @var{value} possibilities, resulting 12079 in the first @var{if-value} for a match, or in the optional 12080 @var{default}. This is shorthand for: 12081 @example 12082 m4_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} 12091 This macro was introduced in Autoconf 2.62. Similar to @code{m4_if}, 12092 except that each @var{test} is expanded only when it is encountered. 12093 This is useful for short-circuiting expensive tests; while @code{m4_if} 12094 requires all its strings to be expanded up front before doing 12095 comparisons, @code{m4_cond} only expands a @var{test} when all earlier 12096 tests have failed. 12097 12098 For an example, these two sequences give the same result, but in the 12099 case where @samp{$1} does not contain a backslash, the @code{m4_cond} 12100 version only expands @code{m4_index} once, instead of five times, for 12101 faster computation if this is a common case for @samp{$1}. Notice that 12102 every third argument is unquoted for @code{m4_if}, and quoted for 12103 @code{m4_cond}: 12104 12105 @example 12106 m4_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]) 12112 m4_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} 12129 If @var{expr-1} contains text, use it. Otherwise, select @var{expr-2}. 12130 @code{m4_default} expands the result, while @code{m4_default_quoted} 12131 does not. Useful for providing a fixed default if the expression that 12132 results in @var{expr-1} would otherwise be empty. The difference 12133 between @code{m4_default} and @code{m4_default_nblank} is whether an 12134 argument consisting of just blanks (space, tab, newline) is 12135 significant. When using the expanding versions, note that an argument 12136 may contain text but still expand to an empty string. 12137 12138 @example 12139 m4_define([active], [ACTIVE])dnl 12140 m4_define([empty], [])dnl 12141 m4_define([demo1], [m4_default([$1], [$2])])dnl 12142 m4_define([demo2], [m4_default_quoted([$1], [$2])])dnl 12143 m4_define([demo3], [m4_default_nblank([$1], [$2])])dnl 12144 m4_define([demo4], [m4_default_nblank_quoted([$1], [$2])])dnl 12145 demo1([active], [default]) 12146 @result{}ACTIVE 12147 demo1([], [active]) 12148 @result{}ACTIVE 12149 demo1([empty], [text]) 12150 @result{} 12151 -demo1([ ], [active])- 12152 @result{}- - 12153 demo2([active], [default]) 12154 @result{}active 12155 demo2([], [active]) 12156 @result{}active 12157 demo2([empty], [text]) 12158 @result{}empty 12159 -demo2([ ], [active])- 12160 @result{}- - 12161 demo3([active], [default]) 12162 @result{}ACTIVE 12163 demo3([], [active]) 12164 @result{}ACTIVE 12165 demo3([empty], [text]) 12166 @result{} 12167 -demo3([ ], [active])- 12168 @result{}-ACTIVE- 12169 demo4([active], [default]) 12170 @result{}active 12171 demo4([], [active]) 12172 @result{}active 12173 demo4([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} 12182 If @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} 12190 If @var{cond} is empty or consists only of blanks (space, tab, newline), 12191 then expand @var{if-blank}; otherwise, expand @var{if-text}. Two 12192 variants exist, in order to make it easier to select the correct logical 12193 sense when using only two parameters. Note that this is more efficient 12194 than the equivalent behavior of: 12195 @example 12196 m4_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} 12202 This is shorthand for: 12203 @example 12204 m4_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} 12210 If @var{macro} is undefined, or is defined as the empty string, expand 12211 to @var{if-false}. Otherwise, expands to @var{if-true}. Similar to: 12212 @example 12213 m4_ifval(m4_defn([@var{macro}]), [@var{if-true}], [@var{if-false}]) 12214 @end example 12215 @noindent 12216 except 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} 12221 Expands to @var{if-true} if @var{cond} is not empty, otherwise to 12222 @var{if-false}. This is shorthand for: 12223 @example 12224 m4_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} 12230 Similar to @code{m4_ifval}, except guarantee that a newline is present 12231 after any non-empty expansion. Often followed by @code{dnl}. 12232 @end defmac 12233 12234 @defmac m4_n (@var{text}) 12235 @msindex{n} 12236 Expand to @var{text}, and add a newline if @var{text} is not empty. 12237 Often followed by @code{dnl}. 12238 @end defmac 12239 12240 12241 @node Looping constructs 12242 @subsection Looping constructs 12243 12244 The following macros are useful in implementing recursive algorithms in 12245 M4, including loop operations. An M4 list is formed by quoting a list 12246 of 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]}. 12249 It is common to see lists with unquoted elements when those elements are 12250 not likely to be macro names, as in @samp{[fputc_unlocked, 12251 fgetc_unlocked]}. 12252 12253 Although not generally recommended, it is possible for quoted lists to 12254 have side effects; all side effects are expanded only once, and prior to 12255 visiting any list element. On the other hand, the fact that unquoted 12256 macros are expanded exactly once means that macros without side effects 12257 can be used to generate lists. For example, 12258 12259 @example 12260 m4_foreach([i], [[1], [2], [3]m4_errprintn([hi])], [i]) 12261 @error{}hi 12262 @result{}123 12263 m4_define([list], [[1], [2], [3]]) 12264 @result{} 12265 m4_foreach([i], [list], [i]) 12266 @result{}123 12267 @end example 12268 12269 @defmac m4_argn (@var{n}, @ovar{arg}@dots{}) 12270 @msindex{argn} 12271 Extracts argument @var{n} (larger than 0) from the remaining arguments. 12272 If 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} 12279 Expands to the quoted first @var{arg}. Can be used with @code{m4_cdr} 12280 to recursively iterate 12281 through 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} 12287 Expands to a quoted list of all but the first @var{arg}, or the empty 12288 string if there was only one argument. Generally, when using quoted 12289 lists of quoted elements, @code{m4_cdr} should be called without any 12290 extra quotes. 12291 12292 For example, this is a simple implementation of @code{m4_map}; note how 12293 each iteration checks for the end of recursion, then merely applies the 12294 first argument to the first element of the list, then repeats with the 12295 rest of the list. (The actual implementation in M4sugar is a bit more 12296 involved, to gain some speed and share code with @code{m4_map_sep}, and 12297 also to avoid expanding side effects in @samp{$2} twice). 12298 @example 12299 m4_define([m4_map], [m4_ifval([$2], 12300 [m4_apply([$1], m4_car($2))[]$0([$1], m4_cdr($2))])])dnl 12301 m4_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} 12309 Loop over the numeric values between @var{first} and @var{last} 12310 including bounds by increments of @var{step}. For each iteration, 12311 expand @var{expression} with the numeric value assigned to @var{var}. 12312 If @var{step} is omitted, it defaults to @samp{1} or @samp{-1} depending 12313 on the order of the limits. If given, @var{step} has to match this 12314 order. The number of iterations is determined independently from 12315 definition of @var{var}; iteration cannot be short-circuited or 12316 lengthened 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} 12321 Loop over the comma-separated M4 list @var{list}, assigning each value 12322 to @var{var}, and expand @var{expression}. The following example 12323 outputs two lines: 12324 12325 @example 12326 m4_foreach([myvar], [[foo], [bar, baz]], 12327 [echo myvar 12328 ])dnl 12329 @result{}echo foo 12330 @result{}echo bar, baz 12331 @end example 12332 12333 Note 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} 12340 Loop over the white-space-separated list @var{list}, assigning each value 12341 to @var{var}, and expand @var{expression}. If @var{var} is only 12342 referenced once in @var{expression}, it is more efficient to use 12343 @code{m4_map_args_w}. 12344 12345 The 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} 12357 Loop over the comma separated quoted list of argument descriptions in 12358 @var{list}, and invoke @var{macro} with the arguments. An argument 12359 description is in turn a comma-separated quoted list of quoted elements, 12360 suitable 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 12363 arguments. The macros @code{m4_map_sep} and @code{m4_mapall_sep} 12364 additionally expand @var{separator} between invocations of @var{macro}. 12365 12366 Note that @var{separator} is expanded, unlike in @code{m4_join}. When 12367 separating output with commas, this means that the map result can be 12368 used 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 12372 m4_map([m4_count], []) 12373 @result{} 12374 m4_map([ m4_count], [[], 12375 [[1]], 12376 [[1], [2]]]) 12377 @result{} 1 2 12378 m4_mapall([ m4_count], [[], 12379 [[1]], 12380 [[1], [2]]]) 12381 @result{} 0 1 2 12382 m4_map_sep([m4_eval], [,], [[[1+2]], 12383 [[10], [16]]]) 12384 @result{}3,a 12385 m4_map_sep([m4_echo], [,], [[[a]], [[b]]]) 12386 @result{}a,b 12387 m4_count(m4_map_sep([m4_echo], [,], [[[a]], [[b]]])) 12388 @result{}2 12389 m4_map_sep([m4_echo], [[,]], [[[a]], [[b]]]) 12390 @result{}a,b 12391 m4_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} 12398 Repeatedly invoke @var{macro} with each successive @var{arg} as its only 12399 argument. In the following example, three solutions are presented with 12400 the same expansion; the solution using @code{m4_map_args} is the most 12401 efficient. 12402 @example 12403 m4_define([active], [ACTIVE])dnl 12404 m4_foreach([var], [[plain], [active]], [ m4_echo(m4_defn([var]))]) 12405 @result{} plain active 12406 m4_map([ m4_echo], [[[plain]], [[active]]]) 12407 @result{} plain active 12408 m4_map_args([ m4_echo], [plain], [active]) 12409 @result{} plain active 12410 @end example 12411 12412 In cases where it is useful to operate on additional parameters besides 12413 the list elements, the macro @code{m4_curry} can be used in @var{macro} 12414 to supply the argument currying necessary to generate the desired 12415 argument list. In the following example, @code{list_add_n} is more 12416 efficient than @code{list_add_x}. On the other hand, using 12417 @code{m4_map_args_sep} can be even more efficient. 12418 12419 @example 12420 m4_define([list], [[1], [2], [3]])dnl 12421 m4_define([add], [m4_eval(([$1]) + ([$2]))])dnl 12422 dnl list_add_n(N, ARG...) 12423 dnl Output a list consisting of each ARG added to N 12424 m4_define([list_add_n], 12425 [m4_shift(m4_map_args([,m4_curry([add], [$1])], m4_shift($@@)))])dnl 12426 list_add_n([1], list) 12427 @result{}2,3,4 12428 list_add_n([2], list) 12429 @result{}3,4,5 12430 m4_define([list_add_x], 12431 [m4_shift(m4_foreach([var], m4_dquote(m4_shift($@@)), 12432 [,add([$1],m4_defn([var]))]))])dnl 12433 list_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} 12441 For every pair of arguments @var{arg}, invoke @var{macro} with two 12442 arguments. If there is an odd number of arguments, invoke 12443 @var{macro-end}, which defaults to @var{macro}, with the remaining 12444 argument. 12445 12446 @example 12447 m4_map_args_pair([, m4_reverse], [], [1], [2], [3]) 12448 @result{}, 2, 1, 3 12449 m4_map_args_pair([, m4_reverse], [, m4_dquote], [1], [2], [3]) 12450 @result{}, 2, 1, [3] 12451 m4_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} 12458 Expand the sequence @code{@var{pre}[@var{arg}]@var{post}} for each 12459 argument, additionally expanding @var{sep} between arguments. One 12460 common use of this macro is constructing a macro call, where the opening 12461 and closing parentheses are split between @var{pre} and @var{post}; in 12462 particular, @code{m4_map_args([@var{macro}], [@var{arg}])} is equivalent 12463 to @code{m4_map_args_sep([@var{macro}(], [)], [], [@var{arg}])}. This 12464 macro provides the most efficient means for iterating over an arbitrary 12465 list of arguments, particularly when repeatedly constructing a macro 12466 call 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} 12471 Expand the sequence @code{@var{pre}[word]@var{post}} for each word in 12472 the whitespace-separated @var{string}, additionally expanding @var{sep} 12473 between words. This macro provides the most efficient means for 12474 iterating over a whitespace-separated string. In particular, 12475 @code{m4_map_args_w([@var{string}], [@var{action}(], [)])} is more 12476 efficient 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}, 12487 along with validation that enough arguments were passed in to match the 12488 shift count, and that the count is positive. @code{m4_shift2} and 12489 @code{m4_shift3} are specializations 12490 of @code{m4_shiftn}, introduced in Autoconf 2.62, and are more efficient 12491 for 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} 12498 For 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 12503 there any guarantee that the current definition of @var{macro} matches 12504 the argument that was passed to @var{action}. The macro @code{m4_curry} 12505 can be used if @var{action} needs more than one argument, although in 12506 that case it is more efficient to use @var{m4_stack_foreach_sep}. 12507 12508 Due to technical limitations, there are a few low-level m4sugar 12509 functions, such as @code{m4_pushdef}, that cannot be used as the 12510 @var{macro} argument. 12511 12512 @example 12513 m4_pushdef([a], [1])m4_pushdef([a], [2])dnl 12514 m4_stack_foreach([a], [ m4_incr]) 12515 @result{} 2 3 12516 m4_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} 12526 Expand 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 12529 oldest definition first, while @code{m4_stack_foreach_sep_lifo} visits 12530 the current definition first. This macro provides the most efficient 12531 means 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 12539 The following macros give some control over the order of the evaluation 12540 by adding or removing levels of quotes. 12541 12542 @defmac m4_apply (@var{macro}, @var{list}) 12543 @msindex{apply} 12544 Apply the elements of the quoted, comma-separated @var{list} as the 12545 arguments to @var{macro}. If @var{list} is empty, invoke @var{macro} 12546 without arguments. Note the difference between @code{m4_indir}, which 12547 expects its first argument to be a macro name but can use names that are 12548 otherwise invalid, and @code{m4_apply}, where @var{macro} can contain 12549 other text, but must end in a valid macro name. 12550 @example 12551 m4_apply([m4_count], []) 12552 @result{}0 12553 m4_apply([m4_count], [[]]) 12554 @result{}1 12555 m4_apply([m4_count], [[1], [2]]) 12556 @result{}2 12557 m4_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} 12564 This macro returns the decimal count of the number of arguments it was 12565 passed. 12566 @end defmac 12567 12568 @defmac m4_curry (@var{macro}, @var{arg}@dots{}) 12569 @msindex{curry} 12570 This macro performs argument currying. The expansion of this macro is 12571 another macro name that expects exactly one argument; that argument is 12572 then appended to the @var{arg} list, and then @var{macro} is expanded 12573 with the resulting argument list. 12574 12575 @example 12576 m4_curry([m4_curry], [m4_reverse], [1])([2])([3]) 12577 @result{}3, 2, 1 12578 @end example 12579 12580 Unfortunately, due to a limitation in M4 1.4.x, it is not possible to 12581 pass 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. 12583 This behavior is rectified by using M4 1.6 or newer. 12584 @end defmac 12585 12586 @defmac m4_do (@var{arg}, @dots{}) 12587 @msindex{do} 12588 This macro loops over its arguments and expands each @var{arg} in 12589 sequence. Its main use is for readability; it allows the use of 12590 indentation and fewer @code{dnl} to result in the same expansion. This 12591 macro guarantees that no expansion will be concatenated with subsequent 12592 text; to achieve full concatenation, use @code{m4_unquote(m4_join([], 12593 @var{arg@dots{}}))}. 12594 12595 @example 12596 m4_define([ab],[1])m4_define([bc],[2])m4_define([abc],[3])dnl 12597 m4_do([a],[b])c 12598 @result{}abc 12599 m4_unquote(m4_join([],[a],[b]))c 12600 @result{}3 12601 m4_define([a],[A])m4_define([b],[B])m4_define([c],[C])dnl 12602 m4_define([AB],[4])m4_define([BC],[5])m4_define([ABC],[6])dnl 12603 m4_do([a],[b])c 12604 @result{}ABC 12605 m4_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} 12612 Return the arguments as a quoted list of quoted arguments. 12613 Conveniently, if there is just one @var{arg}, this effectively adds a 12614 level of quoting. 12615 @end defmac 12616 12617 @defmac m4_dquote_elt (@var{arg}, @dots{}) 12618 @msindex{dquote_elt} 12619 Return the arguments as a series of double-quoted arguments. Whereas 12620 @code{m4_dquote} returns a single argument, @code{m4_dquote_elt} returns 12621 as many arguments as it was passed. 12622 @end defmac 12623 12624 @defmac m4_echo (@var{arg}, @dots{}) 12625 @msindex{echo} 12626 Return the arguments, with the same level of quoting. Other than 12627 discarding whitespace after unquoted commas, this macro is a no-op. 12628 @end defmac 12629 12630 @defmac m4_expand (@var{arg}) 12631 @msindex{expand} 12632 Return the expansion of @var{arg} as a quoted string. Whereas 12633 @code{m4_quote} is designed to collect expanded text into a single 12634 argument, @code{m4_expand} is designed to perform one level of expansion 12635 on quoted text. One distinction is in the treatment of whitespace 12636 following a comma in the original @var{arg}. Any time multiple 12637 arguments are collected into one with @code{m4_quote}, the M4 argument 12638 collection rules discard the whitespace. However, with @code{m4_expand}, 12639 whitespace is preserved, even after the expansion of macros contained in 12640 @var{arg}. Additionally, @code{m4_expand} is able to expand text that 12641 would involve an unterminated comment, whereas expanding that same text 12642 as the argument to @code{m4_quote} runs into difficulty in finding the 12643 end of the argument. Since manipulating diversions during argument 12644 collection is inherently unsafe, @code{m4_expand} issues an error if 12645 @var{arg} attempts to change the current diversion (@pxref{Diversion 12646 support}). 12647 12648 @example 12649 m4_define([active], [ACT, IVE])dnl 12650 m4_define([active2], [[ACT, IVE]])dnl 12651 m4_quote(active, active) 12652 @result{}ACT,IVE,ACT,IVE 12653 m4_expand([active, active]) 12654 @result{}ACT, IVE, ACT, IVE 12655 m4_quote(active2, active2) 12656 @result{}ACT, IVE,ACT, IVE 12657 m4_expand([active2, active2]) 12658 @result{}ACT, IVE, ACT, IVE 12659 m4_expand([# m4_echo]) 12660 @result{}# m4_echo 12661 m4_quote(# m4_echo) 12662 ) 12663 @result{}# m4_echo) 12664 @result{} 12665 @end example 12666 12667 Note that @code{m4_expand} cannot handle an @var{arg} that expands to 12668 literal unbalanced quotes, but that quadrigraphs can be used when 12669 unbalanced output is necessary. Likewise, unbalanced parentheses should 12670 be supplied with double quoting or a quadrigraph. 12671 12672 @example 12673 m4_define([pattern], [[!@@<:@@]])dnl 12674 m4_define([bar], [BAR])dnl 12675 m4_expand([case $foo in 12676 m4_defn([pattern])@@:@}@@ bar ;; 12677 *[)] blah ;; 12678 esac]) 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} 12688 This macro was introduced in Autoconf 2.62. Expands to nothing, 12689 ignoring all of its arguments. By itself, this isn't very useful. 12690 However, it can be used to conditionally ignore an arbitrary number of 12691 arguments, by deciding which macro name to apply to a list of arguments. 12692 @example 12693 dnl foo outputs a message only if [debug] is defined. 12694 m4_define([foo], 12695 [m4_ifdef([debug],[AC_MSG_NOTICE],[m4_ignore])([debug message])]) 12696 @end example 12697 12698 Note that for earlier versions of Autoconf, the macro @code{__gnu__} can 12699 serve the same purpose, although it is less readable. 12700 @end defmac 12701 12702 @defmac m4_make_list (@var{arg}, @dots{}) 12703 @msindex{make_list} 12704 This macro exists to aid debugging of M4sugar algorithms. Its net 12705 effect is similar to @code{m4_dquote}---it produces a quoted list of 12706 quoted arguments, for each @var{arg}. The difference is that this 12707 version uses a comma-newline separator instead of just comma, to improve 12708 readability of the list; with the result that it is less efficient than 12709 @code{m4_dquote}. 12710 @example 12711 m4_define([zero],[0])m4_define([one],[1])m4_define([two],[2])dnl 12712 m4_dquote(zero, [one], [[two]]) 12713 @result{}[0],[one],[[two]] 12714 m4_make_list(zero, [one], [[two]]) 12715 @result{}[0], 12716 @result{}[one], 12717 @result{}[[two]] 12718 m4_foreach([number], m4_dquote(zero, [one], [[two]]), [ number]) 12719 @result{} 0 1 two 12720 m4_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} 12731 Return the arguments as a single entity, i.e., wrap them into a pair of 12732 quotes. This effectively collapses multiple arguments into one, 12733 although it loses whitespace after unquoted commas in the process. 12734 @end defmac 12735 12736 @defmac m4_reverse (@var{arg}, @dots{}) 12737 @msindex{reverse} 12738 Outputs each argument with the same level of quoting, but in reverse 12739 order, and with space following each comma for readability. 12740 12741 @example 12742 m4_define([active], [ACT,IVE]) 12743 @result{} 12744 m4_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} 12751 This macro was introduced in Autoconf 2.62. Expand each argument, 12752 separated by commas. For a single @var{arg}, this effectively removes a 12753 layer of quoting, and @code{m4_unquote([@var{arg}])} is more efficient 12754 than the equivalent @code{m4_do([@var{arg}])}. For multiple arguments, 12755 this results in an unquoted list of expansions. This is commonly used 12756 with @code{m4_split}, in order to convert a single quoted list into a 12757 series of quoted elements. 12758 @end defmac 12759 12760 The following example aims at emphasizing the difference between several 12761 scenarios: 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} 12766 dnl Overquote, so that quotes are visible. 12767 m4_define([show], [$[]1 = [$1], $[]@@ = [$@@]]) 12768 m4_define([a], [A]) 12769 m4_define([mkargs], [1, 2[,] 3]) 12770 m4_define([arg1], [[$1]]) 12771 m4_divert([0])dnl 12772 show(a, b) 12773 show([a, b]) 12774 show(m4_quote(a, b)) 12775 show(m4_dquote(a, b)) 12776 show(m4_expand([a, b])) 12777 12778 arg1(mkargs) 12779 arg1([mkargs]) 12780 arg1(m4_defn([mkargs])) 12781 arg1(m4_quote(mkargs)) 12782 arg1(m4_dquote(mkargs)) 12783 arg1(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 12791 1 12792 mkargs 12793 1, 2[,] 3 12794 1,2, 3 12795 [1],[2, 3] 12796 1, 2, 3 12797 @end example 12798 12799 12800 @node Text processing Macros 12801 @subsection String manipulation in M4 12802 12803 The following macros may be used to manipulate strings in M4. Many of 12804 the macros in this section intentionally result in quoted strings as 12805 output, rather than subjecting the arguments to further expansions. As 12806 a result, if you are manipulating text that contains active M4 12807 characters, the arguments are passed with single quoting rather than 12808 double. 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} 12815 Redefine @var{macro-name} to its former contents with @var{separator} 12816 and @var{string} added at the end. If @var{macro-name} was undefined 12817 before (but not if it was defined but empty), then no @var{separator} is 12818 added. As of Autoconf 2.62, neither @var{string} nor @var{separator} 12819 are 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} 12823 to 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. 12827 Also, @code{m4_append_uniq} warns if @var{separator} is not empty, but 12828 occurs within @var{string}, since that can lead to duplicates. 12829 12830 Note that @code{m4_append} can scale linearly in the length of the final 12831 string, depending on the quality of the underlying M4 implementation, 12832 while @code{m4_append_uniq} has an inherent quadratic scaling factor. 12833 If an algorithm can tolerate duplicates in the final string, use the 12834 former for speed. If duplicates must be avoided, consider using 12835 @code{m4_set_add} instead (@pxref{Set manipulation Macros}). 12836 12837 @example 12838 m4_define([active], [ACTIVE])dnl 12839 m4_append([sentence], [This is an])dnl 12840 m4_append([sentence], [ active ])dnl 12841 m4_append([sentence], [symbol.])dnl 12842 sentence 12843 @result{}This is an ACTIVE symbol. 12844 m4_undefine([active])dnl 12845 @result{}This is an active symbol. 12846 m4_append_uniq([list], [one], [, ], [new], [existing]) 12847 @result{}new 12848 m4_append_uniq([list], [one], [, ], [new], [existing]) 12849 @result{}existing 12850 m4_append_uniq([list], [two], [, ], [new], [existing]) 12851 @result{}new 12852 m4_append_uniq([list], [three], [, ], [new], [existing]) 12853 @result{}new 12854 m4_append_uniq([list], [two], [, ], [new], [existing]) 12855 @result{}existing 12856 list 12857 @result{}one, two, three 12858 m4_dquote(list) 12859 @result{}[one],[two],[three] 12860 m4_append([list2], [one], [[, ]])dnl 12861 m4_append_uniq([list2], [two], [[, ]])dnl 12862 m4_append([list2], [three], [[, ]])dnl 12863 list2 12864 @result{}one, two, three 12865 m4_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} 12872 This macro was introduced in Autoconf 2.62. It is similar to 12873 @code{m4_append_uniq}, but treats @var{strings} as a whitespace 12874 separated 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 12877 m4_append_uniq_w([numbers], [1 1 2])dnl 12878 m4_append_uniq_w([numbers], [ 2 3 ])dnl 12879 numbers 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} 12888 Output @var{string} in quotes, but without a trailing newline. The 12889 macro @code{m4_chomp} is slightly faster, and removes at most one 12890 newline; the macro @code{m4_chomp_all} removes all consecutive trailing 12891 newlines. Unlike @code{m4_flatten}, embedded newlines are left intact, 12892 and 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} 12898 This macro produces a quoted string containing the pairwise combination 12899 of every element of the quoted, comma-separated @var{prefix-list}, and 12900 every element from the @var{suffix} arguments. Each pairwise 12901 combination is joined with @var{infix} in the middle, and successive 12902 pairs are joined by @var{separator}. No expansion occurs on any of the 12903 arguments. No output occurs if either the @var{prefix} or @var{suffix} 12904 list is empty, but the lists can contain empty elements. 12905 @example 12906 m4_define([a], [oops])dnl 12907 m4_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 12909 m4_combine([, ], [[a], [b]], [-]) 12910 @result{} 12911 m4_combine([, ], [[a], [b]], [-], []) 12912 @result{}a-, b- 12913 m4_combine([, ], [], [-], [1], [2]) 12914 @result{} 12915 m4_combine([, ], [[]], [-], [1], [2]) 12916 @result{}-1, -2 12917 @end example 12918 @end defmac 12919 12920 @defmac m4_escape (@var{string}) 12921 @msindex{escape} 12922 Convert all instances of @samp{[}, @samp{]}, @samp{#}, and @samp{$} 12923 within @var{string} into their respective quadrigraphs. The result is 12924 still a quoted string. 12925 @end defmac 12926 12927 @defmac m4_flatten (@var{string}) 12928 @msindex{flatten} 12929 Flatten @var{string} into a single line. Delete all backslash-newline 12930 pairs, and replace all remaining newlines with a space. The result is 12931 still 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} 12938 Concatenate each @var{arg}, separated by @var{separator}. 12939 @code{joinall} uses every argument, while @code{join} omits empty 12940 arguments so that there are no back-to-back separators in the output. 12941 The result is a quoted string. 12942 @example 12943 m4_define([active], [ACTIVE])dnl 12944 m4_join([|], [one], [], [active], [two]) 12945 @result{}one|active|two 12946 m4_joinall([|], [one], [], [active], [two]) 12947 @result{}one||active|two 12948 @end example 12949 12950 Note that if all you intend to do is join @var{args} with commas between 12951 them, to form a quoted list suitable for @code{m4_foreach}, it is more 12952 efficient to use @code{m4_dquote}. 12953 @end defmac 12954 12955 @defmac m4_newline (@ovar{text}) 12956 @msindex{newline} 12957 This macro was introduced in Autoconf 2.62, and expands to a newline, 12958 followed by any @var{text}. 12959 It is primarily useful for maintaining macro formatting, and ensuring 12960 that M4 does not discard leading whitespace during argument collection. 12961 @end defmac 12962 12963 @defmac m4_normalize (@var{string}) 12964 @msindex{normalize} 12965 Remove leading and trailing spaces and tabs, sequences of 12966 backslash-then-newline, and replace multiple spaces, tabs, and newlines 12967 with 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 12969 that 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} 12975 Backslash-escape all characters in @var{string} that are active in 12976 regexps. 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} 12982 Split @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. 12984 If @var{regexp} is given, use it instead of @samp{[\t ]+} for splitting. 12985 If @var{string} is empty, the result is an empty list. 12986 @end defmac 12987 12988 @defmac m4_strip (@var{string}) 12989 @msindex{strip} 12990 Strip whitespace from @var{string}. Sequences of spaces and tabs are 12991 reduced to a single space, then leading and trailing spaces are removed. 12992 The result is still a quoted string. Note that this does not interfere 12993 with newlines; if you want newlines stripped as well, consider 12994 @code{m4_flatten}, or do it all at once with @code{m4_normalize}. To 12995 quickly 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} 13000 Add a text box around @var{message}, using @var{frame} as the border 13001 character above and below the message. The @var{frame} argument must be 13002 a single byte, and does not support quadrigraphs. 13003 The frame correctly accounts for 13004 the subsequent expansion of @var{message}. For example: 13005 @example 13006 m4_define([macro], [abc])dnl 13007 m4_text_box([macro]) 13008 @result{}## --- ## 13009 @result{}## abc ## 13010 @result{}## --- ## 13011 @end example 13012 13013 The @var{message} must contain balanced quotes and parentheses, although 13014 quadrigraphs 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} 13020 Break @var{string} into a series of whitespace-separated words, then 13021 output those words separated by spaces, and wrapping lines any time the 13022 output would exceed @var{width} columns. If given, @var{prefix1} begins 13023 the first line, and @var{prefix} begins all wrapped lines. If 13024 @var{prefix1} is longer than @var{prefix}, then the first line consists 13025 of just @var{prefix1}. If @var{prefix} is longer than @var{prefix1}, 13026 padding is inserted so that the first word of @var{string} begins at the 13027 same indentation as all wrapped lines. Note that using literal tab 13028 characters in any of the arguments will interfere with the calculation 13029 of width. No expansions occur on @var{prefix}, @var{prefix1}, or the 13030 words of @var{string}, although quadrigraphs are recognized. 13031 13032 For some examples: 13033 @example 13034 m4_text_wrap([Short string */], [ ], [/* ], [20]) 13035 @result{}/* Short string */ 13036 m4_text_wrap([Much longer string */], [ ], [/* ], [20]) 13037 @result{}/* Much longer 13038 @result{} string */ 13039 m4_text_wrap([Short doc.], [ ], [ --short ], [30]) 13040 @result{} --short Short doc. 13041 m4_text_wrap([Short doc.], [ ], [ --too-wide ], [30]) 13042 @result{} --too-wide 13043 @result{} Short doc. 13044 m4_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} 13056 Return @var{string} with letters converted to upper or lower case, 13057 respectively. 13058 @end defmac 13059 13060 @node Number processing Macros 13061 @subsection Arithmetic computation in M4 13062 13063 The following macros facilitate integer arithmetic operations. 13064 Where a parameter is documented as taking an arithmetic expression, you 13065 can use anything that can be parsed by @code{m4_eval}. 13066 13067 @defmac m4_cmp (@var{expr-1}, @var{expr-2}) 13068 @msindex{cmp} 13069 Compare the arithmetic expressions @var{expr-1} and @var{expr-2}, and 13070 expand to @samp{-1} if @var{expr-1} is smaller, @samp{0} if they are 13071 equal, 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} 13076 Compare the two M4 lists consisting of comma-separated arithmetic 13077 expressions, left to right. Expand to @samp{-1} for the first element 13078 pairing where the value from @var{list-1} is smaller, @samp{1} where the 13079 value from @var{list-2} is smaller, or @samp{0} if both lists have the 13080 same values. If one list is shorter than the other, the remaining 13081 elements of the longer list are compared against zero. 13082 @example 13083 m4_list_cmp([1, 0], [1]) 13084 @result{}0 13085 m4_list_cmp([1, [1 * 0]], [1, 0]) 13086 @result{}0 13087 m4_list_cmp([1, 2], [1, 0]) 13088 @result{}1 13089 m4_list_cmp([1, [1+1], 3],[1, 2]) 13090 @result{}1 13091 m4_list_cmp([1, 2, -3], [1, 2]) 13092 @result{}-1 13093 m4_list_cmp([1, 0], [1, 2]) 13094 @result{}-1 13095 m4_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} 13102 This macro was introduced in Autoconf 2.62. Expand to the decimal value 13103 of the maximum arithmetic expression among all the arguments. 13104 @end defmac 13105 13106 @defmac m4_min (@var{arg}, @dots{}) 13107 @msindex{min} 13108 This macro was introduced in Autoconf 2.62. Expand to the decimal value 13109 of the minimum arithmetic expression among all the arguments. 13110 @end defmac 13111 13112 @defmac m4_sign (@var{expr}) 13113 @msindex{sign} 13114 Expand 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} 13121 This macro was introduced in Autoconf 2.53, but had a number of 13122 usability limitations that were not lifted until Autoconf 2.62. Compare 13123 the 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, 13125 or @samp{1} @var{version-2} is smaller. Version strings must be a list 13126 of elements separated by @samp{.}, @samp{,} or @samp{-}, where each 13127 element is a number along with optional case-insensitive letters 13128 designating beta releases. The comparison stops at the leftmost element 13129 that contains a difference, although a 0 element compares equal to a 13130 missing element. 13131 13132 It is permissible to include commit identifiers in @var{version}, such 13133 as an abbreviated SHA1 of the commit, provided there is still a 13134 monotonically increasing prefix to allow for accurate version-based 13135 comparisons. For example, this paragraph was written when the 13136 development snapshot of autoconf claimed to be at version 13137 @samp{2.61a-248-dc51}, or 248 commits after the 2.61a release, with an 13138 abbreviated commit identification of @samp{dc51}. 13139 13140 @example 13141 m4_version_compare([1.1], [2.0]) 13142 @result{}-1 13143 m4_version_compare([2.0b], [2.0a]) 13144 @result{}1 13145 m4_version_compare([1.1.1], [1.1.1a]) 13146 @result{}-1 13147 m4_version_compare([1.2], [1.1.1a]) 13148 @result{}1 13149 m4_version_compare([1.0], [1]) 13150 @result{}0 13151 m4_version_compare([1.1pre], [1.1PRE]) 13152 @result{}0 13153 m4_version_compare([1.1a], [1,10]) 13154 @result{}-1 13155 m4_version_compare([2.61a], [2.61a-248-dc51]) 13156 @result{}-1 13157 m4_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} 13165 Compares @var{version} against the version of Autoconf currently 13166 running. 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 13168 currently executing, expand @var{if-old}, which defaults to printing an 13169 error message and exiting m4sugar with status 63. When given only one 13170 argument, this behaves like @code{AC_PREREQ} (@pxref{Versioning}). 13171 Remember that the autoconf philosophy favors feature checks over version 13172 checks. 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 13181 Sometimes, it is necessary to track a set of data, where the order does 13182 not matter and where there are no duplicates in the set. The following 13183 macros facilitate set manipulations. Each set is an opaque object, 13184 which can only be accessed via these basic operations. The underlying 13185 implementation guarantees linear scaling for set creation, which is more 13186 efficient than using the quadratic @code{m4_append_uniq}. Both set 13187 names and values can be arbitrary strings, except for unbalanced quotes. 13188 This implementation ties up memory for removed elements until the next 13189 operation that must traverse all the elements of a set; and although 13190 that may slow down some operations until the memory for removed elements 13191 is 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} 13195 Adds 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 13197 previously in the set. Operates in amortized constant time, so that set 13198 creation scales linearly. 13199 @end defmac 13200 13201 @defmac m4_set_add_all (@var{set}, @var{value}@dots{}) 13202 @msindex{set_add_all} 13203 Adds each @var{value} to the set @var{set}. This is slightly more 13204 efficient 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} 13210 Expands @var{if-present} if the string @var{value} is a member of 13211 @var{set}, otherwise @var{if-absent}. 13212 13213 @example 13214 m4_set_contains([a], [1], [yes], [no]) 13215 @result{}no 13216 m4_set_add([a], [1], [added], [dup]) 13217 @result{}added 13218 m4_set_add([a], [1], [added], [dup]) 13219 @result{}dup 13220 m4_set_contains([a], [1], [yes], [no]) 13221 @result{}yes 13222 m4_set_remove([a], [1], [removed], [missing]) 13223 @result{}removed 13224 m4_set_contains([a], [1], [yes], [no]) 13225 @result{}no 13226 m4_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} 13235 Expands 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 13238 memory occupied by removed elements, while @code{m4_set_dump} is a 13239 faster one-shot action that also deletes the set. No provision is made 13240 for disambiguating members that contain a non-empty @var{sep} as a 13241 substring; use @code{m4_set_empty} to distinguish between an empty set 13242 and the set containing only the empty string. The order of the output 13243 is 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 13246 set 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 13251 m4_set_add_all([a], [1], [2], [3]) 13252 @result{} 13253 m4_set_contents([a], [-]) 13254 @result{}1-2-3 13255 m4_joinall([-]m4_set_listc([a])) 13256 @result{}1-2-3 13257 m4_set_dump([a], [-]) 13258 @result{}3-2-1 13259 m4_set_contents([a]) 13260 @result{} 13261 m4_set_add([a], []) 13262 @result{} 13263 m4_set_contents([a], [-]) 13264 @result{} 13265 @end example 13266 @end defmac 13267 13268 @defmac m4_set_delete (@var{set}) 13269 @msindex{set_delete} 13270 Delete all elements and memory associated with @var{set}. This is 13271 linear 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} 13280 Compute the relation between @var{seta} and @var{setb}, and output the 13281 result as a list of quoted arguments without duplicates and with a 13282 leading comma. Set difference selects the elements in @var{seta} but 13283 not @var{setb}, intersection selects only elements in both sets, and 13284 union selects elements in either set. These actions are linear in the 13285 sum of the set sizes. The leading comma is necessary to distinguish 13286 between no elements and the empty string as the only element. 13287 13288 @example 13289 m4_set_add_all([a], [1], [2], [3]) 13290 @result{} 13291 m4_set_add_all([b], [3], [], [4]) 13292 @result{} 13293 m4_set_difference([a], [b]) 13294 @result{},1,2 13295 m4_set_difference([b], [a]) 13296 @result{},,4 13297 m4_set_intersection([a], [b]) 13298 @result{},3 13299 m4_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} 13306 Expand @var{if-empty} if the set @var{set} has no elements, otherwise 13307 expand @var{if-elements}. This macro operates in constant time. Using 13308 this 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} 13314 For each element in the set @var{set}, expand @var{action} with the 13315 macro @var{variable} defined as the set element. Behavior is 13316 unspecified if @var{action} recursively lists the contents of @var{set} 13317 (although listing other sets is acceptable), or if it modifies the set 13318 in 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}], 13321 m4_indir([m4_dquote]m4_set_listc([@var{set}])), [@var{action}])}, 13322 although @code{m4_set_map} might be faster still. 13323 13324 @example 13325 m4_set_add_all([a]m4_for([i], [1], [5], [], [,i])) 13326 @result{} 13327 m4_set_contents([a]) 13328 @result{}12345 13329 m4_set_foreach([a], [i], 13330 [m4_if(m4_eval(i&1), [0], [m4_set_remove([a], i, [i])])]) 13331 @result{}24 13332 m4_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} 13341 Produce a list of arguments, where each argument is a quoted element 13342 from the set @var{set}. The variant @code{m4_set_listc} is unambiguous, 13343 by adding a leading comma if there are any set elements, whereas the 13344 variant @code{m4_set_list} cannot distinguish between an empty set and a 13345 set containing only the empty string. These can be directly used in 13346 macros 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 13348 take a quoted list, such as @code{m4_map} or @code{m4_foreach}. Any 13349 memory occupied by removed elements is reclaimed during these macros. 13350 13351 @example 13352 m4_set_add_all([a], [1], [2], [3]) 13353 @result{} 13354 m4_set_list([a]) 13355 @result{}1,2,3 13356 m4_set_list([b]) 13357 @result{} 13358 m4_set_listc([b]) 13359 @result{} 13360 m4_count(m4_set_list([b])) 13361 @result{}1 13362 m4_set_empty([b], [0], [m4_count(m4_set_list([b]))]) 13363 @result{}0 13364 m4_set_add([b], []) 13365 @result{} 13366 m4_set_list([b]) 13367 @result{} 13368 m4_set_listc([b]) 13369 @result{}, 13370 m4_count(m4_set_list([b])) 13371 @result{}1 13372 m4_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} 13379 For each element in the set @var{set}, expand @var{action} with a single 13380 argument of the set element. Behavior is unspecified if @var{action} 13381 recursively lists the contents of @var{set} (although listing other sets 13382 is acceptable), or if it modifies the set in any way other than removing 13383 the element passed as an argument. This macro is faster than either 13384 corresponding 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} 13388 if more than one argument is needed for @var{action}, although it is 13389 more 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} 13394 For each element in the set @var{set}, expand 13395 @code{@var{pre}[element]@var{post}}, additionally expanding @var{sep} 13396 between elements. Behavior is unspecified if the expansion recursively 13397 lists the contents of @var{set} (although listing other sets 13398 is acceptable), or if it modifies the set in any way other than removing 13399 the element visited by the expansion. This macro provides the most 13400 efficient means for non-destructively visiting the elements of a set; in 13401 particular, @code{m4_set_map([@var{set}], [@var{action}])} is equivalent 13402 to @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} 13408 If @var{value} is an element in the set @var{set}, then remove it and 13409 expand @var{if-present}. Otherwise expand @var{if-absent}. This macro 13410 operates in constant time so that multiple removals will scale linearly 13411 rather than quadratically; but when used outside of 13412 @code{m4_set_foreach} or @code{m4_set_map}, it leaves memory occupied 13413 until the set is later 13414 compacted by @code{m4_set_contents} or @code{m4_set_list}. Several 13415 other set operations are then less efficient between the time of element 13416 removal and subsequent memory compaction, but still maintain their 13417 guaranteed scaling performance. 13418 @end defmac 13419 13420 @defmac m4_set_size (@var{set}) 13421 @msindex{set_size} 13422 Expand to the size of the set @var{set}. This implementation operates 13423 in 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 13433 M4sugar provides a means to define suspicious patterns, patterns 13434 describing tokens which should not be found in the output. For 13435 instance, if an Autoconf @file{configure} script includes tokens such as 13436 @samp{AC_DEFINE}, or @samp{dnl}, then most probably something went 13437 wrong (typically a macro was not evaluated because of overquotation). 13438 13439 M4sugar forbids all the tokens matching @samp{^_?m4_} and @samp{^dnl$}. 13440 Additional layers, such as M4sh and Autoconf, add additional forbidden 13441 patterns to the list. 13442 13443 @defmac m4_pattern_forbid (@var{pattern}) 13444 @msindex{pattern_forbid} 13445 Declare that no token matching @var{pattern} must be found in the output. 13446 Comments are not checked; this can be a problem if, for instance, you 13447 have some macro left unexpanded after an @samp{#include}. No consensus 13448 is currently found in the Autoconf community, as some people consider it 13449 should be valid to name macros in comments (which doesn't make sense to 13450 the authors of this documentation: input, such as macros, should be 13451 documented by @samp{dnl} comments; reserving @samp{#}-comments to 13452 document the output). 13453 @end defmac 13454 13455 Of course, you might encounter exceptions to these generic rules, for 13456 instance you might have to refer to @samp{$m4_flags}. 13457 13458 @defmac m4_pattern_allow (@var{pattern}) 13459 @msindex{pattern_allow} 13460 Any 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 13469 At times, it is desirable to see what was happening inside m4, to see 13470 why output was not matching expectations. However, post-processing done 13471 by @command{autom4te} means that directly using the m4 builtin 13472 @code{m4_traceon} is likely to interfere with operation. Also, frequent 13473 diversion changes and the concept of forbidden tokens make it difficult 13474 to use @code{m4_defn} to generate inline comments in the final output. 13475 13476 There 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 13478 of the programs that wrap @command{autom4te}, such as 13479 @command{autoconf}), in order to inspect when a macro is called and with 13480 which arguments. For example, when this paragraph was written, the 13481 autoconf version could be found by: 13482 13483 @example 13484 $ @kbd{autoconf --trace=AC_INIT} 13485 configure.ac:23:AC_INIT:GNU Autoconf:2.63b.95-3963:bug-autoconf@@gnu.org 13486 $ @kbd{autoconf --trace='AC_INIT:version is $2'} 13487 version is 2.63b.95-3963 13488 @end example 13489 13490 Another trick is to print out the expansion of various m4 expressions to 13491 standard error or to an independent file, with no further m4 expansion, 13492 and without interfering with diversion changes or the post-processing 13493 done to standard output. @code{m4_errprintn} shows a given expression 13494 on standard error. For example, if you want to see the expansion of an 13495 autoconf primitive or of one of your autoconf macros, you can do it like 13496 this: 13497 13498 @example 13499 $ @kbd{cat <<\EOF > configure.ac} 13500 AC_INIT 13501 m4_errprintn([The definition of AC_DEFINE_UNQUOTED:]) 13502 m4_errprintn(m4_defn([AC_DEFINE_UNQUOTED])) 13503 AC_OUTPUT 13504 EOF 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 13513 M4sh, pronounced ``mash'', is aiming at producing portable Bourne shell 13514 scripts. This name was coined by Lars J. Aas, who notes that, 13515 according to the Webster's Revised Unabridged Dictionary (1913): 13516 13517 @quotation 13518 Mash \Mash\, n. [Akin to G. meisch, maisch, meische, maische, mash, 13519 wash, and prob.@: to AS. miscian to mix. See ``Mix''.] 13520 13521 @enumerate 1 13522 @item 13523 A mass of mixed ingredients reduced to a soft pulpy state by beating or 13524 pressure@enddots{} 13525 13526 @item 13527 A mixture of meal or bran and water fed to animals. 13528 13529 @item 13530 A mess; trouble. [Obs.] --Beau.@: & Fl. 13531 @end enumerate 13532 @end quotation 13533 13534 M4sh reserves the M4 macro namespace @samp{^_AS_} for internal use, and 13535 the namespace @samp{^AS_} for M4sh macros. It also reserves the shell 13536 and environment variable namespace @samp{^as_}, and the here-document 13537 delimiter namespace @samp{^_AS[A-Z]} in the output file. You should not 13538 define your own macros or output shell code that conflicts with these 13539 namespaces. 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 13551 M4sh provides portable alternatives for some common shell constructs 13552 that 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} 13558 Output the non-directory portion of @var{file-name}. For example, 13559 if @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} 13566 Expand into shell code that will output @var{text} surrounded by a box 13567 with @var{char} in the top and bottom border. @var{text} should not 13568 contain a newline, but may contain shell expansions valid for unquoted 13569 here-documents. @var{char} defaults to @samp{-}, but can be any 13570 character except @samp{/}, @samp{'}, @samp{"}, @samp{\}, 13571 @samp{&}, or @samp{`}. This is useful for outputting a comment box into 13572 log 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} 13578 Expand into a shell @samp{case} statement, where @var{word} is matched 13579 against one or more patterns. @var{if-matched} is run if the 13580 corresponding pattern matched @var{word}, else @var{default} is run. 13581 Avoids several portability issues (@pxref{case, , Limitations of Shell 13582 Builtins}). 13583 @end defmac 13584 13585 @c Deprecated, to be replaced by a better API 13586 @defmac AS_DIRNAME (@var{file-name}) 13587 @asindex{DIRNAME} 13588 Output the directory portion of @var{file-name}. For example, 13589 if @code{$file} is @samp{/one/two/three}, the command 13590 @code{dir=`AS_DIRNAME(["$file"])`} sets @code{dir} to @samp{/one/two}. 13591 13592 This interface may be improved in the future to avoid forks and losing 13593 trailing newlines. 13594 @end defmac 13595 13596 @defmac AS_ECHO (@var{word}) 13597 @asindex{ECHO} 13598 Emits @var{word} to the standard output, followed by a newline. @var{word} 13599 must 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 "\". 13601 Redirections can be placed outside the macro invocation. This is much 13602 more portable than using @command{echo} (@pxref{echo, , Limitations of 13603 Shell Builtins}). 13604 @end defmac 13605 13606 @defmac AS_ECHO_N (@var{word}) 13607 @asindex{ECHO_N} 13608 Emits @var{word} to the standard output, without a following newline. 13609 @var{word} must be a single shell word (typically a quoted string) and, 13610 for 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 "\". 13612 Redirections 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} 13618 Expands to @var{string}, with any characters in @var{chars} escaped with 13619 a backslash (@samp{\}). @var{chars} should be at most four bytes long, 13620 and only contain characters from the set @samp{`\"$}; however, 13621 characters may be safely listed more than once in @var{chars} for the 13622 sake of syntax highlighting editors. The current implementation expands 13623 @var{string} after adding escapes; if @var{string} contains macro calls 13624 that in turn expand to text needing shell quoting, you can use 13625 @code{AS_ESCAPE(m4_dquote(m4_expand([string])))}. 13626 13627 The default for @var{chars} (@samp{\"$`}) is the set of characters 13628 needing escapes when @var{string} will be used literally within double 13629 quotes. One common variant is the set of characters to protect when 13630 @var{string} will be used literally within back-ticks or an unquoted 13631 here-document (@samp{\$`}). Another common variant is @samp{""}, which can 13632 be used to form a double-quoted string containing the same expansions 13633 that would have occurred if @var{string} were expanded in an unquoted 13634 here-document; however, when using this variant, care must be taken that 13635 @var{string} does not use double quotes within complex variable 13636 expansions (such as @samp{$@{foo-`echo "hi"`@}}) that would be broken 13637 with improper escapes. 13638 13639 This macro is often used with @code{AS_ECHO}. For an example, observe 13640 the output generated by the shell code generated from this snippet: 13641 13642 @example 13643 foo=bar 13644 AS_ECHO(["AS_ESCAPE(["$foo" = ])AS_ESCAPE(["$foo"], [""])"]) 13645 @result{}"$foo" = "bar" 13646 m4_define([macro], [a, [\b]]) 13647 AS_ECHO(["AS_ESCAPE([[macro]])"]) 13648 @result{}macro 13649 AS_ECHO(["AS_ESCAPE([macro])"]) 13650 @result{}a, b 13651 AS_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 '. 13657 To escape a string that will be placed within single quotes, use: 13658 13659 @example 13660 m4_bpatsubst([[@var{string}]], ['], ['\\'']) 13661 @end example 13662 @end defmac 13663 13664 @defmac AS_EXECUTABLE_P (@var{file}) 13665 @asindex{EXECUTABLE_P} 13666 Emit code to probe whether @var{file} is a regular file with executable 13667 permissions (and not a directory with search permissions). The caller 13668 is responsible for quoting @var{file}. 13669 @end defmac 13670 13671 @defmac AS_EXIT (@dvar{status, $?}) 13672 @asindex{EXIT} 13673 Emit code to exit the shell with @var{status}, defaulting to @samp{$?}. 13674 This macro 13675 works around shells that see the exit status of the command prior to 13676 @code{exit} inside a @samp{trap 0} handler (@pxref{trap, , Limitations 13677 of Shell Builtins}). 13678 @end defmac 13679 13680 @defmac AS_IF (@var{test1}, @ovar{run-if-true1}, @dots{}, @ovar{run-if-false}) 13681 @asindex{IF} 13682 Run shell code @var{test1}. If @var{test1} exits with a zero status then 13683 run shell code @var{run-if-true1}, else examine further tests. If no test 13684 exits with a zero status, run shell code @var{run-if-false}, with 13685 simplifications if either @var{run-if-true1} or @var{run-if-false} 13686 is empty. For example, 13687 13688 @example 13689 AS_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 13695 ensures any required macros of @code{HANDLE_FOO} 13696 are expanded before the first test. 13697 @end defmac 13698 13699 @defmac AS_MKDIR_P (@var{file-name}) 13700 @asindex{MKDIR_P} 13701 Make the directory @var{file-name}, including intervening directories 13702 as necessary. This is equivalent to @samp{mkdir -p -- @var{file-name}}, 13703 except that it is portable to older versions of @command{mkdir} that 13704 lack support for the @option{-p} option or for the @option{--} 13705 delimiter (@pxref{mkdir, , Limitations of Usual Tools}). Also, 13706 @code{AS_MKDIR_P} 13707 succeeds if @var{file-name} is a symbolic link to an existing directory, 13708 even though Posix is unclear whether @samp{mkdir -p} should 13709 succeed in that case. If creation of @var{file-name} fails, exit the 13710 script. 13711 13712 Also 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} 13717 Emit shell code to set the value of @samp{$?} to @var{status}, as 13718 efficiently as possible. However, this is not guaranteed to abort a 13719 shell running with @code{set -e} (@pxref{set, , Limitations of Shell 13720 Builtins}). This should also be used at the end of a complex shell 13721 function instead of @samp{return} (@pxref{Shell Functions}) to avoid 13722 a DJGPP shell bug. 13723 @end defmac 13724 13725 @defmac AS_TR_CPP (@var{expression}) 13726 @asindex{TR_CPP} 13727 Transform @var{expression} into a valid right-hand side for a C @code{#define}. 13728 For example: 13729 13730 @example 13731 # This outputs "#define HAVE_CHAR_P 1". 13732 # Notice the m4 quoting around #, to prevent an m4 comment 13733 type="char *" 13734 echo "[#]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} 13740 Transform @var{expression} into shell code that generates a valid shell 13741 variable name. The result is literal when possible at m4 time, but must 13742 be used with @code{eval} if @var{expression} causes shell indirections. 13743 For example: 13744 13745 @example 13746 # This outputs "Have it!". 13747 header="sys/some file.h" 13748 eval AS_TR_SH([HAVE_$header])=yes 13749 if 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} 13755 Set the polymorphic shell variable @var{var} to @var{dir}/@var{file}, 13756 but 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} 13762 Unsets the shell variable @var{var}, working around bugs in older 13763 shells (@pxref{unset, , Limitations of Shell 13764 Builtins}). @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} 13770 Compare two strings @var{version-1} and @var{version-2}, possibly 13771 containing shell variables, as version strings, and expand 13772 @var{action-if-less}, @var{action-if-equal}, or @var{action-if-greater} 13773 depending upon the result. 13774 The algorithm to compare is similar to the one used by strverscmp in 13775 glibc (@pxref{String/Array Comparison, , String/Array Comparison, libc, 13776 The 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 13785 Often, it is convenient to write a macro that will emit shell code 13786 operating on a shell variable. The simplest case is when the variable 13787 name is known. But a more powerful idiom is writing shell code that can 13788 work through an indirection, where another variable or command 13789 substitution produces the name of the variable to actually manipulate. 13790 M4sh supports the notion of polymorphic shell variables, making it easy 13791 to write a macro that can deal with either literal or indirect variable 13792 names and output shell code appropriate for both use cases. Behavior is 13793 undefined if expansion of an indirect variable does not result in a 13794 literal 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} 13802 If the expansion of @var{expression} is definitely a shell literal, 13803 expand @var{if-literal}. If the expansion of @var{expression} looks 13804 like it might contain shell indirections (such as @code{$var} or 13805 @code{`expr`}), then @var{if-not} is expanded. Sometimes, it is 13806 possible to output optimized code if @var{expression} consists only of 13807 shell variable expansions (such as @code{$@{var@}}), in which case 13808 @var{if-simple-ref} can be provided; but defaulting to @var{if-not} 13809 should always be safe. @code{AS_LITERAL_WORD_IF} only expands 13810 @var{if-literal} if @var{expression} looks like a single shell word, 13811 containing no whitespace; while @code{AS_LITERAL_IF} allows whitespace 13812 in @var{expression}. 13813 13814 In order to reduce the time spent recognizing whether an 13815 @var{expression} qualifies as a literal or a simple indirection, the 13816 implementation is somewhat conservative: @var{expression} must be a 13817 single shell word (possibly after stripping whitespace), consisting only 13818 of bytes that would have the same meaning whether unquoted or enclosed 13819 in double quotes (for example, @samp{a.b} results in @var{if-literal}, 13820 even though it is not a valid shell variable name; while both @samp{'a'} 13821 and @samp{[$]} result in @var{if-not}, because they behave differently 13822 than @samp{"'a'"} and @samp{"[$]"}). This macro can be used in contexts 13823 for recognizing portable file names (such as in the implementation of 13824 @code{AC_LIBSOURCE}), or coupled with some transliterations for forming 13825 valid variable names (such as in the implementation of @code{AS_TR_SH}, 13826 which uses an additional @code{m4_translit} to convert @samp{.} to 13827 @samp{_}). 13828 13829 This example shows how to read the contents of the shell variable 13830 @code{bar}, exercising all three arguments to @code{AS_LITERAL_IF}. It 13831 results in a script that will output the line @samp{hello} three times. 13832 13833 @example 13834 AC_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"\"])]) 13841 foo=bar bar=hello 13842 MY_ACTION([bar]) 13843 MY_ACTION([`echo bar`]) 13844 MY_ACTION([$foo]) 13845 @end example 13846 @end defmac 13847 13848 @defmac AS_VAR_APPEND (@var{var}, @var{text}) 13849 @asindex{VAR_APPEND} 13850 Emit shell code to append the shell expansion of @var{text} to the end 13851 of the current contents of the polymorphic shell variable @var{var}, 13852 taking advantage of shells that provide the @samp{+=} extension for more 13853 efficient scaling. 13854 13855 For situations where the final contents of @var{var} are relatively 13856 short (less than 256 bytes), it is more efficient to use the simpler 13857 code sequence of @code{@var{var}=$@{@var{var}@}@var{text}} (or its 13858 polymorphic equivalent of @code{AS_VAR_COPY([t], [@var{var}])} and 13859 @code{AS_VAR_SET([@var{var}], ["$t"@var{text}])}). But in the case 13860 when the script will be repeatedly appending text into @code{var}, 13861 issues of scaling start to become apparent. A naive implementation 13862 requires 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 13864 an overall quadratic scaling with multiple appends. This macro takes 13865 advantage of shells which provide the extension 13866 @code{@var{var}+=@var{text}}, which can provide amortized constant time 13867 for a single append, for an overall linear scaling with multiple 13868 appends. Note that unlike @code{AS_VAR_SET}, this macro requires that 13869 @var{text} be quoted properly to avoid field splitting and file name 13870 expansion. 13871 @end defmac 13872 13873 @defmac AS_VAR_ARITH (@var{var}, @var{expression}) 13874 @asindex{VAR_ARITH} 13875 Emit shell code to compute the arithmetic expansion of @var{expression}, 13876 assigning the result as the contents of the polymorphic shell variable 13877 @var{var}. The code takes advantage of shells that provide @samp{$(())} 13878 for fewer forks, but uses @command{expr} as a fallback. Therefore, the 13879 syntax for a valid @var{expression} is rather limited: all operators 13880 must occur as separate shell arguments and with proper quoting, there is 13881 no portable equality operator, all variables containing numeric values 13882 must be expanded prior to the computation, all numeric values must be 13883 provided in decimal without leading zeroes, and the first shell argument 13884 should not be a negative number. In the following example, this snippet 13885 will print @samp{(2+3)*4 == 20}. 13886 13887 @example 13888 bar=3 13889 AS_VAR_ARITH([foo], [\( 2 + $bar \) \* 4]) 13890 echo "(2+$bar)*4 == $foo" 13891 @end example 13892 @end defmac 13893 13894 @defmac AS_VAR_COPY (@var{dest}, @var{source}) 13895 @asindex{VAR_COPY} 13896 Emit shell code to assign the contents of the polymorphic shell variable 13897 @var{source} to the polymorphic shell variable @var{dest}. For example, 13898 executing this M4sh snippet will output @samp{bar hi}: 13899 13900 @example 13901 foo=bar bar=hi 13902 AS_VAR_COPY([a], [foo]) 13903 AS_VAR_COPY([b], [$foo]) 13904 echo "$a $b" 13905 @end example 13906 13907 When it is necessary to access the contents of an indirect variable 13908 inside a shell double-quoted context, the recommended idiom is to first 13909 copy the contents into a temporary literal shell variable. 13910 13911 @smallexample 13912 for header in stdint_h inttypes_h ; do 13913 AS_VAR_COPY([var], [ac_cv_header_$header]) 13914 echo "$header detected: $var" 13915 done 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} 13925 Output a shell conditional statement. If the contents of the 13926 polymorphic shell variable @var{var} match the string @var{word}, 13927 execute @var{if-equal}; otherwise execute @var{if-not-equal}. @var{word} 13928 must be a single shell word (typically a quoted string). Avoids 13929 shell bugs if an interrupt signal arrives while a command substitution 13930 in @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 13939 A common M4sh idiom involves composing shell variable names from an m4 13940 argument (for example, writing a macro that uses a cache variable). 13941 @var{value} can be an arbitrary string, which will be transliterated 13942 into a valid shell name by @code{AS_TR_SH}. In order to access the 13943 composed variable name based on @var{value}, it is easier to declare a 13944 temporary m4 macro @var{m4-name} with @code{AS_VAR_PUSHDEF}, then use 13945 that macro as the argument to subsequent @code{AS_VAR} macros as a 13946 polymorphic variable name, and finally free the temporary macro with 13947 @code{AS_VAR_POPDEF}. These macros are often followed with @code{dnl}, 13948 to avoid excess newlines in the output. 13949 13950 Here is an involved example, that shows the power of writing macros that 13951 can handle composed shell variable names: 13952 13953 @example 13954 m4_define([MY_CHECK_HEADER], 13955 [AS_VAR_PUSHDEF([my_Header], [ac_cv_header_$1])dnl 13956 AS_VAR_IF([my_Header], [yes], [echo "header $1 detected"])dnl 13957 AS_VAR_POPDEF([my_Header])dnl 13958 ]) 13959 MY_CHECK_HEADER([stdint.h]) 13960 for header in inttypes.h stdlib.h ; do 13961 MY_CHECK_HEADER([$header]) 13962 done 13963 @end example 13964 13965 @noindent 13966 In the above example, @code{MY_CHECK_HEADER} can operate on polymorphic 13967 variable names. In the first invocation, the m4 argument is 13968 @code{stdint.h}, which transliterates into a literal @code{stdint_h}. 13969 As a result, the temporary macro @code{my_Header} expands to the literal 13970 shell name @samp{ac_cv_header_stdint_h}. In the second invocation, the 13971 m4 argument to @code{MY_CHECK_HEADER} is @code{$header}, and the 13972 temporary 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} 13975 contains @samp{ac_cv_header_inttypes_h}. If this script is then run on a 13976 platform where all three headers have been previously detected, the 13977 output of the script will include: 13978 13979 @smallexample 13980 header stdint.h detected 13981 header inttypes.h detected 13982 header stdlib.h detected 13983 @end smallexample 13984 @end defmac 13985 13986 @defmac AS_VAR_SET (@var{var}, @ovar{value}) 13987 @asindex{VAR_SET} 13988 Emit 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 13990 subject to field splitting or file name expansion, so if command 13991 substitution is used, it may be done with @samp{`""`} rather than using 13992 an intermediate variable (@pxref{Shell Substitutions}). However, 13993 @var{value} does undergo rescanning for additional macro names; behavior 13994 is 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} 13999 Emit a shell conditional statement, which executes @var{if-set} if the 14000 polymorphic 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} 14006 Emit a shell statement that results in a successful exit status only if 14007 the 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} 14015 Set up the shell to be more compatible with the Bourne shell as 14016 standardized by Posix, if possible. This may involve setting 14017 environment variables, or setting options, or similar 14018 implementation-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 14026 Initialize the M4sh environment. This macro calls @code{m4_init}, then 14027 outputs the @code{#! /bin/sh} line, a notice about where the output was 14028 generated from, and code to sanitize the environment for the rest of the 14029 script. Among other initializations, this sets @env{SHELL} to the shell 14030 chosen to run the script (@pxref{CONFIG_SHELL}), and @env{LC_ALL} to 14031 ensure the C locale. Finally, it changes the current diversion to 14032 @code{BODY}. @code{AS_INIT} is called automatically by @code{AC_INIT} 14033 and @code{AT_INIT}, so shell code in @file{configure}, 14034 @file{config.status}, and @file{testsuite} all benefit from a sanitized 14035 shell environment. 14036 @end defmac 14037 14038 @defmac AS_INIT_GENERATED (@var{file}, @ovar{comment}) 14039 @asindex{INIT_GENERATED} 14040 Emit shell code to start the creation of a subsidiary shell script in 14041 @var{file}, including changing @var{file} to be executable. This macro 14042 populates the child script with information learned from the parent 14043 (thus, the emitted code is equivalent in effect, but more efficient, 14044 than 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 14046 beginning of the child, prior to the shell initialization code, and is 14047 subject to parameter expansion, command substitution, and backslash 14048 quote removal. The 14049 parent 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 14051 full). If successfully created, the parent script can then proceed to 14052 append additional M4sh constructs into the child script. 14053 14054 Note that the child script starts life without a log file open, so if 14055 the parent script uses logging (@pxref{AS_MESSAGE_LOG_FD}), you 14056 must temporarily disable any attempts to use the log file until after 14057 emitting code to open a log within the child. On the other hand, if the 14058 parent script has @code{AS_MESSAGE_FD} redirected somewhere besides 14059 @samp{1}, then the child script already has code that copies stdout to 14060 that descriptor. Currently, the suggested 14061 idiom for writing a M4sh shell script from within another script is: 14062 14063 @example 14064 AS_INIT_GENERATED([@var{file}], [[# My child script. 14065 ]]) || @{ AS_ECHO(["Failed to create child script"]); AS_EXIT; @} 14066 m4_pushdef([AS_MESSAGE_LOG_FD])dnl 14067 cat >> "@var{file}" <<\__EOF__ 14068 # Code to initialize AS_MESSAGE_LOG_FD 14069 m4_popdef([AS_MESSAGE_LOG_FD])dnl 14070 # Additional code 14071 __EOF__ 14072 @end example 14073 14074 This, however, may change in the future as the M4sh interface is 14075 stabilized further. 14076 14077 Also, be aware that use of @env{LINENO} within the child script may 14078 report line numbers relative to their location in the parent script, 14079 even when using @code{AS_LINENO_PREPARE}, if the parent script was 14080 unable 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 14086 Find a shell that supports the special variable @env{LINENO}, which 14087 contains the number of the currently executing line. This macro is 14088 automatically invoked by @code{AC_INIT} in configure scripts. 14089 @end defmac 14090 14091 @defmac AS_ME_PREPARE 14092 @asindex{ME_PREPARE} 14093 Set up variable @env{as_me} to be the basename of the currently executing 14094 script. This macro is automatically invoked by @code{AC_INIT} in 14095 configure scripts. 14096 @end defmac 14097 14098 @defmac AS_TMPDIR (@var{prefix}, @dvar{dir, $@{TMPDIR:=/tmp@}}) 14099 @asindex{TMPDIR} 14100 @evindex TMPDIR 14101 @ovindex tmp 14102 Create, as safely as possible, a temporary sub-directory within 14103 @var{dir} with a name starting with @var{prefix}. @var{prefix} should 14104 be 2-4 characters, to make it slightly easier to identify the owner of 14105 the directory. If @var{dir} is omitted, then the value of @env{TMPDIR} 14106 will be used (defaulting to @samp{/tmp}). On success, the name of the 14107 newly created directory is stored in the shell variable @code{tmp}. On 14108 error, the script is aborted. 14109 14110 Typically, this macro is coupled with some exit traps to delete the created 14111 directory and its contents on exit or interrupt. However, there is a 14112 slight window between when the directory is created and when the name is 14113 actually known to the shell, so an interrupt at the right moment might 14114 leave the temporary directory behind. Hence it is important to use a 14115 @var{prefix} that makes it easier to determine if a leftover temporary 14116 directory from an interrupted script is safe to delete. 14117 14118 The use of the output variable @samp{$tmp} rather than something in the 14119 @samp{as_} namespace is historical; it has the unfortunate consequence 14120 that reusing this otherwise common name for any other purpose inside 14121 your script has the potential to break any cleanup traps designed to 14122 remove the temporary directory. 14123 @end defmac 14124 14125 @defmac AS_SHELL_SANITIZE 14126 @asindex{SHELL_SANITIZE} 14127 Initialize the shell suitably for @command{configure} scripts. This has 14128 the effect of @code{AS_BOURNE_COMPATIBLE}, and sets some other 14129 environment variables for predictable results from configuration tests. 14130 For 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 14145 The following macros define file descriptors used to output messages 14146 (or input values) from @file{configure} scripts. 14147 For example: 14148 14149 @example 14150 echo "$wombats found" >&AS_MESSAGE_LOG_FD 14151 echo 'Enter desired kangaroo count:' >&AS_MESSAGE_FD 14152 read kangaroos <&AS_ORIGINAL_STDIN_FD` 14153 @end example 14154 14155 @noindent 14156 However doing so is seldom needed, because Autoconf provides higher 14157 level macros as described below. 14158 14159 @defmac AS_MESSAGE_FD 14160 @asindex{MESSAGE_FD} 14161 The file descriptor for @samp{checking for...} messages and results. 14162 By default, @code{AS_INIT} sets this to @samp{1} for standalone M4sh 14163 clients. However, @code{AC_INIT} shuffles things around to another file 14164 descriptor, in order to allow the @option{-q} option of 14165 @command{configure} to choose whether messages should go to the script's 14166 standard output or be discarded. 14167 14168 If you want to display some messages, consider using one of the printing 14169 macros (@pxref{Printing Messages}) instead. Copies of messages output 14170 via 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} 14176 This must either be empty, or expand to a file descriptor for log 14177 messages. By default, @code{AS_INIT} sets this macro to the empty 14178 string for standalone M4sh clients, thus disabling logging. However, 14179 @code{AC_INIT} shuffles things around so that both @command{configure} 14180 and @command{config.status} use @file{config.log} for log messages. 14181 Macros that run tools, like @code{AC_COMPILE_IFELSE} (@pxref{Running the 14182 Compiler}), redirect all output to this descriptor. You may want to do 14183 so if you develop such a low-level macro. 14184 @end defmac 14185 14186 @defmac AS_ORIGINAL_STDIN_FD 14187 @asindex{ORIGINAL_STDIN_FD} 14188 This must expand to a file descriptor for the original standard input. 14189 By default, @code{AS_INIT} sets this macro to @samp{0} for standalone 14190 M4sh clients. However, @code{AC_INIT} shuffles things around for 14191 safety. 14192 14193 When @command{configure} runs, it may accidentally execute an 14194 interactive command that has the same name as the non-interactive meant 14195 to be used or checked. If the standard input was the terminal, such 14196 interactive programs would cause @command{configure} to stop, pending 14197 some user input. Therefore @command{configure} redirects its standard 14198 input from @file{/dev/null} during its initialization. This is not 14199 normally a problem, since @command{configure} normally does not need 14200 user input. 14201 14202 In the extreme case where your @file{configure} script really needs to 14203 obtain some values from the original standard input, you can read them 14204 explicitly 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 14213 When you write a feature test that could be applicable to more than one 14214 software package, the best thing to do is encapsulate it in a new macro. 14215 Here 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} 14231 Autoconf macros are defined using the @code{AC_DEFUN} macro, which is 14232 similar to the M4 builtin @code{m4_define} macro; this creates a macro 14233 named @var{name} and with @var{body} as its expansion. In addition to 14234 defining a macro, @code{AC_DEFUN} adds to it some code that is used to 14235 constrain the order in which macros are called, while avoiding redundant 14236 output (@pxref{Prerequisite Macros}). 14237 @end defmac 14238 14239 An Autoconf macro definition looks like this: 14240 14241 @example 14242 AC_DEFUN(@var{macro-name}, @var{macro-body}) 14243 @end example 14244 14245 You 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, 14247 GNU M4}, for more complete information on writing M4 macros. 14248 14249 Most macros fall in one of two general categories. The first category 14250 includes macros which take arguments, in order to generate output 14251 parameterized by those arguments. Macros in this category are designed 14252 to be directly expanded, often multiple times, and should not be used as 14253 the argument to @code{AC_REQUIRE}. The other category includes macros 14254 which are shorthand for a fixed block of text, and therefore do not take 14255 arguments. For this category of macros, directly expanding the macro 14256 multiple times results in redundant output, so it is more common to use 14257 the macro as the argument to @code{AC_REQUIRE}, or to declare the macro 14258 with @code{AC_DEFUN_ONCE} (@pxref{One-Shot Macros}). 14259 14260 Be 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 14262 been previously defined. 14263 14264 Each macro should have a header comment that gives its prototype, and a 14265 brief description. When arguments have default values, display them in 14266 the prototype. For example: 14267 14268 @example 14269 # AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1]) 14270 # -------------------------------------- 14271 m4_define([AC_MSG_ERROR], 14272 [@{ AS_MESSAGE([error: $1], [2]) 14273 exit m4_default([$2], [1]); @}]) 14274 @end example 14275 14276 Comments about the macro should be left in the header comment. Most 14277 other comments make their way into @file{configure}, so just keep 14278 using @samp{#} to introduce comments. 14279 14280 @cindex @code{dnl} 14281 If you have some special comments about pure M4 code, comments 14282 that make no sense in @file{configure} and in the header comment, then 14283 use the builtin @code{dnl}: it causes M4 to discard the text 14284 through the next newline. 14285 14286 Keep 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 14288 that produce no output, such as @code{AC_REQUIRE}. 14289 14290 Public 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}). 14293 Additionally, if it is ever determined that a macro should be made 14294 obsolete, it is easy to convert from @code{AC_DEFUN} to @code{AU_DEFUN} 14295 in order to have @command{autoupdate} assist the user in choosing a 14296 better alternative, but there is no corresponding way to make 14297 @code{m4_define} issue an upgrade notice (@pxref{AU_DEFUN}). 14298 14299 There 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 14302 block of text with a @code{m4_define} macro that will expand to the same 14303 text. But replacing a block of text with an @code{AC_DEFUN} macro with 14304 the same content does not necessarily give the same results, because it 14305 changes the location where any embedded but unsatisfied 14306 @code{AC_REQUIRE} invocations within the block will be expanded. For an 14307 example of this, see @ref{Expanded Before Required}. 14308 14309 @node Macro Names 14310 @section Macro Names 14311 14312 All of the public Autoconf macros have all-uppercase names in the 14313 namespace @samp{^AC_} to prevent them from accidentally conflicting with 14314 other text; Autoconf also reserves the namespace @samp{^_AC_} for 14315 internal macros. All shell variables that they use for internal 14316 purposes have mostly-lowercase names starting with @samp{ac_}. Autoconf 14317 also uses here-document delimiters in the namespace @samp{^_AC[A-Z]}. During 14318 @command{configure}, files produced by Autoconf make heavy use of the 14319 file system namespace @samp{^conf}. 14320 14321 Since Autoconf is built on top of M4sugar (@pxref{Programming in 14322 M4sugar}) and M4sh (@pxref{Programming in M4sh}), you must also be aware 14323 of those namespaces (@samp{^_?\(m4\|AS\)_}). And since 14324 @file{configure.ac} is also designed to be scanned by Autoheader, 14325 Autoscan, Autoupdate, and Automake, you should be aware of the 14326 @samp{^_?A[HNUM]_} namespaces. In general, you @emph{should not use} 14327 the namespace of a package that does not own the macro or shell code you 14328 are writing. 14329 14330 To ensure that your macros don't conflict with present or future 14331 Autoconf macros, you should prefix your own macro names and any shell 14332 variables they use with some other sequence. Possibilities include your 14333 initials, or an abbreviation for the name of your organization or 14334 software package. Historically, people have not always followed the 14335 rule of using a namespace appropriate for their package, and this has 14336 made it difficult for determining the origin of a macro (and where to 14337 report bugs about that macro), as well as difficult for the true 14338 namespace owner to add new macros without interference from pre-existing 14339 uses of third-party macros. Perhaps the best example of this confusion 14340 is the @code{AM_GNU_GETTEXT} macro, which belongs, not to Automake, but 14341 to Gettext. 14342 14343 Most of the Autoconf macros' names follow a structured naming convention 14344 that indicates the kind of feature check by the name. The macro names 14345 consist of several words, separated by underscores, going from most 14346 general to most specific. The names of their cache variables use the 14347 same convention (@pxref{Cache Variable Names}, for more information on 14348 them). 14349 14350 The first word of the name after the namespace initials (such as 14351 @samp{AC_}) usually tells the category 14352 of the feature being tested. Here are the categories used in Autoconf for 14353 specific test macros, the kind of macro that you are more likely to 14354 write. They are also used for cache variables, in all-lowercase. Use 14355 them where applicable; where they're not, invent your own categories. 14356 14357 @table @code 14358 @item C 14359 C language builtin features. 14360 @item DECL 14361 Declarations of C variables in header files. 14362 @item FUNC 14363 Functions in libraries. 14364 @item GROUP 14365 Posix group owners of files. 14366 @item HEADER 14367 Header files. 14368 @item LIB 14369 C libraries. 14370 @item PROG 14371 The base names of programs. 14372 @item MEMBER 14373 Members of aggregates. 14374 @item SYS 14375 Operating system features. 14376 @item TYPE 14377 C builtin or declared types. 14378 @item VAR 14379 C variables in libraries. 14380 @end table 14381 14382 After the category comes the name of the particular feature being 14383 tested. Any further words in the macro name indicate particular aspects 14384 of the feature. For example, @code{AC_PROG_CC_STDC} checks whether the 14385 C compiler supports ISO Standard C. 14386 14387 An internal macro should have a name that starts with an underscore; 14388 Autoconf internals should therefore start with @samp{_AC_}. 14389 Additionally, a macro that is an internal subroutine of another macro 14390 should have a name that starts with an underscore and the name of that 14391 other macro, followed by one or more words saying what the internal 14392 macro 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 14399 When macros statically diagnose abnormal situations, benign or fatal, it 14400 is possible to make @command{autoconf} detect the problem, and refuse to 14401 create @file{configure} in the case of an error. The macros in this 14402 section are considered obsolescent, and new code should use M4sugar 14403 macros for this purpose, see @ref{Diagnostic Macros}. 14404 14405 On the other hand, it is possible to want to detect errors when 14406 @command{configure} is run, which are dependent on the environment of 14407 the 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} 14412 Report @var{message} as a warning (or as an error if requested by the 14413 user) if warnings of the @var{category} are turned on. This macro is 14414 obsolescent; you are encouraged to use: 14415 @example 14416 m4_warn([@var{category}], [@var{message}]) 14417 @end example 14418 @noindent 14419 instead. @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} 14425 Report @var{message} as a syntax warning. This macro is obsolescent; 14426 you are encouraged to use: 14427 @example 14428 m4_warn([syntax], [@var{message}]) 14429 @end example 14430 @noindent 14431 instead. @xref{m4_warn}, for more details, as well as better 14432 finer-grained categories of warnings (not all problems have to do with 14433 syntax). 14434 @end defmac 14435 14436 @defmac AC_FATAL (@var{message}) 14437 @acindex{FATAL} 14438 Report a severe error @var{message}, and have @command{autoconf} die. 14439 This macro is obsolescent; you are encouraged to use: 14440 @example 14441 m4_fatal([@var{message}]) 14442 @end example 14443 @noindent 14444 instead. @xref{m4_fatal}, for more details. 14445 @end defmac 14446 14447 When 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 14455 Some Autoconf macros depend on other macros having been called first in 14456 order to work correctly. Autoconf provides a way to ensure that certain 14457 macros are called if needed and a way to warn the user if macros are 14458 called 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 14471 A macro that you write might need to use values that have previously 14472 been computed by other macros. For example, @code{AC_DECL_YYTEXT} 14473 examines 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 14477 Rather than forcing the user of the macros to keep track of the 14478 dependencies between them, you can use the @code{AC_REQUIRE} macro to do 14479 it automatically. @code{AC_REQUIRE} can ensure that a macro is only 14480 called if it is needed, and only called once. 14481 14482 @defmac AC_REQUIRE (@var{macro-name}) 14483 @acindex{REQUIRE} 14484 If 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 14486 square brackets. @var{macro-name} must have been defined using 14487 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate 14488 that it has been called. 14489 14490 @code{AC_REQUIRE} must be used inside a macro defined by @code{AC_DEFUN}; it 14491 must not be called from the top level. Also, it does not make sense to 14492 require a macro that takes parameters. 14493 @end defmac 14494 14495 @code{AC_REQUIRE} is often misunderstood. It really implements 14496 dependencies between macros in the sense that if one macro depends upon 14497 another, the latter is expanded @emph{before} the body of the 14498 former. To be more precise, the required macro is expanded before 14499 the outermost defined macro in the current expansion stack. 14500 In 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 14505 AC_DEFUN([TRAVOLTA], 14506 [test "$body_temperature_in_celsius" -gt "38" && 14507 dance_floor=occupied]) 14508 AC_DEFUN([NEWTON_JOHN], 14509 [test "x$hair_style" = xcurly && 14510 dance_floor=occupied]) 14511 @end group 14512 14513 @group 14514 AC_DEFUN([RESERVE_DANCE_FLOOR], 14515 [if date | grep '^Sat.*pm' >/dev/null 2>&1; then 14516 AC_REQUIRE([TRAVOLTA]) 14517 AC_REQUIRE([NEWTON_JOHN]) 14518 fi]) 14519 @end group 14520 @end example 14521 14522 @noindent 14523 with this @file{configure.ac} 14524 14525 @example 14526 AC_INIT([Dance Manager], [1.0], [bug-dance@@example.org]) 14527 RESERVE_DANCE_FLOOR 14528 if test "x$dance_floor" = xoccupied; then 14529 AC_MSG_ERROR([cannot pick up here, let's move]) 14530 fi 14531 @end example 14532 14533 @noindent 14534 does not leave you with a better chance to meet a kindred soul at 14535 other times than Saturday night since it expands into: 14536 14537 @example 14538 @group 14539 test "$body_temperature_in_Celsius" -gt "38" && 14540 dance_floor=occupied 14541 test "x$hair_style" = xcurly && 14542 dance_floor=occupied 14543 fi 14544 if date | grep '^Sat.*pm' >/dev/null 2>&1; then 14545 14546 14547 fi 14548 @end group 14549 @end example 14550 14551 This behavior was chosen on purpose: (i) it prevents messages in 14552 required 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 14557 if @dots{}; then 14558 AC_REQUIRE([SOME_CHECK]) 14559 fi 14560 @dots{} 14561 SOME_CHECK 14562 @end group 14563 @end example 14564 14565 However, this implementation can lead to another class of problems. 14566 Consider the case where an outer macro first expands, then indirectly 14567 requires, an inner macro: 14568 14569 @example 14570 AC_DEFUN([TESTA], [[echo in A 14571 if test -n "$SEEN_A" ; then echo duplicate ; fi 14572 SEEN_A=:]]) 14573 AC_DEFUN([TESTB], [AC_REQUIRE([TESTA])[echo in B 14574 if test -z "$SEEN_A" ; then echo bug ; fi]]) 14575 AC_DEFUN([TESTC], [AC_REQUIRE([TESTB])[echo in C]]) 14576 AC_DEFUN([OUTER], [[echo in OUTER] 14577 TESTA 14578 TESTC]) 14579 OUTER 14580 @end example 14581 14582 @noindent 14583 Prior to Autoconf 2.64, the implementation of @code{AC_REQUIRE} 14584 recognized that @code{TESTB} needed to be hoisted prior to the expansion 14585 of @code{OUTER}, but because @code{TESTA} had already been directly 14586 expanded, it failed to hoist @code{TESTA}. Therefore, the expansion of 14587 @code{TESTB} occurs prior to its prerequisites, leading to the following 14588 output: 14589 14590 @example 14591 in B 14592 bug 14593 in OUTER 14594 in A 14595 in C 14596 @end example 14597 14598 @noindent 14599 Newer Autoconf is smart enough to recognize this situation, and hoists 14600 @code{TESTA} even though it has already been expanded, but issues a 14601 syntax warning in the process. This is because the hoisted expansion of 14602 @code{TESTA} defeats the purpose of using @code{AC_REQUIRE} to avoid 14603 redundant code, and causes its own set of problems if the hoisted macro 14604 is not idempotent: 14605 14606 @example 14607 in A 14608 in B 14609 in OUTER 14610 in A 14611 duplicate 14612 in C 14613 @end example 14614 14615 The bug is not in Autoconf, but in the macro definitions. If you ever 14616 pass a particular macro name to @code{AC_REQUIRE}, then you are implying 14617 that the macro only needs to be expanded once. But to enforce this, 14618 either the macro must be declared with @code{AC_DEFUN_ONCE} (although 14619 this only helps in Autoconf 2.64 or newer), or all 14620 uses of that macro should be through @code{AC_REQUIRE}; directly 14621 expanding the macro defeats the point of using @code{AC_REQUIRE} to 14622 eliminate redundant expansion. In the example, this rule of thumb was 14623 violated because @code{TESTB} requires @code{TESTA} while @code{OUTER} 14624 directly expands it. One way of fixing the bug is to factor 14625 @code{TESTA} into two macros, the portion designed for direct and 14626 repeated use (here, named @code{TESTA}), and the portion designed for 14627 one-shot output and used only inside @code{AC_REQUIRE} (here, named 14628 @code{TESTA_PREREQ}). Then, by fixing all clients to use the correct 14629 calling convention according to their needs: 14630 14631 @example 14632 AC_DEFUN([TESTA], [AC_REQUIRE([TESTA_PREREQ])[echo in A]]) 14633 AC_DEFUN([TESTA_PREREQ], [[echo in A_PREREQ 14634 if test -n "$SEEN_A" ; then echo duplicate ; fi 14635 SEEN_A=:]]) 14636 AC_DEFUN([TESTB], [AC_REQUIRE([TESTA_PREREQ])[echo in B 14637 if test -z "$SEEN_A" ; then echo bug ; fi]]) 14638 AC_DEFUN([TESTC], [AC_REQUIRE([TESTB])[echo in C]]) 14639 AC_DEFUN([OUTER], [[echo in OUTER] 14640 TESTA 14641 TESTC]) 14642 OUTER 14643 @end example 14644 14645 @noindent 14646 the resulting output will then obey all dependency rules and avoid any 14647 syntax warnings, whether the script is built with old or new Autoconf 14648 versions: 14649 14650 @example 14651 in A_PREREQ 14652 in B 14653 in OUTER 14654 in A 14655 in C 14656 @end example 14657 14658 The helper macros @code{AS_IF} and @code{AS_CASE} may be used to 14659 enforce expansion of required macros outside of shell conditional 14660 constructs. You are furthermore encouraged, although not required, to 14661 put all @code{AC_REQUIRE} calls 14662 at the beginning of a macro. You can use @code{dnl} to avoid the empty 14663 lines they leave. 14664 14665 @node Suggested Ordering 14666 @subsection Suggested Ordering 14667 @cindex Macros, ordering 14668 @cindex Ordering macros 14669 14670 Some macros should be run before another macro if both are called, but 14671 neither @emph{requires} that the other be called. For example, a macro 14672 that changes the behavior of the C compiler should be called before any 14673 macros that run the C compiler. Many of these dependencies are noted in 14674 the documentation. 14675 14676 Autoconf provides the @code{AC_BEFORE} macro to warn users when macros 14677 with 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 14682 For example, @code{AC_PROG_CPP} checks whether the C compiler 14683 can run the C preprocessor when given the @option{-E} option. It should 14684 therefore be called after any macros that change which C compiler is 14685 being used, such as @code{AC_PROG_CC}. So @code{AC_PROG_CC} contains: 14686 14687 @example 14688 AC_BEFORE([$0], [AC_PROG_CPP])dnl 14689 @end example 14690 14691 @noindent 14692 This warns the user if a call to @code{AC_PROG_CPP} has already occurred 14693 when @code{AC_PROG_CC} is called. 14694 14695 @defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name}) 14696 @acindex{BEFORE} 14697 Make M4 print a warning message to the standard error output if 14698 @var{called-macro-name} has already been called. @var{this-macro-name} 14699 should be the name of the macro that is calling @code{AC_BEFORE}. The 14700 macro @var{called-macro-name} must have been defined using 14701 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate 14702 that 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 14710 Some macros should be called only once, either because calling them 14711 multiple time is unsafe, or because it is bad style. For instance 14712 Autoconf ensures that @code{AC_CANONICAL_BUILD} and cousins 14713 (@pxref{Canonicalizing}) are evaluated only once, because it makes no 14714 sense to run these expensive checks more than once. Such one-shot 14715 macros can be defined using @code{AC_DEFUN_ONCE}. 14716 14717 @defmac AC_DEFUN_ONCE (@var{macro-name}, @var{macro-body}) 14718 @acindex{DEFUN_ONCE} 14719 Declare macro @var{macro-name} like @code{AC_DEFUN} would (@pxref{Macro 14720 Definitions}), but add additional logic that guarantees that only the 14721 first use of the macro (whether by direct expansion or 14722 @code{AC_REQUIRE}) causes an expansion of @var{macro-body}; the 14723 expansion will occur before the start of any enclosing macro defined by 14724 @code{AC_DEFUN}. Subsequent expansions are silently ignored. 14725 Generally, it does not make sense for @var{macro-body} to use parameters 14726 such as @code{$1}. 14727 @end defmac 14728 14729 Prior to Autoconf 2.64, a macro defined by @code{AC_DEFUN_ONCE} would 14730 emit a warning if it was directly expanded a second time, so for 14731 portability, it is better to use @code{AC_REQUIRE} than direct 14732 invocation 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 14740 Configuration and portability technology has evolved over the years. 14741 Often better ways of solving a particular problem are developed, or 14742 ad-hoc approaches are systematized. This process has occurred in many 14743 parts of Autoconf. One result is that some of the macros are now 14744 considered @dfn{obsolete}; they still work, but are no longer considered 14745 the best thing to do, hence they should be replaced with more modern 14746 macros. Ideally, @command{autoupdate} should replace the old macro calls 14747 with their modern implementation. 14748 14749 Autoconf 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} 14754 Define @var{old-macro} as @var{implementation}. The only difference 14755 with @code{AC_DEFUN} is that the user is warned that 14756 @var{old-macro} is now obsolete. 14757 14758 If she then uses @command{autoupdate}, the call to @var{old-macro} is 14759 replaced by the modern @var{implementation}. @var{message} should 14760 include information on what to do after running @command{autoupdate}; 14761 @command{autoupdate} prints it as a warning, and includes it 14762 in the updated @file{configure.ac} file. 14763 14764 The 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 14766 as usual. However, when @command{autoupdate} is run, only M4 and M4sugar 14767 macros are expanded here, while all other macros are disabled and 14768 appear literally in the updated @file{configure.ac}. 14769 @end defmac 14770 14771 @defmac AU_ALIAS (@var{old-name}, @var{new-name}) 14772 @auindex{ALIAS} 14773 Used if the @var{old-name} is to be replaced by a call to @var{new-macro} 14774 with 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 14781 The Autoconf macros follow a strict coding style. You are encouraged to 14782 follow this style, especially if you intend to distribute your macro, 14783 either by contributing it to Autoconf itself or the 14784 @uref{http://@/www.gnu.org/@/software/@/autoconf-archive/, Autoconf Macro 14785 Archive}, or by other means. 14786 14787 The first requirement is to pay great attention to the quotation. For 14788 more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}. 14789 14790 Do not try to invent new interfaces. It is likely that there is a macro 14791 in Autoconf that resembles the macro you are defining: try to stick to 14792 this existing interface (order of arguments, default values, etc.). We 14793 @emph{are} conscious that some of these interfaces are not perfect; 14794 nevertheless, when harmless, homogeneity should be preferred over 14795 creativity. 14796 14797 Be careful about clashes both between M4 symbols and between shell 14798 variables. 14799 14800 If you stick to the suggested M4 naming scheme (@pxref{Macro Names}), 14801 you are unlikely to generate conflicts. Nevertheless, when you need to 14802 set a special value, @emph{avoid using a regular macro name}; rather, 14803 use 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 14805 by setting @code{AC_SUBST_@var{symbol}}, which is a regular macro name. 14806 But since there is a macro named @code{AC_SUBST_FILE}, it was just 14807 impossible to @samp{AC_SUBST(FILE)}! In this case, 14808 @code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should 14809 have been used (yes, with the parentheses). 14810 @c or better yet, high-level macros such as @code{m4_expand_once} 14811 14812 No Autoconf macro should ever enter the user-variable name space; i.e., 14813 except for the variables that are the actual result of running the 14814 macro, all shell variables should start with @code{ac_}. In 14815 addition, small macros or any macro that is likely to be embedded in 14816 other macros should be careful not to use obvious names. 14817 14818 @cindex @code{dnl} 14819 Do not use @code{dnl} to introduce comments: most of the comments you 14820 are likely to write are either header comments which are not output 14821 anyway, or comments that should make their way into @file{configure}. 14822 There are exceptional cases where you do want to comment special M4 14823 constructs, in which case @code{dnl} is right, but keep in mind that it 14824 is unlikely. 14825 14826 M4 ignores the leading blanks and newlines before each argument. 14827 Use this feature to 14828 indent in such a way that arguments are (more or less) aligned with the 14829 opening parenthesis of the macro being called. For instance, instead of 14830 14831 @example 14832 AC_CACHE_CHECK(for EMX OS/2 environment, 14833 ac_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 14839 write 14840 14841 @example 14842 AC_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 14849 or even 14850 14851 @example 14852 AC_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 14860 When using @code{AC_RUN_IFELSE} or any macro that cannot work when 14861 cross-compiling, provide a pessimistic value (typically @samp{no}). 14862 14863 Feel free to use various tricks to prevent auxiliary tools, such as 14864 syntax-highlighting editors, from behaving improperly. For instance, 14865 instead of: 14866 14867 @example 14868 m4_bpatsubst([$1], [$"]) 14869 @end example 14870 14871 @noindent 14872 use 14873 14874 @example 14875 m4_bpatsubst([$1], [$""]) 14876 @end example 14877 14878 @noindent 14879 so that Emacsen do not open an endless ``string'' at the first quote. 14880 For the same reasons, avoid: 14881 14882 @example 14883 test $[#] != 0 14884 @end example 14885 14886 @noindent 14887 and use: 14888 14889 @example 14890 test $[@@%:@@] != 0 14891 @end example 14892 14893 @noindent 14894 Otherwise, the closing bracket would be hidden inside a @samp{#}-comment, 14895 breaking the bracket-matching highlighting from Emacsen. Note the 14896 preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]}, etc. Do 14897 not escape when it is unnecessary. Common examples of useless quotation 14898 are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}), 14899 etc. If you add portability issues to the picture, you'll prefer 14900 @samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something 14901 better than hacking Autoconf @code{:-)}. 14902 14903 When using @command{sed}, don't use @option{-e} except for indenting 14904 purposes. With the @code{s} and @code{y} commands, the preferred 14905 separator is @samp{/} unless @samp{/} itself might appear in the pattern 14906 or replacement, in which case you should use @samp{|}, or optionally 14907 @samp{,} if you know the pattern and replacement cannot contain a file 14908 name. If none of these characters will do, choose a printable character 14909 that cannot appear in the pattern or replacement. Characters from the 14910 set @samp{"#$&'()*;<=>?`|~} are good choices if the pattern or 14911 replacement might contain a file name, since they have special meaning 14912 to 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 14915 macro doesn't use @code{AC_REQUIRE}, is expected to never be the object 14916 of an @code{AC_REQUIRE} directive, and macros required by other macros 14917 inside arguments do not need to be expanded before this macro, then 14918 use @code{m4_define}. In case of doubt, use @code{AC_DEFUN}. 14919 Also 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}). 14922 All the @code{AC_REQUIRE} statements should be at the beginning of the 14923 macro, and each statement should be followed by @code{dnl}. 14924 14925 You should not rely on the number of arguments: instead of checking 14926 whether an argument is missing, test that it is not empty. It provides 14927 both a simpler and a more predictable interface to the user, and saves 14928 room for further arguments. 14929 14930 Unless the macro is short, try to leave the closing @samp{])} at the 14931 beginning of a line, followed by a comment that repeats the name of the 14932 macro being defined. This introduces an additional newline in 14933 @command{configure}; normally, that is not a problem, but if you want to 14934 remove it you can use @samp{[]dnl} on the last line. You can similarly 14935 use @samp{[]dnl} after a macro call to remove its newline. @samp{[]dnl} 14936 is recommended instead of @samp{dnl} to ensure that M4 does not 14937 interpret the @samp{dnl} as being attached to the preceding text or 14938 macro output. For example, instead of: 14939 14940 @example 14941 AC_DEFUN([AC_PATH_X], 14942 [AC_MSG_CHECKING([for X]) 14943 AC_REQUIRE_CPP() 14944 @r{# @dots{}omitted@dots{}} 14945 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes]) 14946 fi]) 14947 @end example 14948 14949 @noindent 14950 you would write: 14951 14952 @example 14953 AC_DEFUN([AC_PATH_X], 14954 [AC_REQUIRE_CPP()[]dnl 14955 AC_MSG_CHECKING([for X]) 14956 @r{# @dots{}omitted@dots{}} 14957 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes]) 14958 fi[]dnl 14959 ])# AC_PATH_X 14960 @end example 14961 14962 If the macro is long, try to split it into logical chunks. Typically, 14963 macros that check for a bug in a function and prepare its 14964 @code{AC_LIBOBJ} replacement should have an auxiliary macro to perform 14965 this setup. Do not hesitate to introduce auxiliary macros to factor 14966 your code. 14967 14968 In order to highlight the recommended coding style, here is a macro 14969 written the old way: 14970 14971 @example 14972 dnl Check for EMX on OS/2. 14973 dnl _AC_EMXOS2 14974 AC_DEFUN(_AC_EMXOS2, 14975 [AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2, 14976 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)], 14977 ac_cv_emxos2=yes, ac_cv_emxos2=no)]) 14978 test "x$ac_cv_emxos2" = xyes && EMXOS2=yes]) 14979 @end example 14980 14981 @noindent 14982 and the new way: 14983 14984 @example 14985 # _AC_EMXOS2 14986 # ---------- 14987 # Check for EMX on OS/2. 14988 m4_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])]) 14993 test "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 15006 When writing your own checks, there are some shell-script programming 15007 techniques you should avoid in order to make your code portable. The 15008 Bourne shell and upward-compatible shells like the Korn shell and Bash 15009 have evolved over the years, and many features added to the original 15010 System7 shell are now supported on all interesting porting targets. 15011 However, the following discussion between Russ Allbery and Robert Lipe 15012 is worth reading: 15013 15014 @noindent 15015 Russ Allbery: 15016 15017 @quotation 15018 The GNU assumption that @command{/bin/sh} is the one and only shell 15019 leads to a permanent deadlock. Vendors don't want to break users' 15020 existing shell scripts, and there are some corner cases in the Bourne 15021 shell that are not completely compatible with a Posix shell. Thus, 15022 vendors who have taken this route will @emph{never} (OK@dots{}``never say 15023 never'') replace the Bourne shell (as @command{/bin/sh}) with a 15024 Posix shell. 15025 @end quotation 15026 15027 @noindent 15028 Robert Lipe: 15029 15030 @quotation 15031 This is exactly the problem. While most (at least most System V's) do 15032 have a Bourne shell that accepts shell functions most vendor 15033 @command{/bin/sh} programs are not the Posix shell. 15034 15035 So while most modern systems do have a shell @emph{somewhere} that meets the 15036 Posix standard, the challenge is to find it. 15037 @end quotation 15038 15039 For this reason, part of the job of M4sh (@pxref{Programming in M4sh}) 15040 is to find such a shell. But to prevent trouble, if you're not using 15041 M4sh you should not take advantage of features that were added after Unix 15042 version 7, circa 1977 (@pxref{Systemology}); you should not use aliases, 15043 negated character classes, or even @command{unset}. @code{#} comments, 15044 while not in Unix version 7, were retrofitted in the original Bourne 15045 shell and can be assumed to be part of the least common denominator. 15046 15047 On the other hand, if you're using M4sh you can assume that the shell 15048 has the features that were added in SVR2 (circa 1984), including shell 15049 functions, 15050 @command{return}, @command{unset}, and I/O redirection for builtins. For 15051 more information, refer to @uref{http://@/www.in-ulm.de/@/~mascheck/@/bourne/}. 15052 However, some pitfalls have to be avoided for portable use of these 15053 constructs; these will be documented in the rest of this chapter. 15054 See in particular @ref{Shell Functions} and @ref{Limitations of 15055 Builtins, , Limitations of Shell Builtins}. 15056 15057 Some ancient systems have quite 15058 small limits on the length of the @samp{#!} line; for instance, 32 15059 bytes (not including the newline) on SunOS 4. 15060 However, these ancient systems are no longer of practical concern. 15061 15062 The set of external programs you should run in a @command{configure} script 15063 is fairly small. @xref{Utilities in Makefiles, , Utilities in 15064 Makefiles, standards, The GNU Coding Standards}, for the list. This 15065 restriction allows users to start out with a fairly small set of 15066 programs and build the rest, avoiding too many interdependencies between 15067 packages. 15068 15069 Some of these external utilities have a portable subset of features; see 15070 @ref{Limitations of Usual Tools}. 15071 15072 There are other sources of documentation about shells. The 15073 specification for the Posix 15074 @uref{http://@/www.opengroup.org/@/susv3/@/utilities/@/xcu_chap02@/.html, Shell 15075 Command Language}, though more generous than the restrictive shell 15076 subset 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 15101 There are several families of shells, most prominently the Bourne family 15102 and the C shell family which are deeply incompatible. If you want to 15103 write portable shell scripts, avoid members of the C shell family. The 15104 @uref{http://@/www.faqs.org/@/faqs/@/unix-faq/@/shell/@/shell-differences/, the 15105 Shell difference FAQ} includes a small history of Posix shells, and a 15106 comparison between several of them. 15107 15108 Below we describe some of the members of the Bourne shell family. 15109 15110 @table @asis 15111 @item Ash 15112 @cindex Ash 15113 Ash is often used on GNU/Linux and BSD 15114 systems as a light-weight Bourne-compatible shell. Ash 0.2 has some 15115 bugs that are fixed in the 0.3.x series, but portable shell scripts 15116 should work around them, since version 0.2 is still shipped with many 15117 GNU/Linux distributions. 15118 15119 To be compatible with Ash 0.2: 15120 15121 @itemize @minus 15122 @item 15123 don't use @samp{$?} after expanding empty or unset variables, 15124 or at the start of an @command{eval}: 15125 15126 @example 15127 foo= 15128 false 15129 $foo 15130 echo "Do not use it: $?" 15131 false 15132 eval 'echo "Do not use it: $?"' 15133 @end example 15134 15135 @item 15136 don't use command substitution within variable expansion: 15137 15138 @example 15139 cat $@{FOO=`bar`@} 15140 @end example 15141 15142 @item 15143 beware that single builtin substitutions are not performed by a 15144 subshell, hence their effect applies to the current shell! @xref{Shell 15145 Substitutions}, item ``Command Substitution''. 15146 @end itemize 15147 15148 @item Bash 15149 @cindex Bash 15150 To detect whether you are running Bash, test whether 15151 @code{BASH_VERSION} is set. To require 15152 Posix compatibility, run @samp{set -o posix}. @xref{Bash POSIX 15153 Mode, , Bash Posix Mode, bash, The GNU Bash Reference 15154 Manual}, for details. 15155 15156 @item Bash 2.05 and later 15157 @cindex Bash 2.05 and later 15158 Versions 2.05 and later of Bash use a different format for the 15159 output of the @command{set} builtin, designed to make evaluating its 15160 output easier. However, this output is not compatible with earlier 15161 versions of Bash (or with many other shells, probably). So if 15162 you use Bash 2.05 or higher to execute @command{configure}, 15163 you'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} 15171 The Korn shell is compatible with the Bourne family and it mostly 15172 conforms to Posix. It has two major variants commonly 15173 called @samp{ksh88} and @samp{ksh93}, named after the years of initial 15174 release. It is usually called @command{ksh}, but is called @command{sh} 15175 on some hosts if you set your path appropriately. 15176 15177 Solaris systems have three variants: 15178 @prindex @command{/usr/bin/ksh} on Solaris 15179 @command{/usr/bin/ksh} is @samp{ksh88}; it is 15180 standard 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}. 15186 Variants that are not standard may be parts of optional 15187 packages. There is no extra charge for these packages, but they are 15188 not part of a minimal OS install and therefore some installations may 15189 not have it. 15190 15191 Starting with Tru64 Version 4.0, the Korn shell @command{/usr/bin/ksh} 15192 is also available as @command{/usr/bin/posix/sh}. If the environment 15193 variable @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of 15194 the standard shell conform to Posix. 15195 15196 @item Pdksh 15197 @prindex @samp{pdksh} 15198 A public-domain clone of the Korn shell called @command{pdksh} is widely 15199 available: it has most of the @samp{ksh88} features along with a few of 15200 its own. It usually sets @code{KSH_VERSION}, except if invoked as 15201 @command{/bin/sh} on OpenBSD, and similarly to Bash you can require 15202 Posix compatibility by running @samp{set -o posix}. Unfortunately, with 15203 @command{pdksh} 5.2.14 (the latest stable version as of January 2007) 15204 Posix mode is buggy and causes @command{pdksh} to depart from Posix in 15205 at least one respect, see @ref{Shell Substitutions}. 15206 15207 @item Zsh 15208 @cindex Zsh 15209 To detect whether you are running @command{zsh}, test whether 15210 @code{ZSH_VERSION} is set. By default @command{zsh} is @emph{not} 15211 compatible with the Bourne shell: you must execute @samp{emulate sh}, 15212 and for @command{zsh} versions before 3.1.6-dev-18 you must also 15213 set @code{NULLCMD} to @samp{:}. @xref{Compatibility, , Compatibility, 15214 zsh, The Z Shell Manual}, for details. 15215 15216 The default Mac OS X @command{sh} was originally Zsh; it was changed to 15217 Bash 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 15225 The Korn shell (up to at least version M-12/28/93d) has a bug when 15226 invoked on a file whose name does not contain a slash. It first 15227 searches for the file's name in @env{PATH}, and if found it executes 15228 that rather than the original file. For example, assuming there is a 15229 binary executable @file{/usr/bin/script} in your @env{PATH}, the last 15230 command 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} 15238 ksh: script: cannot execute 15239 @end example 15240 15241 Bash 2.03 has a bug when invoked with the @option{-c} option: if the 15242 option-argument ends in backslash-newline, Bash incorrectly reports a 15243 syntax error. The problem does not occur if a character follows the 15244 backslash: 15245 15246 @example 15247 $ @kbd{$ bash -c 'echo foo \} 15248 > @kbd{'} 15249 bash: -c: line 2: syntax error: unexpected end of file 15250 $ @kbd{bash -c 'echo foo \} 15251 > @kbd{ '} 15252 foo 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 15263 Don't rely on @samp{\} being preserved just because it has no special 15264 meaning together with the next symbol. In the native @command{sh} 15265 on OpenBSD 2.7 @samp{\"} expands to @samp{"} in here-documents with 15266 unquoted delimiter. As a general rule, if @samp{\\} expands to @samp{\} 15267 use @samp{\\} to get @samp{\}. 15268 15269 With 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 15281 and with Bash: 15282 15283 @example 15284 @group 15285 bash-2.04$ @kbd{cat <<EOF 15286 > \" \\ 15287 > EOF} 15288 \" \ 15289 @end group 15290 @end example 15291 15292 Using command substitutions in a here-document that is fed to a shell 15293 function 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 $?} 15302 1 15303 @end example 15304 15305 Some shells mishandle large here-documents: for example, 15306 Solaris 10 @command{dtksh} and the UnixWare 7.1.1 Posix shell, which are 15307 derived from Korn shell version M-12/28/93d, mishandle braced variable 15308 expansion that crosses a 1024- or 4096-byte buffer boundary 15309 within a here-document. Only the part of the variable name after the boundary 15310 is used. For example, @code{$@{variable@}} could be replaced by the expansion 15311 of @code{$@{ble@}}. If the end of the variable name is aligned with the block 15312 boundary, the shell reports an error, as if you used @code{$@{@}}. 15313 Instead of @code{$@{variable-default@}}, the shell may expand 15314 @code{$@{riable-default@}}, or even @code{$@{fault@}}. This bug can often 15315 be worked around by omitting the braces: @code{$variable}. The bug was 15316 fixed in 15317 @samp{ksh93g} (1998-04-30) but as of 2006 many operating systems were 15318 still shipping older versions with the bug. 15319 15320 Empty 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 15322 newline, whereas other shells create an empty file: 15323 15324 @example 15325 cat >file <<EOF 15326 EOF 15327 @end example 15328 15329 Many shells (including the Bourne shell) implement here-documents 15330 inefficiently. In particular, some shells can be extremely inefficient when 15331 a single statement contains many here-documents. For instance if your 15332 @file{configure.ac} includes something like: 15333 15334 @example 15335 @group 15336 if <cross_compiling>; then 15337 assume this and that 15338 else 15339 check this 15340 check that 15341 check something else 15342 @dots{} 15343 on and on forever 15344 @dots{} 15345 fi 15346 @end group 15347 @end example 15348 15349 A shell parses the whole @code{if}/@code{fi} construct, creating 15350 temporary files for each here-document in it. Some shells create links 15351 for such here-documents on every @code{fork}, so that the clean-up code 15352 they had installed correctly removes them. It is creating the links 15353 that can take the shell forever. 15354 15355 Moving the tests out of the @code{if}/@code{fi}, or creating multiple 15356 @code{if}/@code{fi} constructs, would improve the performance 15357 significantly. Anyway, this kind of construct is not exactly the 15358 typical use of Autoconf. In fact, it's even not recommended, because M4 15359 macros can't look into shell conditionals, so we may fail to expand a 15360 macro when it was expanded before in a conditional path, and the 15361 condition turned out to be false at runtime, and we end up not 15362 executing the macro at all. 15363 15364 Be careful with the use of @samp{<<-} to unindent here-documents. The 15365 behavior is only portable for stripping leading @key{TAB}s, and things 15366 can silently break if an overzealous editor converts to using leading 15367 spaces (not all shells are nice enough to warn about unterminated 15368 here-documents). 15369 15370 @example 15371 $ @kbd{printf 'cat <<-x\n\t1\n\t 2\n\tx\n' | bash && echo done} 15372 1 15373 2 15374 done 15375 $ @kbd{printf 'cat <<-x\n 1\n 2\n x\n' | bash-3.2 && echo done} 15376 1 15377 2 15378 x 15379 done 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 15388 Most shells, if not all (including Bash, Zsh, Ash), output traces on 15389 stderr, even for subshells. This might result in undesirable content 15390 if 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 15397 foo 15398 $ @kbd{bash -x -c '(eval "echo foo >&2") 2>stderr'} 15399 $ @kbd{cat stderr} 15400 + eval 'echo foo >&2' 15401 ++ echo foo 15402 foo 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 15408 foo 15409 @end example 15410 15411 @noindent 15412 One workaround is to grep out uninteresting lines, hoping not to remove 15413 good ones. 15414 15415 If you intend to redirect both standard error and standard output, 15416 redirect standard output first. This works better with HP-UX, 15417 since its shell mishandles tracing if standard error is redirected 15418 first: 15419 15420 @example 15421 $ @kbd{sh -x -c ': 2>err >out'} 15422 + : 15423 + 2> err $ @kbd{cat err} 15424 1> out 15425 @end example 15426 15427 Don't try to redirect the standard error of a command substitution. It 15428 must be done @emph{inside} the command substitution. When running 15429 @samp{: `cd /zorglub` 2>/dev/null} expect the error message to 15430 escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly. 15431 15432 On the other hand, some shells, such as Solaris or FreeBSD 15433 @command{/bin/sh}, warn about missing programs before performing 15434 redirections. Therefore, to silently check whether a program exists, it 15435 is necessary to perform redirections on a subshell or brace group: 15436 @example 15437 $ @kbd{/bin/sh -c 'nosuch 2>/dev/null'} 15438 nosuch: 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 15444 FreeBSD 6.2 sh may mix the trace output lines from the statements in a 15445 shell pipeline. 15446 15447 It is worth noting that Zsh (but not Ash nor Bash) makes it possible 15448 in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}. 15449 15450 Some shells, like @command{ash}, don't recognize bi-directional 15451 redirection (@samp{<>}). And even on shells that recognize it, it is 15452 not portable to use on fifos: Posix does not require read-write support 15453 for 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} 15459 bash: echo: write error: Communication error on send 15460 @end example 15461 15462 @noindent 15463 Furthermore, versions of @command{dash} before 0.5.6 mistakenly truncate 15464 regular files when using @samp{<>}: 15465 15466 @example 15467 $ @kbd{echo a > file} 15468 $ @kbd{bash -c ': 1<>file'; cat file} 15469 a 15470 $ @kbd{dash -c ': 1<>file'; cat file} 15471 $ rm a 15472 @end example 15473 15474 When catering to old systems, don't redirect the same file descriptor 15475 several times, as you are doomed to failure under Ultrix. 15476 15477 @example 15478 ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995 15479 UWS V4.4 (Rev. 11) 15480 $ @kbd{eval 'echo matter >fullness' >void} 15481 illegal io 15482 $ @kbd{eval '(echo matter >fullness)' >void} 15483 illegal io 15484 $ @kbd{(eval '(echo matter >fullness)') >void} 15485 Ambiguous output redirect. 15486 @end example 15487 15488 @noindent 15489 In each case the expected result is of course @file{fullness} containing 15490 @samp{matter} and @file{void} being empty. However, this bug is 15491 probably not of practical concern to modern platforms. 15492 15493 Solaris 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 15495 shell function after the first call: 15496 15497 @example 15498 $ @kbd{for i in 1 2 3 ; do : >x$i; done} 15499 $ @kbd{ls x*} 15500 x1 15501 $ @kbd{f () @{ : >$1; @}; f y1; f y2; f y3;} 15502 $ @kbd{ls y*} 15503 y1 15504 @end example 15505 15506 @noindent 15507 As a workaround, @command{echo} or @command{eval} can be used. 15508 15509 Don't rely on file descriptors 0, 1, and 2 remaining closed in a 15510 subsidiary program. If any of these descriptors is closed, the 15511 operating system may open an unspecified file for the descriptor in the 15512 new process image. Posix 2008 says this may be done only if the 15513 subsidiary program is set-user-ID or set-group-ID, but HP-UX 11.23 does 15514 it even for ordinary programs, and the next version of Posix will allow 15515 HP-UX behavior. 15516 15517 If you want a file descriptor above 2 to be inherited into a child 15518 process, then you must use redirections specific to that command or a 15519 containing 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 15523 that 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} 15528 hello 15529 $ @kbd{bash -c 'exec 5>t; ksh ./k; exec 5>&-; cat t} 15530 hello 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'} 15534 hello 15535 $ @kbd{ksh -c '@{ ksh ./k; @} 5>t; cat t'} 15536 hello 15537 $ @kbd{ksh -c '5>t ksh ./k; cat t} 15538 hello 15539 @end example 15540 15541 Don't rely on duplicating a closed file descriptor to cause an 15542 error. With Solaris @command{/bin/sh}, failed duplication is silently 15543 ignored, which can cause unintended leaks to the original file 15544 descriptor. In this example, observe the leak to standard output: 15545 15546 @example 15547 $ @kbd{bash -c 'echo hi >&3' 3>&-; echo $?} 15548 bash: 3: Bad file descriptor 15549 1 15550 $ @kbd{/bin/sh -c 'echo hi >&3' 3>&-; echo $?} 15551 hi 15552 0 15553 @end example 15554 15555 Fortunately, an attempt to close an already closed file descriptor will 15556 portably succeed. Likewise, it is safe to use either style of 15557 @samp{@var{n}<&-} or @samp{@var{n}>&-} for closing a file descriptor, 15558 even if it doesn't match the read/write mode that the file descriptor 15559 was opened with. 15560 15561 DOS 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 15563 perfectly portable among Posix hosts. 15564 15565 A few ancient systems reserved some file descriptors. By convention, 15566 file descriptor 3 was opened to @file{/dev/tty} when you logged into 15567 Eighth Edition (1985) through Tenth Edition Unix (1989). File 15568 descriptor 4 had a special use on the Stardent/Kubota Titan (circa 15569 1990), though we don't now remember what it was. Both these systems are 15570 obsolete, so it's now safe to treat file descriptors 3 and 4 like any 15571 other file descriptors. 15572 15573 On the other hand, you can't portably use multi-digit file descriptors. 15574 Solaris @command{ksh} doesn't understand any file descriptor larger than 15575 @samp{9}: 15576 15577 @example 15578 $ @kbd{bash -c 'exec 10>&-'; echo $?} 15579 0 15580 $ @kbd{ksh -c 'exec 9>&-'; echo $?} 15581 0 15582 $ @kbd{ksh -c 'exec 10>&-'; echo $?} 15583 ksh[1]: exec: 10: not found 15584 127 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 15593 Portable handling of signals within the shell is another major source of 15594 headaches. This is worsened by the fact that various different, mutually 15595 incompatible approaches are possible in this area, each with its 15596 distinctive merits and demerits. A detailed description of these possible 15597 approaches, as well as of their pros and cons, can be found in 15598 @uref{http://www.cons.org/cracauer/sigint.html, this article}. 15599 15600 Solaris 10 @command{/bin/sh} automatically traps most signals by default; 15601 @c See: <http://dbaspot.com/shell/396118-bourne-shell-exit-code-term.html> 15602 the shell still exits with error upon termination by one of those signals, 15603 but in such a case the exit status might be somewhat unexpected (even if 15604 allowed by POSIX, strictly speaking): 15605 15606 @example 15607 $ @kbd{bash -c 'kill -1 $$'; echo $?} # Will exit 128 + (signal number). 15608 Hangup 15609 129 15610 $ @kbd{/bin/ksh -c 'kill -15 $$'; echo $?} # Likewise. 15611 Terminated 15612 143 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} 15617 signal 1: 15618 Hangup 15619 129 15620 signal 2: 15621 208 15622 signal 3: 15623 208 15624 signal 15: 15625 208 15626 @end example 15627 15628 This gets even worse if one is using the POSIX `wait' interface to get 15629 details about the shell process terminations: it will result in the shell 15630 having 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 */ 15637 int 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 @} 15646 END 15647 @c $$ font-lock 15648 $ @kbd{cc -o foo foo.c} 15649 $ @kbd{./a.out} # On GNU/Linux 15650 Terminated by signal: no 15651 Exited normally: yes 15652 $ @kbd{./a.out} # On Solaris 10 15653 Terminated by signal: yes 15654 Exited normally: no 15655 @end example 15656 15657 Various shells seem to handle @code{SIGQUIT} specially: they ignore it even 15658 if 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 15660 are 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). 15662 Still, @code{SIGQUIT} seems to be trappable quite portably within all 15663 these shells. OTOH, some other shells doesn't special-case the handling 15664 of @code{SIGQUIT}; among these shells are at least @code{pdksh} 5.2.14, 15665 Solaris 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> 15668 Some shells (especially Korn shells and derivatives) might try to 15669 propagate to themselves a signal that has killed a child process; this is 15670 not a bug, but a conscious design choice (although its overall value might 15671 be debatable). The exact details of how this is attained vary from shell 15672 to shell. For example, upon running @code{perl -e 'kill 2, $$'}, after 15673 the perl process has been interrupted AT&T @code{ksh93} (2011) will 15674 proceed to send itself a @code{SIGINT}, while Solaris 10 @code{/bin/ksh} 15675 and @code{/usr/xpg4/bin/sh} will proceed to exit with status 130 (i.e., 15676 128 + 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> 15680 Some Korn shells, when a child process die due receiving a signal with 15681 signal number @var{n}, can leave in @samp{$?} an exit status of 15682 256+@var{n} instead of the more common 128+@var{n}. Observe the 15683 difference between AT&T @code{ksh93} (2011) and @code{bash} 4.1.5 on 15684 Debian: 15685 15686 @example 15687 $ @kbd{/bin/ksh -c 'sh -c "kill -1 \$\$"; echo $?'} 15688 /bin/ksh: line 1: 7837: Hangup 15689 257 15690 $ @kbd{/bin/bash -c 'sh -c "kill -1 \$\$"; echo $?'} 15691 /bin/bash: line 1: 7861 Hangup (sh -c "kill -1 \$\$") 15692 129 15693 @end example 15694 15695 @noindent 15696 This @command{ksh} behavior is allowed by POSIX, if implemented with 15697 due care; see this @uref{http://www.austingroupbugs.net/view.php?id=51, 15698 Austin Group discussion} for more background. However, if it is not 15699 implemented with proper care, such a behavior might cause problems 15700 in some corner cases. To see why, assume we have a ``wrapper'' script 15701 like this: 15702 15703 @example 15704 #!/bin/sh 15705 # Ignore some signals in the shell only, not in its child processes. 15706 trap : 1 2 13 15 15707 wrapped_command "$@@" 15708 ret=$? 15709 other_command 15710 exit $ret 15711 @end example 15712 15713 @noindent 15714 If @command{wrapped_command} is interrupted by a @code{SIGHUP} (which 15715 has signal number 1), @code{ret} will be set to 257. Unless the 15716 @command{exit} shell builtin is smart enough to understand that such 15717 a value can only have originated from a signal, and adjust the final 15718 wait status of the shell appropriately, the value 257 will just get 15719 truncated to 1 by the closing @code{exit} call, so that a caller of 15720 the script will have no way to determine that termination by a signal 15721 was 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 15727 sh -c 'kill -1 $$' 15728 ret=$? 15729 echo $ret 15730 exit $ret 15731 $ @kbd{/bin/ksh foo.sh; echo $?} 15732 foo.sh: line 2: 12479: Hangup 15733 257 15734 1 15735 $ @kbd{/bin/bash foo.sh; echo $?} 15736 foo.sh: line 2: 12487 Hangup (sh -c 'kill -1 $$') 15737 129 15738 129 15739 @end example 15740 15741 @node File System Conventions 15742 @section File System Conventions 15743 @cindex File system conventions 15744 15745 Autoconf uses shell-script processing extensively, so the file names 15746 that it processes should not contain characters that are special to the 15747 shell. Special characters include space, tab, newline, NUL, and 15748 the following: 15749 15750 @example 15751 " # $ & ' ( ) * ; < = > ? [ \ ` | 15752 @end example 15753 15754 Also, file names should not begin with @samp{~} or @samp{-}, and should 15755 contain neither @samp{-} immediately after @samp{/} nor @samp{~} 15756 immediately after @samp{:}. On Posix-like platforms, directory names 15757 should not contain @samp{:}, as this runs afoul of @samp{:} used as the 15758 path separator. 15759 15760 These restrictions apply not only to the files that you distribute, but 15761 also to the absolute file names of your source, build, and destination 15762 directories. 15763 15764 On some Posix-like platforms, @samp{!} and @samp{^} are special too, so 15765 they should be avoided. 15766 15767 Posix lets implementations treat leading @file{//} specially, but 15768 requires leading @file{///} and beyond to be equivalent to @file{/}. 15769 Most Unix variants treat @file{//} like @file{/}. However, some treat 15770 @file{//} as a ``super-root'' that can provide access to files that are 15771 not otherwise reachable from @file{/}. The super-root tradition began 15772 with Apollo Domain/OS, which died out long ago, but unfortunately Cygwin 15773 has revived it. 15774 15775 While @command{autoconf} and friends are usually run on some Posix 15776 variety, they can be used on other systems, most notably DOS 15777 variants. This impacts several assumptions regarding file names. 15778 15779 @noindent 15780 For example, the following code: 15781 15782 @example 15783 case $foo_dir in 15784 /*) # Absolute 15785 ;; 15786 *) 15787 foo_dir=$dots$foo_dir ;; 15788 esac 15789 @end example 15790 15791 @noindent 15792 fails to properly detect absolute file names on those systems, because 15793 they can use a drivespec, and usually use a backslash as directory 15794 separator. If you want to be portable to DOS variants (at the 15795 price of rejecting valid but oddball Posix file names like @file{a:\b}), 15796 you can check for absolute file names like this: 15797 15798 @cindex absolute file names, detect 15799 @example 15800 case $foo_dir in 15801 [\\/]* | ?:[\\/]* ) # Absolute 15802 ;; 15803 *) 15804 foo_dir=$dots$foo_dir ;; 15805 esac 15806 @end example 15807 15808 @noindent 15809 Make sure you quote the brackets if appropriate and keep the backslash as 15810 first character (@pxref{case, , Limitations of Shell Builtins}). 15811 15812 Also, because the colon is used as part of a drivespec, these systems don't 15813 use it as path separator. When creating or accessing paths, you can use the 15814 @code{PATH_SEPARATOR} output variable instead. @command{configure} sets this 15815 to the appropriate value for the build system (@samp{:} or @samp{;}) when it 15816 starts up. 15817 15818 File names need extra care as well. While DOS variants 15819 that are Posixy enough to run @command{autoconf} (such as DJGPP) 15820 are usually able to handle long file names properly, there are still 15821 limitations that can seriously break packages. Several of these issues 15822 can be easily detected by the 15823 @uref{ftp://@/ftp.gnu.org/@/gnu/@/non-gnu/@/doschk/@/doschk-1.1.tar.gz, doschk} 15824 package. 15825 15826 A short overview follows; problems are marked with SFN/LFN to 15827 indicate where they apply: SFN means the issues are only relevant to 15828 plain DOS, not to DOS under Microsoft Windows 15829 variants, while LFN identifies problems that exist even under 15830 Microsoft Windows variants. 15831 15832 @table @asis 15833 @item No multiple dots (SFN) 15834 DOS cannot handle multiple dots in file names. This is an especially 15835 important thing to remember when building a portable configure script, 15836 as @command{autoconf} uses a .in suffix for template files. 15837 15838 This is perfectly OK on Posix variants: 15839 15840 @example 15841 AC_CONFIG_HEADERS([config.h]) 15842 AC_CONFIG_FILES([source.c foo.bar]) 15843 AC_OUTPUT 15844 @end example 15845 15846 @noindent 15847 but 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 15849 to DOS-based environments, you should use this instead: 15850 15851 @example 15852 AC_CONFIG_HEADERS([config.h:config.hin]) 15853 AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in]) 15854 AC_OUTPUT 15855 @end example 15856 15857 @item No leading dot (SFN) 15858 DOS cannot handle file names that start with a dot. This is usually 15859 not important for @command{autoconf}. 15860 15861 @item Case insensitivity (LFN) 15862 DOS is case insensitive, so you cannot, for example, have both a 15863 file called @samp{INSTALL} and a directory called @samp{install}. This 15864 also affects @command{make}; if there's a file called @samp{INSTALL} in 15865 the directory, @samp{make install} does nothing (unless the 15866 @samp{install} target is marked as PHONY). 15867 15868 @item The 8+3 limit (SFN) 15869 Because the DOS file system only stores the first 8 characters of 15870 the file name and the first 3 of the extension, those must be unique. 15871 That 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 15876 The 8+3 limit is not usually a problem under Microsoft Windows, as it 15877 uses numeric 15878 tails in the short version of file names to make them unique. However, a 15879 registry setting can turn this behavior off. While this makes it 15880 possible to share file trees containing long file names between SFN 15881 and LFN environments, it also means the above problem applies there 15882 as well. 15883 15884 @item Invalid characters (LFN) 15885 Some characters are invalid in DOS file names, and should therefore 15886 be avoided. In a LFN environment, these are @samp{/}, @samp{\}, 15887 @samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}. 15888 In a SFN environment, other characters are also invalid. These 15889 include @samp{+}, @samp{,}, @samp{[} and @samp{]}. 15890 15891 @item Invalid names (LFN) 15892 Some DOS file names are reserved, and cause problems if you 15893 try 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}. 15896 File 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 15905 Nowadays portable patterns can use negated character classes like 15906 @samp{[!-aeiou]}. The older syntax @samp{[^-aeiou]} is supported by 15907 some shells but not others; hence portable scripts should never use 15908 @samp{^} as the first character of a bracket pattern. 15909 15910 Outside the C locale, patterns like @samp{[a-z]} are problematic since 15911 they may match characters that are not lower-case letters. 15912 15913 @node Shell Substitutions 15914 @section Shell Substitutions 15915 @cindex Shell substitutions 15916 15917 Contrary to a persistent urban legend, the Bourne shell does not 15918 systematically split variables and back-quoted expressions, in particular 15919 on the right-hand side of assignments and in the argument of @code{case}. 15920 For instance, the following code: 15921 15922 @example 15923 case "$given_srcdir" in 15924 .) top_srcdir="`echo "$dots" | sed 's|/$||'`" ;; 15925 *) top_srcdir="$dots$given_srcdir" ;; 15926 esac 15927 @end example 15928 15929 @noindent 15930 is more readable when written as: 15931 15932 @example 15933 case $given_srcdir in 15934 .) top_srcdir=`echo "$dots" | sed 's|/$||'` ;; 15935 *) top_srcdir=$dots$given_srcdir ;; 15936 esac 15937 @end example 15938 15939 @noindent 15940 and in fact it is even @emph{more} portable: in the first case of the 15941 first attempt, the computation of @code{top_srcdir} is not portable, 15942 since not all shells properly understand @code{"`@dots{}"@dots{}"@dots{}`"}, 15943 for example Solaris 10 ksh: 15944 15945 @example 15946 $ @kbd{foo="`echo " bar" | sed 's, ,,'`"} 15947 ksh: : cannot execute 15948 ksh: bar | sed 's, ,,': cannot execute 15949 @end example 15950 15951 @noindent 15952 Posix does not specify behavior for this sequence. On the other hand, 15953 behavior for @code{"`@dots{}\"@dots{}\"@dots{}`"} is specified by Posix, 15954 but in practice, not all shells understand it the same way: pdksh 5.2.14 15955 prints spurious quotes when in Posix mode: 15956 15957 @example 15958 $ @kbd{echo "`echo \"hello\"`"} 15959 hello 15960 $ @kbd{set -o posix} 15961 $ @kbd{echo "`echo \"hello\"`"} 15962 "hello" 15963 @end example 15964 15965 @noindent 15966 There is just no portable way to use double-quoted strings inside 15967 double-quoted back-quoted expressions (pfew!). 15968 15969 Bash 4.1 has a bug where quoted empty strings adjacent to unquoted 15970 parameter expansions are elided during word splitting. Meanwhile, zsh 15971 does not perform word splitting except when in Bourne compatibility 15972 mode. In the example below, the correct behavior is to have five 15973 arguments to the function, and exactly two spaces on either side of the 15974 middle @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"" -'} 15979 3- - - 15980 $ @kbd{ksh -c 'n() @{ echo "$#$@@"; @}; f=" - "; n - ""$f"" -'} 15981 5- - - 15982 $ @kbd{zsh -c 'n() @{ echo "$#$@@"; @}; f=" - "; n - ""$f"" -'} 15983 3- - - 15984 $ @kbd{zsh -c 'emulate sh;} 15985 > @kbd{n() @{ echo "$#$@@"; @}; f=" - "; n - ""$f"" -'} 15986 5- - - 15987 @end example 15988 15989 @noindent 15990 You can work around this by doing manual word splitting, such as using 15991 @samp{"$str" $list} rather than @samp{"$str"$list}. 15992 15993 There are also portability pitfalls with particular expansions: 15994 15995 @table @code 15996 @item $@@ 15997 @cindex @code{"$@@"} 15998 One of the most famous shell-portability issues is related to 15999 @samp{"$@@"}. When there are no positional arguments, Posix says 16000 that @samp{"$@@"} is supposed to be equivalent to nothing, but the 16001 original Unix version 7 Bourne shell treated it as equivalent to 16002 @samp{""} instead, and this behavior survives in later implementations 16003 like Digital Unix 5.0. 16004 16005 The traditional way to work around this portability problem is to use 16006 @samp{$@{1+"$@@"@}}. Unfortunately this method does not work with 16007 Zsh (3.x and 4.x), which is used on Mac OS X@. When emulating 16008 the Bourne shell, Zsh performs word splitting on @samp{$@{1+"$@@"@}}: 16009 16010 @example 16011 zsh $ @kbd{emulate sh} 16012 zsh $ @kbd{for i in "$@@"; do echo $i; done} 16013 Hello World 16014 ! 16015 zsh $ @kbd{for i in $@{1+"$@@"@}; do echo $i; done} 16016 Hello 16017 World 16018 ! 16019 @end example 16020 16021 @noindent 16022 Zsh handles plain @samp{"$@@"} properly, but we can't use plain 16023 @samp{"$@@"} because of the portability problems mentioned above. 16024 One workaround relies on Zsh's ``global aliases'' to convert 16025 @samp{$@{1+"$@@"@}} into @samp{"$@@"} by itself: 16026 16027 @example 16028 test "$@{ZSH_VERSION+set@}" = set && alias -g '$@{1+"$@@"@}'='"$@@"' 16029 @end example 16030 16031 Zsh only recognizes this alias when a shell word matches it exactly; 16032 @samp{"foo"$@{1+"$@@"@}} remains subject to word splitting. Since this 16033 case always yields at least one shell word, use plain @samp{"$@@"}. 16034 16035 A more conservative workaround is to avoid @samp{"$@@"} if it is 16036 possible that there may be no positional arguments. For example, 16037 instead of: 16038 16039 @example 16040 cat conftest.c "$@@" 16041 @end example 16042 16043 you can use this instead: 16044 16045 @example 16046 case $# in 16047 0) cat conftest.c;; 16048 *) cat conftest.c "$@@";; 16049 esac 16050 @end example 16051 16052 Autoconf 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{$@@} 16055 persists for any length of time. 16056 16057 16058 @item $@{10@} 16059 @cindex positional parameters 16060 The 10th, 11th, @dots{} positional parameters can be accessed only after 16061 a @code{shift}. The 7th Edition shell reported an error if given 16062 @code{$@{10@}}, and 16063 Solaris 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@}} 16068 bad substitution 16069 @end example 16070 16071 Conversely, not all shells obey the Posix rule that when braces are 16072 omitted, multiple digits beyond a @samp{$} imply the single-digit 16073 positional parameter expansion concatenated with the remaining literal 16074 digits. 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'} 16078 a0 a0 16079 $ @kbd{dash -c 'set a b c d e f g h i j; echo $10 $@{1@}0'} 16080 j 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}@}} 16089 Old BSD shells, including the Ultrix @code{sh}, don't accept the 16090 colon for any shell substitution, and complain and die. 16091 Similarly for $@{@var{var}:=@var{value}@}, $@{@var{var}:?@var{value}@}, etc. 16092 However, all shells that support functions allow the use of colon in 16093 shell substitution, and since m4sh requires functions, you can portably 16094 use null variable substitution patterns in configure scripts. 16095 16096 @item $@{@var{var}+@var{value}@} 16097 @cindex @code{$@{@var{var}+@var{value}@}} 16098 When 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 16101 context 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'\''@}'} 16108 b c 16109 $ @kbd{/bin/sh -c 'echo "$@{a-b c@}"'} 16110 b c 16111 $ @kbd{/bin/sh -c 'cat <<EOF 16112 $@{a-b c@} 16113 EOF} 16114 b c 16115 @end example 16116 16117 According to Posix, if an expansion occurs inside double quotes, then 16118 the use of unquoted double quotes within @var{value} is unspecified, and 16119 any single quotes become literal characters; in that case, escaping must 16120 be done with backslash. Likewise, the use of unquoted here-documents is 16121 a 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"@}"'} 16127 b c 16128 $ @kbd{bash -c 'echo "$@{a-"b c"@}"'} 16129 b c 16130 $ @kbd{/bin/sh -c 'a=; echo $@{a+'\''b c'\''@}'} 16131 b 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@}"'} 16137 b c 16138 $ @kbd{/bin/sh -c 'cat <<EOF 16139 $@{a-"b c"@} 16140 EOF'} 16141 "b c" 16142 $ @kbd{/bin/sh -c 'cat <<EOF 16143 $@{a-'b c'@} 16144 EOF'} 16145 'b c' 16146 $ @kbd{bash -c 'cat <<EOF 16147 $@{a-"b c"@} 16148 EOF'} 16149 b c 16150 $ @kbd{bash -c 'cat <<EOF 16151 $@{a-'b c'@} 16152 EOF'} 16153 'b c' 16154 @end example 16155 16156 Perhaps the easiest way to work around quoting issues in a manner 16157 portable to all shells is to place the results in a temporary variable, 16158 then use @samp{$t} as the @var{value}, rather than trying to inline 16159 the expression needing quoting. 16160 16161 @example 16162 $ @kbd{/bin/sh -c 't="b c\"'\''@}\\"; echo "$@{a-$t@}"'} 16163 b c"'@}\ 16164 $ @kbd{ksh -c 't="b c\"'\''@}\\"; echo "$@{a-$t@}"'} 16165 b c"'@}\ 16166 $ @kbd{bash -c 't="b c\"'\''@}\\"; echo "$@{a-$t@}"'} 16167 b c"'@}\ 16168 @end example 16169 16170 @item $@{@var{var}=@var{value}@} 16171 @cindex @code{$@{@var{var}=@var{value}@}} 16172 When using @samp{$@{@var{var}=@var{value}@}} to assign a default value 16173 to @var{var}, remember that even though the assignment to @var{var} does 16174 not undergo file name expansion, the result of the variable expansion 16175 does unless the expansion occurred within double quotes. In particular, 16176 when using @command{:} followed by unquoted variable expansion for the 16177 side effect of setting a default value, if the final value of 16178 @samp{$var} contains any globbing characters (either from @var{value} or 16179 from prior contents), the shell has to spend time performing file name 16180 expansion and field splitting even though those results will not be 16181 used. Therefore, it is a good idea to consider double quotes when performing 16182 default initialization; while remembering how this impacts any quoting 16183 characters appearing in @var{value}. 16184 16185 @example 16186 $ @kbd{time bash -c ': "$@{a=/usr/bin/*@}"; echo "$a"'} 16187 /usr/bin/* 16188 16189 real 0m0.005s 16190 user 0m0.002s 16191 sys 0m0.003s 16192 $ @kbd{time bash -c ': $@{a=/usr/bin/*@}; echo "$a"'} 16193 /usr/bin/* 16194 16195 real 0m0.039s 16196 user 0m0.026s 16197 sys 0m0.009s 16198 $ @kbd{time bash -c 'a=/usr/bin/*; : $@{a=noglob@}; echo "$a"'} 16199 /usr/bin/* 16200 16201 real 0m0.031s 16202 user 0m0.020s 16203 sys 0m0.010s 16204 16205 $ @kbd{time bash -c 'a=/usr/bin/*; : "$@{a=noglob@}"; echo "$a"'} 16206 /usr/bin/* 16207 16208 real 0m0.006s 16209 user 0m0.002s 16210 sys 0m0.003s 16211 @end example 16212 16213 As with @samp{+} and @samp{-}, you must use quotes when using @samp{=} 16214 if the @var{value} contains more than one shell word; either single 16215 quotes for just the @var{value}, or double quotes around the entire 16216 expansion: 16217 16218 @example 16219 $ @kbd{: $@{var1='Some words'@}} 16220 $ @kbd{: "$@{var2=like this@}"} 16221 $ @kbd{echo $var1 $var2} 16222 Some words like this 16223 @end example 16224 16225 @noindent 16226 otherwise some shells, such as Solaris @command{/bin/sh} or on Digital 16227 Unix V 5.0, die because of a ``bad substitution''. Meanwhile, Posix 16228 requires that with @samp{=}, quote removal happens prior to the 16229 assignment, and the expansion be the final contents of @var{var} without 16230 quoting (and thus subject to field splitting), in contrast to the 16231 behavior with @samp{-} passing the quoting through to the final 16232 expansion. However, @command{bash} 4.1 does not obey this rule. 16233 16234 @example 16235 $ @kbd{ksh -c 'echo $@{var-a\ \ b@}'} 16236 a b 16237 $ @kbd{ksh -c 'echo $@{var=a\ \ b@}'} 16238 a b 16239 $ @kbd{bash -c 'echo $@{var=a\ \ b@}'} 16240 a b 16241 @end example 16242 16243 Finally, Posix states that when mixing @samp{$@{a=b@}} with regular 16244 commands, it is unspecified whether the assignments affect the parent 16245 shell environment. It is best to perform assignments independently from 16246 commands, 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}@}} 16262 Solaris @command{/bin/sh} has a frightening bug in its handling of 16263 literal assignments. Imagine you need set a variable to a string containing 16264 @samp{@}}. This @samp{@}} character confuses Solaris @command{/bin/sh} 16265 when the affected variable was already set. This bug can be exercised 16266 by 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 16282 It seems that @samp{@}} is interpreted as matching @samp{$@{}, even 16283 though it is enclosed in single quotes. The problem doesn't happen 16284 using double quotes, or when using a temporary variable holding the 16285 problematic string. 16286 16287 @item $@{@var{var}=@var{expanded-value}@} 16288 @cindex @code{$@{@var{var}=@var{expanded-value}@}} 16289 On Ultrix, 16290 running 16291 16292 @example 16293 default="yu,yaa" 16294 : $@{var="$default"@} 16295 @end example 16296 16297 @noindent 16298 sets @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of 16299 each 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 16301 expands $var. Here are two means to make this shell confess its sins: 16302 16303 @example 16304 $ @kbd{cat -v <<EOF 16305 $var 16306 EOF} 16307 @end example 16308 16309 @noindent 16310 and 16311 16312 @example 16313 $ @kbd{set | grep '^var=' | cat -v} 16314 @end example 16315 16316 One classic incarnation of this bug is: 16317 16318 @example 16319 default="a b c" 16320 : $@{list="$default"@} 16321 for c in $list; do 16322 echo $c 16323 done 16324 @end example 16325 16326 @noindent 16327 You'll get @samp{a b c} on a single line. Why? Because there are no 16328 spaces in @samp{$list}: there are @samp{M- }, i.e., spaces with the 8th 16329 bit set, hence no IFS splitting is performed!!! 16330 16331 One 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 16333 then that QNX 4.25 then sets @var{list} to the @emph{last} item of 16334 @var{default}! 16335 16336 The portable way out consists in using a double assignment, to switch 16337 the 8th bit twice on Ultrix: 16338 16339 @example 16340 list=$@{list="$default"@} 16341 @end example 16342 16343 @noindent 16344 @dots{}but beware of the @samp{@}} bug from Solaris (see above). For safety, 16345 use: 16346 16347 @example 16348 test "$@{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}@}} 16361 Posix requires support for these usages, but they do not work with many 16362 traditional shells, e.g., Solaris 10 @command{/bin/sh}. 16363 16364 Also, @command{pdksh} 5.2.14 mishandles some @var{word} forms. For 16365 example 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 16367 yields the empty string. 16368 16369 16370 @item `@var{commands}` 16371 @cindex @code{`@var{commands}`} 16372 @cindex Command Substitution 16373 Posix requires shells to trim all trailing newlines from command 16374 output 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 16378 While in general it makes no sense, do not substitute a single builtin 16379 with side effects, because Ash 0.2, trying to optimize, does not fork a 16380 subshell to perform the command. 16381 16382 For instance, if you wanted to check that @command{cd} is silent, do not 16383 use @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 16393 The result of @samp{foo=`exit 1`} is left as an exercise to the reader. 16394 16395 The MSYS shell leaves a stray byte in the expansion of a double-quoted 16396 command substitution of a native program, if the end of the substitution 16397 is not aligned with the end of the double quote. This may be worked 16398 around 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 16406 Upon interrupt or SIGTERM, some shells may abort a command substitution, 16407 replace it with a null string, and wrongly evaluate the enclosing 16408 command before entering the trap or ending the script. This can lead to 16409 spurious errors: 16410 16411 @example 16412 $ @kbd{sh -c 'if test `sleep 5; echo hi` = hi; then echo yes; fi'} 16413 $ @kbd{^C} 16414 sh: test: hi: unexpected operator/operand 16415 @end example 16416 16417 @noindent 16418 You can avoid this by assigning the command substitution to a temporary 16419 variable: 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})} 16429 This construct is meant to replace @samp{`@var{commands}`}, 16430 and it has most of the problems listed under @code{`@var{commands}`}. 16431 16432 This construct can be 16433 nested while this is impossible to do portably with back quotes. 16434 Unfortunately it is not yet universally supported. Most notably, even recent 16435 releases of Solaris don't support it: 16436 16437 @example 16438 $ @kbd{showrev -c /bin/sh | grep version} 16439 Command version: SunOS 5.10 Generic 121005-03 Oct 2006 16440 $ @kbd{echo $(echo blah)} 16441 syntax error: `(' unexpected 16442 @end example 16443 16444 @noindent 16445 nor does IRIX 6.5's Bourne shell: 16446 @example 16447 $ @kbd{uname -a} 16448 IRIX firebird-image 6.5 07151432 IP22 16449 $ @kbd{echo $(echo blah)} 16450 $(echo blah) 16451 @end example 16452 16453 If you do use @samp{$(@var{commands})}, make sure that the commands 16454 do not start with a parenthesis, as that would cause confusion with 16455 a different notation @samp{$((@var{expression}))} that in modern 16456 shells is an arithmetic expression not a command. To avoid the 16457 confusion, insert a space between the two opening parentheses. 16458 16459 Avoid @var{commands} that contain unbalanced parentheses in 16460 here-documents, comments, or case statement patterns, as many shells 16461 mishandle them. For example, Bash 3.1, @samp{ksh88}, @command{pdksh} 16462 5.2.14, and Zsh 4.2.6 all mishandle the following valid command: 16463 16464 @example 16465 echo $(case x in x) echo hello;; esac) 16466 @end example 16467 16468 16469 @item $((@var{expression})) 16470 @cindex @code{$((@var{expression}))} 16471 Arithmetic expansion is not portable as some shells (most 16472 notably Solaris 10 @command{/bin/sh}) don't support it. 16473 16474 Among shells that do support @samp{$(( ))}, not all of them obey the 16475 Posix rule that octal and hexadecimal constants must be recognized: 16476 16477 @example 16478 $ @kbd{bash -c 'echo $(( 010 + 0x10 ))'} 16479 24 16480 $ @kbd{zsh -c 'echo $(( 010 + 0x10 ))'} 16481 26 16482 $ @kbd{zsh -c 'emulate sh; echo $(( 010 + 0x10 ))'} 16483 24 16484 $ @kbd{pdksh -c 'echo $(( 010 + 0x10 ))'} 16485 pdksh: 010 + 0x10 : bad number `0x10' 16486 $ @kbd{pdksh -c 'echo $(( 010 ))'} 16487 10 16488 @end example 16489 16490 When it is available, using arithmetic expansion provides a noticeable 16491 speedup in script execution; but testing for support requires 16492 @command{eval} to avoid syntax errors. The following construct is used 16493 by @code{AS_VAR_ARITH} to provide arithmetic computation when all 16494 arguments are provided in decimal and without a leading zero, and all 16495 operators are properly quoted and appear as distinct arguments: 16496 16497 @example 16498 if ( eval 'test $(( 1 + 1 )) = 2' ) 2>/dev/null; then 16499 eval 'func_arith () 16500 @{ 16501 func_arith_result=$(( $* )) 16502 @}' 16503 else 16504 func_arith () 16505 @{ 16506 func_arith_result=`expr "$@@"` 16507 @} 16508 fi 16509 func_arith 1 + 1 16510 foo=$func_arith_result 16511 @end example 16512 16513 16514 @item ^ 16515 @cindex @code{^} quoting 16516 Always 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 16526 When setting several variables in a row, be aware that the order of the 16527 evaluation is undefined. For instance @samp{foo=1 foo=2; echo $foo} 16528 gives @samp{1} with Solaris @command{/bin/sh}, but @samp{2} with Bash. 16529 You must use 16530 @samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}. 16531 16532 Don't rely on the following to find @file{subdir/program}: 16533 16534 @example 16535 PATH=subdir$PATH_SEPARATOR$PATH program 16536 @end example 16537 16538 @noindent 16539 as this does not work with Zsh 3.0.6. Use something like this 16540 instead: 16541 16542 @example 16543 (PATH=subdir$PATH_SEPARATOR$PATH; export PATH; exec program) 16544 @end example 16545 16546 Don't rely on the exit status of an assignment: Ash 0.2 does not change 16547 the status and propagates that of the last statement: 16548 16549 @example 16550 $ @kbd{false || foo=bar; echo $?} 16551 1 16552 $ @kbd{false || foo=`:`; echo $?} 16553 0 16554 @end example 16555 16556 @noindent 16557 and to make things even worse, QNX 4.25 just sets the exit status 16558 to 0 in any case: 16559 16560 @example 16561 $ @kbd{foo=`exit 1`; echo $?} 16562 0 16563 @end example 16564 16565 To assign default values, follow this algorithm: 16566 16567 @enumerate 16568 @item 16569 If the default value is a literal and does not contain any closing 16570 brace, use: 16571 16572 @example 16573 : "$@{var='my literal'@}" 16574 @end example 16575 16576 @item 16577 If the default value contains no closing brace, has to be expanded, and 16578 the 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 16586 If the default value contains no closing brace, has to be expanded, and 16587 the variable being initialized is intended to be IFS-split (i.e., it's a list), 16588 then use: 16589 16590 @example 16591 var=$@{var="$default"@} 16592 @end example 16593 16594 @item 16595 If the default value contains a closing brace, then use: 16596 16597 @example 16598 test "$@{var+set@}" = set || var="has a '@}'" 16599 @end example 16600 @end enumerate 16601 16602 In most cases @samp{var=$@{var="$default"@}} is fine, but in case of 16603 doubt, just use the last form. @xref{Shell Substitutions}, items 16604 @samp{$@{@var{var}:-@var{value}@}} and @samp{$@{@var{var}=@var{value}@}} 16605 for the rationale. 16606 16607 @node Parentheses 16608 @section Parentheses in Shell Scripts 16609 @cindex Shell parentheses 16610 16611 Beware of two opening parentheses in a row, as many shell 16612 implementations treat them specially, and Posix says that a portable 16613 script cannot use @samp{((} outside the @samp{$((} form used for shell 16614 arithmetic. In traditional shells, @samp{((cat))} behaves like 16615 @samp{(cat)}; but many shells, including 16616 Bash and the Korn shell, treat @samp{((cat))} as an arithmetic 16617 expression equivalent to @samp{let "cat"}, and may or may not report an 16618 error when they detect that @samp{cat} is not a number. As another 16619 example, @samp{pdksh} 5.2.14 does not treat the following code 16620 as a traditional shell would: 16621 16622 @example 16623 if ((true) || false); then 16624 echo ok 16625 fi 16626 @end example 16627 16628 @noindent 16629 To work around this problem, insert a space between the two opening 16630 parentheses. 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 16637 Unpatched Tru64 5.1 @command{sh} omits the last slash of command-line 16638 arguments 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 16653 Unpatched Tru64 4.0 @command{sh} adds a slash after @samp{"$var"} if the 16654 variable is empty and the second double-quote is followed by a word that 16655 begins and ends with slash: 16656 16657 @example 16658 $ @kbd{sh -xc 'p=; echo "$p"/ouch/'} 16659 p= 16660 + echo //ouch/ 16661 //ouch/ 16662 @end example 16663 16664 However, our understanding is that patches are available, so perhaps 16665 it'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 16672 Some shell variables should not be used, since they can have a deep 16673 influence on the behavior of the shell. In order to recover a sane 16674 behavior from the shell, some variables should be unset; M4sh takes 16675 care of this and provides fallback values, whenever needed, to cater 16676 for a very old @file{/bin/sh} that does not support @command{unset}. 16677 (@pxref{Portable Shell, , Portable Shell Programming}). 16678 16679 As a general rule, shell variable names containing a lower-case letter 16680 are safe; you can define and use these variables without worrying about 16681 their effect on the underlying system, and without worrying about 16682 whether the shell changes them unexpectedly. (The exception is the 16683 shell variable @code{status}, as described below.) 16684 16685 Here is a list of names that are known to cause trouble. This list is 16686 not exhaustive, but you should be safe if you avoid the name 16687 @code{status} and names containing only upper-case letters and 16688 underscores. 16689 16690 @c Alphabetical order, case insensitive, `A' before `a'. 16691 @table @code 16692 @item ? 16693 Not all shells correctly reset @samp{$?} after conditionals (@pxref{if, 16694 , Limitations of Shell Builtins}). Not all shells manage @samp{$?} 16695 correctly 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 $?'} 16701 0 16702 $ @kbd{zsh -c 'false; $empty; echo $?'} 16703 1 16704 @end example 16705 16706 @item _ 16707 @evindex _ 16708 Many shells reserve @samp{$_} for various purposes, e.g., the name of 16709 the last command executed. 16710 16711 @item BIN_SH 16712 @evindex BIN_SH 16713 In Tru64, if @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of 16714 the standard shell conform to Posix. 16715 16716 @item CDPATH 16717 @evindex CDPATH 16718 When this variable is set it specifies a list of directories to search 16719 when invoking @code{cd} with a relative file name that did not start 16720 with @samp{./} or @samp{../}. Posix 16721 1003.1-2001 says that if a nonempty directory name from @env{CDPATH} 16722 is used successfully, @code{cd} prints the resulting absolute 16723 file name. Unfortunately this output can break idioms like 16724 @samp{abs=`cd src && pwd`} because @code{abs} receives the name twice. 16725 Also, many shells do not conform to this part of Posix; for 16726 example, @command{zsh} prints the result only if a directory name 16727 other than @file{.} was chosen from @env{CDPATH}. 16728 16729 In 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 16736 You can also avoid output by ensuring that your directory name is 16737 absolute or anchored at @samp{./}, as in @samp{abs=`cd ./src && pwd`}. 16738 16739 Configure scripts use M4sh, which automatically unsets @env{CDPATH} if 16740 possible, so you need not worry about this problem in those scripts. 16741 16742 @item CLICOLOR_FORCE 16743 @evindex CLICOLOR_FORCE 16744 When this variable is set, some implementations of tools like 16745 @command{ls} attempt to add color to their output via terminal escape 16746 sequences, even when the output is not directed to a terminal, and can 16747 thus cause spurious failures in scripts. Configure scripts use M4sh, 16748 which automatically unsets this variable. 16749 16750 @item DUALCASE 16751 @evindex DUALCASE 16752 In the MKS shell, case statements and file name generation are 16753 case-insensitive unless @env{DUALCASE} is nonzero. 16754 Autoconf-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 16768 These variables should not matter for shell scripts, since they are 16769 supposed to affect only interactive shells. However, at least one 16770 shell (the pre-3.0 UWIN Korn shell) gets confused about 16771 whether it is interactive, which means that (for example) a @env{PS1} 16772 with a side effect can unexpectedly modify @samp{$?}. To work around 16773 this bug, M4sh scripts (including @file{configure} scripts) do something 16774 like this: 16775 16776 @example 16777 (unset ENV) >/dev/null 2>&1 && unset ENV MAIL MAILPATH 16778 PS1='$ ' 16779 PS2='> ' 16780 PS4='+ ' 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 16789 The 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} 16792 to find whether a command exists, since they might report the wrong 16793 result if @env{FPATH} is also set. 16794 16795 @item GREP_OPTIONS 16796 @evindex GREP_OPTIONS 16797 When this variable is set, some implementations of @command{grep} honor 16798 these options, even if the options include direction to enable colored 16799 output via terminal escape sequences, and the result can cause spurious 16800 failures when the output is not directed to a terminal. Configure 16801 scripts use M4sh, which automatically unsets this variable. 16802 16803 @item IFS 16804 @evindex IFS 16805 Long ago, shell scripts inherited @env{IFS} from the environment, 16806 but this caused many problems so modern shells ignore any environment 16807 settings for @env{IFS}. 16808 16809 Don't set the first character of @env{IFS} to backslash. Indeed, 16810 Bourne shells use the first character (backslash) when joining the 16811 components in @samp{"$@@"} and some shells then reinterpret (!)@: the 16812 backslash escapes, so you can end up with backspace and other strange 16813 characters. 16814 16815 The proper value for @env{IFS} (in regular code, not when performing 16816 splits) is @samp{@key{SPC}@key{TAB}@key{RET}}. The first character is 16817 especially important, as it is used to join the arguments in @samp{$*}; 16818 however, note that traditional shells, but also bash-2.04, fail to adhere 16819 to this and join with a space anyway. 16820 16821 M4sh guarantees that @env{IFS} will have the default value at the 16822 beginning of a script, and many macros within autoconf rely on this 16823 setting. It is okay to use blocks of shell code that temporarily change 16824 the value of @env{IFS} in order to split on another character, but 16825 remember to restore it before expanding further macros. 16826 16827 Unsetting @code{IFS} instead of resetting it to the default sequence 16828 is not suggested, since code that tries to save and restore the 16829 variable's value will incorrectly reset it to an empty value, thus 16830 disabling field splitting: 16831 16832 @example 16833 unset IFS 16834 # default separators used for field splitting 16835 16836 save_IFS=$IFS 16837 IFS=: 16838 # ... 16839 IFS=$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 16860 You should set all these variables to @samp{C} because so much 16861 configuration code assumes the C locale and Posix requires that locale 16862 environment variables be set to @samp{C} if the C locale is desired; 16863 @file{configure} scripts and M4sh do that for you. 16864 Export 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 16875 extension that overrides @env{LC_ALL} in some cases, so you (or M4sh) 16876 should 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 16891 These locale environment variables are GNU extensions. They 16892 are treated like their Posix brethren (@env{LC_COLLATE}, 16893 etc.)@: as described above. 16894 16895 @item LINENO 16896 @evindex LINENO 16897 Most modern shells provide the current line number in @code{LINENO}. 16898 Its value is the line number of the beginning of the current command. 16899 M4sh, and hence Autoconf, attempts to execute @command{configure} with 16900 a shell that supports @code{LINENO}. If no such shell is available, it 16901 attempts to implement @code{LINENO} with a Sed prepass that replaces each 16902 instance of the string @code{$LINENO} (not followed by an alphanumeric 16903 character) with the line's number. In M4sh scripts you should execute 16904 @code{AS_LINENO_PREPARE} so that these workarounds are included in 16905 your script; configure scripts do this automatically in @code{AC_INIT}. 16906 16907 You should not rely on @code{LINENO} within @command{eval} or shell 16908 functions, as the behavior differs in practice. The presence of a 16909 quoted newline within simple commands can alter which line number is 16910 used as the starting point for @code{$LINENO} substitutions within that 16911 command. Also, the possibility of the Sed prepass means that you should 16912 not rely on @code{$LINENO} when quoted, when in here-documents, or when 16913 line continuations are used. Subshells should be OK, though. In the 16914 following example, lines 1, 9, and 14 are portable, but the other 16915 instances of @code{$LINENO} do not have deterministic values: 16916 16917 @example 16918 @group 16919 $ @kbd{cat lineno} 16920 echo 1. $LINENO 16921 echo "2. $LINENO 16922 3. $LINENO" 16923 cat <<EOF 16924 5. $LINENO 16925 6. $LINENO 16926 7. \$LINENO 16927 EOF 16928 ( echo 9. $LINENO ) 16929 eval 'echo 10. $LINENO' 16930 eval 'echo 11. $LINENO 16931 echo 12. $LINENO' 16932 echo 13. '$LINENO' 16933 echo 14. $LINENO ' 16934 15.' $LINENO 16935 f () @{ echo $1 $LINENO; 16936 echo $1 $LINENO @} 16937 f 18. 16938 echo 19. \ 16939 $LINENO 16940 @end group 16941 @group 16942 $ @kbd{bash-3.2 ./lineno} 16943 1. 1 16944 2. 3 16945 3. 3 16946 5. 4 16947 6. 4 16948 7. $LINENO 16949 9. 9 16950 10. 10 16951 11. 12 16952 12. 13 16953 13. $LINENO 16954 14. 14 16955 15. 14 16956 18. 16 16957 18. 17 16958 19. 19 16959 @end group 16960 @group 16961 $ @kbd{zsh-4.3.4 ./lineno} 16962 1. 1 16963 2. 2 16964 3. 2 16965 5. 4 16966 6. 4 16967 7. $LINENO 16968 9. 9 16969 10. 1 16970 11. 1 16971 12. 2 16972 13. $LINENO 16973 14. 14 16974 15. 14 16975 18. 0 16976 18. 1 16977 19. 19 16978 @end group 16979 @group 16980 $ @kbd{pdksh-5.2.14 ./lineno} 16981 1. 1 16982 2. 2 16983 3. 2 16984 5. 4 16985 6. 4 16986 7. $LINENO 16987 9. 9 16988 10. 0 16989 11. 0 16990 12. 0 16991 13. $LINENO 16992 14. 14 16993 15. 14 16994 18. 16 16995 18. 17 16996 19. 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} 17011 1. 1 17012 2. 2 17013 3. 3 17014 5. 5 17015 6. 6 17016 7. \7 17017 9. 9 17018 10. 10 17019 11. 11 17020 12. 12 17021 13. 13 17022 14. 14 17023 15. 15 17024 18. 16 17025 18. 17 17026 19. 20 17027 @end group 17028 @end example 17029 17030 In particular, note that @file{config.status} (and any other subsidiary 17031 script created by @code{AS_INIT_GENERATED}) might report line numbers 17032 relative to the parent script as a result of the potential Sed pass. 17033 17034 @item NULLCMD 17035 @evindex NULLCMD 17036 When executing the command @samp{>foo}, @command{zsh} executes 17037 @samp{$NULLCMD >foo} unless it is operating in Bourne shell 17038 compatibility mode and the @command{zsh} version is newer 17039 than 3.1.6-dev-18. If you are using an older @command{zsh} 17040 and forget to set @env{NULLCMD}, 17041 your script might be suspended waiting for data on its standard input. 17042 17043 @item options 17044 @evindex options 17045 For @command{zsh} 4.3.10, @env{options} is treated as an associative 17046 array even after @code{emulate sh}, so it should not be used. 17047 17048 @item PATH_SEPARATOR 17049 @evindex PATH_SEPARATOR 17050 On DJGPP systems, the @env{PATH_SEPARATOR} environment 17051 variable can be set to either @samp{:} or @samp{;} to control the path 17052 separator 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 17055 if you plan to use non-Posix shells to execute files. @xref{File System 17056 Conventions}, for more information about @code{PATH_SEPARATOR}. 17057 17058 @item POSIXLY_CORRECT 17059 @evindex POSIXLY_CORRECT 17060 In the GNU environment, exporting @env{POSIXLY_CORRECT} with any value 17061 (even empty) causes programs to try harder to conform to Posix. 17062 Autoconf does not directly manipulate this variable, but @command{bash} 17063 ties the shell variable @env{POSIXLY_CORRECT} to whether the script is 17064 running in Posix mode. Therefore, take care when exporting or unsetting 17065 this variable, so as not to change whether @command{bash} is in Posix 17066 mode. 17067 17068 @example 17069 $ @kbd{bash --posix -c 'set -o | grep posix} 17070 > @kbd{unset POSIXLY_CORRECT} 17071 > @kbd{set -o | grep posix'} 17072 posix on 17073 posix off 17074 @end example 17075 17076 @item PWD 17077 @evindex PWD 17078 Posix 1003.1-2001 requires that @command{cd} and 17079 @command{pwd} must update the @env{PWD} environment variable to point 17080 to the logical name of the current directory, but traditional shells 17081 do not support this. This can cause confusion if one shell instance 17082 maintains @env{PWD} but a subsidiary and different shell does not know 17083 about @env{PWD} and executes @command{cd}; in this case @env{PWD} 17084 points to the wrong directory. Use @samp{`pwd`} rather than 17085 @samp{$PWD}. 17086 17087 @item RANDOM 17088 @evindex RANDOM 17089 Many shells provide @code{RANDOM}, a variable that returns a different 17090 integer each time it is used. Most of the time, its value does not 17091 change when it is not used, but on IRIX 6.5 the value changes all 17092 the time. This can be observed by using @command{set}. It is common 17093 practice to use @code{$RANDOM} as part of a file name, but code 17094 shouldn't rely on @code{$RANDOM} expanding to a nonempty string. 17095 17096 @item status 17097 @evindex status 17098 This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6), 17099 hence read-only. Do not use it. 17100 @end table 17101 17102 @node Shell Functions 17103 @section Shell Functions 17104 @cindex Shell Functions 17105 17106 Nowadays, it is difficult to find a shell that does not support 17107 shell functions at all. However, some differences should be expected. 17108 17109 When declaring a shell function, you must include whitespace between the 17110 @samp{)} after the function name and the start of the compound 17111 expression, to avoid upsetting @command{ksh}. While it is possible to 17112 use any compound command, most scripts use @samp{@{@dots{}@}}. 17113 17114 @example 17115 $ @kbd{/bin/sh -c 'a()@{ echo hi;@}; a'} 17116 hi 17117 $ @kbd{ksh -c 'a()@{ echo hi;@}; a'} 17118 ksh: syntax error at line 1: `@}' unexpected 17119 $ @kbd{ksh -c 'a() @{ echo hi;@}; a'} 17120 hi 17121 @end example 17122 17123 Inside a shell function, you should not rely on the error status of a 17124 subshell 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 17126 find a shell that does not exhibit the bug, zsh might be the only shell 17127 present on the user's machine. 17128 17129 Likewise, the state of @samp{$?} is not reliable when entering a shell 17130 function. This has the effect that using a function as the first 17131 command 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 $?} 17135 2 17136 2 17137 $ @kbd{ash -c 'foo() @{ echo $?; @}; trap foo 0; (exit 2); exit 2'; echo $?} 17138 0 17139 2 17140 @end example 17141 17142 DJGPP bash 2.04 has a bug in that @command{return} from a 17143 shell function which also used a command substitution causes a 17144 segmentation fault. To work around the issue, you can use 17145 @command{return} from a subshell, or @samp{AS_SET_STATUS} as last command 17146 in the execution flow of the function (@pxref{Common Shell Constructs}). 17147 17148 Not 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'} 17154 oops 17155 @end example 17156 17157 Shell variables and functions may share the same namespace, for example 17158 with Solaris 10 @command{/bin/sh}: 17159 17160 @example 17161 $ @kbd{f () @{ :; @}; f=; f} 17162 f: not found 17163 @end example 17164 17165 @noindent 17166 For this reason, Autoconf (actually M4sh, @pxref{Programming in M4sh}) 17167 uses the prefix @samp{as_fn_} for its functions. 17168 17169 Handling of positional parameters and shell options varies among shells. 17170 For example, Korn shells reset and restore trace output (@samp{set -x}) 17171 and other options upon function entry and exit. Inside a function, 17172 IRIX sh sets @samp{$0} to the function name. 17173 17174 It is not portable to pass temporary environment variables to shell 17175 functions. Solaris @command{/bin/sh} does not see the variable. 17176 Meanwhile, not all shells follow the Posix rule that the assignment must 17177 affect 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 17191 Some ancient Bourne shell variants with function support did not reset 17192 @samp{$@var{i}, @var{i} >= 0}, upon function exit, so effectively the 17193 arguments of the script were lost after the first function invocation. 17194 It is probably not worth worrying about these shells any more. 17195 17196 With AIX sh, a @command{trap} on 0 installed in a shell function 17197 triggers at function exit rather than at script exit. @xref{trap, , 17198 Limitations 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 17205 No, no, we are serious: some shells do have limitations! :) 17206 17207 You should always keep in mind that any builtin or command may support 17208 options, and therefore differ in behavior with arguments 17209 starting with a dash. For instance, even the innocent @samp{echo "$word"} 17210 can give unexpected results when @code{word} starts with a dash. It is 17211 often possible to avoid this problem using @samp{echo "x$word"}, taking 17212 the @samp{x} into account later in the pipe. Many of these limitations 17213 can 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{.} 17221 Use @command{.} only with regular files (use @samp{test -f}). Bash 17222 2.03, for instance, chokes on @samp{. /dev/null}. Remember that 17223 @command{.} uses @env{PATH} if its argument contains no slashes. Also, 17224 some shells, including bash 3.2, implicitly append the current directory 17225 to this @env{PATH} search, even though Posix forbids it. So if you want 17226 to use @command{.} on a file @file{foo} in the current directory, you 17227 must use @samp{. ./foo}. 17228 17229 Not all shells gracefully handle syntax errors within a sourced file. 17230 On one extreme, some non-interactive shells abort the entire script. On 17231 the other, @command{zsh} 4.3.10 has a bug where it fails to react to the 17232 syntax 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' 17239 1 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' 17244 0 17245 @end example 17246 17247 @item @command{!} 17248 @c -------------- 17249 @prindex @command{!} 17250 The Unix version 7 shell did not support 17251 negating the exit status of commands with @command{!}, and this feature 17252 is still absent from some shells (e.g., Solaris @command{/bin/sh}). 17253 Other shells, such as FreeBSD @command{/bin/sh} or @command{ash}, have 17254 bugs when using @command{!}: 17255 17256 @example 17257 $ @kbd{sh -c '! : | :'; echo $?} 17258 1 17259 $ @kbd{ash -c '! : | :'; echo $?} 17260 0 17261 $ @kbd{sh -c '! @{ :; @}'; echo $?} 17262 1 17263 $ @kbd{ash -c '! @{ :; @}'; echo $?} 17264 @{: not found 17265 Syntax error: "@}" unexpected 17266 2 17267 @end example 17268 17269 Shell code like this: 17270 17271 @example 17272 if ! cmp file1 file2 >/dev/null 2>&1; then 17273 echo files differ or trouble 17274 fi 17275 @end example 17276 17277 is therefore not portable in practice. Typically it is easy to rewrite 17278 such code, e.g.: 17279 17280 @example 17281 cmp file1 file2 >/dev/null 2>&1 || 17282 echo files differ or trouble 17283 @end example 17284 17285 More generally, one can always rewrite @samp{! @var{command}} as: 17286 17287 @example 17288 if @var{command}; then (exit 1); else :; fi 17289 @end example 17290 17291 17292 @item @command{@{...@}} 17293 @c -------------------- 17294 @prindex @command{@{...@}} 17295 Bash 3.2 (and earlier versions) sometimes does not properly set 17296 @samp{$?} when failing to write redirected output of a compound command. 17297 This problem is most commonly observed with @samp{@{@dots{}@}}; it does 17298 not occur with @samp{(@dots{})}. For example: 17299 17300 @example 17301 $ @kbd{bash -c '@{ echo foo; @} >/bad; echo $?'} 17302 bash: line 1: /bad: Permission denied 17303 0 17304 $ @kbd{bash -c 'while :; do echo; done >/bad; echo $?'} 17305 bash: line 1: /bad: Permission denied 17306 0 17307 @end example 17308 17309 To work around the bug, prepend @samp{:;}: 17310 17311 @example 17312 $ @kbd{bash -c ':;@{ echo foo; @} >/bad; echo $?'} 17313 bash: line 1: /bad: Permission denied 17314 1 17315 @end example 17316 17317 Posix requires a syntax error if a brace list has no contents. However, 17318 not all shells obey this rule; and on shells where empty lists are 17319 permitted, the effect on @samp{$?} is inconsistent. To avoid problems, 17320 ensure that a brace list is never empty. 17321 17322 @example 17323 $ @kbd{bash -c 'false; @{ @}; echo $?' || echo $?} 17324 bash: line 1: syntax error near unexpected token `@}' 17325 bash: line 1: `false; @{ @}; echo $?' 17326 2 17327 $ @kbd{zsh -c 'false; @{ @}; echo $?' || echo $?} 17328 1 17329 $ @kbd{pdksh -c 'false; @{ @}; echo $?' || echo $?} 17330 0 17331 @end example 17332 17333 17334 @item @command{break} 17335 @c ------------------ 17336 @prindex @command{break} 17337 The use of @samp{break 2} etc.@: is safe. 17338 17339 17340 @anchor{case} 17341 @item @command{case} 17342 @c ----------------- 17343 @prindex @command{case} 17344 You don't need to quote the argument; no splitting is performed. 17345 17346 You don't need the final @samp{;;}, but you should use it. 17347 17348 Posix requires support for @code{case} patterns with opening 17349 parentheses like this: 17350 17351 @example 17352 case $file_name in 17353 (*.c) echo "C source code";; 17354 esac 17355 @end example 17356 17357 @noindent 17358 but the @code{(} in this example is not portable to many Bourne 17359 shell implementations, which is a pity for those of us using tools that 17360 rely 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 17369 The leading @samp{(} can be omitted safely. Unfortunately, there are 17370 contexts where unbalanced parentheses cause other problems, such as when 17371 using a syntax-highlighting editor that searches for the balancing 17372 counterpart, or more importantly, when using a case statement as an 17373 underquoted argument to an Autoconf macro. @xref{Balancing 17374 Parentheses}, for tradeoffs involved in various styles of dealing with 17375 unbalanced @samp{)}. 17376 17377 Zsh handles pattern fragments derived from parameter expansions or 17378 command 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 17383 match 17384 @end example 17385 17386 @noindent 17387 Because of a bug in its @code{fnmatch}, Bash fails to properly 17388 handle backslashes in character classes: 17389 17390 @example 17391 bash-2.02$ @kbd{case /tmp in [/\\]*) echo OK;; esac} 17392 bash-2.02$ 17393 @end example 17394 17395 @noindent 17396 This is extremely unfortunate, since you are likely to use this code to 17397 handle Posix or MS-DOS absolute file names. To work around this 17398 bug, always put the backslash first: 17399 17400 @example 17401 bash-2.02$ @kbd{case '\TMP' in [\\/]*) echo OK;; esac} 17402 OK 17403 bash-2.02$ @kbd{case /tmp in [\\/]*) echo OK;; esac} 17404 OK 17405 @end example 17406 17407 Many Bourne shells cannot handle closing brackets in character classes 17408 correctly. 17409 17410 Some shells also have problems with backslash escaping in case you do not want 17411 to match the backslash: both a backslash and the escaped character match this 17412 pattern. To work around this, specify the character class in a variable, so 17413 that quote removal does not apply afterwards, and the special characters don't 17414 have to be backslash-escaped: 17415 17416 @example 17417 $ @kbd{case '\' in [\<]) echo OK;; esac} 17418 OK 17419 $ @kbd{scanset='[<]'; case '\' in $scanset) echo OK;; esac} 17420 $ 17421 @end example 17422 17423 Even with this, Solaris @command{ksh} matches a backslash if the set 17424 contains any 17425 of the characters @samp{|}, @samp{&}, @samp{(}, or @samp{)}. 17426 17427 Conversely, Tru64 @command{ksh} (circa 2003) erroneously always matches 17428 a closing parenthesis if not specified in a character class: 17429 17430 @example 17431 $ @kbd{case foo in *\)*) echo fail ;; esac} 17432 fail 17433 $ @kbd{case foo in *')'*) echo fail ;; esac} 17434 fail 17435 @end example 17436 17437 Some shells, such as Ash 0.3.8, are confused by an empty 17438 @code{case}/@code{esac}: 17439 17440 @example 17441 ash-0.3.8 $ @kbd{case foo in esac;} 17442 @error{}Syntax error: ";" unexpected (expecting ")") 17443 @end example 17444 17445 Posix requires @command{case} to give an exit status of 0 if no cases 17446 match. However, @command{/bin/sh} in Solaris 10 does not obey this 17447 rule. Meanwhile, it is unclear whether a case that matches, but 17448 contains no statements, must also change the exit status to 0. The M4sh 17449 macro @code{AS_CASE} works around these inconsistencies. 17450 17451 @example 17452 $ @kbd{bash -c 'case `false` in ?) ;; esac; echo $?'} 17453 0 17454 $ @kbd{/bin/sh -c 'case `false` in ?) ;; esac; echo $?'} 17455 255 17456 @end example 17457 17458 17459 @item @command{cd} 17460 @c --------------- 17461 @prindex @command{cd} 17462 Posix 1003.1-2001 requires that @command{cd} must support 17463 the @option{-L} (``logical'') and @option{-P} (``physical'') options, 17464 with @option{-L} being the default. However, traditional shells do 17465 not support these options, and their @command{cd} command has the 17466 @option{-P} behavior. 17467 17468 Portable scripts should assume neither option is supported, and should 17469 assume neither behavior is the default. This can be a bit tricky, 17470 since the Posix default behavior means that, for example, 17471 @samp{ls ..} and @samp{cd ..} may refer to different directories if 17472 the current logical directory is a symbolic link. It is safe to use 17473 @code{cd @var{dir}} if @var{dir} contains no @file{..} components. 17474 Also, Autoconf-generated scripts check for this problem when computing 17475 variables like @code{ac_top_srcdir} (@pxref{Configuration Actions}), 17476 so it is safe to @command{cd} to these variables. 17477 17478 Posix states that behavior is undefined if @command{cd} is given an 17479 explicit empty argument. Some shells do nothing, some change to the 17480 first entry in @env{CDPATH}, some change to @env{HOME}, and some exit 17481 the shell rather than returning an error. Unfortunately, this means 17482 that if @samp{$var} is empty, then @samp{cd "$var"} is less predictable 17483 than @samp{cd $var} (at least the latter is well-behaved in all shells 17484 at changing to @env{HOME}, although this is probably not what you wanted 17485 in a script). You should check that a directory name was supplied 17486 before trying to change locations. 17487 17488 @xref{Special Shell Variables}, for portability problems involving 17489 @command{cd} and the @env{CDPATH} environment variable. 17490 Also please see the discussion of the @command{pwd} command. 17491 17492 17493 @anchor{echo} 17494 @item @command{echo} 17495 @c ----------------- 17496 @prindex @command{echo} 17497 The simple @command{echo} is probably the most surprising source of 17498 portability troubles. It is not possible to use @samp{echo} portably 17499 unless both options and escape sequences are omitted. Don't expect any 17500 option. 17501 17502 Do not use backslashes in the arguments, as there is no consensus on 17503 their handling. For @samp{echo '\n' | wc -l}, the @command{sh} of 17504 Solaris outputs 2, but Bash and Zsh (in @command{sh} emulation mode) output 1. 17505 The problem is truly @command{echo}: all the shells 17506 understand @samp{'\n'} as the string composed of a backslash and an 17507 @samp{n}. Within a command substitution, @samp{echo 'string\c'} will 17508 mess up the internal state of ksh88 on AIX 6.1 so that it will print 17509 the first character @samp{s} only, followed by a newline, and then 17510 entirely drop the output of the next echo in a command substitution. 17511 17512 Because of these problems, do not pass a string containing arbitrary 17513 characters to @command{echo}. For example, @samp{echo "$foo"} is safe 17514 only if you know that @var{foo}'s value cannot contain backslashes and 17515 cannot start with @samp{-}. 17516 17517 If this may not be true, @command{printf} is in general safer and 17518 easier to use than @command{echo} and @command{echo -n}. Thus, scripts 17519 where 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 17522 scripts, instead, it is suggested to use a here-document like this: 17523 17524 @example 17525 cat <<EOF 17526 $foo 17527 EOF 17528 @end example 17529 17530 Alternatively, M4sh provides @code{AS_ECHO} and @code{AS_ECHO_N} macros 17531 which choose between various portable implementations: @samp{echo} 17532 or @samp{print} where they work, @command{printf} if it is available, 17533 or else other creative tricks in order to work around the above problems. 17534 17535 17536 @item @command{eval} 17537 @c ----------------- 17538 @prindex @command{eval} 17539 The @command{eval} command is useful in limited circumstances, e.g., 17540 using commands like @samp{eval table_$key=\$value} and @samp{eval 17541 value=table_$key} to simulate a hash table when the key is known to be 17542 alphanumeric. 17543 17544 You should also be wary of common bugs in @command{eval} implementations. 17545 In 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} 17547 4.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 $?'} 17552 0 17553 @end example 17554 17555 The correct behavior here is to output a nonzero value, 17556 but portable scripts should not rely on this. 17557 17558 You should not rely on @code{LINENO} within @command{eval}. 17559 @xref{Special Shell Variables}. 17560 17561 Note that, even though these bugs are easily avoided, 17562 @command{eval} is tricky to use on arbitrary arguments. 17563 It 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 17565 string value is valid, @samp{eval $cmd} might not work as intended, 17566 since it causes field splitting and file name expansion to occur twice, 17567 once for the @command{eval} and once for the command itself. It is 17568 therefore safer to use @samp{eval "$cmd"}. For example, if @var{cmd} 17569 has the value @samp{cat test?.c}, @samp{eval $cmd} might expand to the 17570 equivalent 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 17572 mistakenly attempts to invoke @command{cat} on the file @file{test} and 17573 then execute the command @command{.c}. To avoid this problem, use 17574 @samp{eval "$cmd"} rather than @samp{eval $cmd}. 17575 17576 However, suppose that you want to output the text of the evaluated 17577 command just before executing it. Assuming the previous example, 17578 @samp{echo "Executing: $cmd"} outputs @samp{Executing: cat test?.c}, but 17579 this output doesn't show the user that @samp{test;.c} is the actual name 17580 of the copied file. Conversely, @samp{eval "echo Executing: $cmd"} 17581 works on this example, but it fails with @samp{cmd='cat foo >bar'}, 17582 since it mistakenly replaces the contents of @file{bar} by the 17583 string @samp{cat foo}. No simple, general, and portable solution to 17584 this problem is known. 17585 17586 @item @command{exec} 17587 @c ----------------- 17588 @prindex @command{exec} 17589 Posix describes several categories of shell built-ins. Special 17590 built-ins (such as @command{exit}) must impact the environment of the 17591 current shell, and need not be available through @command{exec}. All 17592 other built-ins are regular, and must not propagate variable assignments 17593 to the environment of the current shell. However, the group of regular 17594 built-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 17596 are offered as a more efficient version of something that must still be 17597 found in a @env{PATH} search (such as @command{echo}). Posix is not 17598 clear on whether @command{exec} must work with the list of 17 utilities 17599 that are invoked without a @env{PATH} search, and many platforms lack an 17600 executable for some of those built-ins: 17601 17602 @example 17603 $ @kbd{sh -c 'exec cd /tmp'} 17604 sh: line 0: exec: cd: not found 17605 @end example 17606 17607 All other built-ins that provide utilities specified by Posix must have 17608 a counterpart executable that exists on @env{PATH}, although Posix 17609 allows @command{exec} to use the built-in instead of the executable. 17610 For example, contrast @command{bash} 3.2 and @command{pdksh} 5.2.14: 17611 17612 @example 17613 $ @kbd{bash -c 'pwd --version' | head -n1} 17614 bash: line 0: pwd: --: invalid option 17615 pwd: usage: pwd [-LP] 17616 $ @kbd{bash -c 'exec pwd --version' | head -n1} 17617 pwd (GNU coreutils) 6.10 17618 $ @kbd{pdksh -c 'exec pwd --version' | head -n1} 17619 pdksh: pwd: --: unknown option 17620 @end example 17621 17622 When it is desired to avoid a regular shell built-in, the workaround is 17623 to 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} 17629 true (GNU coreutils) 6.10 17630 $ @kbd{pdksh -c 'env true --version' | head -n1} 17631 true (GNU coreutils) 6.10 17632 @end example 17633 17634 @item @command{exit} 17635 @c ----------------- 17636 @prindex @command{exit} 17637 The default value of @command{exit} is supposed to be @code{$?}; 17638 unfortunately, some shells, such as the DJGPP port of Bash 2.04, just 17639 perform @samp{exit 0}. 17640 17641 @example 17642 bash-2.04$ @kbd{foo=`exit 1` || echo fail} 17643 fail 17644 bash-2.04$ @kbd{foo=`(exit 1)` || echo fail} 17645 fail 17646 bash-2.04$ @kbd{foo=`(exit 1); exit` || echo fail} 17647 bash-2.04$ 17648 @end example 17649 17650 Using @samp{exit $?} restores the expected behavior. 17651 17652 Some shell scripts, such as those generated by @command{autoconf}, use a 17653 trap to clean up before exiting. If the last shell command exited with 17654 nonzero status, the trap also exits with nonzero status so that the 17655 invoker can tell that an error occurred. 17656 17657 Unfortunately, in some shells, such as Solaris @command{/bin/sh}, an exit 17658 trap ignores the @code{exit} command's argument. In these shells, a trap 17659 cannot 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} 17668 The builtin @command{export} dubs a shell variable @dfn{environment 17669 variable}. Each update of exported variables corresponds to an update 17670 of the environment variables. Conversely, each environment variable 17671 received by the shell when it is launched should be imported as a shell 17672 variable marked as exported. 17673 17674 Alas, many shells, such as Solaris @command{/bin/sh}, 17675 IRIX 6.3, IRIX 5.2, 17676 AIX 4.1.5, and Digital Unix 4.0, forget to 17677 @command{export} the environment variables they receive. As a result, 17678 two variables coexist: the environment variable and the shell 17679 variable. The following code demonstrates this failure: 17680 17681 @example 17682 #!/bin/sh 17683 echo $FOO 17684 FOO=bar 17685 echo $FOO 17686 exec /bin/sh $0 17687 @end example 17688 17689 @noindent 17690 when run with @samp{FOO=foo} in the environment, these shells print 17691 alternately @samp{foo} and @samp{bar}, although they should print only 17692 @samp{foo} and then a sequence of @samp{bar}s. 17693 17694 Therefore you should @command{export} again each environment variable 17695 that you update; the export can occur before or after the assignment. 17696 17697 Posix is not clear on whether the @command{export} of an undefined 17698 variable causes the variable to be defined with the value of an empty 17699 string, or merely marks any future definition of a variable by that name 17700 for 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'} 17705 foo= 17706 @end example 17707 17708 Posix requires @command{export} to honor assignments made as arguments, 17709 but older shells do not support this, including @command{/bin/sh} in 17710 Solaris 10. Portable scripts should separate assignments and exports 17711 into different statements. 17712 17713 @example 17714 $ @kbd{bash -c 'export foo=bar; echo $foo'} 17715 bar 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'} 17719 bar 17720 @end example 17721 17722 @item @command{false} 17723 @c ------------------ 17724 @prindex @command{false} 17725 Don't expect @command{false} to exit with status 1: in native 17726 Solaris @file{/bin/false} exits with status 255. 17727 17728 17729 @item @command{for} 17730 @c ---------------- 17731 @prindex @command{for} 17732 To loop over positional arguments, use: 17733 17734 @example 17735 for arg 17736 do 17737 echo "$arg" 17738 done 17739 @end example 17740 17741 @noindent 17742 You may @emph{not} leave the @code{do} on the same line as @code{for}, 17743 since some shells improperly grok: 17744 17745 @example 17746 for arg; do 17747 echo "$arg" 17748 done 17749 @end example 17750 17751 If you want to explicitly refer to the positional arguments, given the 17752 @samp{$@@} bug (@pxref{Shell Substitutions}), use: 17753 17754 @example 17755 for arg in $@{1+"$@@"@}; do 17756 echo "$arg" 17757 done 17758 @end example 17759 17760 @noindent 17761 But keep in mind that Zsh, even in Bourne shell emulation mode, performs 17762 word splitting on @samp{$@{1+"$@@"@}}; see @ref{Shell Substitutions}, 17763 item @samp{$@@}, for more. 17764 17765 In Solaris @command{/bin/sh}, when the list of arguments of a 17766 @command{for} loop starts with @emph{unquoted} tokens looking like 17767 variable 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'} 17771 x 17772 e=f 17773 @end example 17774 17775 @noindent 17776 Thankfully, quoting the assignment-like tokens, or starting the list 17777 with other tokens (including unquoted variable expansion that results in 17778 an assignment-like result), avoids the problem, so it is easy to work 17779 around: 17780 17781 @example 17782 $ @kbd{/bin/sh -c 'for v in "a=b"; do echo $v; done'} 17783 a=b 17784 $ @kbd{/bin/sh -c 'x=a=b; for v in $x c=d; do echo $v; done'} 17785 a=b 17786 c=d 17787 @end example 17788 17789 @anchor{if} 17790 @item @command{if} 17791 @c --------------- 17792 @prindex @command{if} 17793 Using @samp{!} is not portable. Instead of: 17794 17795 @example 17796 if ! cmp -s file file.new; then 17797 mv file.new file 17798 fi 17799 @end example 17800 17801 @noindent 17802 use: 17803 17804 @example 17805 if cmp -s file file.new; then :; else 17806 mv file.new file 17807 fi 17808 @end example 17809 17810 @noindent 17811 Or, especially if the @dfn{else} branch is short, you can use @code{||}. 17812 In M4sh, the @code{AS_IF} macro provides an easy way to write these kinds 17813 of conditionals: 17814 17815 @example 17816 AS_IF([cmp -s file file.new], [], [mv file.new file]) 17817 @end example 17818 17819 This is especially useful in other M4 macros, where the @dfn{then} and 17820 @dfn{else} branches might be macro arguments. 17821 17822 Some very old shells did not reset the exit status from an @command{if} 17823 with no @command{else}: 17824 17825 @example 17826 $ @kbd{if (exit 42); then true; fi; echo $?} 17827 42 17828 @end example 17829 17830 @noindent 17831 whereas a proper shell should have printed @samp{0}. But this is no 17832 longer a portability problem; any shell that supports functions gets it 17833 correct. However, it explains why some makefiles have lengthy 17834 constructs: 17835 17836 @example 17837 if test -f "$file"; then 17838 install "$file" "$dest" 17839 else 17840 : 17841 fi 17842 @end example 17843 17844 17845 @item @command{printf} 17846 @c ------------------ 17847 @prindex @command{printf} 17848 A format string starting with a @samp{-} can cause problems. 17849 Bash interprets it as an option and 17850 gives an error. And @samp{--} to mark the end of options is not good 17851 in the NetBSD Almquist shell (e.g., 0.4.6) which takes that 17852 literally as the format string. Putting the @samp{-} in a @samp{%c} 17853 or @samp{%s} is probably easiest: 17854 17855 @example 17856 printf %s -foo 17857 @end example 17858 17859 Bash 2.03 mishandles an escape sequence that happens to evaluate to @samp{%}: 17860 17861 @example 17862 $ @kbd{printf '\045'} 17863 bash: printf: `%': missing format character 17864 @end example 17865 17866 Large outputs may cause trouble. On Solaris 2.5.1 through 10, for 17867 example, @file{/usr/bin/printf} is buggy, so when using 17868 @command{/bin/sh} the command @samp{printf %010000x 123} normally dumps 17869 core. 17870 17871 Since @command{printf} is not always a shell builtin, there is a 17872 potential speed penalty for using @code{printf '%s\n'} as a replacement 17873 for 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 17878 portable alternatives to both @command{printf} and @command{echo}. 17879 17880 17881 @item @command{pwd} 17882 @c ---------------- 17883 @prindex @command{pwd} 17884 With modern shells, plain @command{pwd} outputs a ``logical'' 17885 directory name, some of whose components may be symbolic links. These 17886 directory names are in contrast to ``physical'' directory names, whose 17887 components are all directories. 17888 17889 Posix 1003.1-2001 requires that @command{pwd} must support 17890 the @option{-L} (``logical'') and @option{-P} (``physical'') options, 17891 with @option{-L} being the default. However, traditional shells do 17892 not support these options, and their @command{pwd} command has the 17893 @option{-P} behavior. 17894 17895 Portable scripts should assume neither option is supported, and should 17896 assume neither behavior is the default. Also, on many hosts 17897 @samp{/bin/pwd} is equivalent to @samp{pwd -P}, but Posix 17898 does not require this behavior and portable scripts should not rely on 17899 it. 17900 17901 Typically it's best to use plain @command{pwd}. On modern hosts this 17902 outputs logical directory names, which have the following advantages: 17903 17904 @itemize @bullet 17905 @item 17906 Logical names are what the user specified. 17907 @item 17908 Physical names may not be portable from one installation 17909 host to another due to network file system gymnastics. 17910 @item 17911 On modern hosts @samp{pwd -P} may fail due to lack of permissions to 17912 some parent directory, but plain @command{pwd} cannot fail for this 17913 reason. 17914 @end itemize 17915 17916 Also please see the discussion of the @command{cd} command. 17917 17918 17919 @item @command{read} 17920 @c ----------------- 17921 @prindex @command{read} 17922 No 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 17925 redirected from a non-existent or unreadable file. 17926 17927 17928 @anchor{set} 17929 @item @command{set} 17930 @c ---------------- 17931 @prindex @command{set} 17932 With the FreeBSD 6.0 shell, the @command{set} command (without 17933 any options) does not sort its output. 17934 17935 The @command{set} builtin faces the usual problem with arguments 17936 starting with a 17937 dash. Modern shells such as Bash or Zsh understand @option{--} to specify 17938 the end of the options (any argument after @option{--} is a parameter, 17939 even @samp{-x} for instance), but many traditional shells (e.g., Solaris 17940 10 @command{/bin/sh}) simply stop option 17941 processing 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 17946 set x $my_list; shift 17947 @end example 17948 17949 Avoid @samp{set -}, e.g., @samp{set - $my_list}. Posix no 17950 longer requires support for this command, and in traditional shells 17951 @samp{set - $my_list} resets the @option{-v} and @option{-x} options, which 17952 makes scripts harder to debug. 17953 17954 Some 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 17956 better to combine them: 17957 17958 @example 17959 set -ex 17960 @end example 17961 17962 @cindex @command{set -e} 17963 The option @option{-e} has historically been underspecified, with enough 17964 ambiguities to cause numerous differences across various shell 17965 implementations; see for example 17966 @uref{http://www.in-ulm.de/@/~mascheck/@/various/@/set-e/, this overview}, 17967 or @uref{http://www.austingroupbugs.net/@/view.php?id=52, this link}, 17968 documenting a change to Posix 2008 to match @command{ksh88} behavior. 17969 Note that mixing @code{set -e} and shell functions is asking for surprises: 17970 17971 @example 17972 set -e 17973 doit() 17974 @{ 17975 rm file 17976 echo one 17977 @} 17978 doit || echo two 17979 @end example 17980 17981 @noindent 17982 According to the recommendation, @samp{one} should always be output 17983 regardless of whether the @command{rm} failed, because it occurs within 17984 the 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. 17986 Likewise, @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 17990 The BSD shell has had several problems with the @option{-e} 17991 option. Older versions of the BSD 17992 shell (circa 1990) mishandled @samp{&&}, @samp{||}, @samp{if}, and 17993 @samp{case} when @option{-e} was in effect, causing the shell to exit 17994 unexpectedly in some cases. This was particularly a problem with 17995 makefiles, and led to circumlocutions like @samp{sh -c 'test -f file || 17996 touch file'}, where the seemingly-unnecessary @samp{sh -c '@dots{}'} 17997 wrapper works around the bug (@pxref{Failure in Make Rules}). 17998 17999 Even relatively-recent versions of the BSD shell (e.g., OpenBSD 3.4) 18000 wrongly exit with @option{-e} if the last command within a compound 18001 statement fails and is guarded by an @samp{&&} only. For example: 18002 18003 @example 18004 #! /bin/sh 18005 set -e 18006 foo='' 18007 test -n "$foo" && exit 1 18008 echo one 18009 if :; then 18010 test -n "$foo" && exit 1 18011 echo two 18012 test -n "$foo" && exit 1 18013 fi 18014 echo three 18015 @end example 18016 18017 @noindent 18018 does not print @samp{three}. One workaround is to change the last 18019 instance 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 18021 users not to use @samp{sh -e}. 18022 18023 When @samp{set -e} is in effect, a failed command substitution in 18024 Solaris @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'} 18029 foo 18030 bar 18031 @end example 18032 18033 @noindent 18034 Moreover, a command substitution, successful or not, causes this shell to 18035 exit 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'} 18039 ok 18040 $ @kbd{sh -c 'set -e; false `true` && echo notreached; echo ok'} 18041 $ 18042 @end example 18043 18044 Portable scripts should not use @samp{set -e} if @command{trap} is used 18045 to install an exit handler. This is because Tru64/OSF 5.1 @command{sh} 18046 sometimes enters the trap handler with the exit status of the command 18047 prior to the one that triggered the errexit handler: 18048 18049 @example 18050 $ @kbd{sh -ec 'trap '\''echo $?'\'' 0; false'} 18051 0 18052 $ @kbd{sh -c 'set -e; trap '\''echo $?'\'' 0; false'} 18053 1 18054 @end example 18055 18056 @noindent 18057 Thus, 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 18059 statement where it is desirable to abort on failure. 18060 18061 @cindex @command{set -b} 18062 @cindex @command{set -m} 18063 Job control is not provided by all shells, so the use of @samp{set -m} 18064 or @samp{set -b} must be done with care. When using @command{zsh} in 18065 native mode, asynchronous notification (@samp{set -b}) is enabled by 18066 default, and using @samp{emulate sh} to switch to Posix mode does not 18067 clear this setting (although asynchronous notification has no impact 18068 unless job monitoring is also enabled). Also, @command{zsh} 4.3.10 and 18069 earlier have a bug where job control can be manipulated in interactive 18070 shells, but not in subshells or scripts. Furthermore, some shells, like 18071 @command{pdksh}, fail to treat subshells as interactive, even though the 18072 parent shell was. 18073 18074 @example 18075 $ @kbd{echo $ZSH_VERSION} 18076 4.3.10 18077 $ @kbd{set -m; echo $?} 18078 0 18079 $ @kbd{zsh -c 'set -m; echo $?'} 18080 set: can't change option: -m 18081 $ @kbd{(set -m); echo $?} 18082 set: can't change option: -m 18083 1 18084 $ @kbd{pdksh -ci 'echo $-; (echo $-)'} 18085 cim 18086 c 18087 @end example 18088 18089 @cindex @command{set -n} 18090 Use of @command{set -n} (typically via @command{sh -n script}) to 18091 validate a script is not foolproof. Modern @command{ksh93} tries to be 18092 helpful by informing you about better syntax, but switching the script 18093 to use the suggested syntax in order to silence the warnings would 18094 render the script no longer portable to older shells: 18095 18096 @example 18097 $ @kbd{ksh -nc '``'} 18098 ksh: warning: line 1: `...` obsolete, use $(...) 18099 0 18100 @end example 18101 18102 Furthermore, on ancient hosts, such as SunOS 4, @command{sh -n} could go 18103 into an infinite loop; even with that bug fixed, Solaris 8 18104 @command{/bin/sh} takes extremely long to parse large scripts. Autoconf 18105 itself uses @command{sh -n} within its testsuite to check that correct 18106 scripts were generated, but only after first probing for other shell 18107 features (such as @code{test -n "$@{BASH_VERSION+set@}"}) that indicate 18108 a reasonably fast and working implementation. 18109 18110 @item @command{shift} 18111 @c ------------------ 18112 @prindex @command{shift} 18113 Not only is @command{shift}ing a bad idea when there is nothing left to 18114 shift, but in addition it is not portable: the shell of MIPS 18115 RISC/OS 4.52 refuses to do it. 18116 18117 Don't use @samp{shift 2} etc.; while it in the SVR1 shell (1983), 18118 it is also absent in many pre-Posix shells. 18119 18120 18121 @item @command{source} 18122 @c ------------------- 18123 @prindex @command{source} 18124 This 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} 18131 The @code{test} program is the way to perform many file and string 18132 tests. It is often invoked by the alternate name @samp{[}, but using 18133 that name in Autoconf code is asking for trouble since it is an M4 quote 18134 character. 18135 18136 The @option{-a}, @option{-o}, @samp{(}, and @samp{)} operands are not 18137 present in all implementations, and have been marked obsolete by Posix 18138 2008. This is because there are inherent ambiguities in using them. 18139 For example, @samp{test "$1" -a "$2"} looks like a binary operator to 18140 check whether two strings are both non-empty, but if @samp{$1} is the 18141 literal @samp{!}, then some implementations of @command{test} treat it 18142 as a negation of the unary operator @option{-a}. 18143 18144 Thus, portable uses of @command{test} should never have more than four 18145 arguments, and scripts should use shell constructs like @samp{&&} and 18146 @samp{||} instead. If you combine @samp{&&} and @samp{||} in the same 18147 statement, keep in mind that they have equal precedence, so it is often 18148 better to parenthesize even when this is redundant. For example: 18149 18150 @smallexample 18151 # Not portable: 18152 test "X$a" = "X$b" -a \ 18153 '(' "X$c" != "X$d" -o "X$e" = "X$f" ')' 18154 18155 # Portable: 18156 test "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 18161 example, it does not recognize the @option{--} argument as marking the 18162 end of options. 18163 18164 It 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 ------------------------- 18171 To enable @command{configure} scripts to support cross-compilation, they 18172 shouldn't do anything that tests features of the build system instead of 18173 the host system. But occasionally you may find it necessary to check 18174 whether 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 18176 Solaris 10 @command{/bin/sh} 18177 lacks 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 18179 Posix 1003.1-2001, but older shells like Solaris 8 18180 @code{/bin/sh} support only @option{-h}. 18181 18182 For historical reasons, Posix reluctantly allows implementations of 18183 @samp{test -x} that will succeed for the root user, even if no execute 18184 permissions are present. Furthermore, shells do not all agree on 18185 whether Access Control Lists should affect @samp{test -r}, @samp{test 18186 -w}, and @samp{test -x}; some shells base test results strictly on the 18187 current user id compared to file owner and mode, as if by 18188 @code{stat(2)}; while other shells base test results on whether the 18189 current user has the given right, even if that right is only granted by 18190 an ACL, as if by @code{faccessat(2)}. Furthermore, there is a classic 18191 time of check to time of use race between any use of @command{test} 18192 followed by operating on the just-checked file. Therefore, it is a good 18193 idea to write scripts that actually attempt an operation, and are 18194 prepared for the resulting failure if permission is denied, rather than 18195 trying to avoid an operation based solely on whether @command{test} 18196 guessed that it might not be permitted. 18197 18198 @item @command{test} (strings) 18199 @c --------------------------- 18200 Posix says that @samp{test "@var{string}"} succeeds if @var{string} is 18201 not null, but this usage is not portable to traditional platforms like 18202 Solaris 10 @command{/bin/sh}, which mishandle strings like @samp{!} and 18203 @samp{-n}. 18204 18205 Posix 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 18208 shells (such as Solaris, AIX 3.2, UNICOS 10.0.0.6, 18209 Digital Unix 4, etc.)@: get confused if 18210 @var{string} looks like an operator: 18211 18212 @example 18213 $ @kbd{test -n =} 18214 test: argument expected 18215 $ @kbd{test ! -n} 18216 test: argument expected 18217 $ @kbd{test -z ")"; echo $?} 18218 0 18219 @end example 18220 18221 Similarly, Posix says that both @samp{test "@var{string1}" = "@var{string2"}} 18222 and @samp{test "@var{string1}" != "@var{string2"}} work for any pairs of 18223 strings, but in practice this is not true for troublesome strings that 18224 look like operators or parentheses, or that begin with @samp{-}. 18225 18226 It 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 18230 It is common to find variations of the following idiom: 18231 18232 @example 18233 test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" && 18234 @var{action} 18235 @end example 18236 18237 @noindent 18238 to take an action when a token matches a given pattern. Such constructs 18239 should be avoided by using: 18240 18241 @example 18242 case $ac_feature in 18243 *[!-a-zA-Z0-9_]*) @var{action};; 18244 esac 18245 @end example 18246 18247 If the pattern is a complicated regular expression that cannot be 18248 expressed as a shell pattern, use something like this instead: 18249 18250 @example 18251 expr "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} 18264 It is safe to trap at least the signals 1, 2, 13, and 15. You can also 18265 trap 0, i.e., have the @command{trap} run when the script ends (either via an 18266 explicit @command{exit}, or the end of the script). The trap for 0 should be 18267 installed outside of a shell function, or AIX 5.3 @command{/bin/sh} 18268 will invoke the trap at the end of this function. 18269 18270 Posix says that @samp{trap - 1 2 13 15} resets the traps for the 18271 specified signals to their default values, but many common shells (e.g., 18272 Solaris @command{/bin/sh}) misinterpret this and attempt to execute a 18273 ``command'' named @command{-} when the specified conditions arise. 18274 Posix 2008 also added a requirement to support @samp{trap 1 2 13 15} to 18275 reset traps, as this is supported by a larger set of shells, but there 18276 are still shells like @command{dash} that mistakenly try to execute 18277 @command{1} instead of resetting the traps. Therefore, there is no 18278 portable workaround, except for @samp{trap - 0}, for which 18279 @samp{trap '' 0} is a portable substitute. 18280 18281 Although Posix is not absolutely clear on this point, it is widely 18282 admitted that when entering the trap @samp{$?} should be set to the exit 18283 status of the last command run before the trap. The ambiguity can be 18284 summarized as: ``when the trap is launched by an @command{exit}, what is 18285 the @emph{last} command run: that before @command{exit}, or 18286 @command{exit} itself?'' 18287 18288 Bash considers @command{exit} to be the last command, while Zsh and 18289 Solaris @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 18291 that the trap receives: 18292 18293 @example 18294 $ @kbd{cat trap.sh} 18295 trap 'echo $?' 0 18296 (exit 42); exit 0 18297 $ @kbd{zsh trap.sh} 18298 42 18299 $ @kbd{bash trap.sh} 18300 0 18301 @end example 18302 18303 The portable solution is then simple: when you want to @samp{exit 42}, 18304 run @samp{(exit 42); exit 42}, the first @command{exit} being used to 18305 set the exit status to 42 for Zsh, and the second to trigger the trap 18306 and pass 42 as exit status for Bash. In M4sh, this is covered by using 18307 @code{AS_EXIT}. 18308 18309 The shell in FreeBSD 4.0 has the following bug: @samp{$?} is 18310 reset to 0 by empty lines if the code is inside @command{trap}. 18311 18312 @example 18313 $ @kbd{trap 'false} 18314 18315 echo $?' 0 18316 $ @kbd{exit} 18317 0 18318 @end example 18319 18320 @noindent 18321 Fortunately, this bug only affects @command{trap}. 18322 18323 Several shells fail to execute an exit trap that is defined inside a 18324 subshell, when the last command of that subshell is not a builtin. A 18325 workaround is to use @samp{exit $?} as the shell builtin. 18326 18327 @example 18328 $ @kbd{bash -c '(trap "echo hi" 0; /bin/true)'} 18329 hi 18330 $ @kbd{/bin/sh -c '(trap "echo hi" 0; /bin/true)'} 18331 $ @kbd{/bin/sh -c '(trap "echo hi" 0; /bin/true; exit $?)'} 18332 hi 18333 @end example 18334 18335 @noindent 18336 Likewise, 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 $?} 18341 2 18342 $ @kbd{bash-2.05b -c 'trap "/bin/true" 0; exit 2'; echo $?} 18343 0 18344 $ @kbd{bash-2.05b -c 'trap ":; /bin/true" 0; exit 2'; echo $?} 18345 2 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{:} 18353 Don't worry: as far as we know @command{true} is portable. 18354 Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the 18355 portable shell community tends to prefer using @command{:}. This has a 18356 funny side effect: when asked whether @command{false} is more portable 18357 than @command{true} Alexandre Oliva answered: 18358 18359 @quotation 18360 In a sense, yes, because if it doesn't exist, the shell will produce an 18361 exit status of failure, which is correct for @command{false}, but not 18362 for @command{true}. 18363 @end quotation 18364 18365 Remember that even though @samp{:} ignores its arguments, it still takes 18366 time to compute those arguments. It is a good idea to use double quotes 18367 around any arguments to @samp{:} to avoid time spent in field splitting 18368 and file name expansion. 18369 18370 18371 @anchor{unset} 18372 @item @command{unset} 18373 @c ------------------ 18374 @prindex @command{unset} 18375 In 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 18378 with @code{set -e} operation. You can use 18379 18380 @smallexample 18381 FOO=; unset FOO 18382 @end smallexample 18383 18384 @noindent 18385 if you are not sure that @code{FOO} is set. 18386 18387 A few ancient shells lack @command{unset} entirely. For some variables 18388 such as @code{PS1}, you can use a neutralizing value instead: 18389 18390 @smallexample 18391 PS1='$ ' 18392 @end smallexample 18393 18394 Usually, shells that do not support @command{unset} need less effort to 18395 make the environment sane, so for example is not a problem if you cannot 18396 unset @command{CDPATH} on those shells. However, Bash 2.01 mishandles 18397 @code{unset MAIL} and @code{unset MAILPATH} in some cases and dumps core. 18398 So, 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 18407 the case of environment variables. 18408 18409 @item @command{wait} 18410 @c ----------------- 18411 @prindex @command{wait} 18412 The 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 18419 The small set of tools you can expect to find on any machine can still 18420 include 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} 18433 Don't leave white space before the opening parenthesis in a user function call. 18434 Posix does not allow this and GNU Awk rejects it: 18435 18436 @example 18437 $ @kbd{gawk 'function die () @{ print "Aaaaarg!" @} 18438 BEGIN @{ die () @}'} 18439 gawk: cmd. line:2: BEGIN @{ die () @} 18440 gawk: cmd. line:2: ^ parse error 18441 $ @kbd{gawk 'function die () @{ print "Aaaaarg!" @} 18442 BEGIN @{ die() @}'} 18443 Aaaaarg! 18444 @end example 18445 18446 Posix says that if a program contains only @samp{BEGIN} actions, and 18447 contains no instances of @code{getline}, then the program merely 18448 executes the actions without reading input. However, traditional Awk 18449 implementations (such as Solaris 10 @command{awk}) read and discard 18450 input in this case. Portable scripts can redirect input from 18451 @file{/dev/null} to work around the problem. For example: 18452 18453 @example 18454 awk 'BEGIN @{print "hello world"@}' </dev/null 18455 @end example 18456 18457 Posix says that in an @samp{END} action, @samp{$NF} (and presumably, 18458 @samp{$1}) retain their value from the last record read, if no 18459 intervening @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 18462 intermediate variable prior to the @samp{END} block. For example: 18463 18464 @example 18465 $ @kbd{cat end.awk} 18466 @{ tmp = $1 @} 18467 END @{ print "a", $1, $NF, "b", tmp @} 18468 $ @kbd{echo 1 | awk -f end.awk} 18469 a b 1 18470 $ @kbd{echo 1 | gawk -f end.awk} 18471 a 1 1 b 1 18472 @end example 18473 18474 If you want your program to be deterministic, don't depend on @code{for} 18475 on arrays: 18476 18477 @example 18478 $ @kbd{cat for.awk} 18479 END @{ 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} 18486 foo 18487 bar 18488 $ @kbd{nawk -f for.awk </dev/null} 18489 bar 18490 foo 18491 @end example 18492 18493 Some Awk implementations, such as HP-UX 11.0's native one, 18494 mishandle anchors: 18495 18496 @example 18497 $ @kbd{echo xfoo | $AWK '/foo|^bar/ @{ print @}'} 18498 $ @kbd{echo bar | $AWK '/foo|^bar/ @{ print @}'} 18499 bar 18500 $ @kbd{echo xfoo | $AWK '/^bar|foo/ @{ print @}'} 18501 xfoo 18502 $ @kbd{echo bar | $AWK '/^bar|foo/ @{ print @}'} 18503 bar 18504 @end example 18505 18506 @noindent 18507 Either do not depend on such patterns (i.e., use @samp{/^(.*foo|bar)/}, 18508 or use a simple test to reject such implementations. 18509 18510 On @samp{ia64-hp-hpux11.23}, Awk mishandles @code{printf} conversions 18511 after @code{%u}: 18512 18513 @example 18514 $ @kbd{awk 'BEGIN @{ printf "%u %d\n", 0, -1 @}'} 18515 0 0 18516 @end example 18517 18518 AIX version 5.2 has an arbitrary limit of 399 on the 18519 length of regular expressions and literal strings in an Awk program. 18520 18521 Traditional Awk implementations derived from Unix version 7, such as 18522 Solaris @command{/bin/awk}, have many limitations and do not 18523 conform to Posix. Nowadays @code{AC_PROG_AWK} (@pxref{Particular 18524 Programs}) finds you an Awk that doesn't have these problems, but if 18525 for some reason you prefer not to use @code{AC_PROG_AWK} you may need to 18526 address them. For more detailed descriptions, see @ref{Language 18527 History, , @command{awk} language history, gawk, GNU Awk User's Guide}. 18528 18529 Traditional Awk does not support multidimensional arrays or user-defined 18530 functions. 18531 18532 Traditional Awk does not support the @option{-v} option. You can use 18533 assignments after the program instead, e.g., @code{$AWK '@{print v 18534 $1@}' v=x}; however, don't forget that such assignments are not 18535 evaluated until they are encountered (e.g., after any @code{BEGIN} 18536 action). 18537 18538 Traditional Awk does not support the keywords @code{delete} or @code{do}. 18539 18540 Traditional Awk does not support the expressions 18541 @code{@var{a}?@var{b}:@var{c}}, @code{!@var{a}}, @code{@var{a}^@var{b}}, 18542 or @code{@var{a}^=@var{b}}. 18543 18544 Traditional Awk does not support the predefined @code{CONVFMT} or 18545 @code{ENVIRON} variables. 18546 18547 Traditional 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 18551 Traditional Awk @code{getline} is not at all compatible with Posix; 18552 avoid it. 18553 18554 Traditional 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 18557 In code portable to both traditional and modern Awk, @code{FS} must be a 18558 string containing just one ordinary character, and similarly for the 18559 field-separator argument to @code{split}. 18560 18561 Traditional Awk has a limit of 99 fields in a record. Since some Awk 18562 implementations, like Tru64's, split the input even if you don't refer 18563 to any field in the script, to circumvent this problem, set @samp{FS} 18564 to an unusual character and use @code{split}. 18565 18566 Traditional 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 18568 dumps core. 18569 18570 The 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 18572 per run of non-special characters in a @code{printf} format, but these 18573 bugs have been fixed on all practical hosts that we know of. 18574 18575 HP-UX 11.00 and IRIX 6.5 Awk require that input files have a line length 18576 of at most 3070 bytes. 18577 18578 @item @command{basename} 18579 @c --------------------- 18580 @prindex @command{basename} 18581 Not all hosts have a working @command{basename}. 18582 You can use @command{expr} instead. 18583 18584 @c AS_BASENAME is to be replaced by a better API. 18585 @ignore 18586 Not all hosts have a working @command{basename}, and you should instead 18587 use @code{AS_BASENAME} (@pxref{Programming in M4sh}), followed by 18588 @command{expr} if you need to strip a suffix. For example: 18589 18590 @example 18591 a=`basename "$aname"` # This is not portable. 18592 a=`AS_BASENAME(["$aname"])` # This is more portable. 18593 18594 # This is not portable. 18595 c=`basename "$cname" .c` 18596 18597 # This is more portable. 18598 c=`AS_BASENAME(["$cname"])` 18599 case $c in 18600 ?*.c) c=`expr "X$c" : 'X\(.*\)\.c'`;; 18601 esac 18602 @end example 18603 @end ignore 18604 18605 18606 @item @command{cat} 18607 @c ---------------- 18608 @prindex @command{cat} 18609 Don't rely on any option. 18610 18611 18612 @item @command{cc} 18613 @c --------------- 18614 @prindex @command{cc} 18615 The command @samp{cc -c foo.c} traditionally produces an object file 18616 named @file{foo.o}. Most compilers allow @option{-c} to be combined 18617 with @option{-o} to specify a different object file name, but 18618 Posix does not require this combination and a few compilers 18619 lack support for it. @xref{C Compiler}, for how GNU Make 18620 tests for this feature with @code{AC_PROG_CC_C_O}. 18621 18622 When 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 18625 HP-UX @command{cc} doesn't accept @file{.S} files to preprocess and 18626 assemble. @samp{cc -c foo.S} appears to succeed, but in fact does 18627 nothing. 18628 18629 The 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 18639 The C compiler's traditional name is @command{cc}, but other names like 18640 @command{gcc} are common. Posix 1003.1-2001 specifies the 18641 name @command{c99}, but older Posix editions specified 18642 @command{c89} and anyway these standard names are rarely used in 18643 practice. Typically the C compiler is invoked from makefiles that use 18644 @samp{$(CC)}, so the value of the @samp{CC} make variable selects the 18645 compiler name. 18646 18647 @item @command{chgrp} 18648 @itemx @command{chown} 18649 @c ------------------- 18650 @prindex @command{chgrp} 18651 @prindex @command{chown} 18652 It is not portable to change a file's group to a group that the owner 18653 does not belong to. 18654 18655 @item @command{chmod} 18656 @c ------------------ 18657 @prindex @command{chmod} 18658 Avoid usages like @samp{chmod -w file}; use @samp{chmod a-w file} 18659 instead, for two reasons. First, plain @option{-w} does not necessarily 18660 make the file unwritable, since it does not affect mode bits that 18661 correspond to bits in the file mode creation mask. Second, 18662 Posix says that the @option{-w} might be interpreted as an 18663 implementation-specific option, not as a mode; Posix suggests 18664 using @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 18673 DOS files, even if only checking whether two files are different, use 18674 @command{diff} to avoid spurious differences due to differences of 18675 newline encoding. 18676 18677 18678 @item @command{cp} 18679 @c --------------- 18680 @prindex @command{cp} 18681 Avoid the @option{-r} option, since Posix 1003.1-2004 marks it as 18682 obsolescent and its behavior on special files is implementation-defined. 18683 Use @option{-R} instead. On GNU hosts the two options 18684 are equivalent, but on Solaris hosts (for example) @code{cp -r} 18685 reads from pipes instead of replicating them. AIX 5.3 @code{cp -R} may 18686 corrupt its own memory with some directory hierarchies and error out or 18687 dump core: 18688 18689 @example 18690 @kbd{mkdir -p 12345678/12345678/12345678/12345678} 18691 @kbd{touch 12345678/12345678/x} 18692 @kbd{cp -R 12345678 t} 18693 cp: 0653-440 12345678/12345678/: name too long. 18694 @end example 18695 18696 Some @command{cp} implementations (e.g., BSD/OS 4.2) do not allow 18697 trailing slashes at the end of nonexistent destination directories. To 18698 avoid 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. 18703 The ancient SunOS 4 @command{cp} does not support @option{-f}, although 18704 its @command{mv} does. 18705 18706 @cindex timestamp resolution 18707 Traditionally, file timestamps had 1-second resolution, and @samp{cp 18708 -p} copied the timestamps exactly. However, many modern file systems 18709 have timestamps with 1-nanosecond resolution. Unfortunately, some older 18710 @samp{cp -p} implementations truncate timestamps when copying files, 18711 which can cause the destination file to appear to be older than the 18712 source. The exact amount of truncation depends on the resolution of 18713 the system calls that @command{cp} uses. Traditionally this was 18714 @code{utime}, which has 1-second resolution. Less-ancient @command{cp} 18715 implementations such as GNU Core Utilities 5.0.91 (2003) use 18716 @code{utimes}, which has 1-microsecond resolution. Modern 18717 implementations such as GNU Core Utilities 6.12 (2008) can set timestamps to 18718 the full nanosecond resolution, using the modern system calls 18719 @code{futimens} and @code{utimensat} when they are available. As of 18720 2011, though, many platforms do not yet fully support these new system 18721 calls. 18722 18723 Bob Proulx notes that @samp{cp -p} always @emph{tries} to copy 18724 ownerships. But whether it actually does copy ownerships or not is a 18725 system dependent policy decision implemented by the kernel. If the 18726 kernel allows it then it happens. If the kernel does not allow it then 18727 it does not happen. It is not something @command{cp} itself has control 18728 over. 18729 18730 In Unix System V any user can chown files to any other user, and System 18731 V also has a non-sticky @file{/tmp}. That probably derives from the 18732 heritage of System V in a business environment without hostile users. 18733 BSD changed this 18734 to be a more secure model where only root can @command{chown} files and 18735 a sticky @file{/tmp} is used. That undoubtedly derives from the heritage 18736 of BSD in a campus environment. 18737 18738 GNU/Linux and Solaris by default follow BSD, but 18739 can be configured to allow a System V style @command{chown}. On the 18740 other hand, HP-UX follows System V, but can 18741 be configured to use the modern security model and disallow 18742 @command{chown}. Since it is an administrator-configurable parameter 18743 you 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} 18750 Some versions of @command{date} do not recognize special @samp{%} directives, 18751 and unfortunately, instead of complaining, they just pass them through, 18752 and exit with success: 18753 18754 @example 18755 $ @kbd{uname -a} 18756 OSF1 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} 18765 Option @option{-u} is nonportable. 18766 18767 Some 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} 18774 Not all hosts have a working @command{dirname}, and you should instead 18775 use @code{AS_DIRNAME} (@pxref{Programming in M4sh}). For example: 18776 18777 @example 18778 dir=`dirname "$file"` # This is not portable. 18779 dir=`AS_DIRNAME(["$file"])` # This is more portable. 18780 @end example 18781 18782 18783 @item @command{egrep} 18784 @c ------------------ 18785 @prindex @command{egrep} 18786 Posix 1003.1-2001 no longer requires @command{egrep}, 18787 but many hosts do not yet support the Posix 18788 replacement @code{grep -E}. Also, some traditional implementations do 18789 not work on long input lines. To work around these problems, invoke 18790 @code{AC_PROG_EGREP} and then use @code{$EGREP}. 18791 18792 Portable extended regular expressions should use @samp{\} only to escape 18793 characters in the string @samp{$()*+.?[\^@{|}. For example, @samp{\@}} 18794 is not portable, even though it typically matches @samp{@}}. 18795 18796 The empty alternative is not portable. Use @samp{?} instead. For 18797 instance 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|)$' 18803 bar| 18804 > printf "foo\nfoo|\n|bar\nbar\n" | $EGREP '^(foo||bar)$' 18805 foo 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} 18815 Not all implementations obey the Posix rule that @samp{--} separates 18816 options from arguments; likewise, not all implementations provide the 18817 extension to Posix that the first argument can be treated as part of a 18818 valid 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 18821 interpreting it as an option. 18822 18823 No @command{expr} keyword starts with @samp{X}, so use @samp{expr 18824 X"@var{word}" : 'X@var{regex}'} to keep @command{expr} from 18825 misinterpreting @var{word}. 18826 18827 Don't use @code{length}, @code{substr}, @code{match} and @code{index}. 18828 18829 @item @command{expr} (@samp{|}) 18830 @prindex @command{expr} (@samp{|}) 18831 You 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 18834 example: 18835 18836 @example 18837 expr '' \| '' 18838 @end example 18839 18840 Posix 1003.2-1992 returns the empty string 18841 for this case, but traditional Unix returns @samp{0} (Solaris is 18842 one such example). In Posix 1003.1-2001, the specification was 18843 changed to match traditional Unix's behavior (which is 18844 bizarre, but it's too late to fix this). Please note that the same 18845 problem does arise when the empty string results from a computation, 18846 as in: 18847 18848 @example 18849 expr bar : foo \| foo : bar 18850 @end example 18851 18852 @noindent 18853 Avoid this portability problem by avoiding the empty string. 18854 18855 18856 @item @command{expr} (@samp{:}) 18857 @c ---------------------------- 18858 @prindex @command{expr} 18859 Portable @command{expr} regular expressions should use @samp{\} to 18860 escape only characters in the string @samp{$()*.0123456789[\^n@{@}}. 18861 For example, alternation, @samp{\|}, is common but Posix does not 18862 require its support, so it should be avoided in portable scripts. 18863 Similarly, @samp{\+} and @samp{\?} should be avoided. 18864 18865 Portable @command{expr} regular expressions should not begin with 18866 @samp{^}. Patterns are automatically anchored so leading @samp{^} is 18867 not needed anyway. 18868 18869 On the other hand, the behavior of the @samp{$} anchor is not portable 18870 on multi-line strings. Posix is ambiguous whether the anchor applies to 18871 each line, as was done in older versions of the GNU Core Utilities, or 18872 whether it applies only to the end of the overall string, as in 18873 Coreutils 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\)$'} 18881 foo 18882 @end example 18883 18884 The Posix standard is ambiguous as to whether 18885 @samp{expr 'a' : '\(b\)'} outputs @samp{0} or the empty string. 18886 In practice, it outputs the empty string on most platforms, but portable 18887 scripts should not assume this. For instance, the QNX 4.25 native 18888 @command{expr} returns @samp{0}. 18889 18890 One might think that a way to get a uniform behavior would be to use 18891 the empty string as a default value: 18892 18893 @example 18894 expr a : '\(b\)' \| '' 18895 @end example 18896 18897 @noindent 18898 Unfortunately this behaves exactly as the original expression; see the 18899 @command{expr} (@samp{|}) entry for more information. 18900 18901 Some ancient @command{expr} implementations (e.g., SunOS 4 @command{expr} and 18902 Solaris 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 18904 bytes. 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 18906 the rare installer who mistakenly puts @file{/usr/ucb} before 18907 @file{/usr/bin} in @env{PATH}. 18908 18909 On Mac OS X 10.4, @command{expr} mishandles the pattern @samp{[^-]} in 18910 some cases. For example, the command 18911 @example 18912 expr Xpowerpc-apple-darwin8.1.0 : 'X[^-]*-[^-]*-\(.*\)' 18913 @end example 18914 18915 @noindent 18916 outputs @samp{apple-darwin8.1.0} rather than the correct @samp{darwin8.1.0}. 18917 This particular case can be worked around by substituting @samp{[^--]} 18918 for @samp{[^-]}. 18919 18920 Don't leave, there is some more! 18921 18922 The QNX 4.25 @command{expr}, in addition of preferring @samp{0} to 18923 the empty string, has a funny behavior in its exit status: it's always 1 18924 when parentheses are used! 18925 18926 @example 18927 $ @kbd{val=`expr 'a' : 'a'`; echo "$?: $val"} 18928 0: 1 18929 $ @kbd{val=`expr 'a' : 'b'`; echo "$?: $val"} 18930 1: 0 18931 18932 $ @kbd{val=`expr 'a' : '\(a\)'`; echo "?: $val"} 18933 1: a 18934 $ @kbd{val=`expr 'a' : '\(b\)'`; echo "?: $val"} 18935 1: 0 18936 @end example 18937 18938 @noindent 18939 In practice this can be a big problem if you are ready to catch failures 18940 of @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 18948 outputs @samp{a} on most hosts, but @samp{aa} on QNX 4.25. A 18949 simple workaround consists of testing @command{expr} and using a variable 18950 set to @command{expr} or to @command{false} according to the result. 18951 18952 Tru64 @command{expr} incorrectly treats the result as a number, if it 18953 can be interpreted that way: 18954 18955 @example 18956 $ @kbd{expr 00001 : '.*\(...\)'} 18957 1 18958 @end example 18959 18960 On HP-UX 11, @command{expr} only supports a single 18961 sub-expression. 18962 18963 @example 18964 $ @kbd{expr 'Xfoo' : 'X\(f\(oo\)*\)$'} 18965 expr: More than one '\(' was used. 18966 @end example 18967 18968 18969 @item @command{fgrep} 18970 @c ------------------ 18971 @prindex @command{fgrep} 18972 Posix 1003.1-2001 no longer requires @command{fgrep}, 18973 but many hosts do not yet support the Posix 18974 replacement @code{grep -F}. Also, some traditional implementations do 18975 not work on long input lines. To work around these problems, invoke 18976 @code{AC_PROG_FGREP} and then use @code{$FGREP}. 18977 18978 Tru64/OSF 5.1 @command{fgrep} does not match an empty pattern. 18979 18980 18981 @item @command{find} 18982 @c ----------------- 18983 @prindex @command{find} 18984 The option @option{-maxdepth} seems to be GNU specific. 18985 Tru64 v5.1, NetBSD 1.5 and Solaris @command{find} 18986 commands do not understand it. 18987 18988 The replacement of @samp{@{@}} is guaranteed only if the argument is 18989 exactly @emph{@{@}}, not if it's only a part of an argument. For 18990 instance 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 18999 while GNU @command{find} reports @samp{./foo-./foo}. 19000 19001 19002 @anchor{grep} 19003 @item @command{grep} 19004 @c ----------------- 19005 @prindex @command{grep} 19006 Portable scripts can rely on the @command{grep} options @option{-c}, 19007 @option{-l}, @option{-n}, and @option{-v}, but should avoid other 19008 options. For example, don't use @option{-w}, as Posix does not require 19009 it and Irix 6.5.16m's @command{grep} does not support it. Also, 19010 portable scripts should not combine @option{-c} with @option{-l}, 19011 as Posix does not allow this. 19012 19013 Some of the options required by Posix are not portable in practice. 19014 Don't use @samp{grep -q} to suppress output, because many @command{grep} 19015 implementations (e.g., Solaris) do not support @option{-q}. 19016 Don't use @samp{grep -s} to suppress output either, because Posix 19017 says @option{-s} does not suppress output, only some error messages; 19018 also, the @option{-s} option of traditional @command{grep} behaved 19019 like @option{-q} does in most modern implementations. Instead, 19020 redirect the standard output and standard error (in case the file 19021 doesn't exist) of @code{grep} to @file{/dev/null}. Check the exit 19022 status of @code{grep} to determine whether it found a match. 19023 19024 The QNX4 implementation fails to count lines with @code{grep -c '$'}, 19025 but works with @code{grep -c '^'}. Other alternatives for counting 19026 lines are to use @code{sed -n '$='} or @code{wc -l}. 19027 19028 Some traditional @command{grep} implementations do not work on long 19029 input lines. On AIX the default @code{grep} silently truncates long 19030 lines on the input before matching. 19031 19032 Also, many implementations do not support multiple regexps 19033 with @option{-e}: they either reject @option{-e} entirely (e.g., Solaris) 19034 or honor only the last pattern (e.g., IRIX 6.5 and NeXT). To 19035 work around these problems, invoke @code{AC_PROG_GREP} and then use 19036 @code{$GREP}. 19037 19038 Another possible workaround for the multiple @option{-e} problem is to 19039 separate the patterns by newlines, for example: 19040 19041 @example 19042 grep 'foo 19043 bar' in.txt 19044 @end example 19045 19046 @noindent 19047 except that this fails with traditional @command{grep} 19048 implementations and with OpenBSD 3.8 @command{grep}. 19049 19050 Traditional @command{grep} implementations (e.g., Solaris) do not 19051 support the @option{-E} or @option{-F} options. To work around these 19052 problems, invoke @code{AC_PROG_EGREP} and then use @code{$EGREP}, and 19053 similarly for @code{AC_PROG_FGREP} and @code{$FGREP}. Even if you are 19054 willing to require support for Posix @command{grep}, your script should 19055 not use both @option{-E} and @option{-F}, since Posix does not allow 19056 this combination. 19057 19058 Portable @command{grep} regular expressions should use @samp{\} only to 19059 escape characters in the string @samp{$()*.0123456789[\^@{@}}. For example, 19060 alternation, @samp{\|}, is common but Posix does not require its 19061 support in basic regular expressions, so it should be avoided in 19062 portable scripts. Solaris and HP-UX @command{grep} do not support it. 19063 Similarly, 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 19067 Posix does not specify the behavior of @command{grep} on binary files. 19068 An example where this matters is using BSD @command{grep} to 19069 search text that includes embedded ANSI escape sequences for 19070 colored output to terminals (@samp{\033[m} is the sequence to restore 19071 normal output); the behavior depends on whether input is seekable: 19072 19073 @example 19074 $ @kbd{printf 'esc\033[mape\n' > sample} 19075 $ @kbd{grep . sample} 19076 Binary file sample matches 19077 $ @kbd{cat sample | grep .} 19078 escape 19079 @end example 19080 19081 19082 @item @command{join} 19083 @c ----------------- 19084 @prindex @command{join} 19085 Solaris 8 @command{join} has bugs when the second operand is standard 19086 input, and when standard input is a pipe. For example, the following 19087 shell script causes Solaris 8 @command{join} to loop forever: 19088 19089 @example 19090 cat >file <<'EOF' 19091 1 x 19092 2 y 19093 EOF 19094 cat file | join file - 19095 @end example 19096 19097 Use @samp{join - file} instead. 19098 19099 On 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; 19101 the 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 19107 Don't rely on @command{ln} having a @option{-f} option. Symbolic links 19108 are not available on old systems; use @samp{$(LN_S)} as a portable substitute. 19109 19110 For versions of the DJGPP before 2.04, 19111 @command{ln} emulates symbolic links 19112 to executables by generating a stub that in turn calls the real 19113 program. This feature also works with nonexistent files like in the 19114 Posix spec. So @samp{ln -s file link} generates @file{link.exe}, 19115 which attempts to call @file{file.exe} if run. But this feature only 19116 works for executables, so @samp{cp -p} is used instead for these 19117 systems. DJGPP versions 2.04 and later have full support 19118 for symbolic links. 19119 19120 19121 @item @command{ls} 19122 @c --------------- 19123 @prindex @command{ls} 19124 @cindex Listing directories 19125 The portable options are @option{-acdilrtu}. Current practice is for 19126 @option{-l} to output both owner and group, even though ancient versions 19127 of @command{ls} omitted the group. 19128 19129 On ancient hosts, @samp{ls foo} sent the diagnostic @samp{foo not found} 19130 to standard output if @file{foo} did not exist. Hence a shell command 19131 like @samp{sources=`ls *.c 2>/dev/null`} did not always work, since it 19132 was 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 19136 The behavior of @command{ls} on a directory that is being concurrently 19137 modified is not always predictable, because of a data race where cached 19138 information returned by @code{readdir} does not match the current 19139 directory state. In fact, MacOS 10.5 has an intermittent bug where 19140 @code{readdir}, and thus @command{ls}, sometimes lists a file more than 19141 once if other files were added or removed from the directory immediately 19142 prior to the @command{ls} call. Since @command{ls} already sorts its 19143 output, the duplicate entries can be avoided by piping the results 19144 through @code{uniq}. 19145 19146 @anchor{mkdir} 19147 @item @command{mkdir} 19148 @c ------------------ 19149 @prindex @command{mkdir} 19150 @cindex Making directories 19151 No @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}) 19154 or @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs}). 19155 19156 Combining the @option{-m} and @option{-p} options, as in @samp{mkdir -m 19157 go-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 19160 IRIX 6.5 @command{mkdir} often assign the wrong permissions to 19161 any newly-created parents of @var{dir}. 19162 19163 Posix does not clearly specify whether @samp{mkdir -p foo} 19164 should succeed when @file{foo} is a symbolic link to an already-existing 19165 directory. The GNU Core Utilities 5.1.0 @command{mkdir} 19166 succeeds, but Solaris @command{mkdir} fails. 19167 19168 Traditional @code{mkdir -p} implementations suffer from race conditions. 19169 For example, if you invoke @code{mkdir -p a/b} and @code{mkdir -p a/c} 19170 at the same time, both processes might detect that @file{a} is missing, 19171 one might create @file{a}, then the other might try to create @file{a} 19172 and fail with a @code{File exists} diagnostic. The GNU Core 19173 Utilities (@samp{fileutils} version 4.1), FreeBSD 5.0, 19174 NetBSD 2.0.2, and OpenBSD 2.4 are known to be 19175 race-free when two processes invoke @code{mkdir -p} simultaneously, but 19176 earlier versions are vulnerable. Solaris @command{mkdir} is still 19177 vulnerable as of Solaris 10, and other traditional Unix systems are 19178 probably vulnerable too. This possible race is harmful in parallel 19179 builds when several Make rules call @code{mkdir -p} to 19180 construct directories. You may use 19181 @code{install-sh -d} as a safe replacement, provided this script is 19182 recent enough; the copy shipped with Autoconf 2.60 and Automake 1.10 is 19183 OK, 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} 19191 The GNU Coding Standards state that @command{mknod} is safe to use on 19192 platforms where it has been tested to exist; but it is generally portable 19193 only for creating named FIFOs, since device numbers are 19194 platform-specific. Autotest uses @command{mkfifo} to implement parallel 19195 testsuites. Posix states that behavior is unspecified when opening a 19196 named FIFO for both reading and writing; on at least Cygwin, this 19197 results in failure on any attempt to read or write to that file 19198 descriptor. 19199 19200 @item @command{mktemp} 19201 @c ------------------- 19202 @prindex @command{mktemp} 19203 @cindex Creating temporary files 19204 Shell scripts can use temporary files safely with @command{mktemp}, but 19205 it does not exist on all systems. A portable way to create a safe 19206 temporary file name is to create a temporary directory with mode 700 and 19207 use a file inside this directory. Both methods prevent attackers from 19208 gaining control, though @command{mktemp} is far less likely to fail 19209 gratuitously under attack. 19210 19211 Here 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 19235 The only portable options are @option{-f} and @option{-i}. 19236 19237 Moving individual files between file systems is portable (it was in Unix 19238 version 6), 19239 but it is not always atomic: when doing @samp{mv new existing}, there's 19240 a critical section where neither the old nor the new version of 19241 @file{existing} actually exists. 19242 19243 On some systems moving files from @file{/tmp} can sometimes cause 19244 undesirable (but perfectly valid) warnings, even if you created these 19245 files. This is because @file{/tmp} belongs to a group that ordinary 19246 users are not members of, and files created in @file{/tmp} inherit 19247 the group of @file{/tmp}. When the file is copied, @command{mv} issues 19248 a 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 $?} 19255 0 19256 $ @kbd{ls foo} 19257 foo 19258 @end smallexample 19259 19260 @noindent 19261 This annoying behavior conforms to Posix, unfortunately. 19262 19263 Moving directories across mount points is not portable, use @command{cp} 19264 and @command{rm}. 19265 19266 DOS variants cannot rename or remove open files, and do not 19267 support commands like @samp{mv foo bar >foo}, even though this is 19268 perfectly portable among Posix hosts. 19269 19270 19271 @item @command{od} 19272 @c --------------- 19273 @prindex @command{od} 19274 19275 In Mac OS X 10.3, @command{od} does not support the 19276 standard Posix options @option{-A}, @option{-j}, @option{-N}, or 19277 @option{-t}, or the XSI option @option{-s}. The only 19278 supported Posix option is @option{-v}, and the only supported 19279 XSI options are those in @option{-bcdox}. The BSD 19280 @command{hexdump} program can be used instead. 19281 19282 This problem no longer exists in Mac OS X 10.4.3. 19283 19284 19285 @item @command{rm} 19286 @c --------------- 19287 @prindex @command{rm} 19288 The @option{-f} and @option{-r} options are portable. 19289 19290 It is not portable to invoke @command{rm} without options or operands. 19291 On the other hand, Posix now requires @command{rm -f} to silently 19292 succeed when there are no operands (useful for constructs like 19293 @command{rm -rf $filelist} without first checking if @samp{$filelist} 19294 was empty). But this was not always portable; at least NetBSD 19295 @command{rm} built before 2008 would fail with a diagnostic. 19296 19297 A file might not be removed even if its parent directory is writable 19298 and searchable. Many Posix hosts cannot remove a mount point, a named 19299 stream, a working directory, or a last link to a file that is being 19300 executed. 19301 19302 DOS variants cannot rename or remove open files, and do not 19303 support commands like @samp{rm foo >foo}, even though this is 19304 perfectly portable among Posix hosts. 19305 19306 @item @command{rmdir} 19307 @c ------------------ 19308 @prindex @command{rmdir} 19309 Just as with @command{rm}, some platforms refuse to remove a working 19310 directory. 19311 19312 @anchor{sed} 19313 @item @command{sed} 19314 @c ---------------- 19315 @prindex @command{sed} 19316 Patterns should not include the separator (unless escaped), even as part 19317 of a character class. In conformance with Posix, the Cray 19318 @command{sed} rejects @samp{s/[^/]*$//}: use @samp{s%[^/]*$%%}. 19319 Even when escaped, patterns should not include separators that are also 19320 used 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 19322 before evaluating the basic regular expression. 19323 19324 Avoid empty patterns within parentheses (i.e., @samp{\(\)}). Posix does 19325 not require support for empty patterns, and Unicos 9 @command{sed} rejects 19326 them. 19327 19328 Unicos 9 @command{sed} loops endlessly on patterns like @samp{.*\n.*}. 19329 19330 Sed scripts should not use branch labels longer than 7 characters and 19331 should not contain comments; AIX 5.3 @command{sed} rejects indented comments. 19332 HP-UX sed has a limit of 99 commands (not counting @samp{:} commands) and 19333 48 labels, which cannot be circumvented by using more than one script 19334 file. It can execute up to 19 reads with the @samp{r} command per cycle. 19335 Solaris @command{/usr/ucb/sed} rejects usages that exceed a limit of 19336 about 6000 bytes for the internal representation of commands. 19337 19338 Avoid redundant @samp{;}, as some @command{sed} implementations, such as 19339 NetBSD 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/'} 19344 sed: 1: "s/x/x/;;s/x/x/": invalid command code ; 19345 @end example 19346 19347 Some @command{sed} implementations have a buffer limited to 4000 bytes, 19348 and this limits the size of input lines, output lines, and internal 19349 buffers that can be processed portably. Likewise, 19350 not all @command{sed} implementations can handle embedded @code{NUL} or 19351 a missing trailing newline. 19352 19353 Remember that ranges within a bracket expression of a regular expression 19354 are only well-defined in the @samp{C} (or @samp{POSIX}) locale. 19355 Meanwhile, support for character classes like @samp{[[:upper:]]} is not 19356 yet universal, so if you cannot guarantee the setting of @env{LC_ALL}, 19357 it is better to spell out a range @samp{[ABCDEFGHIJKLMNOPQRSTUVWXYZ]} 19358 than to rely on @samp{[A-Z]}. 19359 19360 Additionally, Posix states that regular expressions are only 19361 well-defined on characters. Unfortunately, there exist platforms such 19362 as MacOS X 10.5 where not all 8-bit byte values are valid characters, 19363 even though that platform has a single-byte @samp{C} locale. And Posix 19364 allows the existence of a multi-byte @samp{C} locale, although that does 19365 not yet appear to be a common implementation. At any rate, it means 19366 that 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} 19370 0 19371 $ @kbd{printf '\200\n' | LC_ALL=en_US.ISO8859-1 sed -n /./p | wc -l} 19372 1 19373 @end example 19374 19375 Portable @command{sed} regular expressions should use @samp{\} only to escape 19376 characters in the string @samp{$()*.0123456789[\^n@{@}}. For example, 19377 alternation, @samp{\|}, is common but Posix does not require its 19378 support, so it should be avoided in portable scripts. Solaris 19379 @command{sed} does not support alternation; e.g., @samp{sed '/a\|b/d'} 19380 deletes only lines that contain the literal string @samp{a|b}. 19381 Similarly, @samp{\+} and @samp{\?} should be avoided. 19382 19383 Anchors (@samp{^} and @samp{$}) inside groups are not portable. 19384 19385 Nested parentheses in patterns (e.g., @samp{\(\(a*\)b*)\)}) are 19386 quite portable to current hosts, but was not supported by some ancient 19387 @command{sed} implementations like SVR3. 19388 19389 Some @command{sed} implementations, e.g., Solaris, restrict the special 19390 role of the asterisk @samp{*} to one-character regular expressions and 19391 back-references, and the special role of interval expressions 19392 @samp{\@{@var{m}\@}}, @samp{\@{@var{m},\@}}, or @samp{\@{@var{m},@var{n}\@}} 19393 to 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'} 19397 x2x4 19398 $ @kbd{echo '1*23*4' | /usr/xpg4/bin/sed 's/\(.\)*/x/g'} 19399 x 19400 @end example 19401 19402 The @option{-e} option is mostly portable. 19403 However, its argument 19404 cannot start with @samp{a}, @samp{c}, or @samp{i}, 19405 as this runs afoul of a Tru64 5.1 bug. 19406 Also, its argument cannot be empty, as this fails on AIX 5.3. 19407 Some people prefer to use @samp{-e}: 19408 19409 @example 19410 sed -e '@var{command-1}' \ 19411 -e '@var{command-2}' 19412 @end example 19413 19414 @noindent 19415 as opposed to the equivalent: 19416 19417 @example 19418 sed ' 19419 @var{command-1} 19420 @var{command-2} 19421 ' 19422 @end example 19423 19424 @noindent 19425 The following usage is sometimes equivalent: 19426 19427 @example 19428 sed '@var{command-1};@var{command-2}' 19429 @end example 19430 19431 but 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 19434 should use semicolon only with simple scripts that do not use these 19435 verbs. 19436 19437 Posix up to the 2008 revision requires the argument of the @option{-e} 19438 option to be a syntactically complete script. GNU @command{sed} allows 19439 to pass multiple script fragments, each as argument of a separate 19440 @option{-e} option, that are then combined, with newlines between the 19441 fragments, and a future Posix revision may allow this as well. This 19442 approach is not portable with script fragments ending in backslash; for 19443 example, the @command{sed} programs on Solaris 10, HP-UX 11, and AIX 19444 don't allow splitting in this case: 19445 19446 @example 19447 $ @kbd{echo a | sed -n -e 'i\} 19448 @kbd{0'} 19449 0 19450 $ @kbd{echo a | sed -n -e 'i\' -e 0} 19451 Unrecognized command: 0 19452 @end example 19453 19454 @noindent 19455 In practice, however, this technique of joining fragments 19456 through @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 '@}'} 19462 b 19463 @end example 19464 19465 Commands inside @{ @} brackets are further restricted. Posix 2008 says that 19466 they cannot be preceded by addresses, @samp{!}, or @samp{;}, and that 19467 each command must be followed immediately by a newline, without any 19468 intervening blanks or semicolons. The closing bracket must be alone on 19469 a line, other than white space preceding or following it. However, a 19470 future version of Posix may standardize the use of addresses within brackets. 19471 19472 Contrary to yet another urban legend, you may portably use @samp{&} in 19473 the replacement part of the @code{s} command to mean ``what was 19474 matched''. All descendants of Unix version 7 @command{sed} 19475 (at least; we 19476 don't have first hand experience with older @command{sed} implementations) have 19477 supported it. 19478 19479 Posix requires that you must not have any white space between 19480 @samp{!} and the following command. It is OK to have blanks between 19481 the 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'} 19489 foo 19490 @end example 19491 19492 Posix also says that you should not combine @samp{!} and @samp{;}. If 19493 you use @samp{!}, it is best to put it on a command that is delimited by 19494 newlines rather than @samp{;}. 19495 19496 Also 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. 19498 On the other hand, no white space is allowed between @samp{:} and the 19499 subsequent label name. 19500 19501 If 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 19503 should be followed by a newline. Otherwise some @command{sed} 19504 implementations (e.g., OpenBSD 3.9) do not append a newline to the 19505 inserted text. 19506 19507 Many @command{sed} implementations (e.g., MacOS X 10.4, 19508 OpenBSD 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 19511 work around this incompatibility with Posix: 19512 19513 @example 19514 $ @kbd{echo flushleft | sed 'a\} 19515 > @kbd{ indented} 19516 > @kbd{'} 19517 flushleft 19518 indented 19519 $ @kbd{echo foo | sed 'a\} 19520 > @kbd{\ indented} 19521 > @kbd{'} 19522 flushleft 19523 indented 19524 @end example 19525 19526 Posix requires that with an empty regular expression, the last non-empty 19527 regular expression from either an address specification or substitution 19528 command is applied. However, busybox 1.6.1 complains when using a 19529 substitution command with a replacement containing a back-reference to 19530 an empty regular expression; the workaround is repeating the regular 19531 expression. 19532 19533 @example 19534 $ @kbd{echo abc | busybox sed '/a\(b\)c/ s//\1/'} 19535 sed: No previous regexp. 19536 $ @kbd{echo abc | busybox sed '/a\(b\)c/ s/a\(b\)c/\1/'} 19537 b 19538 @end example 19539 19540 19541 @item @command{sed} (@samp{t}) 19542 @c --------------------------- 19543 @prindex @command{sed} (@samp{t}) 19544 Some old systems have @command{sed} that ``forget'' to reset their 19545 @samp{t} flag when starting a new cycle. For instance on MIPS 19546 RISC/OS, and on IRIX 5.3, if you run the following @command{sed} 19547 script (the line numbers are not actual part of the texts): 19548 19549 @example 19550 s/keep me/kept/g # a 19551 t end # b 19552 s/.*/deleted/g # c 19553 :end # d 19554 @end example 19555 19556 @noindent 19557 on 19558 19559 @example 19560 delete me # 1 19561 delete me # 2 19562 keep me # 3 19563 delete me # 4 19564 @end example 19565 19566 @noindent 19567 you get 19568 19569 @example 19570 deleted 19571 delete me 19572 kept 19573 deleted 19574 @end example 19575 19576 @noindent 19577 instead of 19578 19579 @example 19580 deleted 19581 deleted 19582 kept 19583 deleted 19584 @end example 19585 19586 Why? When processing line 1, (c) matches, therefore sets the @samp{t} 19587 flag, and the output is produced. When processing 19588 line 2, the @samp{t} flag is still set (this is the bug). Command (a) 19589 fails to match, but @command{sed} is not supposed to clear the @samp{t} 19590 flag when a substitution fails. Command (b) sees that the flag is set, 19591 therefore it clears it, and jumps to (d), hence you get @samp{delete me} 19592 instead 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. 19594 Finally, since the flag is clear, line 4 is processed properly. 19595 19596 There are two things one should remember about @samp{t} in @command{sed}. 19597 Firstly, always remember that @samp{t} jumps if @emph{some} substitution 19598 succeeded, not only the immediately preceding substitution. Therefore, 19599 always use a fake @samp{t clear} followed by a @samp{:clear} on the next 19600 line, to reset the @samp{t} flag where needed. 19601 19602 Secondly, you cannot rely on @command{sed} to clear the flag at each new 19603 cycle. 19604 19605 One portable implementation of the script above is: 19606 19607 @example 19608 t clear 19609 :clear 19610 s/keep me/kept/g 19611 t end 19612 s/.*/deleted/g 19613 :end 19614 @end example 19615 19616 @item @command{sleep} 19617 @c ------------------ 19618 @prindex @command{sleep} 19619 Using @command{sleep} is generally portable. However, remember that 19620 adding a @command{sleep} to work around timestamp issues, with a minimum 19621 granularity of one second, doesn't scale well for parallel builds on 19622 modern machines with sub-second process completion. 19623 19624 @item @command{sort} 19625 @c ----------------- 19626 @prindex @command{sort} 19627 Remember that sort order is influenced by the current locale. Inside 19628 @file{configure}, the C locale is in effect, but in Makefile snippets, 19629 you may need to specify @code{LC_ALL=C sort}. 19630 19631 @item @command{tar} 19632 @c ---------------- 19633 @prindex @command{tar} 19634 There are multiple file formats for @command{tar}; if you use Automake, 19635 the macro @code{AM_INIT_AUTOMAKE} has some options controlling which 19636 level of portability to use. 19637 19638 @anchor{touch} 19639 @item @command{touch} 19640 @c ------------------ 19641 @prindex @command{touch} 19642 @cindex timestamp resolution 19643 If you specify the desired timestamp (e.g., with the @option{-r} 19644 option), older @command{touch} implementations use the @code{utime} or 19645 @code{utimes} system call, which can result in the same kind of 19646 timestamp truncation problems that @samp{cp -p} has. 19647 19648 On ancient BSD systems, @command{touch} or any command that 19649 results in an empty file does not update the timestamps, so use a 19650 command like @command{echo} as a workaround. 19651 Also, 19652 GNU @command{touch} 3.16r (and presumably all before that) 19653 fails to work on SunOS 4.1.3 when the empty file is on an 19654 NFS-mounted 4.2 volume. 19655 However, 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 19663 Not all versions of @command{tr} handle all backslash character escapes. 19664 For example, Solaris 10 @command{/usr/ucb/tr} falls over, even though 19665 Solaris contains more modern @command{tr} in other locations. 19666 Using octal escapes is more portable for carriage returns, since 19667 @samp{\015} is the same for both ASCII and EBCDIC, and since use of 19668 literal carriage returns in scripts causes a number of other problems. 19669 But for other characters, like newline, using octal escapes ties the 19670 operation 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} 19674 moo 19675 light 19676 $ @kbd{@{ echo moon; echo light; @} | /usr/bin/tr -d '\n' ; echo} 19677 moonlight 19678 $ @kbd{@{ echo moon; echo light; @} | /usr/ucb/tr -d '\012' ; echo} 19679 moonlight 19680 $ @kbd{nl='} 19681 @kbd{'; @{ echo moon; echo light; @} | /usr/ucb/tr -d "$nl" ; echo} 19682 moonlight 19683 @end example 19684 19685 Not all versions of @command{tr} recognize direct ranges of characters: at 19686 least Solaris @command{/usr/bin/tr} still fails to do so. But you can 19687 use @command{/usr/xpg4/bin/tr} instead, or add brackets (which in Posix 19688 transliterate to themselves). 19689 19690 @example 19691 $ @kbd{echo "Hazy Fantazy" | LC_ALL=C /usr/bin/tr a-z A-Z} 19692 HAZy FAntAZy 19693 $ @kbd{echo "Hazy Fantazy" | LC_ALL=C /usr/bin/tr '[a-z]' '[A-Z]'} 19694 HAZY FANTAZY 19695 $ @kbd{echo "Hazy Fantazy" | LC_ALL=C /usr/xpg4/bin/tr a-z A-Z} 19696 HAZY FANTAZY 19697 @end example 19698 19699 When providing two arguments, be sure the second string is at least as 19700 long as the first. 19701 19702 @example 19703 $ @kbd{echo abc | /usr/xpg4/bin/tr bc d} 19704 adc 19705 $ @kbd{echo abc | coreutils/tr bc d} 19706 add 19707 @end example 19708 19709 Posix requires @command{tr} to operate on binary files. But at least 19710 Solaris @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, 19713 it 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 19725 Solaris @command{/usr/ucb/tr} additionally fails to handle @samp{\0} as the 19726 octal 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 19745 Writing portable makefiles is an art. Since a makefile's commands are 19746 executed by the shell, you must consider the shell portability issues 19747 already mentioned. However, other issues are specific to @command{make} 19748 itself. 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 19776 Posix says that the @samp{$<} construct in makefiles can be 19777 used only in inference rules and in the @samp{.DEFAULT} rule; its 19778 meaning in ordinary rules is unspecified. Solaris @command{make} 19779 for instance replaces it with the empty string. OpenBSD (3.0 and 19780 later) @command{make} diagnoses these uses and errors out. 19781 19782 @node Failure in Make Rules 19783 @section Failure in Make Rules 19784 19785 Posix 2008 requires that @command{make} must invoke each command with 19786 the equivalent of a @samp{sh -e -c} subshell, which causes the 19787 subshell to exit immediately if a subsidiary simple-command fails, 19788 although not all @command{make} implementations have historically 19789 followed this rule. For 19790 example, the command @samp{touch T; rm -f U} may attempt to 19791 remove @file{U} even if the @command{touch} fails, although this is not 19792 permitted with Posix make. One way to work around failures in simple 19793 commands is to reword them so that they always succeed, e.g., @samp{touch 19794 T || :; rm -f U}. 19795 However, even this approach can run into common bugs in BSD 19796 implementations of the @option{-e} option of @command{sh} and 19797 @command{set} (@pxref{set, , Limitations of Shell Builtins}), so if you 19798 are worried 19799 about porting to buggy BSD shells it may be simpler to migrate 19800 complicated @command{make} actions into separate scripts. 19801 19802 @node Special Chars in Names 19803 @section Special Characters in Make Macro Names 19804 19805 Posix limits macro names to nonempty strings containing only 19806 ASCII letters and digits, @samp{.}, and @samp{_}. Many 19807 @command{make} implementations allow a wider variety of characters, but 19808 portable makefiles should avoid them. It is portable to start a name 19809 with a special character, e.g., @samp{$(.FOO)}. 19810 19811 Some ancient @command{make} implementations don't support leading 19812 underscores in macro names. An example is NEWS-OS 4.2R. 19813 19814 @example 19815 $ @kbd{cat Makefile} 19816 _am_include = # 19817 _am_quote = 19818 all:; @@echo this is test 19819 $ @kbd{make} 19820 Make: Must be a separator on rules line 2. Stop. 19821 $ @kbd{cat Makefile2} 19822 am_include = # 19823 am_quote = 19824 all:; @@echo this is test 19825 $ @kbd{make -f Makefile2} 19826 this is test 19827 @end example 19828 19829 @noindent 19830 However, this problem is no longer of practical concern. 19831 19832 @node Backslash-Newline-Empty 19833 @section Backslash-Newline Before Empty Lines 19834 19835 A bug in Bash 2.03 can cause problems if a Make rule contains a 19836 backslash-newline followed by line that expands to nothing. 19837 For example, on Solaris 8: 19838 19839 @example 19840 SHELL = /bin/bash 19841 EMPTY = 19842 foo: 19843 touch foo \ 19844 $(EMPTY) 19845 @end example 19846 19847 @noindent 19848 executes 19849 19850 @example 19851 /bin/bash -c 'touch foo \ 19852 ' 19853 @end example 19854 19855 @noindent 19856 which fails with a syntax error, due to the Bash bug. To avoid this 19857 problem, 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 (a] proulx.com> thinks it was in hpux 8.0 too. 19862 On some versions of HP-UX, @command{make} reads multiple newlines 19863 following a backslash, continuing to the next non-empty line. For 19864 example, 19865 19866 @example 19867 FOO = one \ 19868 19869 BAR = two 19870 19871 test: 19872 : FOO is "$(FOO)" 19873 : BAR is "$(BAR)" 19874 @end example 19875 19876 @noindent 19877 shows @code{FOO} equal to @code{one BAR = two}. Other implementations 19878 sensibly let a backslash continue only to the immediately following 19879 line. 19880 19881 @node Backslash-Newline Comments 19882 @section Backslash-Newline in Make Comments 19883 19884 According to Posix, Make comments start with @code{#} 19885 and continue until an unescaped newline is reached. 19886 19887 @example 19888 $ @kbd{cat Makefile} 19889 # A = foo \ 19890 bar \ 19891 baz 19892 19893 all: 19894 @@echo ok 19895 $ @kbd{make} # GNU make 19896 ok 19897 @end example 19898 19899 @noindent 19900 However this is not always the case. Some implementations 19901 discard everything from @code{#} through the end of the line, ignoring any 19902 trailing backslash. 19903 19904 @example 19905 $ @kbd{pmake} # BSD make 19906 "Makefile", line 3: Need an operator 19907 Fatal errors encountered -- cannot continue 19908 @end example 19909 19910 @noindent 19911 Therefore, if you want to comment out a multi-line definition, prefix each 19912 line 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 19923 Tru64 5.1's @command{make} has been reported to crash when given a 19924 makefile with lines longer than around 20 kB. Earlier versions are 19925 reported to exit with @code{Line too long} diagnostics. 19926 19927 @node Macros and Submakes 19928 @section @code{make macro=value} and Submakes 19929 19930 A command-line variable definition such as @code{foo=bar} overrides any 19931 definition of @code{foo} in a makefile. Some @command{make} 19932 implementations (such as GNU @command{make}) propagate this 19933 override to subsidiary invocations of @command{make}. Some other 19934 implementations do not pass the substitution along to submakes. 19935 19936 @example 19937 $ @kbd{cat Makefile} 19938 foo = foo 19939 one: 19940 @@echo $(foo) 19941 $(MAKE) two 19942 two: 19943 @@echo $(foo) 19944 $ @kbd{make foo=bar} # GNU make 3.79.1 19945 bar 19946 make two 19947 make[1]: Entering directory `/home/adl' 19948 bar 19949 make[1]: Leaving directory `/home/adl' 19950 $ @kbd{pmake foo=bar} # BSD make 19951 bar 19952 pmake two 19953 foo 19954 @end example 19955 19956 You have a few possibilities if you do want the @code{foo=bar} override 19957 to propagate to submakes. One is to use the @option{-e} 19958 option, which causes all environment variables to have precedence over 19959 the makefile macro definitions, and declare foo as an environment 19960 variable: 19961 19962 @example 19963 $ @kbd{env foo=bar make -e} 19964 @end example 19965 19966 The @option{-e} option is propagated to submakes automatically, 19967 and since the environment is inherited between @command{make} 19968 invocations, the @code{foo} macro is overridden in 19969 submakes as expected. 19970 19971 This syntax (@code{foo=bar make -e}) is portable only when used 19972 outside of a makefile, for instance from a script or from the 19973 command 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 19977 Moreover, using @option{-e} could have unexpected side effects if your 19978 environment contains some other macros usually defined by the 19979 makefile. (See also the note about @code{make -e} and @code{SHELL} 19980 below.) 19981 19982 If you can foresee all macros that a user might want to override, then 19983 you can propagate them to submakes manually, from your makefile: 19984 19985 @example 19986 foo = foo 19987 one: 19988 @@echo $(foo) 19989 $(MAKE) foo=$(foo) two 19990 two: 19991 @@echo $(foo) 19992 @end example 19993 19994 Another way to propagate a variable to submakes in a portable way is to 19995 expand an extra variable in every invocation of @samp{$(MAKE)} within 19996 your makefile: 19997 19998 @example 19999 foo = foo 20000 one: 20001 @@echo $(foo) 20002 $(MAKE) $(SUBMAKEFLAGS) two 20003 two: 20004 @@echo $(foo) 20005 @end example 20006 20007 Users must be aware that this technique is in use to take advantage of 20008 it, e.g.@: with @code{make foo=bar SUBMAKEFLAGS='foo=bar'}, but it 20009 allows any macro to be overridden. Makefiles generated by 20010 @command{automake} use this technique, expanding @code{$(AM_MAKEFLAGS)} 20011 on the command lines of submakes (@pxref{Subdirectories, , Automake, 20012 automake, 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 20019 Posix requires @command{make} to use @code{MAKEFLAGS} to affect the 20020 current and recursive invocations of make, but allows implementations 20021 several formats for the variable. It is tricky to parse 20022 @code{$MAKEFLAGS} to determine whether @option{-s} for silent execution 20023 or @option{-k} for continued execution are in effect. For example, you 20024 cannot assume that the first space-separated word in @code{$MAKEFLAGS} 20025 contains single-letter options, since in the Cygwin version of 20026 GNU @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} 20031 all: 20032 @@echo MAKEFLAGS = $(MAKEFLAGS) 20033 $ @kbd{make} 20034 MAKEFLAGS = --unix 20035 $ @kbd{make -k} 20036 MAKEFLAGS = --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 20044 Posix-compliant @command{make} internally uses the @code{$(SHELL)} 20045 macro to spawn shell processes and execute Make rules. This 20046 is a builtin macro supplied by @command{make}, but it can be modified 20047 by a makefile or by a command-line argument. 20048 20049 Not all @command{make} implementations define this @code{SHELL} macro. 20050 Tru64 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 20053 your makefiles. If you use Autoconf, do 20054 20055 @example 20056 SHELL = @@SHELL@@ 20057 @end example 20058 20059 @noindent 20060 If you use Automake, this is done for you. 20061 20062 Do not force @code{SHELL = /bin/sh} because that is not correct 20063 everywhere. Remember, @file{/bin/sh} is not Posix compliant on many 20064 systems, such as FreeBSD 4, NetBSD 3, AIX 3, Solaris 10, or Tru64. 20065 Additionally, DJGPP lacks @code{/bin/sh}, and when its 20066 GNU @command{make} port sees such a setting it enters a 20067 special emulation mode where features like pipes and redirections are 20068 emulated on top of DOS's @command{command.com}. Unfortunately this 20069 emulation is incomplete; for instance it does not handle command 20070 substitutions. Using @code{@@SHELL@@} means that your makefile will 20071 benefit from the same improved shell, such as @command{bash} or 20072 @command{ksh}, that was discovered during @command{configure}, so that 20073 you aren't fighting two different sets of shell bugs between the two 20074 contexts. 20075 20076 Posix-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 20081 However not all @command{make} implementations have this exception. 20082 For instance it's not surprising that Tru64 @command{make} doesn't 20083 protect @code{SHELL}, since it doesn't use it. 20084 20085 @example 20086 $ @kbd{cat Makefile} 20087 SHELL = /bin/sh 20088 FOO = foo 20089 all: 20090 @@echo $(SHELL) 20091 @@echo $(FOO) 20092 $ @kbd{env SHELL=/bin/tcsh FOO=bar make -e} # Tru64 Make 20093 /bin/tcsh 20094 bar 20095 $ @kbd{env SHELL=/bin/tcsh FOO=bar gmake -e} # GNU make 20096 /bin/sh 20097 bar 20098 @end example 20099 20100 Conversely, @command{make} is not supposed to export any changes to the 20101 macro @code{SHELL} to child processes. Again, many implementations 20102 break this rule: 20103 20104 @example 20105 $ @kbd{cat Makefile} 20106 all: 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 20114 sh 20115 @end example 20116 20117 @node Parallel Make 20118 @section Parallel Make 20119 @cindex Parallel @command{make} 20120 20121 Support for parallel execution in @command{make} implementation varies. 20122 Generally, using GNU make is your best bet. 20123 20124 When NetBSD or FreeBSD @command{make} are run in parallel mode, they will 20125 reuse the same shell for multiple commands within one recipe. This can 20126 have various unexpected consequences. For example, changes of directories 20127 or variables persist between recipes, so that: 20128 20129 @example 20130 all: 20131 @@var=value; cd /; pwd; echo $$var; echo $$$$ 20132 @@pwd; echo $$var; echo $$$$ 20133 @end example 20134 20135 @noindent 20136 may output the following with @code{make -j1}, at least on NetBSD up to 20137 5.1 and FreeBSD up to 8.2: 20138 20139 @example 20140 / 20141 value 20142 32235 20143 / 20144 value 20145 32235 20146 @end example 20147 20148 @noindent 20149 while without @option{-j1}, or with @option{-B}, the output looks less 20150 surprising: 20151 20152 @example 20153 / 20154 value 20155 32238 20156 /tmp 20157 20158 32239 20159 @end example 20160 20161 @noindent 20162 Another consequence is that, if one command in a recipe uses @code{exit 0} 20163 to indicate a successful exit, the shell will be gone and the remaining 20164 commands of this recipe will not be executed. 20165 20166 The BSD @command{make} implementations, when run in parallel mode, 20167 will also pass the @command{Makefile} recipes to the shell through 20168 its standard input, thus making it unusable from the recipes: 20169 20170 @example 20171 $ @kbd{cat Makefile} 20172 read: 20173 @@read line; echo LINE: $$line 20174 @c $$ @c restore font-lock 20175 $ @kbd{echo foo | make read} 20176 LINE: foo 20177 $ @kbd{echo foo | make -j1 read} # NetBSD 5.1 and FreeBSD 8.2 20178 LINE: 20179 @end example 20180 20181 @noindent 20182 Moreover, when FreeBSD @command{make} (up at least to 8.2) is run in 20183 parallel mode, it implements the @code{@@} and @code{-} ``recipe 20184 modifiers'' by dynamically modifying the active shell flags. This 20185 behavior has the effects of potentially clobbering the exit status 20186 of recipes silenced with the @code{@@} modifier if they also unset 20187 the @option{errexit} shell flag, and of mangling the output in 20188 unexpected ways: 20189 20190 @example 20191 $ @kbd{cat Makefile} 20192 a: 20193 @@echo $$-; set +e; false 20194 b: 20195 -echo $$-; false; echo set - 20196 $ @kbd{make a; echo status: $?} 20197 ehBc 20198 *** Error code 1 20199 status: 1 20200 $ @kbd{make -j1 a; echo status: $?} 20201 ehB 20202 status: 0 20203 $ @kbd{make b} 20204 echo $-; echo set - 20205 hBc 20206 set - 20207 $ @kbd{make -j1 b} 20208 echo $-; echo hvB 20209 @end example 20210 20211 @noindent 20212 You can avoid all these issues by using the @option{-B} option to enable 20213 compatibility semantics. However, that will effectively also disable 20214 all parallelism as that will cause prerequisites to be updated in the 20215 order they are listed in a rule. 20216 20217 Some 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 20220 error of all their child processes to pipes or temporary regular 20221 files. This can lead to subtly different semantics in the behavior 20222 of the spawned processes. For example, even if the @command{make} 20223 standard output is connected to a tty, the recipe command will not be: 20224 20225 @example 20226 $ @kbd{cat Makefile} 20227 all: 20228 @@test -t 1 && echo "Is a tty" || echo "Is not a tty" 20229 $ @kbd{make -j 2} # FreeBSD 8.2 make 20230 Is not a tty 20231 $ @kbd{make -j 2} # NetBSD 5.1 make 20232 --- all --- 20233 Is not a tty 20234 $ @kbd{dmake -j 2} # Solaris 10 dmake 20235 @var{hostname} --> 1 job 20236 @var{hostname} --> Job output 20237 Is not a tty 20238 @end example 20239 20240 @noindent 20241 On the other hand: 20242 20243 @example 20244 $ @kbd{make -j 2} # GNU make, Heirloom make 20245 Is a tty 20246 @end example 20247 20248 @noindent 20249 The above examples also show additional status output produced in parallel 20250 mode for targets being updated by Solaris @command{dmake} and NetBSD 20251 @command{make} (but @emph{not} by FreeBSD @command{make}). 20252 20253 Furthermore, parallel runs of those @command{make} implementations will 20254 route standard error from commands that they spawn into their own 20255 standard 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 20263 Never put comments in a rule. 20264 20265 Some @command{make} treat anything starting with a tab as a command for 20266 the current rule, even if the tab is immediately followed by a @code{#}. 20267 The @command{make} from Tru64 Unix V5.1 is one of them. The following 20268 makefile runs @code{# foo} through the shell. 20269 20270 @example 20271 all: 20272 # foo 20273 @end example 20274 20275 As a workaround, you can use the @command{:} no-op command with a string 20276 argument that gets ignored: 20277 20278 @example 20279 all: 20280 : "foo" 20281 @end example 20282 20283 Conversely, if you want to use the @samp{#} character in some command, 20284 you can only do so by expanding it inside a rule (@pxref{Comments in 20285 Make 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 20290 foo.h: foo.h.in 20291 sed -e 's|@@''COMMENT_CHAR''@@|@@COMMENT_CHAR@@|g' \ 20292 $(srcdir)/foo.h.in > $@@ 20293 @end example 20294 20295 The funny shell quoting avoids a substitution at @command{config.status} 20296 run 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 20303 In shell scripts, newlines can be used inside string literals. But in 20304 the shell statements of @file{Makefile} rules, this is not possible: 20305 A newline not preceded by a backslash is a separator between shell 20306 statements. Whereas a newline that is preceded by a backslash becomes 20307 part of the shell statement according to POSIX, but gets replaced, 20308 together 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 20310 literal? 20311 20312 The trick is to set up a shell variable that contains a newline: 20313 20314 @example 20315 nlinit=`echo 'nl="'; echo '"'`; eval "$$nlinit" 20316 @end example 20317 20318 For example, in order to create a multiline @samp{sed} expression that 20319 inserts a blank line after every line of a file, this code can be used: 20320 20321 @example 20322 nlinit=`echo 'nl="'; echo '"'`; eval "$$nlinit"; \ 20323 sed -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 20331 Avoid putting comments in macro values as far as possible. Posix 20332 specifies that the text starting from the @samp{#} sign until the end of 20333 the line is to be ignored, which has the unfortunate effect of 20334 disallowing them even within quotes. Thus, the following might lead to 20335 a syntax error at compile time: 20336 20337 @example 20338 CPPFLAGS = "-DCOMMENT_CHAR='#'" 20339 @end example 20340 20341 @noindent 20342 as @samp{CPPFLAGS} may be expanded to @samp{"-DCOMMENT_CHAR='}. 20343 20344 Most @command{make} implementations disregard this and treat single and 20345 double 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 20350 Even without quoting involved, comments can have surprising effects, 20351 because the whitespace before them is part of the variable value: 20352 20353 @example 20354 foo = bar # trailing comment 20355 print: ; @@echo "$(foo)." 20356 @end example 20357 20358 @noindent 20359 prints @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 20367 GNU @command{make} 3.80 mistreats trailing whitespace in macro 20368 substitutions and appends another spurious suffix: 20369 20370 @example 20371 empty = 20372 foo = bar $(empty) 20373 print: ; @@echo $(foo:=.test) 20374 @end example 20375 20376 @noindent 20377 prints @samp{bar.test .test}. 20378 20379 BSD and Solaris @command{make} implementations do not honor trailing 20380 whitespace in macro definitions as Posix requires: 20381 20382 @example 20383 foo = bar # Note the space after "bar". 20384 print: ; @@echo $(foo)t 20385 @end example 20386 20387 @noindent 20388 prints @samp{bart} instead of @samp{bar t}. To work around this, you 20389 can 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 20398 Some @command{make} implementations may strip trailing whitespace off 20399 of macros set on the command line in addition to leading whitespace. 20400 Further, some may strip leading whitespace off of macros set from 20401 environment variables: 20402 20403 @example 20404 $ @kbd{echo 'print: ; @@echo "x$(foo)x$(bar)x"' | 20405 foo=' f f ' make -f - bar=' b b '} 20406 x f f xb b x # AIX, BSD, GNU make 20407 xf f xb b x # HP-UX, IRIX, Tru64/OSF make 20408 x 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 20417 Never name one of your subdirectories @file{obj/} if you don't like 20418 surprises. 20419 20420 If an @file{obj/} directory exists, BSD @command{make} enters it 20421 before reading the makefile. Hence the makefile in the 20422 current directory is not read. 20423 20424 @example 20425 $ @kbd{cat Makefile} 20426 all: 20427 echo Hello 20428 $ @kbd{cat obj/Makefile} 20429 all: 20430 echo World 20431 $ @kbd{make} # GNU make 20432 echo Hello 20433 Hello 20434 $ @kbd{pmake} # BSD make 20435 echo World 20436 World 20437 @end example 20438 20439 @node make -k Status 20440 @section Exit Status of @code{make -k} 20441 @cindex @code{make -k} 20442 20443 Do not rely on the exit status of @code{make -k}. Some implementations 20444 reflect whether they encountered an error in their exit status; other 20445 implementations always succeed. 20446 20447 @example 20448 $ @kbd{cat Makefile} 20449 all: 20450 false 20451 $ @kbd{make -k; echo exit status: $?} # GNU make 20452 false 20453 make: *** [all] Error 1 20454 exit status: 2 20455 $ @kbd{pmake -k; echo exit status: $?} # BSD make 20456 false 20457 *** Error code 1 (continuing) 20458 exit status: 0 20459 @end example 20460 20461 @node VPATH and Make 20462 @section @code{VPATH} and Make 20463 @cindex @code{VPATH} 20464 20465 Posix does not specify the semantics of @code{VPATH}. Typically, 20466 @command{make} supports @code{VPATH}, but its implementation is not 20467 consistent. 20468 20469 Autoconf and Automake support makefiles whose usages of @code{VPATH} are 20470 portable to recent-enough popular implementations of @command{make}, but 20471 to keep the resulting makefiles portable, a package's makefile 20472 prototypes must take the following issues into account. These issues 20473 are 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 20476 stick with GNU @command{make}, since it is the most 20477 commonly-used @command{make} among Autoconf users. 20478 20479 Here are some known issues with some @code{VPATH} 20480 implementations. 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 20496 Do 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 20502 srcdir = @@srcdir@@ 20503 VPATH = @@srcdir@@ 20504 @end example 20505 20506 @noindent 20507 rather than @samp{VPATH = $(srcdir)}. Note that with GNU 20508 Automake, 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 20515 With ancient versions of Sun @command{make}, 20516 any assignment to @code{VPATH} causes @command{make} to execute only 20517 the first set of double-colon rules. 20518 However, 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 20526 Using @code{$<} in explicit rules is not portable. 20527 The prerequisite file must be named explicitly in the rule. If you want 20528 to find the prerequisite via a @code{VPATH} search, you have to code the 20529 whole 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 20536 Some @command{make} implementations, such as Solaris and Tru64, 20537 search for prerequisites in @code{VPATH} and 20538 then rewrite each occurrence as a plain word in the rule. 20539 For instance: 20540 20541 @example 20542 # This isn't portable to GNU make. 20543 VPATH = ../pkg/src 20544 f.c: if.c 20545 cp if.c f.c 20546 @end example 20547 20548 @noindent 20549 executes @code{cp ../pkg/src/if.c f.c} if @file{if.c} is 20550 found in @file{../pkg/src}. 20551 20552 However, this rule leads to real problems in practice. For example, if 20553 the source directory contains an ordinary file named @file{test} that is 20554 used 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 20557 completely unaware of shell syntax used in the rules, so the VPATH 20558 rewrite can potentially apply to @emph{any} whitespace-separated word 20559 in a rule, including shell variables, functions, and keywords. 20560 20561 @example 20562 $ @kbd{mkdir build} 20563 $ @kbd{cd build} 20564 $ @kbd{cat > Makefile <<'END'} 20565 VPATH = .. 20566 all: arg func for echo 20567 func () @{ for arg in "$$@@"; do echo $$arg; done; @}; \ 20568 func "hello world" 20569 END 20570 $ @kbd{touch ../arg ../func ../for ../echo} 20571 $ @kbd{make} 20572 ../func () @{ ../for ../arg in "$@@"; do ../echo $arg; done; @}; \ 20573 ../func "hello world" 20574 sh: syntax error at line 1: `do' unexpected 20575 *** Error code 2 20576 @end example 20577 20578 @noindent 20579 To avoid this problem, portable makefiles should never mention a source 20580 file or dependency whose name is that of a shell keyword like @file{for} 20581 or @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 20585 Because of these problems GNU @command{make} and many other @command{make} 20586 implementations do not rewrite commands, so portable makefiles should 20587 search @code{VPATH} manually. It is tempting to write this: 20588 20589 @smallexample 20590 # This isn't portable to Solaris make. 20591 VPATH = ../pkg/src 20592 f.c: if.c 20593 cp `test -f if.c || echo $(VPATH)/`if.c f.c 20594 @end smallexample 20595 20596 @noindent 20597 However, the ``prerequisite rewriting'' still applies here. So if 20598 @file{if.c} is in @file{../pkg/src}, Solaris and Tru64 @command{make} 20599 execute 20600 20601 @smallexample 20602 cp `test -f ../pkg/src/if.c || echo ../pkg/src/`if.c f.c 20603 @end smallexample 20604 20605 @noindent 20606 which reduces to 20607 20608 @example 20609 cp if.c f.c 20610 @end example 20611 20612 @noindent 20613 and thus fails. Oops. 20614 20615 A simple workaround, and good practice anyway, is to use @samp{$?} and 20616 @samp{$@@} when possible: 20617 20618 @smallexample 20619 VPATH = ../pkg/src 20620 f.c: if.c 20621 cp $? $@@ 20622 @end smallexample 20623 20624 @noindent 20625 but this does not generalize well to commands with multiple 20626 prerequisites. A more general workaround is to rewrite the rule so that 20627 the prerequisite @file{if.c} never appears as a plain word. For 20628 example, 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 20632 VPATH = ../pkg/src 20633 f.c: if.c f1.c 20634 cat `test -f ./if.c || echo $(VPATH)/`if.c f1.c >$@@ 20635 g.c: if.c g1.c 20636 cat `test -f 'if.c' || echo $(VPATH)/`if.c g1.c >$@@ 20637 h.c: if.c h1.c 20638 cat `test -f "if.c" || echo $(VPATH)/`if.c h1.c >$@@ 20639 @end smallexample 20640 20641 Things get worse when your prerequisites are in a macro. 20642 20643 @example 20644 VPATH = ../pkg/src 20645 HEADERS = f.h g.h h.h 20646 install-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 20655 The above @code{install-HEADERS} rule is not Solaris-proof because @code{for 20656 i in $(HEADERS);} is expanded to @code{for i in f.h g.h h.h;} 20657 where @code{f.h} and @code{g.h} are plain words and are hence 20658 subject to @code{VPATH} adjustments. 20659 20660 If the three files are in @file{../pkg/src}, the rule is run as: 20661 20662 @example 20663 for 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; \ 20667 done 20668 @end example 20669 20670 where the two first @command{install} calls fail. For instance, 20671 consider the @code{f.h} installation: 20672 20673 @example 20674 install -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 20682 It reduces to: 20683 20684 @example 20685 install -m 644 \ 20686 ../pkg/src/f.h \ 20687 /usr/local/include/../pkg/src/f.h; 20688 @end example 20689 20690 Note that the manual @code{VPATH} search did not cause any problems here; 20691 however this command installs @file{f.h} in an incorrect directory. 20692 20693 Trying 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 20697 install-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 20706 Now, @code{headers='$(HEADERS)'} macro-expands to: 20707 20708 @example 20709 headers='f.h g.h h.h' 20710 @end example 20711 20712 @noindent 20713 but @code{g.h} is still a plain word. (As an aside, the idiom 20714 @code{headers='$(HEADERS)'; for i in $$headers;} is a good 20715 idea if @code{$(HEADERS)} can be empty, because some shells diagnose a 20716 syntax error on @code{for i in;}.) 20717 20718 One workaround is to strip this unwanted @file{../pkg/src/} prefix manually: 20719 20720 @example 20721 VPATH = ../pkg/src 20722 HEADERS = f.h g.h h.h 20723 install-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 20734 Automake does something similar. However the above hack works only if 20735 the files listed in @code{HEADERS} are in the current directory or a 20736 subdirectory; they should not be in an enclosing directory. If we had 20737 @code{HEADERS = ../f.h}, the above fragment would fail in a VPATH 20738 build with Tru64 @command{make}. The reason is that not only does 20739 Tru64 @command{make} rewrite dependencies, but it also simplifies 20740 them. Hence @code{../f.h} becomes @code{../pkg/f.h} instead of 20741 @code{../pkg/src/../f.h}. This obviously defeats any attempt to strip 20742 a leading @file{../pkg/src/} component. 20743 20744 The following example makes the behavior of Tru64 @command{make} 20745 more apparent. 20746 20747 @example 20748 $ @kbd{cat Makefile} 20749 VPATH = sub 20750 all: ../foo 20751 echo ../foo 20752 $ @kbd{ls} 20753 Makefile foo 20754 $ @kbd{make} 20755 echo foo 20756 foo 20757 @end example 20758 20759 @noindent 20760 Dependency @file{../foo} was found in @file{sub/../foo}, but Tru64 20761 @command{make} simplified it as @file{foo}. (Note that the @file{sub/} 20762 directory does not even exist, this just means that the simplification 20763 occurred before the file was checked for.) 20764 20765 For the record here is how SunOS 4 @command{make} behaves on this 20766 example. 20767 20768 @smallexample 20769 $ @kbd{make} 20770 make: Fatal error: Don't know how to make target `../foo' 20771 $ @kbd{mkdir sub} 20772 $ @kbd{make} 20773 echo sub/../foo 20774 sub/../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 20783 When 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 20790 VPATH = .. 20791 all: foo/bar 20792 END} 20793 $ @kbd{make} 20794 mkdir foo 20795 mkdir foo/bar 20796 @end example 20797 20798 This can yield unexpected results if a rule uses a manual @code{VPATH} 20799 search as presented before. 20800 20801 @example 20802 VPATH = .. 20803 all : foo/bar 20804 command `test -d foo/bar || echo ../`foo/bar 20805 @end example 20806 20807 The above @command{command} is run on the empty @file{foo/bar} 20808 directory 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 20814 GNU @command{make} uses a complex algorithm to decide when it 20815 should use files found via a @code{VPATH} search. @xref{Search 20816 Algorithm, , How Directory Searches are Performed, make, The GNU Make 20817 Manual}. 20818 20819 If a target needs to be rebuilt, GNU @command{make} discards the 20820 file name found during the @code{VPATH} search for this target, and 20821 builds the file locally using the file name given in the makefile. 20822 If a target does not need to be rebuilt, GNU @command{make} uses the 20823 file name found during the @code{VPATH} search. 20824 20825 Other @command{make} implementations, like NetBSD @command{make}, are 20826 easier to describe: the file name found during the @code{VPATH} search 20827 is used whether the target needs to be rebuilt or not. Therefore 20828 new files are created locally, but existing files are updated at their 20829 @code{VPATH} location. 20830 20831 OpenBSD and FreeBSD @command{make}, however, 20832 never perform a 20833 @code{VPATH} search for a dependency that has an explicit rule. 20834 This is extremely annoying. 20835 20836 When attempting a @code{VPATH} build for an autoconfiscated package 20837 (e.g., @code{mkdir build && cd build && ../configure}), this means 20838 GNU 20839 @command{make} builds everything locally in the @file{build} 20840 directory, while BSD @command{make} builds new files locally and 20841 updates existing files in the source directory. 20842 20843 @example 20844 $ @kbd{cat Makefile} 20845 VPATH = .. 20846 all: foo.x bar.x 20847 foo.x bar.x: newer.x 20848 @@echo Building $@@ 20849 $ @kbd{touch ../bar.x} 20850 $ @kbd{touch ../newer.x} 20851 $ @kbd{make} # GNU make 20852 Building foo.x 20853 Building bar.x 20854 $ @kbd{pmake} # NetBSD make 20855 Building foo.x 20856 Building ../bar.x 20857 $ @kbd{fmake} # FreeBSD make, OpenBSD make 20858 Building foo.x 20859 Building bar.x 20860 $ @kbd{tmake} # Tru64 make 20861 Building foo.x 20862 Building bar.x 20863 $ @kbd{touch ../bar.x} 20864 $ @kbd{make} # GNU make 20865 Building foo.x 20866 $ @kbd{pmake} # NetBSD make 20867 Building foo.x 20868 $ @kbd{fmake} # FreeBSD make, OpenBSD make 20869 Building foo.x 20870 Building bar.x 20871 $ @kbd{tmake} # Tru64 make 20872 Building foo.x 20873 Building bar.x 20874 @end example 20875 20876 Note how NetBSD @command{make} updates @file{../bar.x} in its 20877 VPATH location, and how FreeBSD, OpenBSD, and Tru64 20878 @command{make} always 20879 update @file{bar.x}, even when @file{../bar.x} is up to date. 20880 20881 Another point worth mentioning is that once GNU @command{make} has 20882 decided 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 20884 the target occurs as a prerequisite of another rule. 20885 20886 The 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, 20888 because it ignored the @code{VPATH} result of @file{bar.x} while running 20889 the @code{bar.x: newer.x} rule. 20890 20891 @example 20892 $ @kbd{cat Makefile} 20893 VPATH = .. 20894 all: bar.y 20895 bar.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 20903 Building bar.x 20904 cp bar.x bar.y 20905 cp: cannot stat `bar.x': No such file or directory 20906 make: *** [bar.y] Error 1 20907 $ @kbd{pmake} # NetBSD make 20908 Building ../bar.x 20909 cp ../bar.x bar.y 20910 $ @kbd{rm bar.y} 20911 $ @kbd{fmake} # FreeBSD make, OpenBSD make 20912 echo Building bar.x 20913 cp bar.x bar.y 20914 cp: cannot stat `bar.x': No such file or directory 20915 *** Error code 1 20916 $ @kbd{tmake} # Tru64 make 20917 Building bar.x 20918 cp: bar.x: No such file or directory 20919 *** Exit 1 20920 @end example 20921 20922 Note that if you drop away the command from the @code{bar.x: newer.x} 20923 rule, GNU @command{make} magically starts to work: it 20924 knows that @code{bar.x} hasn't been updated, therefore it doesn't 20925 discard the result from @code{VPATH} (@file{../bar.x}) in succeeding 20926 uses. Tru64 also works, but FreeBSD and OpenBSD 20927 still don't. 20928 20929 @example 20930 $ @kbd{cat Makefile} 20931 VPATH = .. 20932 all: bar.y 20933 bar.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 20940 cp ../bar.x bar.y 20941 $ @kbd{rm bar.y} 20942 $ @kbd{pmake} # NetBSD make 20943 cp ../bar.x bar.y 20944 $ @kbd{rm bar.y} 20945 $ @kbd{fmake} # FreeBSD make, OpenBSD make 20946 cp bar.x bar.y 20947 cp: cannot stat `bar.x': No such file or directory 20948 *** Error code 1 20949 $ @kbd{tmake} # Tru64 make 20950 cp ../bar.x bar.y 20951 @end example 20952 20953 It seems the sole solution that would please every @command{make} 20954 implementation is to never rely on @code{VPATH} searches for targets. 20955 In 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 20962 A @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 20968 of a target, without defining a rule. Usually one can list on the one 20969 hand side, the rules, and on the other hand side, the dependencies. 20970 20971 Solaris @command{make} does not support separated dependencies for 20972 targets defined by single suffix rules: 20973 20974 @example 20975 $ @kbd{cat Makefile} 20976 .SUFFIXES: .in 20977 foo: foo.in 20978 .in: 20979 cp $< $@@ 20980 $ @kbd{touch foo.in} 20981 $ @kbd{make} 20982 $ @kbd{ls} 20983 Makefile foo.in 20984 @end example 20985 20986 @noindent 20987 while GNU Make does: 20988 20989 @example 20990 $ @kbd{gmake} 20991 cp foo.in foo 20992 $ @kbd{ls} 20993 Makefile foo foo.in 20994 @end example 20995 20996 Note 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} 21004 cp foo.in foo 21005 @end example 21006 21007 @noindent 21008 and it works with double suffix inference rules: 21009 21010 @example 21011 $ @kbd{cat Makefile} 21012 foo.out: foo.in 21013 .SUFFIXES: .in .out 21014 .in.out: 21015 cp $< $@@ 21016 $ @kbd{make} 21017 cp foo.in foo.out 21018 @end example 21019 21020 As 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 21025 Traditionally, file timestamps had 1-second resolution, and 21026 @command{make} used those timestamps to determine whether one file was 21027 newer than the other. However, many modern file systems have 21028 timestamps with 1-nanosecond resolution. Some @command{make} 21029 implementations look at the entire timestamp; others ignore the 21030 fractional part, which can lead to incorrect results. Normally this 21031 is not a problem, but in some extreme cases you may need to use tricks 21032 like @samp{sleep 1} to work around timestamp truncation bugs. 21033 21034 Commands like @samp{cp -p} and @samp{touch -r} typically do not copy 21035 file timestamps to their full resolutions (@pxref{touch, , Limitations of Usual 21036 Tools}). Hence you should be wary of rules like this: 21037 21038 @example 21039 dest: src 21040 cp -p src dest 21041 @end example 21042 21043 as @file{dest} often appears to be older than @file{src} after the 21044 timestamp is truncated, and this can cause @command{make} to do 21045 needless rework the next time it is invoked. To work around this 21046 problem, you can use a timestamp file, e.g.: 21047 21048 @example 21049 dest-stamp: src 21050 cp -p src dest 21051 date >dest-stamp 21052 @end example 21053 21054 Apart from timestamp resolution, there are also differences in handling 21055 equal timestamps. HP-UX @command{make} updates targets if it has the 21056 same time stamp as one of its prerequisites, in violation of Posix rules. 21057 21058 This can cause spurious rebuilds for repeated runs of @command{make}. 21059 This in turn can cause @command{make} to fail if it tries to rebuild 21060 generated files in a possibly read-only source tree with tools not 21061 present 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 21071 C and C++ programs often use low-level features of the underlying 21072 system, and therefore are often more difficult to make portable to other 21073 platforms. 21074 21075 Several standards have been developed to help make your programs more 21076 portable. If you write programs with these standards in mind, you can 21077 have greater confidence that your programs work on a wide variety 21078 of systems. 21079 @ifhtml 21080 @uref{http://@/gcc.gnu.org/@/onlinedocs/@/gcc/@/Standards.html, Language 21081 Standards Supported by GCC} 21082 @end ifhtml 21083 @ifnothtml 21084 @xref{Standards, , Language Standards Supported by 21085 GCC, gcc, Using the GNU Compiler Collection 21086 (GCC)}, 21087 @end ifnothtml 21088 for a list of C-related standards. Many programs also assume the 21089 @uref{http://@/www.opengroup.org/@/susv3, Posix standard}. 21090 21091 Some old code is written to be portable to K&R C, which predates any C 21092 standard. K&R C compilers are no longer of practical interest, though, 21093 and the rest of section assumes at least C89, the first C standard. 21094 21095 Program portability is a huge topic, and this section can only briefly 21096 introduce common pitfalls. @xref{System Portability, , Portability 21097 between System Types, standards, The GNU Coding Standards}, for 21098 more 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 21115 Autoconf tests and ordinary programs often need to test what is allowed 21116 on a system, and therefore they may need to deliberately exceed the 21117 boundaries of what the standards allow, if only to see whether an 21118 optional feature is present. When you write such a program, you should 21119 keep in mind the difference between constraints, unspecified behavior, 21120 and undefined behavior. 21121 21122 In C, a @dfn{constraint} is a rule that the compiler must enforce. An 21123 example constraint is that C programs must not declare a bit-field with 21124 negative width. Tests can therefore reliably assume that programs with 21125 negative-width bit-fields are rejected by a compiler that conforms 21126 to the standard. 21127 21128 @dfn{Unspecified behavior} is valid behavior, where the standard allows 21129 multiple possibilities. For example, the order of evaluation of 21130 function arguments is unspecified. Some unspecified behavior is 21131 @dfn{implementation-defined}, i.e., documented by the implementation, 21132 but since Autoconf tests cannot read the documentation they cannot 21133 distinguish between implementation-defined and other unspecified 21134 behavior. It is common for Autoconf tests to probe implementations to 21135 determine otherwise-unspecified behavior. 21136 21137 @dfn{Undefined behavior} is invalid behavior, where the standard allows 21138 the implementation to do anything it pleases. For example, 21139 dereferencing a null pointer leads to undefined behavior. If possible, 21140 test programs should avoid undefined behavior, since a program with 21141 undefined behavior might succeed on a test that should fail. 21142 21143 The above rules apply to programs that are intended to conform to the 21144 standard. However, strictly-conforming programs are quite rare, since 21145 the standards are so limiting. A major goal of Autoconf is to support 21146 programs that use implementation features not described by the standard, 21147 and it is fairly common for test programs to violate the above rules, if 21148 the 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 21157 In practice many portable C programs assume that signed integer overflow wraps 21158 around reliably using two's complement arithmetic. Yet the C standard 21159 says that program behavior is undefined on overflow, and in a few cases 21160 C programs do not work on some modern implementations because their 21161 overflows do not wrap around as their authors expected. Conversely, in 21162 signed integer remainder, the C standard requires overflow 21163 behavior 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 21180 In languages like C, unsigned integer overflow reliably wraps around; 21181 e.g., @code{UINT_MAX + 1} yields zero. 21182 This is guaranteed by the C standard and is 21183 portable in practice, unless you specify aggressive, 21184 nonstandard optimization options 21185 suitable only for special applications. 21186 21187 In contrast, the C standard says that signed integer overflow leads to 21188 undefined behavior where a program can do anything, including dumping 21189 core or overrunning a buffer. The misbehavior can even precede the 21190 overflow. Such an overflow can occur during addition, subtraction, 21191 multiplication, division, and left shift. 21192 21193 Despite this requirement of the standard, many C programs and Autoconf 21194 tests assume that signed integer overflow silently wraps around modulo a 21195 power of two, using two's complement arithmetic, so long as you cast the 21196 resulting value to a signed integer type or store it into a signed 21197 integer variable. If you use conservative optimization flags, such 21198 programs are generally portable to the vast majority of modern 21199 platforms, with a few exceptions discussed later. 21200 21201 For historical reasons the C standard also allows implementations with 21202 ones' complement or signed magnitude arithmetic, but it is safe to 21203 assume two's complement nowadays. 21204 21205 Also, overflow can occur when converting an out-of-range value to a 21206 signed integer type. Here a standard implementation must define what 21207 happens, but this might include raising an exception. In practice all 21208 known implementations support silent wraparound in this case, so you need 21209 not 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 21218 There has long been a tension between what the C standard requires for 21219 signed integer overflow, and what C programs commonly assume. The 21220 standard allows aggressive optimizations based on assumptions that 21221 overflow never occurs, but many practical C programs rely on overflow 21222 wrapping around. These programs do not conform to the standard, but 21223 they commonly work in practice because compiler writers are 21224 understandably reluctant to implement optimizations that would break 21225 many programs, unless perhaps a user specifies aggressive optimization. 21226 21227 The C Standard says that if a program has signed integer overflow its 21228 behavior is undefined, and the undefined behavior can even precede the 21229 overflow. 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 21234 if (password == expected_password) 21235 allow_superuser_privileges (); 21236 else if (counter++ == INT_MAX) 21237 abort (); 21238 else 21239 printf ("%d password mismatches\n", counter); 21240 @end example 21241 21242 @noindent 21243 If the @code{int} variable @code{counter} equals @code{INT_MAX}, 21244 @code{counter++} must overflow and the behavior is undefined, so the C 21245 standard allows the compiler to optimize away the test against 21246 @code{INT_MAX} and the @code{abort} call. 21247 Worse, if an earlier bug in the program lets the compiler deduce that 21248 @code{counter == INT_MAX} or that @code{counter} previously overflowed, 21249 the C standard allows the compiler to optimize away the password test 21250 and generate code that allows superuser privileges unconditionally. 21251 21252 Despite this requirement by the standard, it has long been common for C 21253 code to assume wraparound arithmetic after signed overflow, and all 21254 known practical C implementations support some C idioms that assume 21255 wraparound signed arithmetic, even if the idioms do not conform 21256 strictly to the standard. If your code looks like the following 21257 examples it will almost surely work with real-world compilers. 21258 21259 Here is an example derived from the 7th Edition Unix implementation of 21260 @code{atoi} (1979-01-10): 21261 21262 @example 21263 char *p; 21264 int f, n; 21265 @dots{} 21266 while (*p >= '0' && *p <= '9') 21267 n = n * 10 + *p++ - '0'; 21268 return (f ? -n : n); 21269 @end example 21270 21271 @noindent 21272 Even if the input string is in range, on most modern machines this has 21273 signed overflow when computing the most negative integer (the @code{-n} 21274 overflows) or a value near an extreme integer (the first @code{+} 21275 overflows). 21276 21277 Here is another example, derived from the 7th Edition implementation of 21278 @code{rand} (1979-01-10). Here the programmer expects both 21279 multiplication and addition to wrap on overflow: 21280 21281 @example 21282 static long int randx = 1; 21283 @dots{} 21284 randx = randx * 1103515245 + 12345; 21285 return (randx >> 16) & 077777; 21286 @end example 21287 21288 In the following example, derived from the GNU C Library 2.5 21289 implementation of @code{mktime} (2006-09-09), the code assumes 21290 wraparound arithmetic in @code{+} to detect signed overflow: 21291 21292 @example 21293 time_t t, t1, t2; 21294 int sec_requested, sec_adjustment; 21295 @dots{} 21296 t1 = t + sec_requested; 21297 t2 = t1 + sec_adjustment; 21298 if (((t1 < t) != (sec_requested < 0)) 21299 | ((t2 < t1) != (sec_adjustment < 0))) 21300 return -1; 21301 @end example 21302 21303 If your code looks like these examples, it is probably safe even though 21304 it does not strictly conform to the C standard. This might lead one to 21305 believe that one can generally assume wraparound on overflow, but that 21306 is 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 21312 Compilers sometimes generate code that is incompatible with wraparound 21313 integer arithmetic. A simple example is an algebraic simplification: a 21314 compiler might translate @code{(i * 2000) / 1000} to @code{i * 2} 21315 because it assumes that @code{i * 2000} does not overflow. The 21316 translation is not equivalent to the original when overflow occurs: 21317 e.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}, 21319 the original expression returns @minus{}2147483 but the optimized 21320 version returns the mathematically correct value 2147484. 21321 21322 More subtly, loop induction optimizations often exploit the undefined 21323 behavior of signed overflow. Consider the following contrived function 21324 @code{sumc}: 21325 21326 @example 21327 int 21328 sumc (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 21339 To avoid multiplying by 53 each time through the loop, an optimizing 21340 compiler might internally transform @code{sumc} to the equivalent of the 21341 following: 21342 21343 @example 21344 int 21345 transformed_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 21357 This transformation is allowed by the C standard, but it is invalid for 21358 wraparound arithmetic when @code{INT_MAX / 53 < hi}, because then the 21359 overflow in computing expressions like @code{hi * 53} can cause the 21360 expression @code{i <= hi} to yield a different value from the 21361 transformed expression @code{ic <= hic}. 21362 21363 For this reason, compilers that use loop induction and similar 21364 techniques often do not support reliable wraparound arithmetic when a 21365 loop induction variable like @code{ic} is involved. Since loop 21366 induction variables are generated by the compiler, and are not visible 21367 in the source code, it is not always trivial to say whether the problem 21368 affects your code. 21369 21370 Hardly any code actually depends on wraparound arithmetic in cases like 21371 these, so in practice these loop induction optimizations are almost 21372 always useful. However, edge cases in this area can cause problems. 21373 For example: 21374 21375 @example 21376 int j; 21377 for (j = 1; 0 < j; j *= 2) 21378 test (j); 21379 @end example 21380 21381 @noindent 21382 Here, the loop attempts to iterate through all powers of 2 that 21383 @code{int} can represent, but the C standard allows a compiler to 21384 optimize away the comparison and generate an infinite loop, 21385 under the argument that behavior is undefined on overflow. As of this 21386 writing this optimization is not done by any production version of 21387 GCC with @option{-O2}, but it might be performed by other 21388 compilers, or by more aggressive GCC optimization options, 21389 and the GCC developers have not decided whether it will 21390 continue 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 21399 Ideally the safest approach is to avoid signed integer overflow 21400 entirely. For example, instead of multiplying two signed integers, you 21401 can convert them to unsigned integers, multiply the unsigned values, 21402 then test whether the result is in signed range. 21403 21404 Rewriting code in this way will be inconvenient, though, particularly if 21405 the signed values might be negative. Also, it may hurt 21406 performance. Using unsigned arithmetic to check for overflow is 21407 particularly painful to do portably and efficiently when dealing with an 21408 integer type like @code{uid_t} whose width and signedness vary from 21409 platform to platform. 21410 21411 Furthermore, many C applications pervasively assume wraparound behavior 21412 and typically it is not easy to find and remove all these assumptions. 21413 Hence it is often useful to maintain nonstandard code that assumes 21414 wraparound on overflow, instead of rewriting the code. The rest of this 21415 section attempts to give practical advice for this situation. 21416 21417 If your code wants to detect signed integer overflow in @code{sum = a + 21418 b}, it is generally safe to use an expression like @code{(sum < a) != (b 21419 < 0)}. 21420 21421 If your code uses a signed loop index, make sure that the index cannot 21422 overflow, along with all signed expressions derived from the index. 21423 Here is a contrived example of problematic code with two instances of 21424 overflow. 21425 21426 @example 21427 for (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 21436 Because of the two overflows, a compiler might optimize away or 21437 transform the two comparisons in a way that is incompatible with the 21438 wraparound assumption. 21439 21440 If your code uses an expression like @code{(i * 2000) / 1000} and you 21441 actually want the multiplication to wrap around on overflow, use 21442 unsigned arithmetic 21443 to do it, e.g., @code{((int) (i * 2000u)) / 1000}. 21444 21445 If your code assumes wraparound behavior and you want to insulate it 21446 against any GCC optimizations that would fail to support that 21447 behavior, you should use GCC's @option{-fwrapv} option, which 21448 causes signed overflow to wrap around reliably (except for division and 21449 remainder, as discussed in the next section). 21450 21451 If you need to port to platforms where signed integer overflow does not 21452 reliably wrap around (e.g., due to hardware overflow checking, or to 21453 highly aggressive optimizations), you should consider debugging with 21454 GCC's @option{-ftrapv} option, which causes signed overflow to 21455 raise an exception. 21456 21457 @node Signed Integer Division 21458 @subsection Signed Integer Division and Integer Overflow 21459 @cindex division, integer 21460 21461 Overflow in signed 21462 integer division is not always harmless: for example, on CPUs of the 21463 i386 family, dividing @code{INT_MIN} by @code{-1} yields a SIGFPE signal 21464 which by default terminates the program. Worse, taking the remainder 21465 of these two values typically yields the same signal on these CPUs, 21466 even though the C standard requires @code{INT_MIN % -1} to yield zero 21467 because the expression does not overflow. 21468 21469 @node Preprocessor Arithmetic 21470 @section Preprocessor Arithmetic 21471 @cindex preprocessor arithmetic 21472 21473 In C99, preprocessor arithmetic, used for @code{#if} expressions, must 21474 be evaluated as if all signed values are of type @code{intmax_t} and all 21475 unsigned values of type @code{uintmax_t}. Many compilers are buggy in 21476 this area, though. For example, as of 2007, Sun C mishandles @code{#if 21477 LLONG_MIN < 0} on a platform with 32-bit @code{long int} and 64-bit 21478 @code{long long int}. Also, some older preprocessors mishandle 21479 constants ending in @code{LL}. To work around these problems, you can 21480 compute 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 21487 Most modern hosts reliably fail when you attempt to dereference a null 21488 pointer. 21489 21490 On almost all modern hosts, null pointers use an all-bits-zero internal 21491 representation, so you can reliably use @code{memset} with 0 to set all 21492 the pointers in an array to null values. 21493 21494 If @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 21496 the standard says that it has undefined behavior. 21497 21498 @node Buffer Overruns 21499 @section Buffer Overruns and Subscript Errors 21500 @cindex buffer overruns 21501 21502 Buffer overruns and subscript errors are the most common dangerous 21503 errors in C programs. They result in undefined behavior because storing 21504 outside an array typically modifies storage that is used by some other 21505 object, and most modern systems lack runtime checks to catch these 21506 errors. Programs should not rely on buffer overruns being caught. 21507 21508 There is one exception to the usual rule that a portable program cannot 21509 address outside an array. In C, it is valid to compute the address just 21510 past an object, e.g., @code{&a[N]} where @code{a} has @code{N} elements, 21511 so long as you do not dereference the resulting pointer. But it is not 21512 valid to compute the address just before an object, e.g., @code{&a[-1]}; 21513 nor is it valid to compute two past the end, e.g., @code{&a[N+1]}. On 21514 most platforms @code{&a[-1] < &a[0] && &a[N] < &a[N+1]}, but this is not 21515 reliable in general, and it is usually easy enough to avoid the 21516 potential portability problem, e.g., by allocating an extra unused array 21517 element at the start or end. 21518 21519 @uref{http://@/valgrind.org/, Valgrind} can catch many overruns. 21520 GCC 21521 users might also consider using the @option{-fmudflap} option to catch 21522 overruns. 21523 21524 Buffer overruns are usually caused by off-by-one errors, but there are 21525 more subtle ways to get them. 21526 21527 Using @code{int} values to index into an array or compute array sizes 21528 causes problems on typical 64-bit hosts where an array index might 21529 be @math{2^{31}} or larger. Index values of type @code{size_t} avoid this 21530 problem, but cannot be negative. Index values of type @code{ptrdiff_t} 21531 are signed, and are wide enough in practice. 21532 21533 If 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 21535 multiplication overflows. 21536 21537 Many implementations of the @code{alloca} function silently misbehave 21538 and can generate buffer overflows if given sizes that are too large. 21539 The size limits are implementation dependent, but are at least 4000 21540 bytes on all platforms that we know about. 21541 21542 The standard functions @code{asctime}, @code{asctime_r}, @code{ctime}, 21543 @code{ctime_r}, and @code{gets} are prone to buffer overflows, and 21544 portable code should not use them unless the inputs are known to be 21545 within certain limits. The time-related functions can overflow their 21546 buffers if given timestamps out of range (e.g., a year less than -999 21547 or greater than 9999). Time-related buffer overflows cannot happen with 21548 recent-enough versions of the GNU C library, but are possible 21549 with other 21550 implementations. The @code{gets} function is the worst, since it almost 21551 invariably overflows its buffer when presented with an input line larger 21552 than the buffer. 21553 21554 @node Volatile Objects 21555 @section Volatile Objects 21556 @cindex volatile objects 21557 21558 The keyword @code{volatile} is often misunderstood in portable code. 21559 Its use inhibits some memory-access optimizations, but programmers often 21560 wish that it had a different meaning than it actually does. 21561 21562 @code{volatile} was designed for code that accesses special objects like 21563 memory-mapped device registers whose contents spontaneously change. 21564 Such code is inherently low-level, and it is difficult to specify 21565 portably what @code{volatile} means in these cases. The C standard 21566 says, ``What constitutes an access to an object that has 21567 volatile-qualified type is implementation-defined,'' so in theory each 21568 implementation is supposed to fill in the gap by documenting what 21569 @code{volatile} means for that implementation. In practice, though, 21570 this documentation is usually absent or incomplete. 21571 21572 One area of confusion is the distinction between objects defined with 21573 volatile types, and volatile lvalues. From the C standard's point of 21574 view, an object defined with a volatile type has externally visible 21575 behavior. You can think of such objects as having little oscilloscope 21576 probes attached to them, so that the user can observe some properties of 21577 accesses to them, just as the user can observe data written to output 21578 files. However, the standard does not make it clear whether users can 21579 observe 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. */ 21584 static int volatile x; 21585 x = 1; 21586 21587 /* Access two ordinary objects via a volatile lvalue. 21588 It's not clear whether accesses to *P are "visible". */ 21589 int y; 21590 int *z = malloc (sizeof (int)); 21591 int volatile *p; 21592 p = &y; 21593 *p = 1; 21594 p = z; 21595 *p = 1; 21596 @end example 21597 21598 Programmers often wish that @code{volatile} meant ``Perform the memory 21599 access here and now, without merging several memory accesses, without 21600 changing the memory word size, and without reordering.'' But the C 21601 standard does not require this. For objects defined with a volatile 21602 type, accesses must be done before the next sequence point; but 21603 otherwise merging, reordering, and word-size change is allowed. Worse, 21604 it is not clear from the standard whether volatile lvalues provide more 21605 guarantees in general than nonvolatile lvalues, if the underlying 21606 objects are ordinary. 21607 21608 Even when accessing objects defined with a volatile type, 21609 the C standard allows only 21610 extremely limited signal handlers: the behavior is undefined if a signal 21611 handler reads any nonlocal object, or writes to any nonlocal object 21612 whose type is not @code{sig_atomic_t volatile}, or calls any standard 21613 library function other than @code{abort}, @code{signal}, and (if C99) 21614 @code{_Exit}. Hence C compilers need not worry about a signal handler 21615 disturbing 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 21618 character, since it may point into part of a @code{sig_atomic_t 21619 volatile} object.) Posix 21620 adds to the list of library functions callable from a portable signal 21621 handler, but otherwise is like the C standard in this area. 21622 21623 Some C implementations allow memory-access optimizations within each 21624 translation unit, such that actual behavior agrees with the behavior 21625 required by the standard only when calling a function in some other 21626 translation unit, and a signal handler acts like it was called from a 21627 different translation unit. The C standard hints that in these 21628 implementations, objects referred to by signal handlers ``would require 21629 explicit specification of @code{volatile} storage, as well as other 21630 implementation-defined restrictions.'' But unfortunately even for this 21631 special case these other restrictions are often not documented well. 21632 @xref{Volatiles, , When is a Volatile Object Accessed?, gcc, Using the 21633 GNU Compiler Collection (GCC)}, for some 21634 restrictions imposed by GCC. @xref{Defining Handlers, , 21635 Defining Signal Handlers, libc, The GNU C Library}, for some 21636 restrictions imposed by the GNU C library. Restrictions 21637 differ on other platforms. 21638 21639 If possible, it is best to use a signal handler that fits within the 21640 limits imposed by the C and Posix standards. 21641 21642 If this is not practical, you can try the following rules of thumb. A 21643 signal handler should access only volatile lvalues, preferably lvalues 21644 that refer to objects defined with a volatile type, and should not 21645 assume that the accessed objects have an internally consistent state 21646 if they are larger than a machine word. Furthermore, installers 21647 should employ compilers and compiler options that are commonly used 21648 for building operating system kernels, because kernels often need more 21649 from @code{volatile} than the C Standard requires, and installers who 21650 compile an application in a similar environment can sometimes benefit 21651 from the extra constraints imposed by kernels on compilers. 21652 Admittedly we are handwaving somewhat here, as there are few 21653 guarantees in this area; the rules of thumb may help to fix some bugs 21654 but there is a good chance that they will not fix them all. 21655 21656 For @code{volatile}, C++ has the same problems that C does. 21657 Multithreaded applications have even more problems with @code{volatile}, 21658 but they are beyond the scope of this section. 21659 21660 The bottom line is that using @code{volatile} typically hurts 21661 performance but should not hurt correctness. In some cases its use 21662 does help correctness, but these cases are often so poorly understood 21663 that all too often adding @code{volatile} to a data structure merely 21664 alleviates 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 21670 Almost all modern systems use IEEE-754 floating point, and it is safe to 21671 assume IEEE-754 in most portable code these days. For more information, 21672 please see David Goldberg's classic paper 21673 @uref{http://@/www.validlab.com/@/goldberg/@/paper.pdf, What Every Computer 21674 Scientist Should Know About Floating-Point Arithmetic}. 21675 21676 @node Exiting Portably 21677 @section Exiting Portably 21678 @cindex exiting portably 21679 21680 A C or C++ program can exit with status @var{N} by returning 21681 @var{N} from the @code{main} function. Portable programs are supposed 21682 to exit either with status 0 or @code{EXIT_SUCCESS} to succeed, or with 21683 status @code{EXIT_FAILURE} to fail, but in practice it is portable to 21684 fail by exiting with status 1, and test programs that assume Posix can 21685 fail by exiting with status values from 1 through 255. Programs on 21686 SunOS 2.0 (1985) through 3.5.2 (1988) incorrectly exited with zero 21687 status when @code{main} returned nonzero, but ancient systems like these 21688 are no longer of practical concern. 21689 21690 A 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} 21692 function. If a program is specialized to just some platforms, it can fail 21693 by calling functions specific to those platforms, e.g., @code{_exit} 21694 (Posix) and @code{_Exit} (C99). However, like other functions, an exit 21695 function should be declared, typically by including a header. For 21696 example, if a C program calls @code{exit}, it should include @file{stdlib.h} 21697 either directly or via the default includes (@pxref{Default Includes}). 21698 21699 A program can fail due to undefined behavior such as dereferencing a null 21700 pointer, but this is not recommended as undefined behavior allows an 21701 implementation to do whatever it pleases and this includes exiting 21702 successfully. 21703 21704 21705 @c ================================================== Manual Configuration 21706 21707 @node Manual Configuration 21708 @chapter Manual Configuration 21709 21710 A few kinds of features can't be guessed automatically by running test 21711 programs. For example, the details of the object-file format, or 21712 special options that need to be passed to the compiler or linker. You 21713 can check for such features using ad-hoc means, such as having 21714 @command{configure} check the output of the @code{uname} program, or 21715 looking for libraries that are unique to particular systems. However, 21716 Autoconf 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 21732 Autoconf-generated 21733 @command{configure} scripts can make decisions based on a canonical name 21734 for 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 21739 system it's running on. To do so it runs a script called 21740 @command{config.guess}, which infers the name using the @code{uname} 21741 command or symbols predefined by the C preprocessor. 21742 21743 Alternately, the user can specify the system type with command line 21744 arguments to @command{configure} (@pxref{System Type}. Doing so is 21745 necessary when 21746 cross-compiling. In the most complex case of cross-compiling, three 21747 system types are involved. The options to specify them are: 21748 21749 @table @option 21750 @item --build=@var{build-type} 21751 the type of system on which the package is being configured and 21752 compiled. It defaults to the result of running @command{config.guess}. 21753 Specifying a @var{build-type} that differs from @var{host-type} enables 21754 cross-compilation mode. 21755 21756 @item --host=@var{host-type} 21757 the type of system on which the package runs. By default it is the 21758 same as the build machine. Specifying a @var{host-type} that differs 21759 from @var{build-type}, when @var{build-type} was also explicitly 21760 specified, enables cross-compilation mode. 21761 21762 @item --target=@var{target-type} 21763 the type of system for which any compiler tools in the package 21764 produce code (rarely needed). By default, it is the same as host. 21765 @end table 21766 21767 If you mean to override the result of @command{config.guess}, use 21768 @option{--build}, not @option{--host}, since the latter enables 21769 cross-compilation. For historical reasons, 21770 whenever you specify @option{--host}, 21771 be sure to specify @option{--build} too; this will be fixed in the 21772 future. 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 21779 Note that if you do not specify @option{--host}, @command{configure} 21780 fails if it can't run the code generated by the specified compiler. For 21781 example, configuring as follows fails: 21782 21783 @example 21784 ./configure CC=m68k-coff-gcc 21785 @end example 21786 21787 When cross-compiling, @command{configure} will warn about any tools 21788 (compilers, linkers, assemblers) whose name is not prefixed with the 21789 host type. This is an aid to users performing cross-compilation. 21790 Continuing the example above, if a cross-compiler named @command{cc} is 21791 used with a native @command{pkg-config}, then libraries found by 21792 @command{pkg-config} will likely cause subtle build failures; but using 21793 the names @command{m68k-coff-cc} and @command{m68k-coff-pkg-config} 21794 avoids any confusion. Avoiding the warning is as simple as creating the 21795 correct symlinks naming the cross tools. 21796 21797 @cindex @command{config.sub} 21798 @command{configure} recognizes short aliases for many system types; for 21799 example, @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 21803 This section deliberately omits the description of the obsolete 21804 interface; 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 21812 The following macros make the system type available to @command{configure} 21813 scripts. 21814 21815 @ovindex build_alias 21816 @ovindex host_alias 21817 @ovindex target_alias 21818 21819 The 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 21822 if the user did not use them, even if the corresponding 21823 @code{AC_CANONICAL} macro was run. Any configure script may use these 21824 variables anywhere. These are the variables that should be used when in 21825 interaction with the user. 21826 21827 If you need to recognize some special environments based on their system 21828 type, run the following macros to get canonical system names. These 21829 variables are not set before the macro call. 21830 21831 If you use these macros, you must distribute @command{config.guess} and 21832 @command{config.sub} along with your source code. @xref{Output}, for 21833 information about the @code{AC_CONFIG_AUX_DIR} macro which you can use 21834 to 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 21843 Compute the canonical build-system type variable, @code{build}, and its 21844 three individual parts @code{build_cpu}, @code{build_vendor}, and 21845 @code{build_os}. 21846 21847 If @option{--build} was specified, then @code{build} is the 21848 canonicalization of @code{build_alias} by @command{config.sub}, 21849 otherwise 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 21858 Compute the canonical host-system type variable, @code{host}, and its 21859 three individual parts @code{host_cpu}, @code{host_vendor}, and 21860 @code{host_os}. 21861 21862 If @option{--host} was specified, then @code{host} is the 21863 canonicalization of @code{host_alias} by @command{config.sub}, 21864 otherwise 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 21873 Compute the canonical target-system type variable, @code{target}, and its 21874 three individual parts @code{target_cpu}, @code{target_vendor}, and 21875 @code{target_os}. 21876 21877 If @option{--target} was specified, then @code{target} is the 21878 canonicalization of @code{target_alias} by @command{config.sub}, 21879 otherwise it defaults to @code{host}. 21880 @end defmac 21881 21882 Note that there can be artifacts due to the backward compatibility 21883 code. @xref{Hosts and Cross-Compilation}, for more. 21884 21885 @node Using System Type 21886 @section Using the System Type 21887 21888 In @file{configure.ac} the system type is generally used by one or more 21889 @code{case} statements to select system-specifics. Shell wildcards can 21890 be used to match a group of system types. 21891 21892 For example, an extra assembler code object file could be chosen, giving 21893 access to a CPU cycle counter register. @code{$(CYCLE_OBJ)} in the 21894 following would be used in a makefile to add the object to a 21895 program or library. 21896 21897 @example 21898 AS_CASE([$host], 21899 [alpha*-*-*], [CYCLE_OBJ=rpcc.o], 21900 [i?86-*-*], [CYCLE_OBJ=rdtsc.o], 21901 [CYCLE_OBJ=""] 21902 ) 21903 AC_SUBST([CYCLE_OBJ]) 21904 @end example 21905 21906 @code{AC_CONFIG_LINKS} (@pxref{Configuration Links}) is another good way 21907 to select variant source files, for example optimized code for some 21908 CPUs. The configured CPU type doesn't always indicate exact CPU types, 21909 so some runtime capability checks may be necessary too. 21910 21911 @example 21912 case $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]) ;; 21916 esac 21917 @end example 21918 21919 The host system type can also be used to find cross-compilation tools 21920 with @code{AC_CHECK_TOOL} (@pxref{Generic Programs}). 21921 21922 The above examples all show @samp{$host}, since this is where the code 21923 is going to run. Only rarely is it necessary to test @samp{$build} 21924 (which is where the build is being done). 21925 21926 Whenever you're tempted to use @samp{$host} it's worth considering 21927 whether some sort of probe would be better. New system types come along 21928 periodically or previously missing features are added. Well-written 21929 probes can adapt themselves to such things, but hard-coded lists of 21930 names can't. Here are some guidelines, 21931 21932 @itemize @bullet 21933 @item 21934 Availability of libraries and library functions should always be checked 21935 by probing. 21936 @item 21937 Variant behavior of system calls is best identified with runtime tests 21938 if possible, but bug workarounds or obscure difficulties might have to 21939 be driven from @samp{$host}. 21940 @item 21941 Assembler code is inevitably highly CPU-specific and is best selected 21942 according to @samp{$host_cpu}. 21943 @item 21944 Assembler variations like underscore prefix on globals or ELF versus 21945 COFF type directives are however best determined by probing, perhaps 21946 even examining the compiler output. 21947 @end itemize 21948 21949 @samp{$target} is for use by a package creating a compiler or similar. 21950 For ordinary packages it's meaningless and should not be used. It 21951 indicates what the created compiler should generate code for, if it can 21952 cross-compile. @samp{$target} generally selects various hard-coded CPU 21953 and system conventions, since usually the compiler or tools under 21954 construction 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 21963 decisions. There are ways for users to specify where external software 21964 packages are, include or exclude optional features, install programs 21965 under modified names, and set default values for @command{configure} 21966 options. 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 21982 Users consult @samp{configure --help} to learn of configuration 21983 decisions specific to your package. By default, @command{configure} 21984 breaks this output into sections for each type of option; within each 21985 section, help strings appear in the order @file{configure.ac} defines 21986 them: 21987 21988 @example 21989 Optional Features: 21990 @dots{} 21991 --enable-bar include bar 21992 21993 Optional Packages: 21994 @dots{} 21995 --with-foo use foo 21996 @end example 21997 21998 @defmac AC_PRESERVE_HELP_ORDER 21999 @acindex{PRESERVE_HELP_ORDER} 22000 22001 Request an alternate @option{--help} format, in which options of all 22002 types appear together, in the order defined. Call this macro before any 22003 @code{AC_ARG_ENABLE} or @code{AC_ARG_WITH}. 22004 22005 @example 22006 Optional 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 22018 Some packages require, or can optionally use, other software packages 22019 that are already installed. The user can give @command{configure} 22020 command line options to specify which such external software to use. 22021 The 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 22030 For example, @option{--with-gnu-ld} means work with the GNU linker 22031 instead of some other linker. @option{--with-x} means work with The X 22032 Window System. 22033 22034 The user can give an argument by following the package name with 22035 @samp{=} and the argument. Giving an argument of @samp{no} is for 22036 packages that are used by default; it says to @emph{not} use the 22037 package. An argument that is neither @samp{yes} nor @samp{no} could 22038 include a name or number of a version of the other package, to specify 22039 more precisely which other package this program is supposed to work 22040 with. 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 22044 Normally @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 22047 defaults. 22048 22049 For each external software package that may be used, @file{configure.ac} 22050 should call @code{AC_ARG_WITH} to detect whether the @command{configure} 22051 user asked to use it. Whether each package is used or not by default, 22052 and 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} 22058 If the user gave @command{configure} the option @option{--with-@var{package}} 22059 or @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 22062 software package that this program should work with. It should consist 22063 only of alphanumeric characters, dashes, plus signs, and dots. 22064 22065 The option's argument is available to the shell commands 22066 @var{action-if-given} in the shell variable @code{withval}, which is 22067 actually 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, 22070 if you wish. 22071 22072 The argument @var{help-string} is a description of the option that 22073 looks 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 22080 needed. Just make sure the columns line up in @samp{configure 22081 --help}. Avoid tabs in the help string. The easiest way to provide the 22082 proper leading whitespace is to format your @var{help-string} with the macro 22083 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}). 22084 22085 The following example shows how to use the @code{AC_ARG_WITH} macro in 22086 a common situation. You want to let the user decide whether to enable 22087 support for an external library (e.g., the readline library); if the user 22088 specified neither @option{--with-readline} nor @option{--without-readline}, 22089 you want to enable support for readline only if the library is available 22090 on the system. 22091 22092 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved. 22093 @example 22094 AC_ARG_WITH([readline], 22095 [AS_HELP_STRING([--with-readline], 22096 [support fancy command line editing @@<:@@default=check@@:>@@])], 22097 [], 22098 [with_readline=check]) 22099 22100 LIBREADLINE= 22101 AS_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 22114 The next example shows how to use @code{AC_ARG_WITH} to give the user the 22115 possibility to enable support for the readline library, in case it is still 22116 experimental 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 22120 AC_ARG_WITH([readline], 22121 [AS_HELP_STRING([--with-readline], 22122 [enable experimental support for readline])], 22123 [], 22124 [with_readline=no]) 22125 22126 LIBREADLINE= 22127 AS_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 22138 The last example shows how to use @code{AC_ARG_WITH} to give the user the 22139 possibility to disable support for the readline library, given that it is 22140 an 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 22144 AC_ARG_WITH([readline], 22145 [AS_HELP_STRING([--without-readline], 22146 [disable support for readline])], 22147 [], 22148 [with_readline=yes]) 22149 22150 LIBREADLINE= 22151 AS_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 22162 These 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 22172 If a software package has optional compile-time features, the user can 22173 give @command{configure} command line options to specify whether to 22174 compile 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 22183 These options allow users to choose which optional features to build and 22184 install. @option{--enable-@var{feature}} options should never make a 22185 feature behave differently or cause one feature to replace another. 22186 They should only cause parts of the program to be built rather than left 22187 out. 22188 22189 The user can give an argument by following the feature name with 22190 @samp{=} and the argument. Giving an argument of @samp{no} requests 22191 that the feature @emph{not} be made available. A feature with an 22192 argument looks like @option{--enable-debug=stabs}. If no argument is 22193 given, it defaults to @samp{yes}. @option{--disable-@var{feature}} is 22194 equivalent to @option{--enable-@var{feature}=no}. 22195 22196 Normally @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 22199 defaults. 22200 22201 For each optional feature, @file{configure.ac} should call 22202 @code{AC_ARG_ENABLE} to detect whether the @command{configure} user asked 22203 to include it. Whether each feature is included or not by default, and 22204 which 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} 22210 If the user gave @command{configure} the option 22211 @option{--enable-@var{feature}} or @option{--disable-@var{feature}}, run 22212 shell commands @var{action-if-given}. If neither option was given, run 22213 shell commands @var{action-if-not-given}. The name @var{feature} 22214 indicates an optional user-level facility. It should consist only of 22215 alphanumeric characters, dashes, plus signs, and dots. 22216 22217 The option's argument is available to the shell commands 22218 @var{action-if-given} in the shell variable @code{enableval}, which is 22219 actually 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, 22222 if you wish. The @var{help-string} argument is like that of 22223 @code{AC_ARG_WITH} (@pxref{External Software}). 22224 22225 You should format your @var{help-string} with the macro 22226 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}). 22227 22228 See 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 22237 Properly 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 22240 your own @samp{help strings} to line up in the appropriate columns of 22241 @samp{configure --help} just like the standard Autoconf @samp{help 22242 strings} 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 22249 Expands 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 22252 Options}). The following example makes this clearer. 22253 22254 @example 22255 AC_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 22262 Then the last few lines of @samp{configure --help} appear like 22263 this: 22264 22265 @example 22266 --enable and --with options recognized: 22267 --with-foo use foo (default is no) 22268 @end example 22269 22270 Macro expansion is performed on the first argument. However, the second 22271 argument of @code{AS_HELP_STRING} is treated as a whitespace separated 22272 list of text to be reformatted, and is not subject to macro expansion. 22273 Since it is not expanded, it should not be double quoted. 22274 @xref{Autoconf Language}, for a more detailed explanation. 22275 22276 The @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 22278 arguments, as shown in the following example. Be aware that 22279 @var{left-hand-side} may not expand to unbalanced quotes, 22280 although quadrigraphs can be used. 22281 22282 @example 22283 AC_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])]) 22289 MY_ARG_WITH([a_b], [no]) 22290 @end example 22291 @noindent 22292 Here, 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 22299 The parameters @var{indent-column} and @var{wrap-column} were introduced 22300 in Autoconf 2.62. Generally, they should not be specified; they exist 22301 for fine-tuning of the wrapping. 22302 @example 22303 AS_HELP_STRING([--option], [description of option]) 22304 @result{} --option description of option 22305 AS_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 22316 The @command{configure} script checks its command-line options against a 22317 list of known options, like @option{--help} or @option{--config-cache}. 22318 An 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}} 22321 options elicit only a warning, to support configuring entire source 22322 trees. 22323 22324 Source 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 22327 different @option{--with-@var{package}} and 22328 @option{--enable-@var{feature}} options, the GNU Coding 22329 Standards say they must accept unrecognized options without halting. 22330 Even a warning message is undesirable here, so @code{AC_CONFIG_SUBDIRS} 22331 automatically disables the warnings. 22332 22333 This default behavior may be modified in two ways. First, the installer 22334 can invoke @code{configure --disable-option-checking} to disable 22335 these warnings, or invoke @code{configure --enable-option-checking=fatal} 22336 options to turn them into fatal errors, respectively. Second, the 22337 maintainer can use @code{AC_DISABLE_OPTION_CHECKING}. 22338 22339 @defmac AC_DISABLE_OPTION_CHECKING 22340 @acindex{DISABLE_OPTION_CHECKING} 22341 22342 By default, disable warnings related to any unrecognized 22343 @option{--with-@var{package}} or @option{--enable-@var{feature}} 22344 options. This is implied by @code{AC_CONFIG_SUBDIRS}. 22345 22346 The 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 22357 Some software packages require complex site-specific information. Some 22358 examples are host names to use for certain services, company names, and 22359 email addresses to contact. Since some configuration scripts generated 22360 by Metaconfig ask for such information interactively, people sometimes 22361 wonder how to get that information in Autoconf-generated configuration 22362 scripts, which aren't interactive. 22363 22364 Such site configuration information should be put in a file that is 22365 edited @emph{only by users}, not by programs. The location of the file 22366 can either be based on the @code{prefix} variable, or be a standard 22367 location such as the user's home directory. It could even be specified 22368 by an environment variable. The programs should examine that file at 22369 runtime, rather than at compile time. Runtime configuration is more 22370 convenient for users and makes the configuration process simpler than 22371 getting the information while configuring. @xref{Directory Variables, , 22372 Variables for Installation Directories, standards, The GNU Coding 22373 Standards}, 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 22380 Autoconf supports changing the names of programs when installing them. 22381 In order to use these transformations, @file{configure.ac} must call the 22382 macro @code{AC_ARG_PROGRAM}. 22383 22384 @defmac AC_ARG_PROGRAM 22385 @acindex{ARG_PROGRAM} 22386 @ovindex program_transform_name 22387 Place in output variable @code{program_transform_name} a sequence of 22388 @code{sed} commands for changing the names of installed programs. 22389 22390 If any of the options described below are given to @command{configure}, 22391 program names are transformed accordingly. Otherwise, if 22392 @code{AC_CANONICAL_TARGET} has been called and a @option{--target} value 22393 is given, the target type followed by a dash is used as a prefix. 22394 Otherwise, 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 22406 You can specify name transformations by giving @command{configure} these 22407 command line options: 22408 22409 @table @option 22410 @item --program-prefix=@var{prefix} 22411 prepend @var{prefix} to the names; 22412 22413 @item --program-suffix=@var{suffix} 22414 append @var{suffix} to the names; 22415 22416 @item --program-transform-name=@var{expression} 22417 perform @code{sed} substitution @var{expression} on the names. 22418 @end table 22419 22420 @node Transformation Examples 22421 @subsection Transformation Examples 22422 22423 These transformations are useful with programs that can be part of a 22424 cross-compilation development environment. For example, a 22425 cross-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 22428 with a native Sun 4 assembler. 22429 22430 You can force a program name to begin with @file{g}, if you don't want 22431 GNU programs installed on your system to shadow other programs with 22432 the 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 22434 installed as @file{/usr/local/bin/gdiff}. 22435 22436 As 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 22443 to prepend @samp{g} to most of the program names in a source tree, 22444 excepting those like @code{gdb} that already have one and those like 22445 @code{less} and @code{lesskey} that aren't GNU programs. (That is 22446 assuming that you have a source tree containing those programs that is 22447 set up to use this feature.) 22448 22449 One way to install multiple versions of some programs simultaneously is 22450 to append a version number to the name of one or both. For example, if 22451 you want to keep Autoconf version 1 around for awhile, you can configure 22452 Autoconf version 2 using @option{--program-suffix=2} to install the 22453 programs as @file{/usr/local/bin/autoconf2}, 22454 @file{/usr/local/bin/autoheader2}, etc. Nevertheless, pay attention 22455 that only the binaries are renamed, therefore you'd have problems with 22456 the library files which might overlap. 22457 22458 @node Transformation Rules 22459 @subsection Transformation Rules 22460 22461 Here is how to use the variable @code{program_transform_name} in a 22462 @file{Makefile.in}: 22463 22464 @example 22465 PROGRAMS = cp ls rm 22466 transform = @@program_transform_name@@ 22467 install: 22468 for p in $(PROGRAMS); do \ 22469 $(INSTALL_PROGRAM) $$p $(DESTDIR)$(bindir)/`echo $$p | \ 22470 sed '$(transform)'`; \ 22471 done 22472 22473 uninstall: 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 22480 It is guaranteed that @code{program_transform_name} is never empty, and 22481 that there are no useless separators. Therefore you may safely embed 22482 @code{program_transform_name} within a sed program using @samp{;}: 22483 22484 @example 22485 transform = @@program_transform_name@@ 22486 transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/ 22487 @end example 22488 22489 Whether to do the transformations on documentation files (Texinfo or 22490 @code{man}) is a tricky question; there seems to be no perfect answer, 22491 due to the several reasons for name transforming. Documentation is not 22492 usually particular to a specific architecture, and Texinfo files do not 22493 conflict with system documentation. But they might conflict with 22494 earlier versions of the same files, and @code{man} pages sometimes do 22495 conflict with system documentation. As a compromise, it is probably 22496 best to do name transformations on @code{man} pages but not on Texinfo 22497 manuals. 22498 22499 @node Site Defaults 22500 @section Setting Site Defaults 22501 @cindex Site defaults 22502 @cindex config.site 22503 22504 Autoconf-generated @command{configure} scripts allow your site to provide 22505 default values for some configuration values. You do this by creating 22506 site- and system-wide initialization files. 22507 22508 @evindex CONFIG_SITE 22509 If the environment variable @code{CONFIG_SITE} is set, @command{configure} 22510 uses its value as the name of a shell script to read; it is recommended 22511 that this be an absolute file name. Otherwise, it 22512 reads the shell script @file{@var{prefix}/share/config.site} if it exists, 22513 then @file{@var{prefix}/etc/config.site} if it exists. Thus, 22514 settings in machine-specific files override those in machine-independent 22515 ones in case of conflict. 22516 22517 Site files can be arbitrary shell scripts, but only certain kinds of 22518 code are really appropriate to be in them. Because @command{configure} 22519 reads any cache file after it has read any site files, a site file can 22520 define a default cache file to be shared between all Autoconf-generated 22521 @command{configure} scripts run on that system (@pxref{Cache Files}). If 22522 you set a default cache file in a site file, it is a good idea to also 22523 set the output variable @code{CC} in that site file, because the cache 22524 file is only valid for a particular compiler, but many systems have 22525 several available. 22526 22527 You 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 22529 the same names as the options, with any dashes turned into underscores. 22530 The exceptions are that @option{--without-} and @option{--disable-} options 22531 are like giving the corresponding @option{--with-} or @option{--enable-} 22532 option and the value @samp{no}. Thus, @option{--cache-file=localcache} 22533 sets 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 22536 variable @code{prefix} to the value @samp{/usr}; etc. 22537 22538 Site files are also good places to set default values for other output 22539 variables, such as @code{CFLAGS}, if you need to give them non-default 22540 values: anything you would normally do, repetitively, on the command 22541 line. If you use non-default values for @var{prefix} or 22542 @var{exec_prefix} (wherever you locate the site file), you can set them 22543 in the site file if you specify it with the @code{CONFIG_SITE} 22544 environment variable. 22545 22546 You can set some cache values in the site file itself. Doing this is 22547 useful if you are cross-compiling, where it is impossible to check features 22548 that require running a test program. You could ``prime the cache'' by 22549 setting those values correctly for that system in 22550 @file{@var{prefix}/etc/config.site}. To find out the names of the cache 22551 variables you need to set, see the documentation of the respective 22552 Autoconf macro. If the variables or their semantics are undocumented, 22553 you may need to look for shell variables with @samp{_cv_} in their names 22554 in the affected @command{configure} scripts, or in the Autoconf M4 22555 source code for those macros; but in that case, their name or semantics 22556 may change in a future Autoconf version. 22557 22558 The cache file is careful to not override any variables set in the site 22559 files. Similarly, you should not override command-line options in the 22560 site files. Your code should check that variables such as @code{prefix} 22561 and @code{cache_file} have their default values (as set near the top of 22562 @command{configure}) before changing them. 22563 22564 Here is a sample file @file{/usr/share/local/@/gnu/share/@/config.site}. The 22565 command @samp{configure --prefix=/usr/share/local/gnu} would read this 22566 file (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. 22572 test "$prefix" = NONE && prefix=/usr/share/local/gnu 22573 test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu 22574 test "$sharedstatedir" = '$@{prefix@}/com' && sharedstatedir=/var 22575 test "$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. 22579 if 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 22583 fi 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 22591 Another use of @file{config.site} is for priming the directory variables 22592 @c ``File system'', but slightly obfuscated, as above. 22593 in 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 22597 the 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. 22602 if 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 22606 fi 22607 @end example 22608 22609 @cindex @file{lib64} 22610 @cindex 64-bit libraries 22611 Likewise, on platforms where 64-bit libraries are built by default, then 22612 installed in @file{/usr/local/@/lib64} instead of @file{/usr/local/@/lib}, 22613 it 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. 22618 test "$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 22628 Below are instructions on how to configure a package that uses a 22629 @command{configure} script, suitable for inclusion as an @file{INSTALL} 22630 file in the package. A plain-text version of @file{INSTALL} which you 22631 may 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 22656 The @command{configure} script creates a file named @file{config.status}, 22657 which actually configures, @dfn{instantiates}, the template files. It 22658 also records the configuration options that were specified when the 22659 package was last configured in case reconfiguring is needed. 22660 22661 Synopsis: 22662 @example 22663 ./config.status @ovar{option}@dots{} @ovar{tag}@dots{} 22664 @end example 22665 22666 It configures each @var{tag}; if none are specified, all the templates 22667 are instantiated. A @var{tag} refers to a file or other tag associated 22668 with a configuration action, as specified by an @code{AC_CONFIG_@var{ITEMS}} 22669 macro (@pxref{Configuration Actions}). The files must be specified 22670 without their dependencies, as in 22671 22672 @example 22673 ./config.status foobar 22674 @end example 22675 22676 @noindent 22677 not 22678 22679 @example 22680 ./config.status foobar:foo.in:bar.in 22681 @end example 22682 22683 The supported options are: 22684 22685 @table @option 22686 @item --help 22687 @itemx -h 22688 Print a summary of the command line options, the list of the template 22689 files, and exit. 22690 22691 @item --version 22692 @itemx -V 22693 Print the version number of Autoconf and the configuration settings, 22694 and exit. 22695 22696 @item --config 22697 Print the configuration settings in reusable way, quoted for the shell, 22698 and exit. For example, for a debugging build that otherwise reuses the 22699 configuration from a different build directory @var{build-dir} of a 22700 package in @var{src-dir}, you could use the following: 22701 22702 @example 22703 args=`@var{build-dir}/config.status --config` 22704 eval @var{src-dir}/configure "$args" CFLAGS=-g --srcdir=@var{src-dir} 22705 @end example 22706 22707 @noindent 22708 Note that it may be necessary to override a @option{--srcdir} setting 22709 that was saved in the configuration, if the arguments are used in a 22710 different build directory. 22711 22712 @item --silent 22713 @itemx --quiet 22714 @itemx -q 22715 Do not print progress messages. 22716 22717 @item --debug 22718 @itemx -d 22719 Don't remove the temporary files. 22720 22721 @item --file=@var{file}[:@var{template}] 22722 Require 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 22725 output and/or standard input, respectively, is used. If a 22726 @var{template} file name is relative, it is first looked for in the build 22727 tree, and then in the source tree. @xref{Configuration Actions}, for 22728 more details. 22729 22730 This option and the following ones provide one way for separately 22731 distributed packages to share the values computed by @command{configure}. 22732 Doing so can be useful if some of the packages need a superset of the 22733 features that one of them, perhaps a common library, does. These 22734 options allow a @file{config.status} file to create files other than the 22735 ones that its @file{configure.ac} specifies, so it can be used for a 22736 different package, or for extracting a subset of values. For example, 22737 22738 @example 22739 echo '@@CC@@' | ./config.status --file=- 22740 @end example 22741 22742 @noindent 22743 provides the value of @code{@@CC@@} on standard output. 22744 22745 @item --header=@var{file}[:@var{template}] 22746 Same as @option{--file} above, but with @samp{AC_CONFIG_HEADERS}. 22747 22748 @item --recheck 22749 Ask @file{config.status} to update itself and exit (no instantiation). 22750 This option is useful if you change @command{configure}, so that the 22751 results of some tests might be different from the previous run. The 22752 @option{--recheck} option reruns @command{configure} with the same arguments 22753 you 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, 22756 which prevents @command{configure} from running other @command{configure} 22757 scripts in subdirectories. (This is so other Make rules can 22758 run @file{config.status} when it changes; @pxref{Automatic Remaking}, 22759 for an example). 22760 @end table 22761 22762 @file{config.status} checks several optional environment variables that 22763 can alter its behavior: 22764 22765 @anchor{CONFIG_SHELL} 22766 @defvar CONFIG_SHELL 22767 @evindex CONFIG_SHELL 22768 The shell with which to run @command{configure}. It must be 22769 Bourne-compatible, and the absolute name of the shell should be passed. 22770 The 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 22776 The file name to use for the shell script that records the 22777 configuration. The default is @file{./config.status}. This variable is 22778 useful when one package uses parts of another and the @command{configure} 22779 scripts shouldn't be merged because they are maintained separately. 22780 @end defvar 22781 22782 You can use @file{./config.status} in your makefiles. For example, in 22783 the dependencies given above (@pxref{Automatic Remaking}), 22784 @file{config.status} is run twice when @file{configure.ac} has changed. 22785 If that bothers you, you can make each run only regenerate the files for 22786 that rule: 22787 @example 22788 @group 22789 config.h: stamp-h 22790 stamp-h: config.h.in config.status 22791 ./config.status config.h 22792 echo > stamp-h 22793 22794 Makefile: Makefile.in config.status 22795 ./config.status Makefile 22796 @end group 22797 @end example 22798 22799 The 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 22809 Autoconf changes, and throughout the years some constructs have been 22810 obsoleted. Most of the changes involve the macros, but in some cases 22811 the tools themselves, or even some concepts, are now considered 22812 obsolete. 22813 22814 You may completely skip this chapter if you are new to Autoconf. Its 22815 intention is mainly to help maintainers updating their packages by 22816 understanding 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 22831 instantiate; see @ref{config.status Invocation}, for more details. 22832 Before, environment variables had to be used. 22833 22834 @defvar CONFIG_COMMANDS 22835 @evindex CONFIG_COMMANDS 22836 The tags of the commands to execute. The default is the arguments given 22837 to @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 22843 The files in which to perform @samp{@@@var{variable}@@} substitutions. 22844 The 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 22850 The files in which to substitute C @code{#define} statements. The 22851 default is the arguments given to @code{AC_CONFIG_HEADERS}; if that 22852 macro was not called, @file{config.status} ignores this variable. 22853 @end defvar 22854 22855 @defvar CONFIG_LINKS 22856 @evindex CONFIG_LINKS 22857 The 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 22862 In @ref{config.status Invocation}, using this old interface, the example 22863 would be: 22864 22865 @example 22866 @group 22867 config.h: stamp-h 22868 stamp-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 22873 Makefile: 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 22881 no need to set @code{CONFIG_HEADERS} in the @command{make} rules. Equally 22882 for @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 22892 In order to produce @file{config.h.in}, @command{autoheader} needs to 22893 build or to find templates for each symbol. Modern releases of Autoconf 22894 use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader 22895 Macros}), but in older releases a file, @file{acconfig.h}, contained the 22896 list of needed templates. @command{autoheader} copied comments and 22897 @code{#define} and @code{#undef} statements from @file{acconfig.h} in 22898 the current directory, if present. This file used to be mandatory if 22899 you @code{AC_DEFINE} any additional symbols. 22900 22901 Modern 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: 22904 if @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, 22907 if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@}, 22908 @command{autoheader} copies the lines after that line to the end of the 22909 file it generates. Either or both of those strings may be omitted. An 22910 even older alternate way to produce the same effect in ancient versions 22911 of 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 22913 directory. If they exist, @command{autoheader} copies them to the 22914 beginning and end, respectively, of its output. 22915 22916 In former versions of Autoconf, the files used in preparing a software 22917 package for distribution were: 22918 @example 22919 @group 22920 configure.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 22932 Using only the @code{AH_} macros, @file{configure.ac} should be 22933 self-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 22940 The @command{autoupdate} program updates a @file{configure.ac} file that 22941 calls Autoconf macros by their old names to use the current macro names. 22942 In version 2 of Autoconf, most of the macros were renamed to use a more 22943 uniform and descriptive naming scheme. @xref{Macro Names}, for a 22944 description of the new scheme. Although the old names still work 22945 (@pxref{Obsolete Macros}, for a list of the old macros and the corresponding 22946 new names), you can make your @file{configure.ac} files more readable 22947 and make it easier to use the current Autoconf documentation if you 22948 update them to use the new macro names. 22949 22950 @evindex SIMPLE_BACKUP_SUFFIX 22951 If given no arguments, @command{autoupdate} updates @file{configure.ac}, 22952 backing up the original version with the suffix @file{~} (or the value 22953 of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is 22954 set). If you give @command{autoupdate} an argument, it reads that file 22955 instead of @file{configure.ac} and writes the updated file to the 22956 standard output. 22957 22958 @noindent 22959 @command{autoupdate} accepts the following options: 22960 22961 @table @option 22962 @item --help 22963 @itemx -h 22964 Print a summary of the command line options and exit. 22965 22966 @item --version 22967 @itemx -V 22968 Print the version number of Autoconf and exit. 22969 22970 @item --verbose 22971 @itemx -v 22972 Report processing steps. 22973 22974 @item --debug 22975 @itemx -d 22976 Don't remove the temporary files. 22977 22978 @item --force 22979 @itemx -f 22980 Force the update even if the file has not changed. Disregard the cache. 22981 22982 @item --include=@var{dir} 22983 @itemx -I @var{dir} 22984 Also look for input files in @var{dir}. Multiple invocations accumulate. 22985 Directories are browsed from last to first. 22986 22987 @item --prepend-include=@var{dir} 22988 @itemx -B @var{dir} 22989 Prepend directory @var{dir} to the search path. This is used to include 22990 the language-specific files before any third-party macros. 22991 @end table 22992 22993 @node Obsolete Macros 22994 @section Obsolete Macros 22995 22996 Several macros are obsoleted in Autoconf, for various reasons (typically 22997 they failed to quote properly, couldn't be extended for more recent 22998 issues, etc.). They are still supported, but deprecated: their use 22999 should be avoided. 23000 23001 During the jump from Autoconf version 1 to version 2, most of the 23002 macros were renamed to use a more uniform and descriptive naming scheme, 23003 but their signature did not change. @xref{Macro Names}, for a 23004 description of the new naming scheme. Below, if there is just the mapping 23005 from old names to new names for these macros, the reader is invited to 23006 refer to the definition of the new macro for the signature and the 23007 description. 23008 23009 @defmac AC_AIX 23010 @acindex{AIX} 23011 @cvindex _ALL_SOURCE 23012 This 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} 23018 Replaced by @code{AC_FUNC_ALLOCA} (@pxref{AC_FUNC_ALLOCA}). 23019 @end defmac 23020 23021 @defmac AC_ARG_ARRAY 23022 @acindex{ARG_ARRAY} 23023 Removed because of limited usefulness. 23024 @end defmac 23025 23026 @defmac AC_C_CROSS 23027 @acindex{C_CROSS} 23028 This 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 23034 If the C compiler supports a working @code{long double} type with more 23035 range or precision than the @code{double} type, define 23036 @code{HAVE_LONG_DOUBLE}. 23037 23038 You 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} 23044 Determine the system type and set output variables to the names of the 23045 canonical system types. @xref{Canonicalizing}, for details about the 23046 variables this macro sets. 23047 23048 The user is encouraged to use either @code{AC_CANONICAL_BUILD}, or 23049 @code{AC_CANONICAL_HOST}, or @code{AC_CANONICAL_TARGET}, depending on 23050 the needs. Using @code{AC_CANONICAL_TARGET} is enough to run the two 23051 other macros (@pxref{Canonicalizing}). 23052 @end defmac 23053 23054 @defmac AC_CHAR_UNSIGNED 23055 @acindex{CHAR_UNSIGNED} 23056 Replaced 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} 23061 Autoconf, up to 2.13, used to provide this version of 23062 @code{AC_CHECK_TYPE}, deprecated because of its flaws. First, although 23063 it is a member of the @code{CHECK} clan, it does 23064 more than just checking. Secondly, missing types are defined 23065 using @code{#define}, not @code{typedef}, and this can lead to 23066 problems in the case of pointer types. 23067 23068 This use of @code{AC_CHECK_TYPE} is obsolete and discouraged; see 23069 @ref{Generic Types}, for the description of the current macro. 23070 23071 If the type @var{type} is not defined, define it to be the C (or C++) 23072 builtin type @var{default}, e.g., @samp{short int} or @samp{unsigned int}. 23073 23074 This macro is equivalent to: 23075 23076 @example 23077 AC_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 23083 In 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 23088 If there are three or four arguments, the modern version is used. 23089 23090 @item 23091 If the second argument appears to be a C or C++ type, then the 23092 obsolete 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 23094 followed by one of @samp{[(* } and then by a string of zero or more 23095 characters taken from the set @samp{[]()* _a-zA-Z0-9}. 23096 23097 @item 23098 If the second argument is spelled with the alphabet of valid C and C++ 23099 types, the user is warned and the modern version is used. 23100 23101 @item 23102 Otherwise, the modern version is used. 23103 @end enumerate 23104 23105 @noindent 23106 You are encouraged either to use a valid builtin type, or to use the 23107 equivalent modern code (see above), or better yet, to use 23108 @code{AC_CHECK_TYPES} together with 23109 23110 @example 23111 #ifndef HAVE_LOFF_T 23112 typedef 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} 23120 Same as 23121 23122 @example 23123 AC_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} 23133 This is an obsolete version of @code{AC_TRY_COMPILE} itself replaced by 23134 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}), with the 23135 addition that it prints @samp{checking for @var{echo-text}} to the 23136 standard output first, if @var{echo-text} is non-empty. Use 23137 @code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT} instead to print 23138 messages (@pxref{Printing Messages}). 23139 @end defmac 23140 23141 @defmac AC_CONST 23142 @acindex{CONST} 23143 Replaced by @code{AC_C_CONST} (@pxref{AC_C_CONST}). 23144 @end defmac 23145 23146 @defmac AC_CROSS_CHECK 23147 @acindex{CROSS_CHECK} 23148 Same 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 23155 Check 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 23157 means 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 23161 AC_REQUIRE([AC_CANONICAL_HOST])[]dnl 23162 case $host_os in 23163 *cygwin* ) CYGWIN=yes;; 23164 * ) CYGWIN=no;; 23165 esac 23166 @end example 23167 23168 Beware that the variable @env{CYGWIN} has a special meaning when 23169 running Cygwin, and should not be changed. That's yet another reason 23170 not to use this macro. 23171 @end defmac 23172 23173 @defmac AC_DECL_SYS_SIGLIST 23174 @acindex{DECL_SYS_SIGLIST} 23175 @cvindex SYS_SIGLIST_DECLARED 23176 Same as: 23177 23178 @example 23179 AC_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} 23194 Does 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 23203 Like calling @code{AC_FUNC_CLOSEDIR_VOID} 23204 (@pxref{AC_FUNC_CLOSEDIR_VOID}) and @code{AC_HEADER_DIRENT} 23205 (@pxref{AC_HEADER_DIRENT}), 23206 but defines a different set of C preprocessor macros to indicate which 23207 header 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} 23220 If on DYNIX/ptx, add @option{-lseq} to output variable 23221 @code{LIBS}. This macro used to be defined as 23222 23223 @example 23224 AC_CHECK_LIB([seq], [getmntent], [LIBS="-lseq $LIBS"]) 23225 @end example 23226 23227 @noindent 23228 now 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 23234 Defined the output variable @code{EXEEXT} based on the output of the 23235 compiler, which is now done automatically. Typically set to empty 23236 string if Posix and @samp{.exe} if a DOS variant. 23237 @end defmac 23238 23239 @defmac AC_EMXOS2 23240 @acindex{EMXOS2} 23241 Similar to @code{AC_CYGWIN} but checks for the EMX environment on OS/2 23242 and sets @code{EMXOS2}. Don't use this macro, the dignified means to 23243 check 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} 23250 This is an obsolete version of @code{AC_ARG_ENABLE} that does not 23251 support providing a help string (@pxref{AC_ARG_ENABLE}). 23252 @end defmac 23253 23254 @defmac AC_ERROR 23255 @acindex{ERROR} 23256 Replaced by @code{AC_MSG_ERROR} (@pxref{AC_MSG_ERROR}). 23257 @end defmac 23258 23259 @defmac AC_FIND_X 23260 @acindex{FIND_X} 23261 Replaced by @code{AC_PATH_X} (@pxref{AC_PATH_X}). 23262 @end defmac 23263 23264 @defmac AC_FIND_XTRA 23265 @acindex{FIND_XTRA} 23266 Replaced by @code{AC_PATH_XTRA} (@pxref{AC_PATH_XTRA}). 23267 @end defmac 23268 23269 @defmac AC_FOREACH 23270 @acindex{FOREACH} 23271 Replaced by @code{m4_foreach_w} (@pxref{m4_foreach_w}). 23272 @end defmac 23273 23274 @defmac AC_FUNC_CHECK 23275 @acindex{FUNC_CHECK} 23276 Replaced 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} 23285 Do nothing. Formerly, this macro checked whether @code{setvbuf} takes 23286 the buffering type as its second argument and the buffer pointer as the 23287 third, instead of the other way around, and defined 23288 @code{SETVBUF_REVERSED}. However, the last systems to have the problem 23289 were those based on SVR2, which became obsolete in 1987, and the macro 23290 is 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} 23298 If @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 23302 These 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} 23308 Replaced by @code{AC_PROG_GCC_TRADITIONAL} (@pxref{AC_PROG_GCC_TRADITIONAL}). 23309 @end defmac 23310 23311 @defmac AC_GETGROUPS_T 23312 @acindex{GETGROUPS_T} 23313 Replaced by @code{AC_TYPE_GETGROUPS} (@pxref{AC_TYPE_GETGROUPS}). 23314 @end defmac 23315 23316 @defmac AC_GETLOADAVG 23317 @acindex{GETLOADAVG} 23318 Replaced 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 23324 This 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} 23330 Replaced by @code{AC_CHECK_FUNCS} (@pxref{AC_CHECK_FUNCS}). 23331 @end defmac 23332 23333 @defmac AC_HAVE_HEADERS 23334 @acindex{HAVE_HEADERS} 23335 Replaced 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} 23341 This macro is equivalent to calling @code{AC_CHECK_LIB} with a 23342 @var{function} argument of @code{main}. In addition, @var{library} can 23343 be written as any of @samp{foo}, @option{-lfoo}, or @samp{libfoo.a}. In 23344 all 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} 23351 Replaced by @code{AC_SYS_INTERPRETER} (@pxref{AC_SYS_INTERPRETER}). 23352 @end defmac 23353 23354 @defmac AC_HEADER_CHECK 23355 @acindex{HEADER_CHECK} 23356 Replaced by @code{AC_CHECK_HEADER} (@pxref{AC_CHECK_HEADER}). 23357 @end defmac 23358 23359 @defmac AC_HEADER_EGREP 23360 @acindex{HEADER_EGREP} 23361 Replaced by @code{AC_EGREP_HEADER} (@pxref{AC_EGREP_HEADER}). 23362 @end defmac 23363 23364 @defmac AC_HELP_STRING 23365 @acindex{HELP_STRING} 23366 Replaced 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} 23371 Formerly @code{AC_INIT} used to have a single argument, and was 23372 equivalent to: 23373 23374 @example 23375 AC_INIT 23376 AC_CONFIG_SRCDIR(@var{unique-file-in-source-dir}) 23377 @end example 23378 See @ref{AC_INIT} and @ref{AC_CONFIG_SRCDIR}. 23379 @end defmac 23380 23381 @defmac AC_INLINE 23382 @acindex{INLINE} 23383 Replaced 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 23389 If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}. 23390 Use @samp{AC_CHECK_SIZEOF(int)} instead (@pxref{AC_CHECK_SIZEOF}). 23391 @end defmac 23392 23393 @defmac AC_IRIX_SUN 23394 @acindex{IRIX_SUN} 23395 If 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 23398 of the password and group functions, use @samp{AC_CHECK_LIB(sun, 23399 getpwnam)}. Up to Autoconf 2.13, it used to be 23400 23401 @example 23402 AC_CHECK_LIB([sun], [getmntent], [LIBS="-lsun $LIBS"]) 23403 @end example 23404 23405 @noindent 23406 now it is defined as 23407 23408 @example 23409 AC_FUNC_GETMNTENT 23410 AC_CHECK_LIB([sun], [getpwnam]) 23411 @end example 23412 23413 @noindent 23414 See @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 23420 This macro adds @option{-lcposix} to output variable @code{LIBS} if 23421 necessary for Posix facilities. Sun dropped support for the obsolete 23422 INTERACTIVE Systems Corporation Unix on 2006-07-23. New programs 23423 need 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} 23429 Same as @samp{AC_LANG([C])} (@pxref{AC_LANG}). 23430 @end defmac 23431 23432 @defmac AC_LANG_CPLUSPLUS 23433 @acindex{LANG_CPLUSPLUS} 23434 Same as @samp{AC_LANG([C++])} (@pxref{AC_LANG}). 23435 @end defmac 23436 23437 @defmac AC_LANG_FORTRAN77 23438 @acindex{LANG_FORTRAN77} 23439 Same as @samp{AC_LANG([Fortran 77])} (@pxref{AC_LANG}). 23440 @end defmac 23441 23442 @defmac AC_LANG_RESTORE 23443 @acindex{LANG_RESTORE} 23444 Select the @var{language} that is saved on the top of the stack, as set 23445 by @code{AC_LANG_SAVE}, remove it from the stack, and call 23446 @code{AC_LANG(@var{language})}. @xref{Language Choice}, for the 23447 preferred way to change languages. 23448 @end defmac 23449 23450 @defmac AC_LANG_SAVE 23451 @acindex{LANG_SAVE} 23452 Remember the current language (as set by @code{AC_LANG}) on a stack. 23453 The 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} 23459 This is an obsolete version of @code{AC_CONFIG_LINKS} 23460 (@pxref{AC_CONFIG_LINKS}. An updated version of: 23461 23462 @example 23463 AC_LINK_FILES(config/$machine.h config/$obj_format.h, 23464 host.h object.h) 23465 @end example 23466 23467 @noindent 23468 is: 23469 23470 @example 23471 AC_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} 23478 Replaced 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 23484 Define @code{LONG_64_BITS} if the C type @code{long int} is 64 bits wide. 23485 Use 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} 23491 If the C compiler supports a working @code{long double} type with more 23492 range or precision than the @code{double} type, define 23493 @code{HAVE_LONG_DOUBLE}. 23494 23495 You 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} 23501 Replaced by 23502 @example 23503 AC_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} 23511 Replaced 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 23517 Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were 23518 defined in @file{memory.h}. Today it is equivalent to 23519 @samp{AC_CHECK_HEADERS([memory.h])} (@pxref{AC_CHECK_HEADERS}). Adjust 23520 your code to depend upon 23521 @code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}; see @ref{Standard 23522 Symbols}. 23523 @end defmac 23524 23525 @defmac AC_MINGW32 23526 @acindex{MINGW32} 23527 Similar to @code{AC_CYGWIN} but checks for the MinGW compiler 23528 environment and sets @code{MINGW32}. Don't use this macro, the 23529 dignified 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 23538 This 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} 23544 Replaced by @code{AC_PROG_CC_C_O} (@pxref{AC_PROG_CC_C_O}). 23545 @end defmac 23546 23547 @defmac AC_MMAP 23548 @acindex{MMAP} 23549 Replaced by @code{AC_FUNC_MMAP} (@pxref{AC_FUNC_MMAP}). 23550 @end defmac 23551 23552 @defmac AC_MODE_T 23553 @acindex{MODE_T} 23554 Replaced 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 23560 Defined the output variable @code{OBJEXT} based on the output of the 23561 compiler, after .c files have been excluded. Typically set to @samp{o} 23562 if Posix, @samp{obj} if a DOS variant. 23563 Now the compiler checking macros handle 23564 this automatically. 23565 @end defmac 23566 23567 @defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion}) 23568 @acindex{OBSOLETE} 23569 Make 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 23571 where it was called. @var{this-macro-name} should be the name of the 23572 macro that is calling @code{AC_OBSOLETE}. If @var{suggestion} is given, 23573 it is printed at the end of the warning message; for example, it can be 23574 a suggestion for what to use instead of @var{this-macro-name}. 23575 23576 For instance 23577 23578 @example 23579 AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl 23580 @end example 23581 23582 @noindent 23583 You are encouraged to use @code{AU_DEFUN} instead, since it gives better 23584 services to the user (@pxref{AU_DEFUN}). 23585 @end defmac 23586 23587 @defmac AC_OFF_T 23588 @acindex{OFF_T} 23589 Replaced 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} 23594 The use of @code{AC_OUTPUT} with arguments is deprecated. This obsoleted 23595 interface is equivalent to: 23596 23597 @example 23598 @group 23599 AC_CONFIG_FILES(@var{file}@dots{}) 23600 AC_CONFIG_COMMANDS([default], 23601 @var{extra-cmds}, @var{init-cmds}) 23602 AC_OUTPUT 23603 @end group 23604 @end example 23605 23606 @noindent 23607 See @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} 23612 Specify additional shell commands to run at the end of 23613 @file{config.status}, and shell commands to initialize any variables 23614 from @command{configure}. This macro may be called multiple times. It is 23615 obsolete, replaced by @code{AC_CONFIG_COMMANDS} (@pxref{AC_CONFIG_COMMANDS}). 23616 23617 Here is an unrealistic example: 23618 23619 @example 23620 fubar=27 23621 AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.], 23622 [fubar=$fubar]) 23623 AC_OUTPUT_COMMANDS([echo this is another, extra, bit], 23624 [echo init bit]) 23625 @end example 23626 23627 Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an 23628 additional 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} 23631 can safely be given macro calls as arguments: 23632 23633 @example 23634 AC_CONFIG_COMMANDS(foo, [my_FOO()]) 23635 @end example 23636 23637 @noindent 23638 Conversely, where one level of quoting was enough for literal strings 23639 with @code{AC_OUTPUT_COMMANDS}, you need two with 23640 @code{AC_CONFIG_COMMANDS}. The following lines are equivalent: 23641 23642 @example 23643 @group 23644 AC_OUTPUT_COMMANDS([echo "Square brackets: []"]) 23645 AC_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} 23652 Replaced by @code{AC_TYPE_PID_T} (@pxref{AC_TYPE_PID_T}). 23653 @end defmac 23654 23655 @defmac AC_PREFIX 23656 @acindex{PREFIX} 23657 Replaced by @code{AC_PREFIX_PROGRAM} (@pxref{AC_PREFIX_PROGRAM}). 23658 @end defmac 23659 23660 @defmac AC_PROGRAMS_CHECK 23661 @acindex{PROGRAMS_CHECK} 23662 Replaced by @code{AC_CHECK_PROGS} (@pxref{AC_CHECK_PROGS}). 23663 @end defmac 23664 23665 @defmac AC_PROGRAMS_PATH 23666 @acindex{PROGRAMS_PATH} 23667 Replaced by @code{AC_PATH_PROGS} (@pxref{AC_PATH_PROGS}). 23668 @end defmac 23669 23670 @defmac AC_PROGRAM_CHECK 23671 @acindex{PROGRAM_CHECK} 23672 Replaced by @code{AC_CHECK_PROG} (@pxref{AC_CHECK_PROG}). 23673 @end defmac 23674 23675 @defmac AC_PROGRAM_EGREP 23676 @acindex{PROGRAM_EGREP} 23677 Replaced by @code{AC_EGREP_CPP} (@pxref{AC_EGREP_CPP}). 23678 @end defmac 23679 23680 @defmac AC_PROGRAM_PATH 23681 @acindex{PROGRAM_PATH} 23682 Replaced by @code{AC_PATH_PROG} (@pxref{AC_PATH_PROG}). 23683 @end defmac 23684 23685 @defmac AC_REMOTE_TAPE 23686 @acindex{REMOTE_TAPE} 23687 Removed because of limited usefulness. 23688 @end defmac 23689 23690 @defmac AC_RESTARTABLE_SYSCALLS 23691 @acindex{RESTARTABLE_SYSCALLS} 23692 This macro was renamed @code{AC_SYS_RESTARTABLE_SYSCALLS}. However, 23693 these days portable programs should use @code{sigaction} with 23694 @code{SA_RESTART} if they want restartable system calls. They should 23695 not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a 23696 system call is restartable is a dynamic issue, not a configuration-time 23697 issue. 23698 @end defmac 23699 23700 @defmac AC_RETSIGTYPE 23701 @acindex{RETSIGTYPE} 23702 Replaced by @code{AC_TYPE_SIGNAL} (@pxref{AC_TYPE_SIGNAL}), which itself 23703 is obsolete when assuming C89 or better. 23704 @end defmac 23705 23706 @defmac AC_RSH 23707 @acindex{RSH} 23708 Removed because of limited usefulness. 23709 @end defmac 23710 23711 @defmac AC_SCO_INTL 23712 @acindex{SCO_INTL} 23713 @ovindex LIBS 23714 If on SCO Unix, add @option{-lintl} to output variable @code{LIBS}. This 23715 macro used to do this: 23716 23717 @example 23718 AC_CHECK_LIB([intl], [strftime], [LIBS="-lintl $LIBS"]) 23719 @end example 23720 23721 @noindent 23722 Now 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} 23727 Replaced by 23728 @example 23729 AC_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} 23737 Replaced by @code{AC_PROG_MAKE_SET} (@pxref{AC_PROG_MAKE_SET}). 23738 @end defmac 23739 23740 @defmac AC_SIZEOF_TYPE 23741 @acindex{SIZEOF_TYPE} 23742 Replaced by @code{AC_CHECK_SIZEOF} (@pxref{AC_CHECK_SIZEOF}). 23743 @end defmac 23744 23745 @defmac AC_SIZE_T 23746 @acindex{SIZE_T} 23747 Replaced 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} 23752 Replaced by @code{AC_HEADER_STAT} (@pxref{AC_HEADER_STAT}). 23753 @end defmac 23754 23755 @defmac AC_STDC_HEADERS 23756 @acindex{STDC_HEADERS} 23757 Replaced by @code{AC_HEADER_STDC} (@pxref{AC_HEADER_STDC}). 23758 @end defmac 23759 23760 @defmac AC_STRCOLL 23761 @acindex{STRCOLL} 23762 Replaced 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 23769 If @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 23772 the future. This macro is obsoleted, and should be replaced by 23773 23774 @example 23775 AC_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 23785 If @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 23788 in the future. Actually, even the new macro is obsolete and should be 23789 replaced by: 23790 @example 23791 AC_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} 23799 Replaced by @code{AC_CHECK_MEMBERS} (@pxref{AC_CHECK_MEMBERS}). 23800 @end defmac 23801 23802 @defmac AC_ST_BLOCKS 23803 @acindex{ST_BLOCKS} 23804 Replaced by @code{AC_STRUCT_ST_BLOCKS} (@pxref{AC_STRUCT_ST_BLOCKS}). 23805 @end defmac 23806 23807 @defmac AC_ST_RDEV 23808 @acindex{ST_RDEV} 23809 Replaced 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 23815 If the system automatically restarts a system call that is interrupted 23816 by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}. This macro does 23817 not check whether system calls are restarted in general---it checks whether a 23818 signal handler installed with @code{signal} (but not @code{sigaction}) 23819 causes system calls to be restarted. It does not check whether system calls 23820 can be restarted when interrupted by signals that have no handler. 23821 23822 These days portable programs should use @code{sigaction} with 23823 @code{SA_RESTART} if they want restartable system calls. They should 23824 not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a 23825 system call is restartable is a dynamic issue, not a configuration-time 23826 issue. 23827 @end defmac 23828 23829 @defmac AC_SYS_SIGLIST_DECLARED 23830 @acindex{SYS_SIGLIST_DECLARED} 23831 This macro was renamed @code{AC_DECL_SYS_SIGLIST}. However, even that 23832 name 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} 23838 This 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} 23844 This 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} 23850 Replaced 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} 23855 Replaced 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} 23861 Same as: 23862 23863 @example 23864 AC_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 23874 This macro double quotes both @var{includes} and @var{function-body}. 23875 23876 For C and C++, @var{includes} is any @code{#include} statements needed 23877 by the code in @var{function-body} (@var{includes} is ignored if 23878 the currently selected language is Fortran or Fortran 77). The compiler 23879 and 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} 23885 Same as: 23886 23887 @example 23888 AC_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 23897 This 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} 23903 Same as: 23904 23905 @example 23906 AC_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 23916 This macro double quotes both @var{includes} and @var{function-body}. 23917 23918 Depending on the current language (@pxref{Language Choice}), create a 23919 test program to see whether a function whose body consists of 23920 @var{function-body} can be compiled and linked. If the file compiles 23921 and links successfully, run shell commands @var{action-if-found}, 23922 otherwise run @var{action-if-not-found}. 23923 23924 This macro double quotes both @var{includes} and @var{function-body}. 23925 23926 For C and C++, @var{includes} is any @code{#include} statements needed 23927 by the code in @var{function-body} (@var{includes} is ignored if 23928 the currently selected language is Fortran or Fortran 77). The compiler 23929 and 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} 23937 This macro is equivalent to 23938 @example 23939 AC_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} 23949 Same as: 23950 23951 @example 23952 AC_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} 23968 If @file{signal.h} declares @code{signal} as returning a pointer to a 23969 function returning @code{void}, define @code{RETSIGTYPE} to be 23970 @code{void}; otherwise, define it to be @code{int}. These days, it is 23971 portable to assume C89, and that signal handlers return @code{void}, 23972 without needing to use this macro or @code{RETSIGTYPE}. 23973 23974 When targeting older K&R C, it is possible to define signal handlers as 23975 returning type @code{RETSIGTYPE}, and omit a return statement: 23976 23977 @example 23978 @group 23979 RETSIGTYPE 23980 hup_handler () 23981 @{ 23982 @dots{} 23983 @} 23984 @end group 23985 @end example 23986 @end defmac 23987 23988 @defmac AC_UID_T 23989 @acindex{UID_T} 23990 Replaced by @code{AC_TYPE_UID_T} (@pxref{AC_TYPE_UID_T}). 23991 @end defmac 23992 23993 @defmac AC_UNISTD_H 23994 @acindex{UNISTD_H} 23995 Same 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 24001 Define @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} 24008 Replaced 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} 24013 If the cache file is inconsistent with the current host, target and 24014 build system types, it used to execute @var{cmd} or print a default 24015 error message. This is now handled by default. 24016 @end defmac 24017 24018 @defmac AC_VERBOSE (@var{result-description}) 24019 @acindex{VERBOSE} 24020 Replaced by @code{AC_MSG_RESULT} (@pxref{AC_MSG_RESULT}). 24021 @end defmac 24022 24023 @defmac AC_VFORK 24024 @acindex{VFORK} 24025 Replaced by @code{AC_FUNC_FORK} (@pxref{AC_FUNC_FORK}). 24026 @end defmac 24027 24028 @defmac AC_VPRINTF 24029 @acindex{VPRINTF} 24030 Replaced by @code{AC_FUNC_VPRINTF} (@pxref{AC_FUNC_VPRINTF}). 24031 @end defmac 24032 24033 @defmac AC_WAIT3 24034 @acindex{WAIT3} 24035 This macro was renamed @code{AC_FUNC_WAIT3}. However, these days 24036 portable 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} 24042 Replaced 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} 24048 This is an obsolete version of @code{AC_ARG_WITH} that does not 24049 support providing a help string (@pxref{AC_ARG_WITH}). 24050 @end defmac 24051 24052 @defmac AC_WORDS_BIGENDIAN 24053 @acindex{WORDS_BIGENDIAN} 24054 Replaced 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 24060 This macro used to add @option{-lx} to output variable @code{LIBS} if on 24061 Xenix. 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 24064 running XENIX on which you should not depend: 24065 24066 @example 24067 AC_MSG_CHECKING([for Xenix]) 24068 AC_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 24076 Don't use this macro, the dignified means to check the nature of the 24077 host is using @code{AC_CANONICAL_HOST} (@pxref{Canonicalizing}). 24078 @end defmac 24079 24080 @defmac AC_YYTEXT_POINTER 24081 @acindex{YYTEXT_POINTER} 24082 This macro was renamed @code{AC_DECL_YYTEXT}, which in turn was 24083 integrated 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 24091 Autoconf version 2 is mostly backward compatible with version 1. 24092 However, it introduces better ways to do some things, and doesn't 24093 support some of the ugly things in version 1. So, depending on how 24094 sophisticated your @file{configure.ac} files are, you might have to do 24095 some manual work in order to upgrade to version 2. This chapter points 24096 out some problems to watch for when upgrading. Also, perhaps your 24097 @command{configure} scripts could benefit from some of the new features in 24098 version 2; the changes are summarized in the file @file{NEWS} in the 24099 Autoconf 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 24112 If you have an @file{aclocal.m4} installed with Autoconf (as opposed to 24113 in a particular package's source directory), you must rename it to 24114 @file{acsite.m4}. @xref{autoconf Invocation}. 24115 24116 If you distribute @file{install.sh} with your package, rename it to 24117 @file{install-sh} so @command{make} builtin rules don't inadvertently 24118 create a file called @file{install} from it. @code{AC_PROG_INSTALL} 24119 looks for the script under both names, but it is best to use the new name. 24120 24121 If 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 24123 use the @code{AH_} macros. @xref{Autoheader Macros}. 24124 24125 @node Changed Makefiles 24126 @subsection Changed Makefiles 24127 24128 Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in 24129 your @file{Makefile.in} files, so they can take advantage of the values 24130 of those variables in the environment when @command{configure} is run. 24131 Doing this isn't necessary, but it's a convenience for users. 24132 24133 Also 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 24135 they were produced by @command{configure}. Automatically selecting the 24136 right comment syntax for all the kinds of files that people call 24137 @code{AC_OUTPUT} on became too much work. 24138 24139 Add @file{config.log} and @file{config.cache} to the list of files you 24140 remove in @code{distclean} targets. 24141 24142 If you have the following in @file{Makefile.in}: 24143 24144 @example 24145 prefix = /usr/local 24146 exec_prefix = $(prefix) 24147 @end example 24148 24149 @noindent 24150 you must change it to: 24151 24152 @example 24153 prefix = @@prefix@@ 24154 exec_prefix = @@exec_prefix@@ 24155 @end example 24156 24157 @noindent 24158 The old behavior of replacing those variables without @samp{@@} 24159 characters around them has been removed. 24160 24161 @node Changed Macros 24162 @subsection Changed Macros 24163 24164 Many of the macros were renamed in Autoconf version 2. You can still 24165 use the old names, but the new ones are clearer, and it's easier to find 24166 the documentation for them. @xref{Obsolete Macros}, for a table showing the 24167 new names for the old macros. Use the @command{autoupdate} program to 24168 convert your @file{configure.ac} to using the new macro names. 24169 @xref{autoupdate Invocation}. 24170 24171 Some macros have been superseded by similar ones that do the job better, 24172 but are not call-compatible. If you get warnings about calling obsolete 24173 macros while running @command{autoconf}, you may safely ignore them, but 24174 your @command{configure} script generally works better if you follow 24175 the advice that is printed about what to replace the obsolete macros with. In 24176 particular, the mechanism for reporting the results of tests has 24177 changed. If you were using @command{echo} or @code{AC_VERBOSE} (perhaps 24178 via @code{AC_COMPILE_CHECK}), your @command{configure} script's output 24179 looks better if you switch to @code{AC_MSG_CHECKING} and 24180 @code{AC_MSG_RESULT}. @xref{Printing Messages}. Those macros work best 24181 in conjunction with cache variables. @xref{Caching Results}. 24182 24183 24184 24185 @node Changed Results 24186 @subsection Changed Results 24187 24188 If you were checking the results of previous tests by examining the 24189 shell variable @code{DEFS}, you need to switch to checking the values of 24190 the cache variables for those tests. @code{DEFS} no longer exists while 24191 @command{configure} is running; it is only created when generating output 24192 files. This difference from version 1 is because properly quoting the 24193 contents of that variable turned out to be too cumbersome and 24194 inefficient to do every time @code{AC_DEFINE} is called. @xref{Cache 24195 Variable Names}. 24196 24197 For example, here is a @file{configure.ac} fragment written for Autoconf 24198 version 1: 24199 24200 @example 24201 AC_HAVE_FUNCS(syslog) 24202 case "$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 ;; 24216 esac 24217 @end example 24218 24219 Here is a way to write it for version 2: 24220 24221 @example 24222 AC_CHECK_FUNCS([syslog]) 24223 if 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 24229 fi 24230 @end example 24231 24232 If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding 24233 backslashes before quotes, you need to remove them. It now works 24234 predictably, and does not treat quotes (except back quotes) specially. 24235 @xref{Setting Output Variables}. 24236 24237 All 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, 24239 though for backward compatibility some use the empty string instead. If 24240 you 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 24246 When defining your own macros, you should now use @code{AC_DEFUN} 24247 instead of @code{define}. @code{AC_DEFUN} automatically calls 24248 @code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE} 24249 do not interrupt other macros, to prevent nested @samp{checking@dots{}} 24250 messages on the screen. There's no actual harm in continuing to use the 24251 older way, but it's less convenient and attractive. @xref{Macro 24252 Definitions}. 24253 24254 You probably looked at the macros that came with Autoconf as a guide for 24255 how to do things. It would be a good idea to take a look at the new 24256 versions of them, as the style is somewhat improved and they take 24257 advantage of some new features. 24258 24259 If you were doing tricky things with undocumented Autoconf internals 24260 (macros, variables, diversions), check whether you need to change 24261 anything to account for changes that have been made. Perhaps you can 24262 even use an officially supported technique in version 2 instead of 24263 kludging. Or perhaps not. 24264 24265 To speed up your locally written feature tests, add caching to them. 24266 See whether any of your tests are of general enough usefulness to 24267 encapsulate 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 24275 The introduction of the previous section (@pxref{Autoconf 1}) perfectly 24276 suits this section@enddots{} 24277 24278 @quotation 24279 Autoconf version 2.50 is mostly backward compatible with version 2.13. 24280 However, it introduces better ways to do some things, and doesn't 24281 support some of the ugly things in version 2.13. So, depending on how 24282 sophisticated your @file{configure.ac} files are, you might have to do 24283 some manual work in order to upgrade to version 2.50. This chapter 24284 points out some problems to watch for when upgrading. Also, perhaps 24285 your @command{configure} scripts could benefit from some of the new 24286 features 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 24301 The most important changes are invisible to you: the implementation of 24302 most macros have completely changed. This allowed more factorization of 24303 the code, better error messages, a higher uniformity of the user's 24304 interface etc. Unfortunately, as a side effect, some construct which 24305 used to (miraculously) work might break starting with Autoconf 2.50. 24306 The most common culprit is bad quotation. 24307 24308 For instance, in the following example, the message is not properly 24309 quoted: 24310 24311 @example 24312 AC_INIT 24313 AC_CHECK_HEADERS(foo.h, , 24314 AC_MSG_ERROR(cannot find foo.h, bailing out)) 24315 AC_OUTPUT 24316 @end example 24317 24318 @noindent 24319 Autoconf 2.13 simply ignores it: 24320 24321 @example 24322 $ @kbd{autoconf-2.13; ./configure --silent} 24323 creating cache ./config.cache 24324 configure: error: cannot find foo.h 24325 $ 24326 @end example 24327 24328 @noindent 24329 while Autoconf 2.50 produces a broken @file{configure}: 24330 24331 @example 24332 $ @kbd{autoconf-2.50; ./configure --silent} 24333 configure: 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 24339 The message needs to be quoted, and the @code{AC_MSG_ERROR} invocation 24340 too! 24341 24342 @example 24343 AC_INIT([Example], [1.0], [bug-example@@example.org]) 24344 AC_CHECK_HEADERS([foo.h], [], 24345 [AC_MSG_ERROR([cannot find foo.h, bailing out])]) 24346 AC_OUTPUT 24347 @end example 24348 24349 Many many (and many more) Autoconf macros were lacking proper quotation, 24350 including no less than@dots{} @code{AC_DEFUN} itself! 24351 24352 @example 24353 $ @kbd{cat configure.in} 24354 AC_DEFUN([AC_PROG_INSTALL], 24355 [# My own much better version 24356 ]) 24357 AC_INIT 24358 AC_PROG_INSTALL 24359 AC_OUTPUT 24360 $ @kbd{autoconf-2.13} 24361 autoconf: Undefined macros: 24362 ***BUG in Autoconf--please report*** AC_FD_MSG 24363 ***BUG in Autoconf--please report*** AC_EPI 24364 configure.in:1:AC_DEFUN([AC_PROG_INSTALL], 24365 configure.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 24377 While Autoconf was relatively dormant in the late 1990s, Automake 24378 provided Autoconf-like macros for a while. Starting with Autoconf 2.50 24379 in 2001, Autoconf provided 24380 versions of these macros, integrated in the @code{AC_} namespace, 24381 instead of @code{AM_}. But in order to ease the upgrading via 24382 @command{autoupdate}, bindings to such @code{AM_} macros are provided. 24383 24384 Unfortunately older versions of Automake (e.g., Automake 1.4) 24385 did not quote the names of these macros. 24386 Therefore, 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 24389 expanded, replaced with its Autoconf definition. 24390 24391 Fortunately Autoconf catches pre-@code{AC_INIT} expansions, and 24392 complains, in its own words: 24393 24394 @example 24395 $ @kbd{cat configure.ac} 24396 AC_INIT([Example], [1.0], [bug-example@@example.org]) 24397 AM_TYPE_PTRDIFF_T 24398 $ @kbd{aclocal-1.4} 24399 $ @kbd{autoconf} 24400 aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion 24401 aclocal.m4:17: the top level 24402 autom4te: m4 failed with exit status: 1 24403 $ 24404 @end example 24405 24406 Modern versions of Automake no longer define most of these 24407 macros, and properly quote the names of the remaining macros. 24408 If you must use an old Automake, do not depend upon macros from Automake 24409 as it is simply not its job 24410 to provide macros (but the one it requires itself): 24411 24412 @example 24413 $ @kbd{cat configure.ac} 24414 AC_INIT([Example], [1.0], [bug-example@@example.org]) 24415 AM_TYPE_PTRDIFF_T 24416 $ @kbd{rm aclocal.m4} 24417 $ @kbd{autoupdate} 24418 autoupdate: `configure.ac' is updated 24419 $ @kbd{cat configure.ac} 24420 AC_INIT([Example], [1.0], [bug-example@@example.org]) 24421 AC_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 24432 Based on the experience of compiler writers, and after long public 24433 debates, many aspects of the cross-compilation chain have changed: 24434 24435 @itemize @minus 24436 @item 24437 the relationship between the build, host, and target architecture types, 24438 24439 @item 24440 the command line interface for specifying them to @command{configure}, 24441 24442 @item 24443 the variables defined in @command{configure}, 24444 24445 @item 24446 the enabling of cross-compilation mode. 24447 @end itemize 24448 24449 @sp 1 24450 24451 The relationship between build, host, and target have been cleaned up: 24452 the chain of default is now simply: target defaults to host, host to 24453 build, and build to the result of @command{config.guess}. Nevertheless, 24454 in order to ease the transition from 2.13 to 2.50, the following 24455 transition scheme is implemented. @emph{Do not rely on it}, as it will 24456 be completely disabled in a couple of releases (we cannot keep it, as it 24457 proves to cause more problems than it cures). 24458 24459 They all default to the result of running @command{config.guess}, unless 24460 you specify either @option{--build} or @option{--host}. In this case, 24461 the default becomes the system type you specified. If you specify both, 24462 and they're different, @command{configure} enters cross compilation 24463 mode, so it doesn't run any tests that require execution. 24464 24465 Hint: if you mean to override the result of @command{config.guess}, 24466 prefer @option{--build} over @option{--host}. 24467 24468 @sp 1 24469 24470 For backward compatibility, @command{configure} accepts a system 24471 type as an option by itself. Such an option overrides the 24472 defaults for build, host, and target system types. The following 24473 configure statement configures a cross toolchain that runs on 24474 NetBSD/alpha but generates code for GNU Hurd/sparc, 24475 which is also the build platform. 24476 24477 @example 24478 ./configure --host=alpha-netbsd sparc-gnu 24479 @end example 24480 24481 @sp 1 24482 24483 In Autoconf 2.13 and before, the variables @code{build}, @code{host}, 24484 and @code{target} had a different semantics before and after the 24485 invocation of @code{AC_CANONICAL_BUILD} etc. Now, the argument of 24486 @option{--build} is strictly copied into @code{build_alias}, and is left 24487 empty otherwise. After the @code{AC_CANONICAL_BUILD}, @code{build} is 24488 set to the canonicalized build type. To ease the transition, before, 24489 its contents is the same as that of @code{build_alias}. Do @emph{not} 24490 rely on this broken feature. 24491 24492 For consistency with the backward compatibility scheme exposed above, 24493 when @option{--host} is specified but @option{--build} isn't, the build 24494 system is assumed to be the same as @option{--host}, and 24495 @samp{build_alias} is set to that value. Eventually, this 24496 historically incorrect behavior will go away. 24497 24498 @sp 1 24499 24500 The former scheme to enable cross-compilation proved to cause more harm 24501 than good, in particular, it used to be triggered too easily, leaving 24502 regular end users puzzled in front of cryptic error messages. 24503 @command{configure} could even enter cross-compilation mode only 24504 because the compiler was not functional. This is mainly because 24505 @command{configure} used to try to detect cross-compilation, instead of 24506 waiting for an explicit flag from the user. 24507 24508 Now, @command{configure} enters cross-compilation mode if and only if 24509 @option{--host} is passed. 24510 24511 That's the short documentation. To ease the transition between 2.13 and 24512 its successors, a more complicated scheme is implemented. @emph{Do not 24513 rely on the following}, as it will be removed in the near future. 24514 24515 If you specify @option{--host}, but not @option{--build}, when 24516 @command{configure} performs the first compiler test it tries to run 24517 an executable produced by the compiler. If the execution fails, it 24518 enters cross-compilation mode. This is fragile. Moreover, by the time 24519 the compiler test is performed, it may be too late to modify the 24520 build-system type: other tests may have already been performed. 24521 Therefore, 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 24529 enters cross-compilation mode. The former interface, which 24530 consisted in setting the compiler to a cross-compiler without informing 24531 @command{configure} is obsolete. For instance, @command{configure} 24532 fails if it can't run the code generated by the specified compiler if you 24533 configure 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 24543 Up to Autoconf 2.13, the replacement of functions was triggered via the 24544 variable @code{LIBOBJS}. Since Autoconf 2.50, the macro 24545 @code{AC_LIBOBJ} should be used instead (@pxref{Generic Functions}). 24546 Starting at Autoconf 2.53, the use of @code{LIBOBJS} is an error. 24547 24548 This change is mandated by the unification of the GNU Build System 24549 components. In particular, the various fragile techniques used to parse 24550 a @file{configure.ac} are all replaced with the use of traces. As a 24551 consequence, any action must be traceable, which obsoletes critical 24552 variable assignments. Fortunately, @code{LIBOBJS} was the only problem, 24553 and it can even be handled gracefully (read, ``without your having to 24554 change something''). 24555 24556 There were two typical uses of @code{LIBOBJS}: asking for a replacement 24557 function, and adjusting @code{LIBOBJS} for Automake and/or Libtool. 24558 24559 @sp 1 24560 24561 As for function replacement, the fix is immediate: use 24562 @code{AC_LIBOBJ}. For instance: 24563 24564 @example 24565 LIBOBJS="$LIBOBJS fnmatch.o" 24566 LIBOBJS="$LIBOBJS malloc.$ac_objext" 24567 @end example 24568 24569 @noindent 24570 should be replaced with: 24571 24572 @example 24573 AC_LIBOBJ([fnmatch]) 24574 AC_LIBOBJ([malloc]) 24575 @end example 24576 24577 @sp 1 24578 24579 @ovindex LIBOBJDIR 24580 When used with Automake 1.10 or newer, a suitable value for 24581 @code{LIBOBJDIR} is set so that the @code{LIBOBJS} and @code{LTLIBOBJS} 24582 can be referenced from any @file{Makefile.am}. Even without Automake, 24583 arranging for @code{LIBOBJDIR} to be set correctly enables 24584 referencing @code{LIBOBJS} and @code{LTLIBOBJS} in another directory. 24585 The @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}} 24595 Since 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}, 24598 and @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 24603 a more consistent interface: @code{AC_TRY_COMPILE} etc.@: were double 24604 quoting their arguments; 24605 24606 @item 24607 the combinatoric explosion is solved by decomposing on the one hand the 24608 generation of sources, and on the other hand executing the program; 24609 24610 @item 24611 this scheme helps supporting more languages than plain C and C++. 24612 @end itemize 24613 24614 In addition to the change of syntax, the philosophy has changed too: 24615 while emphasis was put on speed at the expense of accuracy, today's 24616 Autoconf promotes accuracy of the testing framework at, ahem@dots{}, the 24617 expense of speed. 24618 24619 24620 As a perfect example of what is @emph{not} to be done, here is how to 24621 find out whether a header file contains a particular declaration, such 24622 as a typedef, a structure, a structure member, or a function. Use 24623 @code{AC_EGREP_HEADER} instead of running @code{grep} directly on the 24624 header file; on some systems the symbol might be defined in another 24625 header file that the file you are checking includes. 24626 24627 As a (bad) example, here is how you should not check for C preprocessor 24628 symbols, either defined by header files or predefined by the C 24629 preprocessor: using @code{AC_EGREP_CPP}: 24630 24631 @example 24632 @group 24633 AC_EGREP_CPP(yes, 24634 [#ifdef _AIX 24635 yes 24636 #endif 24637 ], is_aix=yes, is_aix=no) 24638 @end group 24639 @end example 24640 24641 The above example, properly written would (i) use 24642 @code{AC_LANG_PROGRAM}, and (ii) run the compiler: 24643 24644 @example 24645 @group 24646 AC_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 24666 stabilizing. Although we believe that Autotest is useful as-is, this 24667 documentation describes an interface which might change in the future: 24668 do not depend upon Autotest without subscribing to the Autoconf mailing 24669 lists.} 24670 @end display 24671 24672 It is paradoxical that portable projects depend on nonportable tools 24673 to run their test suite. Autoconf by itself is the paragon of this 24674 problem: although it aims at perfectly portability, up to 2.13 its 24675 test suite was using DejaGNU, a rich and complex testing 24676 framework, but which is far from being standard on Posix systems. 24677 Worse yet, it was likely to be missing on the most fragile platforms, 24678 the very platforms that are most likely to torture Autoconf and 24679 exhibit deficiencies. 24680 24681 To circumvent this problem, many package maintainers have developed their 24682 own testing framework, based on simple shell scripts whose sole outputs 24683 are exit status values describing whether the test succeeded. Most of 24684 these tests share common patterns, and this can result in lots of 24685 duplicated code and tedious maintenance. 24686 24687 Following exactly the same reasoning that yielded to the inception of 24688 Autoconf, Autotest provides a test suite generation framework, based on 24689 M4 macros building a portable shell script. The suite itself is 24690 equipped with automatic logging and tracing facilities which greatly 24691 diminish the interaction with bug reporters, and simple timing reports. 24692 24693 Autoconf itself has been using Autotest for years, and we do attest that 24694 it has considerably improved the strength of the test suite and the 24695 quality of bug reports. Other projects are known to use some generation 24696 of Autotest, such as Bison, Free Recode, Free Wdiff, GNU Tar, each of 24697 them with different needs, and this usage has validated Autotest as a general 24698 testing framework. 24699 24700 Nonetheless, compared to DejaGNU, Autotest is inadequate for 24701 interactive 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 24723 Generating testing or validation suites using Autotest is rather easy. 24724 The whole validation suite is held in a file to be processed through 24725 @command{autom4te}, itself using GNU M4 under the hood, to 24726 produce a stand-alone Bourne shell script which then gets distributed. 24727 Neither @command{autom4te} nor GNU M4 are needed at 24728 the installer's end. 24729 24730 @cindex test group 24731 Each 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 24733 executed together, usually because one test in the group creates data 24734 files that a later test in the same group needs to read. Complex test 24735 groups make later debugging more tedious. It is much better to 24736 keep only a few tests per test group. Ideally there is only one test 24737 per test group. 24738 24739 For all but the simplest packages, some file such as @file{testsuite.at} 24740 does not fully hold all test sources, as these are often easier to 24741 maintain in separate files. Each of these separate files holds a single 24742 test group, or a sequence of test groups all addressing some common 24743 functionality in the package. In such cases, @file{testsuite.at} 24744 merely initializes the validation suite, and sometimes does elementary 24745 health checking, before listing include statements for all other test 24746 files. The special file @file{package.m4}, containing the 24747 identification of the package, is automatically included if found. 24748 24749 A convenient alternative consists in moving all the global issues 24750 (local Autotest macros, elementary health checking, and @code{AT_INIT} 24751 invocation) into the file @code{local.at}, and making 24752 @file{testsuite.at} be a simple list of @code{m4_include}s of sub test 24753 suites. In such case, generating the whole test suite or pieces of it 24754 is only a matter of choosing the @command{autom4te} command line 24755 arguments. 24756 24757 The validation scripts that Autotest produces are by convention called 24758 @command{testsuite}. When run, @command{testsuite} executes each test 24759 group in turn, producing only one summary line per test to say if that 24760 particular test succeeded or failed. At end of all tests, summarizing 24761 counters get printed. One debugging directory is left for each test 24762 group which failed, if any: such directories are named 24763 @file{testsuite.dir/@var{nn}}, where @var{nn} is the sequence number of 24764 the 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 24769 of 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 24778 In the ideal situation, none of the tests fail, and consequently no 24779 debugging directory is left behind for validation. 24780 24781 It often happens in practice that individual tests in the validation 24782 suite need to get information coming out of the configuration process. 24783 Some of this information, common for all validation suites, is provided 24784 through the file @file{atconfig}, automatically created by 24785 @code{AC_CONFIG_TESTDIR}. For configuration information which your 24786 testing environment specifically needs, you might prepare an optional 24787 file named @file{atlocal.in}, instantiated by @code{AC_CONFIG_FILES}. 24788 The configuration process produces @file{atconfig} and @file{atlocal} 24789 out of these two input files, and these two produced files are 24790 automatically read by the @file{testsuite} script. 24791 24792 Here is a diagram showing the relationship between files. 24793 24794 @noindent 24795 Files used in preparing a software package for distribution: 24796 24797 @example 24798 [package.m4] -->. 24799 \ 24800 subfile-1.at ->. [local.at] ---->+ 24801 ... \ \ 24802 subfile-i.at ---->-- testsuite.at -->-- autom4te* -->testsuite 24803 ... / 24804 subfile-n.at ->' 24805 @end example 24806 24807 @noindent 24808 Files 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 24819 Files created during test suite execution: 24820 24821 @example 24822 atconfig -->. .--> testsuite.log 24823 \ / 24824 >-- testsuite* --< 24825 / \ 24826 [atlocal] ->' `--> [testsuite.dir] 24827 @end example 24828 24829 24830 @node Autotest Logs 24831 @subsection Autotest Logs 24832 24833 When run, the test suite creates a log file named after itself, e.g., a 24834 test suite named @command{testsuite} creates @file{testsuite.log}. It 24835 contains a lot of information, usually more than maintainers actually 24836 need, but therefore most of the time it contains all that is needed: 24837 24838 @table @asis 24839 @item command line arguments 24840 A bad but unfortunately widespread habit consists of 24841 setting environment variables before the command, such as in 24842 @samp{CC=my-home-grown-cc ./testsuite}. The test suite does not 24843 know this change, hence (i) it cannot report it to you, and (ii) 24844 it cannot preserve the value of @code{CC} for subsequent runs. 24845 Autoconf faced exactly the same problem, and solved it by asking 24846 users to pass the variable definitions as command line arguments. 24847 Autotest requires this rule, too, but has no means to enforce it; the log 24848 then contains a trace of the variables that were changed by the user. 24849 24850 @item @file{ChangeLog} excerpts 24851 The topmost lines of all the @file{ChangeLog} files found in the source 24852 hierarchy. This is especially useful when bugs are reported against 24853 development versions of the package, since the version string does not 24854 provide sufficient information to know the exact state of the sources 24855 the user compiled. Of course, this relies on the use of a 24856 @file{ChangeLog}. 24857 24858 @item build machine 24859 Running a test suite in a cross-compile environment is not an easy task, 24860 since it would mean having the test suite run on a machine @var{build}, 24861 while running programs on a machine @var{host}. It is much simpler to 24862 run both the test suite and the programs on @var{host}, but then, from 24863 the point of view of the test suite, there remains a single environment, 24864 @var{host} = @var{build}. The log contains relevant information on the 24865 state of the @var{build} machine, including some important environment 24866 variables. 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 24871 The absolute file name and answers to @option{--version} of the tested 24872 programs (see @ref{Writing Testsuites}, @code{AT_TESTED}). 24873 24874 @item configuration log 24875 The contents of @file{config.log}, as created by @command{configure}, 24876 are appended. It contains the configuration flags and a detailed report 24877 on the configuration itself. 24878 @end table 24879 24880 24881 @node Writing Testsuites 24882 @section Writing @file{testsuite.at} 24883 24884 The @file{testsuite.at} is a Bourne shell script making use of special 24885 Autotest M4 macros. It often contains a call to @code{AT_INIT} near 24886 its beginning followed by one call to @code{m4_include} per source file 24887 for tests. Each such included file, or the remainder of 24888 @file{testsuite.at} if include files are not used, contain a sequence of 24889 test groups. Each test group begins with a call to @code{AT_SETUP}, 24890 then an arbitrary number of shell commands or calls to @code{AT_CHECK}, 24891 and then completes with a call to @code{AT_CLEANUP}. Multiple test 24892 groups can be categorized by a call to @code{AT_BANNER}. 24893 24894 All of the public Autotest macros have all-uppercase names in the 24895 namespace @samp{^AT_} to prevent them from accidentally conflicting with 24896 other text; Autoconf also reserves the namespace @samp{^_AT_} for 24897 internal macros. All shell variables used in the testsuite for internal 24898 purposes have mostly-lowercase names starting with @samp{at_}. Autotest 24899 also uses here-document delimiters in the namespace @samp{^_AT[A-Z]}, and 24900 makes use of the file system namespace @samp{^at-}. 24901 24902 Since Autoconf is built on top of M4sugar (@pxref{Programming in 24903 M4sugar}) and M4sh (@pxref{Programming in M4sh}), you must also be aware 24904 of those namespaces (@samp{^_?\(m4\|AS\)_}). In general, you 24905 @emph{should not use} the namespace of a package that does not own the 24906 macro 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. 24911 Initialize Autotest. Giving a @var{name} to the test suite is 24912 encouraged if your package includes several test suites. Before this 24913 macro is called, @code{AT_PACKAGE_STRING} and 24914 @code{AT_PACKAGE_BUGREPORT} must be defined, which are used to display 24915 information about the testsuite to the user. Typically, these macros 24916 are provided by a file @file{package.m4} built by @command{make} 24917 (@pxref{Making testsuite Scripts}), in order to inherit the package 24918 name, 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 24924 State that, in addition to the Free Software Foundation's copyright on 24925 the Autotest macros, parts of your test suite are covered by 24926 @var{copyright-notice}. 24927 24928 The @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} 24936 Accept options from the space-separated list @var{options}, a list that 24937 has leading dashes removed from the options. Long options will be 24938 prefixed with @samp{--}, single-character options with @samp{-}. The 24939 first word in this list is the primary @var{option}, any others are 24940 assumed to be short-hand aliases. The variable associated with it 24941 is @code{at_arg_@var{option}}, with any dashes in @var{option} replaced 24942 with underscores. 24943 24944 If the user passes @option{--@var{option}} to the @command{testsuite}, 24945 the variable will be set to @samp{:}. If the user does not pass the 24946 option, or passes @option{--no-@var{option}}, then the variable will be 24947 set 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, 24952 the variable @code{at_optarg} will be set to @samp{:} or @samp{false} as 24953 appropriate. @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 24957 complete 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 24962 It is recommended that you use a package-specific prefix to @var{options} 24963 names 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} 24970 Accept options with arguments from the space-separated list 24971 @var{options}, a list that has leading dashes removed from the options. 24972 Long options will be prefixed with @samp{--}, single-character options 24973 with @samp{-}. The first word in this list is the primary @var{option}, 24974 any others are assumed to be short-hand aliases. The variable associated 24975 with it is @code{at_arg_@var{option}}, with any dashes in @var{option} 24976 replaced with underscores. 24977 24978 If the user passes @option{--@var{option}=@var{arg}} or 24979 @option{--@var{option} @var{arg}} to the @command{testsuite}, the 24980 variable 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, 24984 the 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 24988 complete 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 24993 It is recommended that you use a package-specific prefix to @var{options} 24994 names in order to avoid clashes with future Autotest built-in options. 24995 @end defmac 24996 24997 @defmac AT_COLOR_TESTS 24998 @atindex{COLOR_TESTS} 24999 Enable colored test results by default when the output is connected to 25000 a terminal. 25001 @end defmac 25002 25003 @defmac AT_TESTED (@var{executables}) 25004 @atindex{TESTED} 25005 Log the file name and answer to @option{--version} of each program in 25006 space-separated list @var{executables}. Several invocations register 25007 new executables, in other words, don't fear registering one program 25008 several times. 25009 25010 Autotest test suites rely on @env{PATH} to find the tested program. 25011 This avoids the need to generate absolute names of the various tools, and 25012 makes it possible to test installed programs. Therefore, knowing which 25013 programs are being exercised is crucial to understanding problems in 25014 the test suite itself, or its occasional misuses. It is a good idea to 25015 also subscribe foreign programs you depend upon, to avoid incompatible 25016 diagnostics. 25017 @end defmac 25018 25019 @sp 1 25020 25021 @defmac AT_BANNER (@var{test-category-name}) 25022 @atindex{BANNER} 25023 This macro identifies the start of a category of related test groups. 25024 When the resulting @file{testsuite} is invoked with more than one test 25025 group to run, its output will include a banner containing 25026 @var{test-category-name} prior to any tests run from that category. The 25027 banner should be no more than about 40 or 50 characters. A blank banner 25028 indicates uncategorized tests; an empty line will be inserted after 25029 tests from an earlier category, effectively ending that category. 25030 @end defmac 25031 25032 @defmac AT_SETUP (@var{test-group-name}) 25033 @atindex{SETUP} 25034 This macro starts a group of related tests, all to be executed in the 25035 same subshell. It accepts a single argument, which holds a few words 25036 (no more than about 30 or 40 characters) quickly describing the purpose 25037 of the test group being started. @var{test-group-name} must not expand 25038 to unbalanced quotes, although quadrigraphs can be used. 25039 @end defmac 25040 25041 @defmac AT_KEYWORDS (@var{keywords}) 25042 @atindex{KEYWORDS} 25043 Associate the space-separated list of @var{keywords} to the enclosing 25044 test group. This makes it possible to run ``slices'' of the test suite. 25045 For instance, if some of your test groups exercise some @samp{foo} 25046 feature, 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 25051 Several invocations within a test group accumulate new keywords. In 25052 other words, don't fear registering the same keyword several times in a 25053 test group. 25054 @end defmac 25055 25056 @defmac AT_CAPTURE_FILE (@var{file}) 25057 @atindex{CAPTURE_FILE} 25058 If the current test group fails, log the contents of @var{file}. 25059 Several 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} 25064 Make 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 25066 such as a @code{test} command. Tests before @command{AT_FAIL_IF} 25067 will be executed and may still cause the test group to be skipped. 25068 You can instantiate this macro many times from within the same test group. 25069 25070 You 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 25072 use @command{AT_CHECK} like 25073 @example 25074 AT_CHECK([if @var{shell-condition}; then exit 99; fi]) 25075 @end example 25076 @noindent 25077 so that such output is properly recorded in the @file{testsuite.log} 25078 file. 25079 @end defmac 25080 25081 @defmac AT_SKIP_IF (@var{shell-condition}) 25082 @atindex{SKIP_IF} 25083 Determine whether the test should be skipped because it requires 25084 features that are unsupported on the machine under test. 25085 @var{shell-condition} is a shell expression such as a @code{test} 25086 command. Tests before @command{AT_SKIP_IF} will be executed 25087 and may still cause the test group to fail. You can instantiate this 25088 macro many times from within the same test group. 25089 25090 You 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 25092 use @command{AT_CHECK} like 25093 @example 25094 AT_CHECK([if @var{shell-condition}; then exit 77; fi]) 25095 @end example 25096 @noindent 25097 so that such output is properly recorded in the @file{testsuite.log} 25098 file. 25099 @end defmac 25100 25101 @defmac AT_XFAIL_IF (@var{shell-condition}) 25102 @atindex{XFAIL_IF} 25103 Determine whether the test is expected to fail because it is a known 25104 bug (for unsupported features, you should skip the test). 25105 @var{shell-condition} is a shell expression such as a @code{test} 25106 command; you can instantiate this macro many times from within the 25107 same test group, and one of the conditions is enough to turn 25108 the test into an expected failure. 25109 @end defmac 25110 25111 @defmac AT_CLEANUP 25112 @atindex{CLEANUP} 25113 End the current test group. 25114 @end defmac 25115 25116 @sp 1 25117 25118 @defmac AT_DATA (@var{file}, @var{contents}) 25119 @atindex{DATA} 25120 Initialize an input data @var{file} with given @var{contents}. Of 25121 course, the @var{contents} have to be properly quoted between square 25122 brackets to protect against included commas or spurious M4 25123 expansion. @var{contents} must be empty or end with a newline. 25124 @var{file} must 25125 be 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 25135 Execute a test by performing given shell @var{commands} in a subshell. 25136 @var{commands} is output as-is, so shell expansions are honored. These 25137 commands should normally exit with @var{status}, while producing expected 25138 @var{stdout} and @var{stderr} contents. If @var{commands} exit with 25139 unexpected 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 25141 immediately 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. 25144 At 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 25147 This macro must be invoked in between @code{AT_SETUP} and @code{AT_CLEANUP}. 25148 25149 If @var{status} is the literal @samp{ignore}, then the corresponding 25150 exit status is not checked, except for the special cases of 77 (skip) 25151 and 99 (hard failure). The existence of hard failures allows one to 25152 mark a test as an expected failure with @code{AT_XFAIL_IF} because a 25153 feature has not yet been implemented, but to still distinguish between 25154 gracefully handling the missing feature and dumping core. A hard 25155 failure also inhibits post-test actions in @var{run-if-fail}. 25156 25157 If the value of the @var{stdout} or @var{stderr} parameter is one of the 25158 literals in the following table, then the test treats the output 25159 according to the rules of that literal. Otherwise, the value of the 25160 parameter is treated as text that must exactly match the output given by 25161 @var{commands} on standard output and standard error (including an empty 25162 parameter for no output); any differences are captured in the testsuite 25163 log and the test is failed (unless an unexpected exit status of 77 25164 skipped the test instead). The difference between @code{AT_CHECK} and 25165 @code{AT_CHECK_UNQUOTED} is that only the latter performs shell variable 25166 expansion (@samp{$}), command substitution (@samp{`}), and backslash 25167 escaping (@samp{\}) on comparison text given in the @var{stdout} and 25168 @var{stderr} arguments; if the text includes a trailing newline, this 25169 would be the same as if it were specified via an unquoted 25170 here-document. (However, there is no difference in the interpretation 25171 of @var{commands}). 25172 25173 @table @samp 25174 @item ignore 25175 The content of the output is ignored, but still captured in the test 25176 group log (if the testsuite is run with option @option{-v}, the test 25177 group log is displayed as the test is run; if the test group later 25178 fails, the test group log is also copied into the overall testsuite 25179 log). This action is valid for both @var{stdout} and @var{stderr}. 25180 25181 @item ignore-nolog 25182 The content of the output is ignored, and nothing is captured in the log 25183 files. If @var{commands} are likely to produce binary output (including 25184 long lines) or large amounts of output, then logging the output can make 25185 it harder to locate details related to subsequent tests within the 25186 group, and could potentially corrupt terminal display of a user running 25187 @command{testsuite -v}. 25188 25189 @item stdout 25190 For the @var{stdout} parameter, capture the content of standard output 25191 to both the file @file{stdout} and the test group log. Subsequent 25192 commands in the test group can then post-process the file. This action 25193 is often used when it is desired to use @command{grep} to look for a 25194 substring in the output, or when the output must be post-processed to 25195 normalize error messages into a common form. 25196 25197 @item stderr 25198 Like @samp{stdout}, except that it only works for the @var{stderr} 25199 parameter, and the standard error capture file will be named 25200 @file{stderr}. 25201 25202 @item stdout-nolog 25203 @itemx stderr-nolog 25204 Like @samp{stdout} or @samp{stderr}, except that the captured output is 25205 not duplicated into the test group log. This action is particularly 25206 useful for an intermediate check that produces large amounts of data, 25207 which will be followed by another check that filters down to the 25208 relevant data, as it makes it easier to locate details in the log. 25209 25210 @item expout 25211 For the @var{stdout} parameter, compare standard output contents with 25212 the previously created file @file{expout}, and list any differences in 25213 the testsuite log. 25214 25215 @item experr 25216 Like @samp{expout}, except that it only works for the @var{stderr} 25217 parameter, 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} 25225 Initialize and execute an Erlang module named @var{module} that performs 25226 tests following the @var{test-spec} EUnit test specification. 25227 @var{test-spec} must be a valid EUnit test specification, as defined in 25228 the @uref{http://@/erlang.org/@/doc/@/apps/@/eunit/@/index.html, EUnit 25229 Reference Manual}. @var{erlflags} are optional command-line options 25230 passed to the Erlang interpreter to execute the test Erlang module. 25231 Typically, @var{erlflags} defines at least the paths to directories 25232 containing the compiled Erlang modules under test, as @samp{-pa path1 25233 path2 ...}. 25234 25235 For example, the unit tests associated with Erlang module @samp{testme}, 25236 which compiled code is in subdirectory @file{src}, can be performed 25237 with: 25238 25239 @example 25240 AT_CHECK_EUNIT([testme_testsuite], [@{module, testme@}], 25241 [-pa "$@{abs_top_builddir@}/src"]) 25242 @end example 25243 25244 This macro must be invoked in between @code{AT_SETUP} and @code{AT_CLEANUP}. 25245 25246 Variables @code{ERL}, @code{ERLC}, and (optionally) @code{ERLCFLAGS} 25247 must be defined as the path of the Erlang interpreter, the path of the 25248 Erlang compiler, and the command-line flags to pass to the compiler, 25249 respectively. 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 25252 variables are automatically defined in the testsuite. If @code{ERL} or 25253 @code{ERLC} is not defined, the test group is skipped. 25254 25255 If the EUnit library cannot be found, i.e. if module @code{eunit} cannot 25256 be loaded, the test group is skipped. Otherwise, if @var{test-spec} is 25257 an invalid EUnit test specification, the test group fails. Otherwise, 25258 if the EUnit test passes, shell commands @var{run-if-pass} are executed 25259 or, if the EUnit test fails, shell commands @var{run-if-fail} are 25260 executed and the test group fails. 25261 25262 Only the generated test Erlang module is automatically compiled and 25263 executed. If @var{test-spec} involves testing other Erlang modules, 25264 e.g. module @samp{testme} in the example above, those modules must be 25265 already compiled. 25266 25267 If the testsuite is run in verbose mode, with option @option{--verbose}, 25268 EUnit is also run in verbose mode to output more details about 25269 individual unit tests. 25270 @end defmac 25271 25272 25273 @node testsuite Invocation 25274 @section Running @command{testsuite} Scripts 25275 @cindex @command{testsuite} 25276 25277 Autotest test suites support the following options: 25278 25279 @table @option 25280 @item --help 25281 @itemx -h 25282 Display the list of options and exit successfully. 25283 25284 @item --version 25285 @itemx -V 25286 Display the version of the test suite and exit successfully. 25287 25288 @item --directory=@var{dir} 25289 @itemx -C @var{dir} 25290 Change the current directory to @var{dir} before creating any files. 25291 Useful for running the testsuite in a subdirectory from a top-level 25292 Makefile. 25293 25294 @item --jobs@r{[}=@var{n}@r{]} 25295 @itemx -j@ovar{n} 25296 Run @var{n} tests in parallel, if possible. If @var{n} is not given, 25297 run all given tests in parallel. Note that there should be no space 25298 before the argument to @option{-j}, as @option{-j @var{number}} denotes 25299 the separate arguments @option{-j} and @option{@var{number}}, see below. 25300 25301 In parallel mode, the standard input device of the testsuite script is 25302 not available to commands inside a test group. Furthermore, banner 25303 lines are not printed, and the summary line for each test group is 25304 output after the test group completes. Summary lines may appear 25305 unordered. If verbose and trace output are enabled (see below), they 25306 may appear intermixed from concurrently running tests. 25307 25308 Parallel mode requires the @command{mkfifo} command to work, and will be 25309 silently disabled otherwise. 25310 25311 @item --clean 25312 @itemx -c 25313 Remove all the files the test suite might have created and exit. Meant 25314 for @code{clean} Make targets. 25315 25316 @item --list 25317 @itemx -l 25318 List all the tests (or only the selection), including their possible 25319 keywords. 25320 @end table 25321 25322 @sp 1 25323 25324 By default all tests are performed (or described with @option{--list}) 25325 silently in the default environment, but the environment, set of tests, 25326 and verbosity level can be tuned: 25327 25328 @table @samp 25329 @item @var{variable}=@var{value} 25330 Set the environment @var{variable} to @var{value}. Use this rather 25331 than @samp{FOO=foo ./testsuite} as debugging scripts would then run in a 25332 different environment. 25333 25334 @cindex @code{AUTOTEST_PATH} 25335 The variable @code{AUTOTEST_PATH} specifies the testing path to prepend 25336 to @env{PATH}. Relative directory names (not starting with 25337 @samp{/}) are considered to be relative to the top level of the 25338 package being built. All directories are made absolute, first 25339 starting from the top level @emph{build} tree, then from the 25340 @emph{source} tree. For instance @samp{./testsuite 25341 AUTOTEST_PATH=tests:bin} for a @file{/src/foo-1.0} source package built 25342 in @file{/tmp/foo} results in @samp{/tmp/foo/tests:/tmp/foo/bin} and 25343 then @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} 25350 Add the corresponding test groups, with obvious semantics, to the 25351 selection. 25352 25353 @item --keywords=@var{keywords} 25354 @itemx -k @var{keywords} 25355 Add to the selection the test groups with title or keywords (arguments 25356 to @code{AT_SETUP} or @code{AT_KEYWORDS}) that match @emph{all} keywords 25357 of the comma separated list @var{keywords}, case-insensitively. Use 25358 @samp{!} immediately before the keyword to invert the selection for this 25359 keyword. By default, the keywords match whole words; enclose them in 25360 @samp{.*} to also match parts of words. 25361 25362 For example, running 25363 25364 @example 25365 @kbd{./testsuite -k 'autoupdate,.*FUNC.*'} 25366 @end example 25367 25368 @noindent 25369 selects all tests tagged @samp{autoupdate} @emph{and} with tags 25370 containing @samp{FUNC} (as in @samp{AC_CHECK_FUNC}, @samp{AC_FUNC_ALLOCA}, 25371 etc.), while 25372 25373 @example 25374 @kbd{./testsuite -k '!autoupdate' -k '.*FUNC.*'} 25375 @end example 25376 25377 @noindent 25378 selects all tests not tagged @samp{autoupdate} @emph{or} with tags 25379 containing @samp{FUNC}. 25380 25381 @item --errexit 25382 @itemx -e 25383 If any test fails, immediately abort testing. This implies 25384 @option{--debug}: post test group clean up, and top-level logging 25385 are inhibited. This option is meant for the full test 25386 suite, it is not really useful for generated debugging scripts. 25387 If the testsuite is run in parallel mode using @option{--jobs}, 25388 then concurrently running tests will finish before exiting. 25389 25390 @item --verbose 25391 @itemx -v 25392 Force more verbosity in the detailed output of what is being done. This 25393 is the default for debugging scripts. 25394 25395 @item --color 25396 @itemx --color@r{[}=never@r{|}auto@r{|}always@r{]} 25397 Enable colored test results. Without an argument, or with @samp{always}, 25398 test results will be colored. With @samp{never}, color mode is turned 25399 off. Otherwise, if either the macro @code{AT_COLOR_TESTS} is used by 25400 the testsuite author, or the argument @samp{auto} is given, then test 25401 results are colored if standard output is connected to a terminal. 25402 25403 @item --debug 25404 @itemx -d 25405 Do not remove the files after a test group was performed---but they are 25406 still removed @emph{before}, therefore using this option is sane when 25407 running several test groups. Create debugging scripts. Do not 25408 overwrite the top-level 25409 log (in order to preserve a supposedly existing full log file). This is 25410 the default for debugging scripts, but it can also be useful to debug 25411 the testsuite itself. 25412 25413 @item --recheck 25414 Add to the selection all test groups that failed or passed unexpectedly 25415 during the last non-debugging test run. 25416 25417 @item --trace 25418 @itemx -x 25419 Trigger shell tracing of the test groups. 25420 @end table 25421 25422 Besides these options accepted by every Autotest testsuite, the 25423 testsuite author might have added package-specific options 25424 via the @code{AT_ARG_OPTION} and @code{AT_ARG_OPTION_ARG} macros 25425 (@pxref{Writing Testsuites}); refer to @command{testsuite --help} and 25426 the package documentation for details. 25427 25428 25429 @node Making testsuite Scripts 25430 @section Making @command{testsuite} Scripts 25431 25432 For putting Autotest into movement, you need some configuration and 25433 makefile machinery. We recommend, at least if your package uses deep or 25434 shallow hierarchies, that you use @file{tests/} as the name of the 25435 directory holding all your tests and their makefile. Here is a 25436 check 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} 25448 Make sure to create the file @file{package.m4}, which defines the 25449 identity of the package. It must define @code{AT_PACKAGE_STRING}, the 25450 full signature of the package, and @code{AT_PACKAGE_BUGREPORT}, the 25451 address to which bug reports should be sent. For sake of completeness, 25452 we 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. 25456 Be sure to distribute @file{package.m4} and to put it into the source 25457 hierarchy: the test suite ought to be shipped! See below for an example 25458 @file{Makefile} excerpt. 25459 25460 @item 25461 Invoke @code{AC_CONFIG_TESTDIR}. 25462 25463 @defmac AC_CONFIG_TESTDIR (@var{directory}, @dvar{test-path, directory}) 25464 @acindex{CONFIG_TESTDIR} 25465 An Autotest test suite is to be configured in @var{directory}. This 25466 macro 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 25472 Still 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 25477 The appropriate @file{Makefile} should be modified so the validation in 25478 your package is triggered by @samp{make check}. An example is provided 25479 below. 25480 @end itemize 25481 25482 With Automake, here is a minimal example for inclusion in 25483 @file{tests/Makefile.am}, in order to link @samp{make check} with a 25484 validation 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 25505 EXTRA_DIST = testsuite.at $(srcdir)/package.m4 $(TESTSUITE) atlocal.in 25506 TESTSUITE = $(srcdir)/testsuite 25507 25508 check-local: atconfig atlocal $(TESTSUITE) 25509 $(SHELL) '$(TESTSUITE)' $(TESTSUITEFLAGS) 25510 25511 installcheck-local: atconfig atlocal $(TESTSUITE) 25512 $(SHELL) '$(TESTSUITE)' AUTOTEST_PATH='$(bindir)' \ 25513 $(TESTSUITEFLAGS) 25514 25515 clean-local: 25516 test ! -f '$(TESTSUITE)' || \ 25517 $(SHELL) '$(TESTSUITE)' --clean 25518 25519 AUTOM4TE = $(SHELL) $(srcdir)/build-aux/missing --run autom4te 25520 AUTOTEST = $(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 25526 Note that the built testsuite is distributed; this is necessary because 25527 users might not have Autoconf installed, and thus would not be able to 25528 rebuild it. Likewise, the use of @file{missing} provides the user with 25529 a nicer error message if they modify a source file to the testsuite, and 25530 accidentally trigger the rebuild rules. 25531 25532 You might want to list explicitly the dependencies, i.e., the list of 25533 the files @file{testsuite.at} includes. 25534 25535 If you don't use Automake, you should include the above example in 25536 @file{tests/@/Makefile.in}, along with additional lines inspired from 25537 the following: 25538 25539 @example 25540 subdir = tests 25541 PACKAGE_NAME = @@PACKAGE_NAME@@ 25542 PACKAGE_TARNAME = @@PACKAGE_TARNAME@@ 25543 PACKAGE_VERSION = @@PACKAGE_VERSION@@ 25544 PACKAGE_STRING = @@PACKAGE_STRING@@ 25545 PACKAGE_BUGREPORT = @@PACKAGE_BUGREPORT@@ 25546 PACKAGE_URL = @@PACKAGE_URL@@ 25547 25548 atconfig: $(top_builddir)/config.status 25549 cd $(top_builddir) && \ 25550 $(SHELL) ./config.status $(subdir)/$@@ 25551 25552 atlocal: $(srcdir)/atlocal.in $(top_builddir)/config.status 25553 cd $(top_builddir) && \ 25554 $(SHELL) ./config.status $(subdir)/$@@ 25555 @end example 25556 25557 @noindent 25558 and manage to have @code{$(EXTRA_DIST)} distributed. You will also want 25559 to distribute the file @file{build-aux/@/missing} from the Automake 25560 project; a copy of this file resides in the Autoconf source tree. 25561 25562 With all this in place, and if you have not initialized @samp{TESTSUITEFLAGS} 25563 within your makefile, you can fine-tune test suite execution with this 25564 variable, for example: 25565 25566 @example 25567 make 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 25577 Several questions about Autoconf come up occasionally. Here some of them 25578 are 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 25597 What are the restrictions on distributing @command{configure} 25598 scripts that Autoconf generates? How does that affect my 25599 programs that use them? 25600 @end display 25601 25602 There are no restrictions on how the configuration scripts that Autoconf 25603 produces may be distributed or used. In Autoconf version 1, they were 25604 covered by the GNU General Public License. We still encourage 25605 software authors to distribute their work under terms like those of the 25606 GPL, but doing so is not required to use Autoconf. 25607 25608 Of 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 25611 exception to the GPL when they are used with an Autoconf-generated 25612 @command{configure} script, which permits you to distribute them under the 25613 same terms as the rest of your package. @file{install-sh} is from the X 25614 Consortium and is not copyrighted. 25615 25616 @node Why GNU M4 25617 @section Why Require GNU M4? 25618 25619 @display 25620 Why does Autoconf require GNU M4? 25621 @end display 25622 25623 Many M4 implementations have hard-coded limitations on the size and 25624 number of macros that Autoconf exceeds. They also lack several 25625 builtin macros that it would be difficult to get along without in a 25626 sophisticated application like Autoconf, including: 25627 25628 @example 25629 m4_builtin 25630 m4_indir 25631 m4_bpatsubst 25632 __file__ 25633 __line__ 25634 @end example 25635 25636 Autoconf requires version 1.4.6 or later of GNU M4. 25637 25638 Since only software maintainers need to use Autoconf, and since GNU 25639 M4 is simple to configure and install, it seems reasonable to require 25640 GNU M4 to be installed also. Many maintainers of GNU and 25641 other free software already have most of the GNU utilities 25642 installed, since they prefer them. 25643 25644 @node Bootstrapping 25645 @section How Can I Bootstrap? 25646 @cindex Bootstrap 25647 25648 @display 25649 If Autoconf requires GNU M4 and GNU M4 has an Autoconf 25650 @command{configure} script, how do I bootstrap? It seems like a chicken 25651 and egg problem! 25652 @end display 25653 25654 This is a misunderstanding. Although GNU M4 does come with a 25655 @command{configure} script produced by Autoconf, Autoconf is not required 25656 in order to run the script and install GNU M4. Autoconf is only 25657 required if you want to change the M4 @command{configure} script, which few 25658 people have to do (mainly its maintainer). 25659 25660 @node Why Not Imake 25661 @section Why Not Imake? 25662 @cindex Imake 25663 25664 @display 25665 Why not use Imake instead of @command{configure} scripts? 25666 @end display 25667 25668 Several people have written addressing this question, so 25669 adaptations of their explanations are included here. 25670 25671 The following answer is based on one written by Richard Pixley: 25672 25673 @quotation 25674 Autoconf generated scripts frequently work on machines that it has 25675 never been set up to handle before. That is, it does a good job of 25676 inferring a configuration for a new system. Imake cannot do this. 25677 25678 Imake uses a common database of host specific data. For X11, this makes 25679 sense because the distribution is made as a collection of tools, by one 25680 central authority who has control over the database. 25681 25682 GNU tools are not released this way. Each GNU tool has a 25683 maintainer; these maintainers are scattered across the world. Using a 25684 common database would be a maintenance nightmare. Autoconf may appear 25685 to be this kind of database, but in fact it is not. Instead of listing 25686 host dependencies, it lists program requirements. 25687 25688 If you view the GNU suite as a collection of native tools, then the 25689 problems are similar. But the GNU development tools can be 25690 configured as cross tools in almost any host+target permutation. All of 25691 these configurations can be installed concurrently. They can even be 25692 configured to share host independent files across hosts. Imake doesn't 25693 address these issues. 25694 25695 Imake templates are a form of standardization. The GNU coding 25696 standards address the same issues without necessarily imposing the same 25697 restrictions. 25698 @end quotation 25699 25700 25701 Here is some further explanation, written by Per Bothner: 25702 25703 @quotation 25704 One of the advantages of Imake is that it is easy to generate large 25705 makefiles using the @samp{#include} and macro mechanisms of @command{cpp}. 25706 However, @code{cpp} is not programmable: it has limited conditional 25707 facilities, and no looping. And @code{cpp} cannot inspect its 25708 environment. 25709 25710 All of these problems are solved by using @code{sh} instead of 25711 @code{cpp}. The shell is fully programmable, has macro substitution, 25712 can execute (or source) other shell scripts, and can inspect its 25713 environment. 25714 @end quotation 25715 25716 25717 Paul Eggert elaborates more: 25718 25719 @quotation 25720 With Autoconf, installers need not assume that Imake itself is already 25721 installed and working well. This may not seem like much of an advantage 25722 to people who are accustomed to Imake. But on many hosts Imake is not 25723 installed or the default installation is not working well, and requiring 25724 Imake to install a package hinders the acceptance of that package on 25725 those hosts. For example, the Imake template and configuration files 25726 might not be installed properly on a host, or the Imake build procedure 25727 might wrongly assume that all source files are in one big directory 25728 tree, or the Imake configuration might assume one compiler whereas the 25729 package or the installer needs to use another, or there might be a 25730 version mismatch between the Imake expected by the package and the Imake 25731 supported by the host. These problems are much rarer with Autoconf, 25732 where each package comes with its own independent configuration 25733 processor. 25734 25735 Also, Imake often suffers from unexpected interactions between 25736 @command{make} and the installer's C preprocessor. The fundamental problem 25737 here is that the C preprocessor was designed to preprocess C programs, 25738 not makefiles. This is much less of a problem with Autoconf, 25739 which uses the general-purpose preprocessor M4, and where the 25740 package's author (rather than the installer) does the preprocessing in a 25741 standard way. 25742 @end quotation 25743 25744 25745 Finally, Mark Eichin notes: 25746 25747 @quotation 25748 Imake isn't all that extensible, either. In order to add new features to 25749 Imake, you need to provide your own project template, and duplicate most 25750 of the features of the existing one. This means that for a sophisticated 25751 project, using the vendor-provided Imake templates fails to provide any 25752 leverage---since they don't cover anything that your own project needs 25753 (unless it is an X11 program). 25754 25755 On the other side, though: 25756 25757 The one advantage that Imake has over @command{configure}: 25758 @file{Imakefile} files tend to be much shorter (likewise, less redundant) 25759 than @file{Makefile.in} files. There is a fix to this, however---at least 25760 for the Kerberos V5 tree, we've modified things to call in common 25761 @file{post.in} and @file{pre.in} makefile fragments for the 25762 entire tree. This means that a lot of common things don't have to be 25763 duplicated, 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 25771 My program needs library files, installed in @code{datadir} and 25772 similar. If I use 25773 25774 @example 25775 AC_DEFINE_UNQUOTED([DATADIR], [$datadir], 25776 [Define to the read-only architecture-independent 25777 data directory.]) 25778 @end example 25779 25780 @noindent 25781 I get 25782 25783 @example 25784 #define DATADIR "$@{prefix@}/share" 25785 @end example 25786 @end display 25787 25788 As already explained, this behavior is on purpose, mandated by the 25789 GNU Coding Standards, see @ref{Installation Directory 25790 Variables}. There are several means to achieve a similar goal: 25791 25792 @itemize @minus 25793 @item 25794 Do not use @code{AC_DEFINE} but use your makefile to pass the 25795 actual value of @code{datadir} via compilation flags. 25796 @xref{Installation Directory Variables}, for the details. 25797 25798 @item 25799 This solution can be simplified when compiling a program: you may either 25800 extend the @code{CPPFLAGS}: 25801 25802 @example 25803 CPPFLAGS = -DDATADIR='"$(datadir)"' @@CPPFLAGS@@ 25804 @end example 25805 25806 @noindent 25807 If you are using Automake, you should use @code{AM_CPPFLAGS} instead: 25808 25809 @example 25810 AM_CPPFLAGS = -DDATADIR='"$(datadir)"' 25811 @end example 25812 25813 @noindent 25814 Alternatively, create a dedicated header file: 25815 25816 @example 25817 DISTCLEANFILES = myprog-paths.h 25818 myprog-paths.h: Makefile 25819 echo '#define DATADIR "$(datadir)"' >$@@ 25820 @end example 25821 25822 @noindent 25823 The gnulib module @samp{configmake} provides such a header with all the 25824 standard directory variables defined, @pxref{configmake,,, gnulib, GNU 25825 Gnulib}. 25826 25827 @item 25828 Use @code{AC_DEFINE} but have @command{configure} compute the literal 25829 value of @code{datadir} and others. Many people have wrapped macros to 25830 automate this task; for an example, see the macro @code{AC_DEFINE_DIR} from 25831 the @uref{http://@/www.gnu.org/@/software/@/autoconf-archive/, Autoconf Macro 25832 Archive}. 25833 25834 This solution does not conform to the GNU Coding Standards. 25835 25836 @item 25837 Note that all the previous solutions hard wire the absolute name of 25838 these directories in the executables, which is not a good property. You 25839 may try to compute the names relative to @code{prefix}, and try to 25840 find @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 25848 What is this directory @file{autom4te.cache}? Can I safely remove it? 25849 @end display 25850 25851 In the GNU Build System, @file{configure.ac} plays a central 25852 role 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 25855 check the completeness of @file{configure.ac}, @command{autoreconf} to 25856 check the GNU Build System components that are used. To 25857 ``read @file{configure.ac}'' actually means to compile it with M4, 25858 which can be a long process for complex @file{configure.ac}. 25859 25860 This is why all these tools, instead of running directly M4, invoke 25861 @command{autom4te} (@pxref{autom4te Invocation}) which, while answering to 25862 a 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 25865 stores 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%, 25868 and is increasing with the size of @file{configure.ac}. 25869 25870 But it is and remains being simply a cache: you can safely remove it. 25871 25872 @sp 1 25873 25874 @display 25875 Can I permanently get rid of it? 25876 @end display 25877 25878 The creation of this cache can be disabled from 25879 @file{~/.autom4te.cfg}, see @ref{Customizing autom4te}, for more 25880 details. You should be aware that disabling the cache slows down the 25881 Autoconf test suite by 40%. The more GNU Build System 25882 components are used, the more the cache is useful; for instance 25883 running @samp{autoreconf -f} on the Core Utilities is twice slower without 25884 the cache @emph{although @option{--force} implies that the cache is 25885 not 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 25892 The most important guideline to bear in mind when checking for 25893 features is to mimic as much as possible the intended use. 25894 Unfortunately, old versions of @code{AC_CHECK_HEADER} and 25895 @code{AC_CHECK_HEADERS} failed to follow this idea, and called 25896 the preprocessor, instead of the compiler, to check for headers. As a 25897 result, incompatibilities between headers went unnoticed during 25898 configuration, and maintainers finally had to deal with this issue 25899 elsewhere. 25900 25901 The transition began with Autoconf 2.56. As of Autoconf 2.64 both 25902 checks are performed, and @command{configure} complains loudly if the 25903 compiler and the preprocessor do not agree. However, only the compiler 25904 result is considered. 25905 25906 Consider the following example: 25907 25908 @smallexample 25909 $ @kbd{cat number.h} 25910 typedef int number; 25911 $ @kbd{cat pi.h} 25912 const number pi = 3; 25913 $ @kbd{cat configure.ac} 25914 AC_INIT([Example], [1.0], [bug-example@@example.org]) 25915 AC_CHECK_HEADERS([pi.h]) 25916 $ @kbd{autoconf -Wall} 25917 $ @kbd{./configure} 25918 checking for gcc... gcc 25919 checking for C compiler default output file name... a.out 25920 checking whether the C compiler works... yes 25921 checking whether we are cross compiling... no 25922 checking for suffix of executables... 25923 checking for suffix of object files... o 25924 checking whether we are using the GNU C compiler... yes 25925 checking whether gcc accepts -g... yes 25926 checking for gcc option to accept ISO C89... none needed 25927 checking how to run the C preprocessor... gcc -E 25928 checking for grep that handles long lines and -e... grep 25929 checking for egrep... grep -E 25930 checking for ANSI C header files... yes 25931 checking for sys/types.h... yes 25932 checking for sys/stat.h... yes 25933 checking for stdlib.h... yes 25934 checking for string.h... yes 25935 checking for memory.h... yes 25936 checking for strings.h... yes 25937 checking for inttypes.h... yes 25938 checking for stdint.h... yes 25939 checking for unistd.h... yes 25940 checking pi.h usability... no 25941 checking pi.h presence... yes 25942 configure: WARNING: pi.h: present but cannot be compiled 25943 configure: WARNING: pi.h: check for missing prerequisite headers? 25944 configure: WARNING: pi.h: see the Autoconf documentation 25945 configure: WARNING: pi.h: section "Present But Cannot Be Compiled" 25946 configure: WARNING: pi.h: proceeding with the compiler's result 25947 configure: WARNING: ## -------------------------------------- ## 25948 configure: WARNING: ## Report this to bug-example@@example.org ## 25949 configure: WARNING: ## -------------------------------------- ## 25950 checking for pi.h... yes 25951 @end smallexample 25952 25953 @noindent 25954 The proper way the handle this case is using the fourth argument 25955 (@pxref{Generic Headers}): 25956 25957 @example 25958 $ @kbd{cat configure.ac} 25959 AC_INIT([Example], [1.0], [bug-example@@example.org]) 25960 AC_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} 25967 checking for gcc... gcc 25968 checking for C compiler default output... a.out 25969 checking whether the C compiler works... yes 25970 checking whether we are cross compiling... no 25971 checking for suffix of executables... 25972 checking for suffix of object files... o 25973 checking whether we are using the GNU C compiler... yes 25974 checking whether gcc accepts -g... yes 25975 checking for gcc option to accept ANSI C... none needed 25976 checking for number.h... yes 25977 checking for pi.h... yes 25978 @end example 25979 25980 See @ref{Particular Headers}, for a list of headers with their 25981 prerequisites. 25982 25983 @node Expanded Before Required 25984 @section Expanded Before Required 25985 25986 @cindex expanded before required 25987 Older versions of Autoconf silently built files with incorrect ordering 25988 between dependent macros if an outer macro first expanded, then later 25989 indirectly required, an inner macro. Starting with Autoconf 2.64, this 25990 situation no longer generates out-of-order code, but results in 25991 duplicate 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 26017 To avoid this warning, decide what purpose the macro in question serves. 26018 If it only needs to be expanded once (for example, if it provides 26019 initialization text used by later macros), then the simplest fix is to 26020 change the macro to be declared with @code{AC_DEFUN_ONCE} 26021 (@pxref{One-Shot Macros}), although this only works in Autoconf 2.64 and 26022 newer. A more portable fix is to change all 26023 instances of direct calls to instead go through @code{AC_REQUIRE} 26024 (@pxref{Prerequisite Macros}). If, instead, the macro is parameterized 26025 by arguments or by the current definition of other macros in the m4 26026 environment, then the macro should always be directly expanded instead 26027 of required. 26028 26029 For another case study, consider this example trimmed down from an 26030 actual package. Originally, the package contained shell code and 26031 multiple macro invocations at the top level of @file{configure.ac}: 26032 26033 @example 26034 AC_DEFUN([FOO], [AC_COMPILE_IFELSE([@dots{}])]) 26035 foobar= 26036 AC_PROG_CC 26037 FOO 26038 @end example 26039 26040 @noindent 26041 but that was getting complex, so the author wanted to offload some of 26042 the 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 26044 macro: 26045 26046 @example 26047 AC_DEFUN([FOO], [AC_COMPILE_IFELSE([@dots{}])]) 26048 AC_DEFUN([BAR], [ 26049 foobar= 26050 AC_PROG_CC 26051 FOO 26052 ]) 26053 BAR 26054 @end example 26055 26056 @noindent 26057 With older versions of Autoconf, the setting of @samp{foobar=} occurs 26058 before the single compiler check, as the author intended. But with 26059 Autoconf 2.64, this issues the ``expanded before it was required'' 26060 warning for @code{AC_PROG_CC}, and outputs two copies of the compiler 26061 check, one before @samp{foobar=}, and one after. To understand why this 26062 is happening, remember that the use of @code{AC_COMPILE_IFELSE} includes 26063 a call to @code{AC_REQUIRE([AC_PROG_CC])} under the hood. According to 26064 the 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 26067 use of @samp{foobar=}. The older versions of Autoconf were broken with 26068 regards to the rules of @code{AC_REQUIRE}, which explains why the code 26069 changed from one over to two copies of @code{AC_PROG_CC} when upgrading 26070 autoconf. In other words, the author was unknowingly relying on a bug 26071 exploit to get the desired results, and that exploit broke once the bug 26072 was fixed. 26073 26074 So, what recourse does the author have, to restore their intended 26075 semantics of setting @samp{foobar=} prior to a single compiler check, 26076 regardless of whether Autoconf 2.63 or 2.64 is used? One idea is to 26077 remember that only @code{AC_DEFUN} is impacted by @code{AC_REQUIRE}; 26078 there is always the possibility of using the lower-level 26079 @code{m4_define}: 26080 26081 @example 26082 AC_DEFUN([FOO], [AC_COMPILE_IFELSE([@dots{}])]) 26083 m4_define([BAR], [ 26084 foobar= 26085 AC_PROG_CC 26086 FOO 26087 ]) 26088 BAR 26089 @end example 26090 26091 @noindent 26092 This works great if everything is in the same file. However, it does 26093 not help in the case where the author wants to have @command{aclocal} 26094 find the definition of @code{BAR} from its own file, since 26095 @command{aclocal} requires the use of @code{AC_DEFUN}. In this case, a 26096 better fix is to recognize that if @code{BAR} also uses 26097 @code{AC_REQUIRE}, then there will no longer be direct expansion prior 26098 to a subsequent require. Then, by creating yet another helper macro, 26099 the author can once again guarantee a single invocation of 26100 @code{AC_PROG_CC}, which will still occur after @code{foobar=}. The 26101 author can also use @code{AC_BEFORE} to make sure no other macro 26102 appearing before @code{BAR} has triggered an unwanted expansion of 26103 @code{AC_PROG_CC}. 26104 26105 @example 26106 AC_DEFUN([FOO], [AC_COMPILE_IFELSE([@dots{}])]) 26107 AC_DEFUN([BEFORE_CC], [ 26108 foobar= 26109 ]) 26110 AC_DEFUN([BAR], [ 26111 AC_BEFORE([$0], [AC_PROG_CC])dnl 26112 AC_REQUIRE([BEFORE_CC])dnl 26113 AC_REQUIRE([AC_PROG_CC])dnl 26114 FOO 26115 ]) 26116 BAR 26117 @end example 26118 26119 26120 @node Debugging 26121 @section Debugging @command{configure} scripts 26122 26123 While in general, @command{configure} scripts generated by Autoconf 26124 strive to be fairly portable to various systems, compilers, shells, and 26125 other tools, it may still be necessary to debug a failing test, broken 26126 script or makefile, or fix or override an incomplete, faulty, or erroneous 26127 test, especially during macro development. Failures can occur at all levels, 26128 in M4 syntax or semantics, shell script issues, or due to bugs in the 26129 test or the tools invoked by @command{configure}. Together with the 26130 rather arcane error message that @command{m4} and @command{make} may 26131 produce when their input contains syntax errors, this can make debugging 26132 rather painful. 26133 26134 Nevertheless, here is a list of hints and strategies that may help: 26135 26136 @itemize 26137 @item 26138 When @command{autoconf} fails, common causes for error include: 26139 26140 @itemize 26141 @item 26142 mismatched or unbalanced parentheses or braces (@pxref{Balancing 26143 Parentheses}), 26144 26145 @item under- or overquoted macro arguments (@pxref{Autoconf 26146 Language}, @pxref{Quoting and Parameters}, @pxref{Quotation and Nested 26147 Macros}), 26148 26149 @item spaces between macro name and opening parenthesis (@pxref{Autoconf 26150 Language}). 26151 @end itemize 26152 26153 Typically, it helps to go back to the last working version of the input 26154 and compare the differences for each of these errors. Another 26155 possibility is to sprinkle pairs of @code{m4_traceon} and 26156 @code{m4_traceoff} judiciously in the code, either without a parameter 26157 or listing some macro names and watch @command{m4} expand its input 26158 verbosely (@pxref{Debugging via autom4te}). 26159 26160 @item 26161 Sometimes @command{autoconf} succeeds but the generated 26162 @command{configure} script has invalid shell syntax. You can detect this 26163 case by running @samp{bash -n configure} or @samp{sh -n configure}. 26164 If this command fails, the same tips apply, as if @command{autoconf} had 26165 failed. 26166 26167 @item 26168 Debugging @command{configure} script execution may be done by sprinkling 26169 pairs of @code{set -x} and @code{set +x} into the shell script before 26170 and 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 26173 search for markers like @samp{checking for} a particular test in the 26174 @var{log-file}. 26175 26176 @item 26177 Alternatively, you might use a shell with debugging capabilities like 26178 @uref{http://bashdb.sourceforge.net/, bashdb}. 26179 26180 @item 26181 When @command{configure} tests produce invalid results for your system, 26182 it may be necessary to override them: 26183 26184 @itemize 26185 @item 26186 For programs, tools or libraries variables, preprocessor, compiler, or 26187 linker flags, it is often sufficient to override them at @command{make} 26188 run time with some care (@pxref{Macros and Submakes}). Since this 26189 normally won't cause @command{configure} to be run again with these 26190 changed settings, it may fail if the changed variable would have caused 26191 different test results from @command{configure}, so this may work only 26192 for simple differences. 26193 26194 @item 26195 Most tests which produce their result in a substituted variable allow to 26196 override the test by setting the variable on the @command{configure} 26197 command line (@pxref{Compilers and Options}, @pxref{Defining Variables}, 26198 @pxref{Particular Systems}). 26199 26200 @item 26201 Many tests store their result in a cache variable (@pxref{Caching 26202 Results}). This lets you override them either on the 26203 @command{configure} command line as above, or through a primed cache or 26204 site file (@pxref{Cache Files}, @pxref{Site Defaults}). The name of a 26205 cache variable is documented with a test macro or may be inferred from 26206 @ref{Cache Variable Names}; the precise semantics of undocumented 26207 variables are often internal details, subject to change. 26208 @end itemize 26209 26210 @item 26211 Alternatively, @command{configure} may produce invalid results because 26212 of uncaught programming errors, in your package or in an upstream 26213 library package. For example, when @code{AC_CHECK_LIB} fails to find a 26214 library with a specified function, always check @file{config.log}. This 26215 will reveal the exact error that produced the failing result: the 26216 library linked by @code{AC_CHECK_LIB} probably has a fatal bug. 26217 @end itemize 26218 26219 Conversely, as macro author, you can make it easier for users of your 26220 macro: 26221 26222 @itemize 26223 @item 26224 by minimizing dependencies between tests and between test results as far 26225 as possible, 26226 26227 @item 26228 by using @command{make} variables to factorize and allow 26229 override of settings at @command{make} run time, 26230 26231 @item 26232 by honoring the GNU Coding Standards and not overriding flags 26233 reserved for the user except temporarily during @command{configure} 26234 tests, 26235 26236 @item 26237 by not requiring users of your macro to use the cache variables. 26238 Instead, 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, 26240 then 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 26252 You may be wondering, Why was Autoconf originally written? How did it 26253 get into its present form? (Why does it look like gorilla spit?) If 26254 you're not wondering, then this chapter contains no information useful 26255 to you, and you might as well skip it. If you @emph{are} wondering, 26256 then 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 26269 In June 1991 I was maintaining many of the GNU utilities for the 26270 Free Software Foundation. As they were ported to more platforms and 26271 more programs were added, the number of @option{-D} options that users 26272 had to select in the makefile (around 20) became burdensome. 26273 Especially for me---I had to test each new release on a bunch of 26274 different systems. So I wrote a little shell script to guess some of 26275 the correct settings for the fileutils package, and released it as part 26276 of fileutils 2.0. That @command{configure} script worked well enough that 26277 the next month I adapted it (by hand) to create similar @command{configure} 26278 scripts for several other GNU utilities packages. Brian Berliner 26279 also adapted one of my scripts for his CVS revision control system. 26280 26281 Later that summer, I learned that Richard Stallman and Richard Pixley 26282 were developing similar scripts to use in the GNU compiler tools; 26283 so I adapted my @command{configure} scripts to support their evolving 26284 interface: using the file name @file{Makefile.in} as the templates; 26285 adding @samp{+srcdir}, the first option (of many); and creating 26286 @file{config.status} files. 26287 26288 @node Exodus 26289 @section Exodus 26290 26291 As I got feedback from users, I incorporated many improvements, using 26292 Emacs to search and replace, cut and paste, similar changes in each of 26293 the scripts. As I adapted more GNU utilities packages to use 26294 @command{configure} scripts, updating them all by hand became impractical. 26295 Rich Murphey, the maintainer of the GNU graphics utilities, sent me 26296 mail saying that the @command{configure} scripts were great, and asking if 26297 I had a tool for generating them that I could send him. No, I thought, 26298 but I should! So I started to work out how to generate them. And the 26299 journey from the slavery of hand-written @command{configure} scripts to the 26300 abundance and ease of Autoconf began. 26301 26302 Cygnus @command{configure}, which was being developed at around that time, 26303 is table driven; it is meant to deal mainly with a discrete number of 26304 system types with a small number of mainly unguessable features (such as 26305 details of the object file format). The automatic configuration system 26306 that Brian Fox had developed for Bash takes a similar approach. For 26307 general use, it seems to me a hopeless cause to try to maintain an 26308 up-to-date database of which features each variant of each operating 26309 system has. It's easier and more reliable to check for most features on 26310 the fly---especially on hybrid systems that people have hacked on 26311 locally or that have patches from vendors installed. 26312 26313 I considered using an architecture similar to that of Cygnus 26314 @command{configure}, where there is a single @command{configure} script that 26315 reads pieces of @file{configure.in} when run. But I didn't want to have 26316 to distribute all of the feature tests with every package, so I settled 26317 on having a different @command{configure} made from each 26318 @file{configure.in} by a preprocessor. That approach also offered more 26319 control and flexibility. 26320 26321 I looked briefly into using the Metaconfig package, by Larry Wall, 26322 Harlan Stenn, and Raphael Manfredi, but I decided not to for several 26323 reasons. The @command{Configure} scripts it produces are interactive, 26324 which I find quite inconvenient; I didn't like the ways it checked for 26325 some features (such as library functions); I didn't know that it was 26326 still being maintained, and the @command{Configure} scripts I had 26327 seen didn't work on many modern systems (such as System V R4 and NeXT); 26328 it wasn't flexible in what it could do in response to a feature's 26329 presence or absence; I found it confusing to learn; and it was too big 26330 and complex for my needs (I didn't realize then how much Autoconf would 26331 eventually have to grow). 26332 26333 I considered using Perl to generate my style of @command{configure} 26334 scripts, but decided that M4 was better suited to the job of simple 26335 textual substitutions: it gets in the way less, because output is 26336 implicit. Plus, everyone already has it. (Initially I didn't rely on 26337 the GNU extensions to M4.) Also, some of my friends at the 26338 University of Maryland had recently been putting M4 front ends on 26339 several programs, including @code{tvtwm}, and I was interested in trying 26340 out a new language. 26341 26342 @node Leviticus 26343 @section Leviticus 26344 26345 Since my @command{configure} scripts determine the system's capabilities 26346 automatically, with no interactive user intervention, I decided to call 26347 the program that generates them Autoconfig. But with a version number 26348 tacked on, that name would be too long for old Unix file systems, 26349 so I shortened it to Autoconf. 26350 26351 In the fall of 1991 I called together a group of fellow questers after 26352 the Holy Grail of portability (er, that is, alpha testers) to give me 26353 feedback as I encapsulated pieces of my handwritten scripts in M4 macros 26354 and continued to add features and improve the techniques used in the 26355 checks. Prominent among the testers were Fran@,{c}ois Pinard, who came up 26356 with the idea of making an Autoconf shell script to run M4 26357 and check for unresolved macro calls; Richard Pixley, who suggested 26358 running the compiler instead of searching the file system to find 26359 include files and symbols, for more accurate results; Karl Berry, who 26360 got Autoconf to configure @TeX{} and added the macro index to the 26361 documentation; and Ian Lance Taylor, who added support for creating a C 26362 header file as an alternative to putting @option{-D} options in a 26363 makefile, so he could use Autoconf for his UUCP package. 26364 The alpha testers cheerfully adjusted their files again and again as the 26365 names and calling conventions of the Autoconf macros changed from 26366 release to release. They all contributed many specific checks, great 26367 ideas, and bug fixes. 26368 26369 @node Numbers 26370 @section Numbers 26371 26372 In July 1992, after months of alpha testing, I released Autoconf 1.0, 26373 and converted many GNU packages to use it. I was surprised by how 26374 positive the reaction to it was. More people started using it than I 26375 could keep track of, including people working on software that wasn't 26376 part of the GNU Project (such as TCL, FSP, and Kerberos V5). 26377 Autoconf continued to improve rapidly, as many people using the 26378 @command{configure} scripts reported problems they encountered. 26379 26380 Autoconf turned out to be a good torture test for M4 implementations. 26381 Unix M4 started to dump core because of the length of the 26382 macros that Autoconf defined, and several bugs showed up in GNU 26383 M4 as well. Eventually, we realized that we needed to use some 26384 features that only GNU M4 has. 4.3BSD M4, in 26385 particular, has an impoverished set of builtin macros; the System V 26386 version is better, but still doesn't provide everything we need. 26387 26388 More development occurred as people put Autoconf under more stresses 26389 (and to uses I hadn't anticipated). Karl Berry added checks for X11. 26390 david zuhn contributed C++ support. Fran@,{c}ois Pinard made it diagnose 26391 invalid arguments. Jim Blandy bravely coerced it into configuring 26392 GNU Emacs, laying the groundwork for several later improvements. 26393 Roland McGrath got it to configure the GNU C Library, wrote the 26394 @command{autoheader} script to automate the creation of C header file 26395 templates, and added a @option{--verbose} option to @command{configure}. 26396 Noah 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 26399 Autoconf''.) Roland and Noah improved the quoting protection in 26400 @code{AC_DEFINE} and fixed many bugs, especially when I got sick of 26401 dealing with portability problems from February through June, 1993. 26402 26403 @node Deuteronomy 26404 @section Deuteronomy 26405 26406 A long wish list for major features had accumulated, and the effect of 26407 several years of patching by various people had left some residual 26408 cruft. In April 1994, while working for Cygnus Support, I began a major 26409 revision of Autoconf. I added most of the features of the Cygnus 26410 @command{configure} that Autoconf had lacked, largely by adapting the 26411 relevant parts of Cygnus @command{configure} with the help of david zuhn 26412 and 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} 26415 scripts in subdirectories. Adding these features enabled Ken to convert 26416 GNU @code{as}, and Rob Savoye to convert DejaGNU, to using 26417 Autoconf. 26418 26419 I added more features in response to other peoples' requests. Many 26420 people had asked for @command{configure} scripts to share the results of 26421 the checks between runs, because (particularly when configuring a large 26422 source tree, like Cygnus does) they were frustratingly slow. Mike 26423 Haertel suggested adding site-specific initialization scripts. People 26424 distributing software that had to unpack on MS-DOS asked for a way to 26425 override the @file{.in} extension on the file names, which produced file 26426 names like @file{config.h.in} containing two dots. Jim Avera did an 26427 extensive examination of the problems with quoting in @code{AC_DEFINE} 26428 and @code{AC_SUBST}; his insights led to significant improvements. 26429 Richard Stallman asked that compiler output be sent to @file{config.log} 26430 instead of @file{/dev/null}, to help people debug the Emacs 26431 @command{configure} script. 26432 26433 I made some other changes because of my dissatisfaction with the quality 26434 of the program. I made the messages showing results of the checks less 26435 ambiguous, always printing a result. I regularized the names of the 26436 macros and cleaned up coding style inconsistencies. I added some 26437 auxiliary utilities that I had developed to help convert source code 26438 packages to use Autoconf. With the help of Fran@,{c}ois Pinard, I made 26439 the macros not interrupt each others' messages. (That feature revealed 26440 some performance bottlenecks in GNU M4, which he hastily 26441 corrected!) I reorganized the documentation around problems people want 26442 to solve. And I began a test suite, because experience had shown that 26443 Autoconf has a pronounced tendency to regress when we change it. 26444 26445 Again, several alpha testers gave invaluable feedback, especially 26446 Fran@,{c}ois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn, 26447 and Mark Eichin. 26448 26449 Finally, version 2.0 was ready. And there was much rejoicing. (And I 26450 have 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 26479 This is an alphabetical list of the environment variables that might 26480 influence Autoconf checks. 26481 26482 @printindex ev 26483 26484 @node Output Variable Index 26485 @appendixsec Output Variable Index 26486 26487 This is an alphabetical list of the variables that Autoconf can 26488 substitute into files that it creates, typically one or more 26489 makefiles. @xref{Setting Output Variables}, for more information 26490 on how this is done. 26491 26492 @printindex ov 26493 26494 @node Preprocessor Symbol Index 26495 @appendixsec Preprocessor Symbol Index 26496 26497 This is an alphabetical list of the C preprocessor symbols that the 26498 Autoconf macros define. To work with Autoconf, C source code needs to 26499 use 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 26506 This is an alphabetical list of documented cache variables used 26507 by macros defined in Autoconf. Autoconf macros may use additional cache 26508 variables internally. 26509 @ifset shortindexflag 26510 To make the list easier to use, the variables are listed without their 26511 preceding @samp{ac_cv_}. 26512 @end ifset 26513 26514 @printindex CA 26515 26516 @node Autoconf Macro Index 26517 @appendixsec Autoconf Macro Index 26518 26519 This is an alphabetical list of the Autoconf macros. 26520 @ifset shortindexflag 26521 To make the list easier to use, the macros are listed without their 26522 preceding @samp{AC_}. 26523 @end ifset 26524 26525 @printindex AC 26526 26527 @node M4 Macro Index 26528 @appendixsec M4 Macro Index 26529 26530 This is an alphabetical list of the M4, M4sugar, and M4sh macros. 26531 @ifset shortindexflag 26532 To make the list easier to use, the macros are listed without their 26533 preceding @samp{m4_} or @samp{AS_}. The prefix is @samp{m4_} for 26534 all-lowercase macro names and @samp{AS_} for all-uppercase macro 26535 names. 26536 @end ifset 26537 26538 @printindex MS 26539 26540 @node Autotest Macro Index 26541 @appendixsec Autotest Macro Index 26542 26543 This is an alphabetical list of the Autotest macros. 26544 @ifset shortindexflag 26545 To make the list easier to use, the macros are listed without their 26546 preceding @samp{AT_}. 26547 @end ifset 26548 26549 @printindex AT 26550 26551 @node Program & Function Index 26552 @appendixsec Program and Function Index 26553 26554 This is an alphabetical list of the programs and functions whose 26555 portability is discussed in this document. 26556 26557 @printindex pr 26558 26559 @node Concept Index 26560 @appendixsec Concept Index 26561 26562 This is an alphabetical list of the files, tools, and concepts 26563 introduced 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
Indexes created Tue Mar 03 05:31:39 UTC 2026