1This is autoconf.info, produced by makeinfo version 4.13 from 2autoconf.texi. 3 4This manual (24 April 2012) is for GNU Autoconf (version 2.69), a 5package for creating scripts to configure source code packages using 6templates and an M4 macro package. 7 8 Copyright (C) 1992-1996, 1998-2012 Free Software Foundation, Inc. 9 10 Permission is granted to copy, distribute and/or modify this 11 document under the terms of the GNU Free Documentation License, 12 Version 1.3 or any later version published by the Free Software 13 Foundation; with no Invariant Sections, no Front-Cover texts, and 14 no Back-Cover Texts. A copy of the license is included in the 15 section entitled "GNU Free Documentation License." 16 17INFO-DIR-SECTION Software development 18START-INFO-DIR-ENTRY 19* Autoconf: (autoconf). Create source code configuration scripts. 20END-INFO-DIR-ENTRY 21 22INFO-DIR-SECTION Individual utilities 23START-INFO-DIR-ENTRY 24* autoscan: (autoconf)autoscan Invocation. 25 Semi-automatic `configure.ac' writing 26* ifnames: (autoconf)ifnames Invocation. Listing conditionals in source. 27* autoconf-invocation: (autoconf)autoconf Invocation. 28 How to create configuration scripts 29* autoreconf: (autoconf)autoreconf Invocation. 30 Remaking multiple `configure' scripts 31* autoheader: (autoconf)autoheader Invocation. 32 How to create configuration templates 33* autom4te: (autoconf)autom4te Invocation. 34 The Autoconf executables backbone 35* configure: (autoconf)configure Invocation. Configuring a package. 36* autoupdate: (autoconf)autoupdate Invocation. 37 Automatic update of `configure.ac' 38* config.status: (autoconf)config.status Invocation. Recreating configurations. 39* testsuite: (autoconf)testsuite Invocation. Running an Autotest test suite. 40END-INFO-DIR-ENTRY 41 42 43File: autoconf.info, Node: Top, Next: Introduction, Up: (dir) 44 45Autoconf 46******** 47 48This manual (24 April 2012) is for GNU Autoconf (version 2.69), a 49package for creating scripts to configure source code packages using 50templates and an M4 macro package. 51 52 Copyright (C) 1992-1996, 1998-2012 Free Software Foundation, Inc. 53 54 Permission is granted to copy, distribute and/or modify this 55 document under the terms of the GNU Free Documentation License, 56 Version 1.3 or any later version published by the Free Software 57 Foundation; with no Invariant Sections, no Front-Cover texts, and 58 no Back-Cover Texts. A copy of the license is included in the 59 section entitled "GNU Free Documentation License." 60 61* Menu: 62 63* Introduction:: Autoconf's purpose, strengths, and weaknesses 64* The GNU Build System:: A set of tools for portable software packages 65* Making configure Scripts:: How to organize and produce Autoconf scripts 66* Setup:: Initialization and output 67* Existing Tests:: Macros that check for particular features 68* Writing Tests:: How to write new feature checks 69* Results:: What to do with results from feature checks 70* Programming in M4:: Layers on top of which Autoconf is written 71* Programming in M4sh:: Shell portability layer 72* Writing Autoconf Macros:: Adding new macros to Autoconf 73* Portable Shell:: Shell script portability pitfalls 74* Portable Make:: Makefile portability pitfalls 75* Portable C and C++:: C and C++ portability pitfalls 76* Manual Configuration:: Selecting features that can't be guessed 77* Site Configuration:: Local defaults for `configure' 78* Running configure Scripts:: How to use the Autoconf output 79* config.status Invocation:: Recreating a configuration 80* Obsolete Constructs:: Kept for backward compatibility 81* Using Autotest:: Creating portable test suites 82* FAQ:: Frequent Autoconf Questions, with answers 83* History:: History of Autoconf 84* GNU Free Documentation License:: License for copying this manual 85* Indices:: Indices of symbols, concepts, etc. 86 87 --- The Detailed Node Listing --- 88 89The GNU Build System 90 91* Automake:: Escaping makefile hell 92* Gnulib:: The GNU portability library 93* Libtool:: Building libraries portably 94* Pointers:: More info on the GNU build system 95 96Making `configure' Scripts 97 98* Writing Autoconf Input:: What to put in an Autoconf input file 99* autoscan Invocation:: Semi-automatic `configure.ac' writing 100* ifnames Invocation:: Listing the conditionals in source code 101* autoconf Invocation:: How to create configuration scripts 102* autoreconf Invocation:: Remaking multiple `configure' scripts 103 104Writing `configure.ac' 105 106* Shell Script Compiler:: Autoconf as solution of a problem 107* Autoconf Language:: Programming in Autoconf 108* Autoconf Input Layout:: Standard organization of `configure.ac' 109 110Initialization and Output Files 111 112* Initializing configure:: Option processing etc. 113* Versioning:: Dealing with Autoconf versions 114* Notices:: Copyright, version numbers in `configure' 115* Input:: Where Autoconf should find files 116* Output:: Outputting results from the configuration 117* Configuration Actions:: Preparing the output based on results 118* Configuration Files:: Creating output files 119* Makefile Substitutions:: Using output variables in makefiles 120* Configuration Headers:: Creating a configuration header file 121* Configuration Commands:: Running arbitrary instantiation commands 122* Configuration Links:: Links depending on the configuration 123* Subdirectories:: Configuring independent packages together 124* Default Prefix:: Changing the default installation prefix 125 126Substitutions in Makefiles 127 128* Preset Output Variables:: Output variables that are always set 129* Installation Directory Variables:: Other preset output variables 130* Changed Directory Variables:: Warnings about `datarootdir' 131* Build Directories:: Supporting multiple concurrent compiles 132* Automatic Remaking:: Makefile rules for configuring 133 134Configuration Header Files 135 136* Header Templates:: Input for the configuration headers 137* autoheader Invocation:: How to create configuration templates 138* Autoheader Macros:: How to specify CPP templates 139 140Existing Tests 141 142* Common Behavior:: Macros' standard schemes 143* Alternative Programs:: Selecting between alternative programs 144* Files:: Checking for the existence of files 145* Libraries:: Library archives that might be missing 146* Library Functions:: C library functions that might be missing 147* Header Files:: Header files that might be missing 148* Declarations:: Declarations that may be missing 149* Structures:: Structures or members that might be missing 150* Types:: Types that might be missing 151* Compilers and Preprocessors:: Checking for compiling programs 152* System Services:: Operating system services 153* Posix Variants:: Special kludges for specific Posix variants 154* Erlang Libraries:: Checking for the existence of Erlang libraries 155 156Common Behavior 157 158* Standard Symbols:: Symbols defined by the macros 159* Default Includes:: Includes used by the generic macros 160 161Alternative Programs 162 163* Particular Programs:: Special handling to find certain programs 164* Generic Programs:: How to find other programs 165 166Library Functions 167 168* Function Portability:: Pitfalls with usual functions 169* Particular Functions:: Special handling to find certain functions 170* Generic Functions:: How to find other functions 171 172Header Files 173 174* Header Portability:: Collected knowledge on common headers 175* Particular Headers:: Special handling to find certain headers 176* Generic Headers:: How to find other headers 177 178Declarations 179 180* Particular Declarations:: Macros to check for certain declarations 181* Generic Declarations:: How to find other declarations 182 183Structures 184 185* Particular Structures:: Macros to check for certain structure members 186* Generic Structures:: How to find other structure members 187 188Types 189 190* Particular Types:: Special handling to find certain types 191* Generic Types:: How to find other types 192 193Compilers and Preprocessors 194 195* Specific Compiler Characteristics:: Some portability issues 196* Generic Compiler Characteristics:: Language independent tests and features 197* C Compiler:: Checking its characteristics 198* C++ Compiler:: Likewise 199* Objective C Compiler:: Likewise 200* Objective C++ Compiler:: Likewise 201* Erlang Compiler and Interpreter:: Likewise 202* Fortran Compiler:: Likewise 203* Go Compiler:: Likewise 204 205Writing Tests 206 207* Language Choice:: Selecting which language to use for testing 208* Writing Test Programs:: Forging source files for compilers 209* Running the Preprocessor:: Detecting preprocessor symbols 210* Running the Compiler:: Detecting language or header features 211* Running the Linker:: Detecting library features 212* Runtime:: Testing for runtime features 213* Systemology:: A zoology of operating systems 214* Multiple Cases:: Tests for several possible values 215 216Writing Test Programs 217 218* Guidelines:: General rules for writing test programs 219* Test Functions:: Avoiding pitfalls in test programs 220* Generating Sources:: Source program boilerplate 221 222Results of Tests 223 224* Defining Symbols:: Defining C preprocessor symbols 225* Setting Output Variables:: Replacing variables in output files 226* Special Chars in Variables:: Characters to beware of in variables 227* Caching Results:: Speeding up subsequent `configure' runs 228* Printing Messages:: Notifying `configure' users 229 230Caching Results 231 232* Cache Variable Names:: Shell variables used in caches 233* Cache Files:: Files `configure' uses for caching 234* Cache Checkpointing:: Loading and saving the cache file 235 236Programming in M4 237 238* M4 Quotation:: Protecting macros from unwanted expansion 239* Using autom4te:: The Autoconf executables backbone 240* Programming in M4sugar:: Convenient pure M4 macros 241* Debugging via autom4te:: Figuring out what M4 was doing 242 243M4 Quotation 244 245* Active Characters:: Characters that change the behavior of M4 246* One Macro Call:: Quotation and one macro call 247* Quoting and Parameters:: M4 vs. shell parameters 248* Quotation and Nested Macros:: Macros calling macros 249* Changequote is Evil:: Worse than INTERCAL: M4 + changequote 250* Quadrigraphs:: Another way to escape special characters 251* Balancing Parentheses:: Dealing with unbalanced parentheses 252* Quotation Rule Of Thumb:: One parenthesis, one quote 253 254Using `autom4te' 255 256* autom4te Invocation:: A GNU M4 wrapper 257* Customizing autom4te:: Customizing the Autoconf package 258 259Programming in M4sugar 260 261* Redefined M4 Macros:: M4 builtins changed in M4sugar 262* Diagnostic Macros:: Diagnostic messages from M4sugar 263* Diversion support:: Diversions in M4sugar 264* Conditional constructs:: Conditions in M4 265* Looping constructs:: Iteration in M4 266* Evaluation Macros:: More quotation and evaluation control 267* Text processing Macros:: String manipulation in M4 268* Number processing Macros:: Arithmetic computation in M4 269* Set manipulation Macros:: Set manipulation in M4 270* Forbidden Patterns:: Catching unexpanded macros 271 272Programming in M4sh 273 274* Common Shell Constructs:: Portability layer for common shell constructs 275* Polymorphic Variables:: Support for indirect variable names 276* Initialization Macros:: Macros to establish a sane shell environment 277* File Descriptor Macros:: File descriptor macros for input and output 278 279Writing Autoconf Macros 280 281* Macro Definitions:: Basic format of an Autoconf macro 282* Macro Names:: What to call your new macros 283* Reporting Messages:: Notifying `autoconf' users 284* Dependencies Between Macros:: What to do when macros depend on other macros 285* Obsoleting Macros:: Warning about old ways of doing things 286* Coding Style:: Writing Autoconf macros a` la Autoconf 287 288Dependencies Between Macros 289 290* Prerequisite Macros:: Ensuring required information 291* Suggested Ordering:: Warning about possible ordering problems 292* One-Shot Macros:: Ensuring a macro is called only once 293 294Portable Shell Programming 295 296* Shellology:: A zoology of shells 297* Invoking the Shell:: Invoking the shell as a command 298* Here-Documents:: Quirks and tricks 299* File Descriptors:: FDs and redirections 300* Signal Handling:: Shells, signals, and headaches 301* File System Conventions:: File names 302* Shell Pattern Matching:: Pattern matching 303* Shell Substitutions:: Variable and command expansions 304* Assignments:: Varying side effects of assignments 305* Parentheses:: Parentheses in shell scripts 306* Slashes:: Slashes in shell scripts 307* Special Shell Variables:: Variables you should not change 308* Shell Functions:: What to look out for if you use them 309* Limitations of Builtins:: Portable use of not so portable /bin/sh 310* Limitations of Usual Tools:: Portable use of portable tools 311 312Portable Make Programming 313 314* $< in Ordinary Make Rules:: $< in ordinary rules 315* Failure in Make Rules:: Failing portably in rules 316* Special Chars in Names:: Special Characters in Macro Names 317* Backslash-Newline-Empty:: Empty lines after backslash-newline 318* Backslash-Newline Comments:: Spanning comments across line boundaries 319* Long Lines in Makefiles:: Line length limitations 320* Macros and Submakes:: `make macro=value' and submakes 321* The Make Macro MAKEFLAGS:: `$(MAKEFLAGS)' portability issues 322* The Make Macro SHELL:: `$(SHELL)' portability issues 323* Parallel Make:: Parallel `make' quirks 324* Comments in Make Rules:: Other problems with Make comments 325* Newlines in Make Rules:: Using literal newlines in rules 326* Comments in Make Macros:: Other problems with Make comments in macros 327* Trailing whitespace in Make Macros:: Macro substitution problems 328* Command-line Macros and whitespace:: Whitespace trimming of values 329* obj/ and Make:: Don't name a subdirectory `obj' 330* make -k Status:: Exit status of `make -k' 331* VPATH and Make:: `VPATH' woes 332* Single Suffix Rules:: Single suffix rules and separated dependencies 333* Timestamps and Make:: Subsecond timestamp resolution 334 335`VPATH' and Make 336 337* Variables listed in VPATH:: `VPATH' must be literal on ancient hosts 338* VPATH and Double-colon:: Problems with `::' on ancient hosts 339* $< in Explicit Rules:: `$<' does not work in ordinary rules 340* Automatic Rule Rewriting:: `VPATH' goes wild on Solaris 341* Tru64 Directory Magic:: `mkdir' goes wild on Tru64 342* Make Target Lookup:: More details about `VPATH' lookup 343 344Portable C and C++ Programming 345 346* Varieties of Unportability:: How to make your programs unportable 347* Integer Overflow:: When integers get too large 348* Preprocessor Arithmetic:: `#if' expression problems 349* Null Pointers:: Properties of null pointers 350* Buffer Overruns:: Subscript errors and the like 351* Volatile Objects:: `volatile' and signals 352* Floating Point Portability:: Portable floating-point arithmetic 353* Exiting Portably:: Exiting and the exit status 354 355Integer Overflow 356 357* Integer Overflow Basics:: Why integer overflow is a problem 358* Signed Overflow Examples:: Examples of code assuming wraparound 359* Optimization and Wraparound:: Optimizations that break uses of wraparound 360* Signed Overflow Advice:: Practical advice for signed overflow issues 361* Signed Integer Division:: `INT_MIN / -1' and `INT_MIN % -1' 362 363Manual Configuration 364 365* Specifying Target Triplets:: Specifying target triplets 366* Canonicalizing:: Getting the canonical system type 367* Using System Type:: What to do with the system type 368 369Site Configuration 370 371* Help Formatting:: Customizing `configure --help' 372* External Software:: Working with other optional software 373* Package Options:: Selecting optional features 374* Pretty Help Strings:: Formatting help string 375* Option Checking:: Controlling checking of `configure' options 376* Site Details:: Configuring site details 377* Transforming Names:: Changing program names when installing 378* Site Defaults:: Giving `configure' local defaults 379 380Transforming Program Names When Installing 381 382* Transformation Options:: `configure' options to transform names 383* Transformation Examples:: Sample uses of transforming names 384* Transformation Rules:: Makefile uses of transforming names 385 386Running `configure' Scripts 387 388* Basic Installation:: Instructions for typical cases 389* Compilers and Options:: Selecting compilers and optimization 390* Multiple Architectures:: Compiling for multiple architectures at once 391* Installation Names:: Installing in different directories 392* Optional Features:: Selecting optional features 393* Particular Systems:: Particular systems 394* System Type:: Specifying the system type 395* Sharing Defaults:: Setting site-wide defaults for `configure' 396* Defining Variables:: Specifying the compiler etc. 397* configure Invocation:: Changing how `configure' runs 398 399Obsolete Constructs 400 401* Obsolete config.status Use:: Obsolete convention for `config.status' 402* acconfig Header:: Additional entries in `config.h.in' 403* autoupdate Invocation:: Automatic update of `configure.ac' 404* Obsolete Macros:: Backward compatibility macros 405* Autoconf 1:: Tips for upgrading your files 406* Autoconf 2.13:: Some fresher tips 407 408Upgrading From Version 1 409 410* Changed File Names:: Files you might rename 411* Changed Makefiles:: New things to put in `Makefile.in' 412* Changed Macros:: Macro calls you might replace 413* Changed Results:: Changes in how to check test results 414* Changed Macro Writing:: Better ways to write your own macros 415 416Upgrading From Version 2.13 417 418* Changed Quotation:: Broken code which used to work 419* New Macros:: Interaction with foreign macros 420* Hosts and Cross-Compilation:: Bugward compatibility kludges 421* AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token 422* AC_ACT_IFELSE vs AC_TRY_ACT:: A more generic scheme for testing sources 423 424Generating Test Suites with Autotest 425 426* Using an Autotest Test Suite:: Autotest and the user 427* Writing Testsuites:: Autotest macros 428* testsuite Invocation:: Running `testsuite' scripts 429* Making testsuite Scripts:: Using autom4te to create `testsuite' 430 431Using an Autotest Test Suite 432 433* testsuite Scripts:: The concepts of Autotest 434* Autotest Logs:: Their contents 435 436Frequent Autoconf Questions, with answers 437 438* Distributing:: Distributing `configure' scripts 439* Why GNU M4:: Why not use the standard M4? 440* Bootstrapping:: Autoconf and GNU M4 require each other? 441* Why Not Imake:: Why GNU uses `configure' instead of Imake 442* Defining Directories:: Passing `datadir' to program 443* Autom4te Cache:: What is it? Can I remove it? 444* Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree 445* Expanded Before Required:: Expanded Before Required 446* Debugging:: Debugging `configure' scripts 447 448History of Autoconf 449 450* Genesis:: Prehistory and naming of `configure' 451* Exodus:: The plagues of M4 and Perl 452* Leviticus:: The priestly code of portability arrives 453* Numbers:: Growth and contributors 454* Deuteronomy:: Approaching the promises of easy configuration 455 456Indices 457 458* Environment Variable Index:: Index of environment variables used 459* Output Variable Index:: Index of variables set in output files 460* Preprocessor Symbol Index:: Index of C preprocessor symbols defined 461* Cache Variable Index:: Index of documented cache variables 462* Autoconf Macro Index:: Index of Autoconf macros 463* M4 Macro Index:: Index of M4, M4sugar, and M4sh macros 464* Autotest Macro Index:: Index of Autotest macros 465* Program & Function Index:: Index of those with portability problems 466* Concept Index:: General index 467 468 469File: autoconf.info, Node: Introduction, Next: The GNU Build System, Prev: Top, Up: Top 470 4711 Introduction 472************** 473 474 A physicist, an engineer, and a computer scientist were discussing the 475 nature of God. "Surely a Physicist," said the physicist, "because 476 early in the Creation, God made Light; and you know, Maxwell's 477 equations, the dual nature of electromagnetic waves, the relativistic 478 consequences..." "An Engineer!," said the engineer, "because 479before making Light, God split the Chaos into Land and Water; it takes a 480 hell of an engineer to handle that big amount of mud, and orderly 481 separation of solids from liquids..." The computer scientist 482 shouted: "And the Chaos, where do you think it was coming from, hmm?" 483 484 --Anonymous 485 486 Autoconf is a tool for producing shell scripts that automatically 487configure software source code packages to adapt to many kinds of 488Posix-like systems. The configuration scripts produced by Autoconf are 489independent of Autoconf when they are run, so their users do not need 490to have Autoconf. 491 492 The configuration scripts produced by Autoconf require no manual user 493intervention when run; they do not normally even need an argument 494specifying the system type. Instead, they individually test for the 495presence of each feature that the software package they are for might 496need. (Before each check, they print a one-line message stating what 497they are checking for, so the user doesn't get too bored while waiting 498for the script to finish.) As a result, they deal well with systems 499that are hybrids or customized from the more common Posix variants. 500There is no need to maintain files that list the features supported by 501each release of each variant of Posix. 502 503 For each software package that Autoconf is used with, it creates a 504configuration script from a template file that lists the system features 505that the package needs or can use. After the shell code to recognize 506and respond to a system feature has been written, Autoconf allows it to 507be shared by many software packages that can use (or need) that feature. 508If it later turns out that the shell code needs adjustment for some 509reason, it needs to be changed in only one place; all of the 510configuration scripts can be regenerated automatically to take advantage 511of the updated code. 512 513 Those who do not understand Autoconf are condemned to reinvent it, 514poorly. The primary goal of Autoconf is making the _user's_ life 515easier; making the _maintainer's_ life easier is only a secondary goal. 516Put another way, the primary goal is not to make the generation of 517`configure' automatic for package maintainers (although patches along 518that front are welcome, since package maintainers form the user base of 519Autoconf); rather, the goal is to make `configure' painless, portable, 520and predictable for the end user of each "autoconfiscated" package. 521And to this degree, Autoconf is highly successful at its goal -- most 522complaints to the Autoconf list are about difficulties in writing 523Autoconf input, and not in the behavior of the resulting `configure'. 524Even packages that don't use Autoconf will generally provide a 525`configure' script, and the most common complaint about these 526alternative home-grown scripts is that they fail to meet one or more of 527the GNU Coding Standards (*note Configuration: 528(standards)Configuration.) that users have come to expect from 529Autoconf-generated `configure' scripts. 530 531 The Metaconfig package is similar in purpose to Autoconf, but the 532scripts it produces require manual user intervention, which is quite 533inconvenient when configuring large source trees. Unlike Metaconfig 534scripts, Autoconf scripts can support cross-compiling, if some care is 535taken in writing them. 536 537 Autoconf does not solve all problems related to making portable 538software packages--for a more complete solution, it should be used in 539concert with other GNU build tools like Automake and Libtool. These 540other tools take on jobs like the creation of a portable, recursive 541makefile with all of the standard targets, linking of shared libraries, 542and so on. *Note The GNU Build System::, for more information. 543 544 Autoconf imposes some restrictions on the names of macros used with 545`#if' in C programs (*note Preprocessor Symbol Index::). 546 547 Autoconf requires GNU M4 version 1.4.6 or later in order to generate 548the scripts. It uses features that some versions of M4, including GNU 549M4 1.3, do not have. Autoconf works better with GNU M4 version 1.4.14 550or later, though this is not required. 551 552 *Note Autoconf 1::, for information about upgrading from version 1. 553*Note History::, for the story of Autoconf's development. *Note FAQ::, 554for answers to some common questions about Autoconf. 555 556 See the Autoconf web page (http://www.gnu.org/software/autoconf/) 557for up-to-date information, details on the mailing lists, pointers to a 558list of known bugs, etc. 559 560 Mail suggestions to the Autoconf mailing list <autoconf@gnu.org>. 561Past suggestions are archived 562(http://lists.gnu.org/archive/html/autoconf/). 563 564 Mail bug reports to the Autoconf Bugs mailing list 565<bug-autoconf@gnu.org>. Past bug reports are archived 566(http://lists.gnu.org/archive/html/bug-autoconf/). 567 568 If possible, first check that your bug is not already solved in 569current development versions, and that it has not been reported yet. 570Be sure to include all the needed information and a short 571`configure.ac' that demonstrates the problem. 572 573 Autoconf's development tree is accessible via `git'; see the 574Autoconf Summary (http://savannah.gnu.org/projects/autoconf/) for 575details, or view the actual repository 576(http://git.sv.gnu.org/gitweb/?p=autoconf.git). Anonymous CVS access 577is also available, see `README' for more details. Patches relative to 578the current `git' version can be sent for review to the Autoconf 579Patches mailing list <autoconf-patches@gnu.org>, with discussion on 580prior patches archived 581(http://lists.gnu.org/archive/html/autoconf-patches/); and all commits 582are posted in the read-only Autoconf Commit mailing list 583<autoconf-commit@gnu.org>, which is also archived 584(http://lists.gnu.org/archive/html/autoconf-commit/). 585 586 Because of its mission, the Autoconf package itself includes only a 587set of often-used macros that have already demonstrated their 588usefulness. Nevertheless, if you wish to share your macros, or find 589existing ones, see the Autoconf Macro Archive 590(http://www.gnu.org/software/autoconf-archive/), which is kindly run by 591Peter Simons <simons@cryp.to>. 592 593 594File: autoconf.info, Node: The GNU Build System, Next: Making configure Scripts, Prev: Introduction, Up: Top 595 5962 The GNU Build System 597********************** 598 599Autoconf solves an important problem--reliable discovery of 600system-specific build and runtime information--but this is only one 601piece of the puzzle for the development of portable software. To this 602end, the GNU project has developed a suite of integrated utilities to 603finish the job Autoconf started: the GNU build system, whose most 604important components are Autoconf, Automake, and Libtool. In this 605chapter, we introduce you to those tools, point you to sources of more 606information, and try to convince you to use the entire GNU build system 607for your software. 608 609* Menu: 610 611* Automake:: Escaping makefile hell 612* Gnulib:: The GNU portability library 613* Libtool:: Building libraries portably 614* Pointers:: More info on the GNU build system 615 616 617File: autoconf.info, Node: Automake, Next: Gnulib, Up: The GNU Build System 618 6192.1 Automake 620============ 621 622The ubiquity of `make' means that a makefile is almost the only viable 623way to distribute automatic build rules for software, but one quickly 624runs into its numerous limitations. Its lack of support for automatic 625dependency tracking, recursive builds in subdirectories, reliable 626timestamps (e.g., for network file systems), and so on, mean that 627developers must painfully (and often incorrectly) reinvent the wheel 628for each project. Portability is non-trivial, thanks to the quirks of 629`make' on many systems. On top of all this is the manual labor 630required to implement the many standard targets that users have come to 631expect (`make install', `make distclean', `make uninstall', etc.). 632Since you are, of course, using Autoconf, you also have to insert 633repetitive code in your `Makefile.in' to recognize `@CC@', `@CFLAGS@', 634and other substitutions provided by `configure'. Into this mess steps 635"Automake". 636 637 Automake allows you to specify your build needs in a `Makefile.am' 638file with a vastly simpler and more powerful syntax than that of a plain 639makefile, and then generates a portable `Makefile.in' for use with 640Autoconf. For example, the `Makefile.am' to build and install a simple 641"Hello world" program might look like: 642 643 bin_PROGRAMS = hello 644 hello_SOURCES = hello.c 645 646The resulting `Makefile.in' (~400 lines) automatically supports all the 647standard targets, the substitutions provided by Autoconf, automatic 648dependency tracking, `VPATH' building, and so on. `make' builds the 649`hello' program, and `make install' installs it in `/usr/local/bin' (or 650whatever prefix was given to `configure', if not `/usr/local'). 651 652 The benefits of Automake increase for larger packages (especially 653ones with subdirectories), but even for small programs the added 654convenience and portability can be substantial. And that's not all... 655 656 657File: autoconf.info, Node: Gnulib, Next: Libtool, Prev: Automake, Up: The GNU Build System 658 6592.2 Gnulib 660========== 661 662GNU software has a well-deserved reputation for running on many 663different types of systems. While our primary goal is to write 664software for the GNU system, many users and developers have been 665introduced to us through the systems that they were already using. 666 667 Gnulib is a central location for common GNU code, intended to be 668shared among free software packages. Its components are typically 669shared at the source level, rather than being a library that gets built, 670installed, and linked against. The idea is to copy files from Gnulib 671into your own source tree. There is no distribution tarball; developers 672should just grab source modules from the repository. The source files 673are available online, under various licenses, mostly GNU GPL or GNU 674LGPL. 675 676 Gnulib modules typically contain C source code along with Autoconf 677macros used to configure the source code. For example, the Gnulib 678`stdbool' module implements a `stdbool.h' header that nearly conforms 679to C99, even on old-fashioned hosts that lack `stdbool.h'. This module 680contains a source file for the replacement header, along with an 681Autoconf macro that arranges to use the replacement header on 682old-fashioned systems. 683 684 685File: autoconf.info, Node: Libtool, Next: Pointers, Prev: Gnulib, Up: The GNU Build System 686 6872.3 Libtool 688=========== 689 690Often, one wants to build not only programs, but libraries, so that 691other programs can benefit from the fruits of your labor. Ideally, one 692would like to produce _shared_ (dynamically linked) libraries, which 693can be used by multiple programs without duplication on disk or in 694memory and can be updated independently of the linked programs. 695Producing shared libraries portably, however, is the stuff of 696nightmares--each system has its own incompatible tools, compiler flags, 697and magic incantations. Fortunately, GNU provides a solution: 698"Libtool". 699 700 Libtool handles all the requirements of building shared libraries for 701you, and at this time seems to be the _only_ way to do so with any 702portability. It also handles many other headaches, such as: the 703interaction of Make rules with the variable suffixes of shared 704libraries, linking reliably with shared libraries before they are 705installed by the superuser, and supplying a consistent versioning system 706(so that different versions of a library can be installed or upgraded 707without breaking binary compatibility). Although Libtool, like 708Autoconf, can be used without Automake, it is most simply utilized in 709conjunction with Automake--there, Libtool is used automatically 710whenever shared libraries are needed, and you need not know its syntax. 711 712 713File: autoconf.info, Node: Pointers, Prev: Libtool, Up: The GNU Build System 714 7152.4 Pointers 716============ 717 718Developers who are used to the simplicity of `make' for small projects 719on a single system might be daunted at the prospect of learning to use 720Automake and Autoconf. As your software is distributed to more and 721more users, however, you otherwise quickly find yourself putting lots 722of effort into reinventing the services that the GNU build tools 723provide, and making the same mistakes that they once made and overcame. 724(Besides, since you're already learning Autoconf, Automake is a piece 725of cake.) 726 727 There are a number of places that you can go to for more information 728on the GNU build tools. 729 730 - Web 731 732 The project home pages for Autoconf 733 (http://www.gnu.org/software/autoconf/), Automake 734 (http://www.gnu.org/software/automake/), Gnulib 735 (http://www.gnu.org/software/gnulib/), and Libtool 736 (http://www.gnu.org/software/libtool/). 737 738 - Automake Manual 739 740 *Note Automake: (automake)Top, for more information on Automake. 741 742 - Books 743 744 The book `GNU Autoconf, Automake and Libtool'(1) describes the 745 complete GNU build environment. You can also find the entire book 746 on-line (http://sources.redhat.com/autobook/). 747 748 749 ---------- Footnotes ---------- 750 751 (1) `GNU Autoconf, Automake and Libtool', by G. V. Vaughan, B. 752Elliston, T. Tromey, and I. L. Taylor. SAMS (originally New Riders), 7532000, ISBN 1578701902. 754 755 756File: autoconf.info, Node: Making configure Scripts, Next: Setup, Prev: The GNU Build System, Up: Top 757 7583 Making `configure' Scripts 759**************************** 760 761The configuration scripts that Autoconf produces are by convention 762called `configure'. When run, `configure' creates several files, 763replacing configuration parameters in them with appropriate values. 764The files that `configure' creates are: 765 766 - one or more `Makefile' files, usually one in each subdirectory of 767 the package (*note Makefile Substitutions::); 768 769 - optionally, a C header file, the name of which is configurable, 770 containing `#define' directives (*note Configuration Headers::); 771 772 - a shell script called `config.status' that, when run, recreates 773 the files listed above (*note config.status Invocation::); 774 775 - an optional shell script normally called `config.cache' (created 776 when using `configure --config-cache') that saves the results of 777 running many of the tests (*note Cache Files::); 778 779 - a file called `config.log' containing any messages produced by 780 compilers, to help debugging if `configure' makes a mistake. 781 782 To create a `configure' script with Autoconf, you need to write an 783Autoconf input file `configure.ac' (or `configure.in') and run 784`autoconf' on it. If you write your own feature tests to supplement 785those that come with Autoconf, you might also write files called 786`aclocal.m4' and `acsite.m4'. If you use a C header file to contain 787`#define' directives, you might also run `autoheader', and you can 788distribute the generated file `config.h.in' with the package. 789 790 Here is a diagram showing how the files that can be used in 791configuration are produced. Programs that are executed are suffixed by 792`*'. Optional files are enclosed in square brackets (`[]'). 793`autoconf' and `autoheader' also read the installed Autoconf macro 794files (by reading `autoconf.m4'). 795 796Files used in preparing a software package for distribution, when using 797just Autoconf: 798 your source files --> [autoscan*] --> [configure.scan] --> configure.ac 799 800 configure.ac --. 801 | .------> autoconf* -----> configure 802 [aclocal.m4] --+---+ 803 | `-----> [autoheader*] --> [config.h.in] 804 [acsite.m4] ---' 805 806 Makefile.in 807 808Additionally, if you use Automake, the following additional productions 809come into play: 810 811 [acinclude.m4] --. 812 | 813 [local macros] --+--> aclocal* --> aclocal.m4 814 | 815 configure.ac ----' 816 817 configure.ac --. 818 +--> automake* --> Makefile.in 819 Makefile.am ---' 820 821Files used in configuring a software package: 822 .-------------> [config.cache] 823 configure* ------------+-------------> config.log 824 | 825 [config.h.in] -. v .-> [config.h] -. 826 +--> config.status* -+ +--> make* 827 Makefile.in ---' `-> Makefile ---' 828 829* Menu: 830 831* Writing Autoconf Input:: What to put in an Autoconf input file 832* autoscan Invocation:: Semi-automatic `configure.ac' writing 833* ifnames Invocation:: Listing the conditionals in source code 834* autoconf Invocation:: How to create configuration scripts 835* autoreconf Invocation:: Remaking multiple `configure' scripts 836 837 838File: autoconf.info, Node: Writing Autoconf Input, Next: autoscan Invocation, Up: Making configure Scripts 839 8403.1 Writing `configure.ac' 841========================== 842 843To produce a `configure' script for a software package, create a file 844called `configure.ac' that contains invocations of the Autoconf macros 845that test the system features your package needs or can use. Autoconf 846macros already exist to check for many features; see *note Existing 847Tests::, for their descriptions. For most other features, you can use 848Autoconf template macros to produce custom checks; see *note Writing 849Tests::, for information about them. For especially tricky or 850specialized features, `configure.ac' might need to contain some 851hand-crafted shell commands; see *note Portable Shell Programming: 852Portable Shell. The `autoscan' program can give you a good start in 853writing `configure.ac' (*note autoscan Invocation::, for more 854information). 855 856 Previous versions of Autoconf promoted the name `configure.in', 857which is somewhat ambiguous (the tool needed to process this file is not 858described by its extension), and introduces a slight confusion with 859`config.h.in' and so on (for which `.in' means "to be processed by 860`configure'"). Using `configure.ac' is now preferred. 861 862* Menu: 863 864* Shell Script Compiler:: Autoconf as solution of a problem 865* Autoconf Language:: Programming in Autoconf 866* Autoconf Input Layout:: Standard organization of `configure.ac' 867 868 869File: autoconf.info, Node: Shell Script Compiler, Next: Autoconf Language, Up: Writing Autoconf Input 870 8713.1.1 A Shell Script Compiler 872----------------------------- 873 874Just as for any other computer language, in order to properly program 875`configure.ac' in Autoconf you must understand _what_ problem the 876language tries to address and _how_ it does so. 877 878 The problem Autoconf addresses is that the world is a mess. After 879all, you are using Autoconf in order to have your package compile 880easily on all sorts of different systems, some of them being extremely 881hostile. Autoconf itself bears the price for these differences: 882`configure' must run on all those systems, and thus `configure' must 883limit itself to their lowest common denominator of features. 884 885 Naturally, you might then think of shell scripts; who needs 886`autoconf'? A set of properly written shell functions is enough to 887make it easy to write `configure' scripts by hand. Sigh! 888Unfortunately, even in 2008, where shells without any function support 889are far and few between, there are pitfalls to avoid when making use of 890them. Also, finding a Bourne shell that accepts shell functions is not 891trivial, even though there is almost always one on interesting porting 892targets. 893 894 So, what is really needed is some kind of compiler, `autoconf', that 895takes an Autoconf program, `configure.ac', and transforms it into a 896portable shell script, `configure'. 897 898 How does `autoconf' perform this task? 899 900 There are two obvious possibilities: creating a brand new language or 901extending an existing one. The former option is attractive: all sorts 902of optimizations could easily be implemented in the compiler and many 903rigorous checks could be performed on the Autoconf program (e.g., 904rejecting any non-portable construct). Alternatively, you can extend 905an existing language, such as the `sh' (Bourne shell) language. 906 907 Autoconf does the latter: it is a layer on top of `sh'. It was 908therefore most convenient to implement `autoconf' as a macro expander: 909a program that repeatedly performs "macro expansions" on text input, 910replacing macro calls with macro bodies and producing a pure `sh' 911script in the end. Instead of implementing a dedicated Autoconf macro 912expander, it is natural to use an existing general-purpose macro 913language, such as M4, and implement the extensions as a set of M4 914macros. 915 916 917File: autoconf.info, Node: Autoconf Language, Next: Autoconf Input Layout, Prev: Shell Script Compiler, Up: Writing Autoconf Input 918 9193.1.2 The Autoconf Language 920--------------------------- 921 922The Autoconf language differs from many other computer languages 923because it treats actual code the same as plain text. Whereas in C, 924for instance, data and instructions have different syntactic status, in 925Autoconf their status is rigorously the same. Therefore, we need a 926means to distinguish literal strings from text to be expanded: 927quotation. 928 929 When calling macros that take arguments, there must not be any white 930space between the macro name and the open parenthesis. 931 932 AC_INIT ([oops], [1.0]) # incorrect 933 AC_INIT([hello], [1.0]) # good 934 935 Arguments should be enclosed within the quote characters `[' and 936`]', and be separated by commas. Any leading blanks or newlines in 937arguments are ignored, unless they are quoted. You should always quote 938an argument that might contain a macro name, comma, parenthesis, or a 939leading blank or newline. This rule applies recursively for every macro 940call, including macros called from other macros. For more details on 941quoting rules, see *note Programming in M4::. 942 943 For instance: 944 945 AC_CHECK_HEADER([stdio.h], 946 [AC_DEFINE([HAVE_STDIO_H], [1], 947 [Define to 1 if you have <stdio.h>.])], 948 [AC_MSG_ERROR([sorry, can't do anything for you])]) 949 950is quoted properly. You may safely simplify its quotation to: 951 952 AC_CHECK_HEADER([stdio.h], 953 [AC_DEFINE([HAVE_STDIO_H], 1, 954 [Define to 1 if you have <stdio.h>.])], 955 [AC_MSG_ERROR([sorry, can't do anything for you])]) 956 957because `1' cannot contain a macro call. Here, the argument of 958`AC_MSG_ERROR' must be quoted; otherwise, its comma would be 959interpreted as an argument separator. Also, the second and third 960arguments of `AC_CHECK_HEADER' must be quoted, since they contain macro 961calls. The three arguments `HAVE_STDIO_H', `stdio.h', and `Define to 1 962if you have <stdio.h>.' do not need quoting, but if you unwisely 963defined a macro with a name like `Define' or `stdio' then they would 964need quoting. Cautious Autoconf users would keep the quotes, but many 965Autoconf users find such precautions annoying, and would rewrite the 966example as follows: 967 968 AC_CHECK_HEADER(stdio.h, 969 [AC_DEFINE(HAVE_STDIO_H, 1, 970 [Define to 1 if you have <stdio.h>.])], 971 [AC_MSG_ERROR([sorry, can't do anything for you])]) 972 973This is safe, so long as you adopt good naming conventions and do not 974define macros with names like `HAVE_STDIO_H', `stdio', or `h'. Though 975it is also safe here to omit the quotes around `Define to 1 if you have 976<stdio.h>.' this is not recommended, as message strings are more likely 977to inadvertently contain commas. 978 979 The following example is wrong and dangerous, as it is underquoted: 980 981 AC_CHECK_HEADER(stdio.h, 982 AC_DEFINE(HAVE_STDIO_H, 1, 983 Define to 1 if you have <stdio.h>.), 984 AC_MSG_ERROR([sorry, can't do anything for you])) 985 986 In other cases, you may have to use text that also resembles a macro 987call. You must quote that text even when it is not passed as a macro 988argument. For example, these two approaches in `configure.ac' (quoting 989just the potential problems, or quoting the entire line) will protect 990your script in case autoconf ever adds a macro `AC_DC': 991 992 echo "Hard rock was here! --[AC_DC]" 993 [echo "Hard rock was here! --AC_DC"] 994 995which results in this text in `configure': 996 997 echo "Hard rock was here! --AC_DC" 998 echo "Hard rock was here! --AC_DC" 999 1000When you use the same text in a macro argument, you must therefore have 1001an extra quotation level (since one is stripped away by the macro 1002substitution). In general, then, it is a good idea to _use double 1003quoting for all literal string arguments_, either around just the 1004problematic portions, or over the entire argument: 1005 1006 AC_MSG_WARN([[AC_DC] stinks --Iron Maiden]) 1007 AC_MSG_WARN([[AC_DC stinks --Iron Maiden]]) 1008 1009 However, the above example triggers a warning about a possibly 1010unexpanded macro when running `autoconf', because it collides with the 1011namespace of macros reserved for the Autoconf language. To be really 1012safe, you can use additional escaping (either a quadrigraph, or 1013creative shell constructs) to silence that particular warning: 1014 1015 echo "Hard rock was here! --AC""_DC" 1016 AC_MSG_WARN([[AC@&t@_DC stinks --Iron Maiden]]) 1017 1018 You are now able to understand one of the constructs of Autoconf that 1019has been continually misunderstood... The rule of thumb is that 1020_whenever you expect macro expansion, expect quote expansion_; i.e., 1021expect one level of quotes to be lost. For instance: 1022 1023 AC_COMPILE_IFELSE(AC_LANG_SOURCE([char b[10];]), [], 1024 [AC_MSG_ERROR([you lose])]) 1025 1026is incorrect: here, the first argument of `AC_LANG_SOURCE' is `char 1027b[10];' and is expanded once, which results in `char b10;'; and the 1028`AC_LANG_SOURCE' is also expanded prior to being passed to 1029`AC_COMPILE_IFELSE'. (There was an idiom common in Autoconf's past to 1030address this issue via the M4 `changequote' primitive, but do not use 1031it!) Let's take a closer look: the author meant the first argument to 1032be understood as a literal, and therefore it must be quoted twice; 1033likewise, the intermediate `AC_LANG_SOURCE' macro should be quoted once 1034so that it is only expanded after the rest of the body of 1035`AC_COMPILE_IFELSE' is in place: 1036 1037 AC_COMPILE_IFELSE([AC_LANG_SOURCE([[char b[10];]])], [], 1038 [AC_MSG_ERROR([you lose])]) 1039 1040Voila`, you actually produce `char b[10];' this time! 1041 1042 On the other hand, descriptions (e.g., the last parameter of 1043`AC_DEFINE' or `AS_HELP_STRING') are not literals--they are subject to 1044line breaking, for example--and should not be double quoted. Even if 1045these descriptions are short and are not actually broken, double 1046quoting them yields weird results. 1047 1048 Some macros take optional arguments, which this documentation 1049represents as [ARG] (not to be confused with the quote characters). 1050You may just leave them empty, or use `[]' to make the emptiness of the 1051argument explicit, or you may simply omit the trailing commas. The 1052three lines below are equivalent: 1053 1054 AC_CHECK_HEADERS([stdio.h], [], [], []) 1055 AC_CHECK_HEADERS([stdio.h],,,) 1056 AC_CHECK_HEADERS([stdio.h]) 1057 1058 It is best to put each macro call on its own line in `configure.ac'. 1059Most of the macros don't add extra newlines; they rely on the newline 1060after the macro call to terminate the commands. This approach makes 1061the generated `configure' script a little easier to read by not 1062inserting lots of blank lines. It is generally safe to set shell 1063variables on the same line as a macro call, because the shell allows 1064assignments without intervening newlines. 1065 1066 You can include comments in `configure.ac' files by starting them 1067with the `#'. For example, it is helpful to begin `configure.ac' files 1068with a line like this: 1069 1070 # Process this file with autoconf to produce a configure script. 1071 1072 1073File: autoconf.info, Node: Autoconf Input Layout, Prev: Autoconf Language, Up: Writing Autoconf Input 1074 10753.1.3 Standard `configure.ac' Layout 1076------------------------------------ 1077 1078The order in which `configure.ac' calls the Autoconf macros is not 1079important, with a few exceptions. Every `configure.ac' must contain a 1080call to `AC_INIT' before the checks, and a call to `AC_OUTPUT' at the 1081end (*note Output::). Additionally, some macros rely on other macros 1082having been called first, because they check previously set values of 1083some variables to decide what to do. These macros are noted in the 1084individual descriptions (*note Existing Tests::), and they also warn 1085you when `configure' is created if they are called out of order. 1086 1087 To encourage consistency, here is a suggested order for calling the 1088Autoconf macros. Generally speaking, the things near the end of this 1089list are those that could depend on things earlier in it. For example, 1090library functions could be affected by types and libraries. 1091 1092 Autoconf requirements 1093 `AC_INIT(PACKAGE, VERSION, BUG-REPORT-ADDRESS)' 1094 information on the package 1095 checks for programs 1096 checks for libraries 1097 checks for header files 1098 checks for types 1099 checks for structures 1100 checks for compiler characteristics 1101 checks for library functions 1102 checks for system services 1103 `AC_CONFIG_FILES([FILE...])' 1104 `AC_OUTPUT' 1105 1106 1107File: autoconf.info, Node: autoscan Invocation, Next: ifnames Invocation, Prev: Writing Autoconf Input, Up: Making configure Scripts 1108 11093.2 Using `autoscan' to Create `configure.ac' 1110============================================= 1111 1112The `autoscan' program can help you create and/or maintain a 1113`configure.ac' file for a software package. `autoscan' examines source 1114files in the directory tree rooted at a directory given as a command 1115line argument, or the current directory if none is given. It searches 1116the source files for common portability problems and creates a file 1117`configure.scan' which is a preliminary `configure.ac' for that 1118package, and checks a possibly existing `configure.ac' for completeness. 1119 1120 When using `autoscan' to create a `configure.ac', you should 1121manually examine `configure.scan' before renaming it to `configure.ac'; 1122it probably needs some adjustments. Occasionally, `autoscan' outputs a 1123macro in the wrong order relative to another macro, so that `autoconf' 1124produces a warning; you need to move such macros manually. Also, if 1125you want the package to use a configuration header file, you must add a 1126call to `AC_CONFIG_HEADERS' (*note Configuration Headers::). You might 1127also have to change or add some `#if' directives to your program in 1128order to make it work with Autoconf (*note ifnames Invocation::, for 1129information about a program that can help with that job). 1130 1131 When using `autoscan' to maintain a `configure.ac', simply consider 1132adding its suggestions. The file `autoscan.log' contains detailed 1133information on why a macro is requested. 1134 1135 `autoscan' uses several data files (installed along with Autoconf) 1136to determine which macros to output when it finds particular symbols in 1137a package's source files. These data files all have the same format: 1138each line consists of a symbol, one or more blanks, and the Autoconf 1139macro to output if that symbol is encountered. Lines starting with `#' 1140are comments. 1141 1142 `autoscan' accepts the following options: 1143 1144`--help' 1145`-h' 1146 Print a summary of the command line options and exit. 1147 1148`--version' 1149`-V' 1150 Print the version number of Autoconf and exit. 1151 1152`--verbose' 1153`-v' 1154 Print the names of the files it examines and the potentially 1155 interesting symbols it finds in them. This output can be 1156 voluminous. 1157 1158`--debug' 1159`-d' 1160 Don't remove temporary files. 1161 1162`--include=DIR' 1163`-I DIR' 1164 Append DIR to the include path. Multiple invocations accumulate. 1165 1166`--prepend-include=DIR' 1167`-B DIR' 1168 Prepend DIR to the include path. Multiple invocations accumulate. 1169 1170 1171File: autoconf.info, Node: ifnames Invocation, Next: autoconf Invocation, Prev: autoscan Invocation, Up: Making configure Scripts 1172 11733.3 Using `ifnames' to List Conditionals 1174======================================== 1175 1176`ifnames' can help you write `configure.ac' for a software package. It 1177prints the identifiers that the package already uses in C preprocessor 1178conditionals. If a package has already been set up to have some 1179portability, `ifnames' can thus help you figure out what its 1180`configure' needs to check for. It may help fill in some gaps in a 1181`configure.ac' generated by `autoscan' (*note autoscan Invocation::). 1182 1183 `ifnames' scans all of the C source files named on the command line 1184(or the standard input, if none are given) and writes to the standard 1185output a sorted list of all the identifiers that appear in those files 1186in `#if', `#elif', `#ifdef', or `#ifndef' directives. It prints each 1187identifier on a line, followed by a space-separated list of the files 1188in which that identifier occurs. 1189 1190`ifnames' accepts the following options: 1191 1192`--help' 1193`-h' 1194 Print a summary of the command line options and exit. 1195 1196`--version' 1197`-V' 1198 Print the version number of Autoconf and exit. 1199 1200 1201File: autoconf.info, Node: autoconf Invocation, Next: autoreconf Invocation, Prev: ifnames Invocation, Up: Making configure Scripts 1202 12033.4 Using `autoconf' to Create `configure' 1204========================================== 1205 1206To create `configure' from `configure.ac', run the `autoconf' program 1207with no arguments. `autoconf' processes `configure.ac' with the M4 1208macro processor, using the Autoconf macros. If you give `autoconf' an 1209argument, it reads that file instead of `configure.ac' and writes the 1210configuration script to the standard output instead of to `configure'. 1211If you give `autoconf' the argument `-', it reads from the standard 1212input instead of `configure.ac' and writes the configuration script to 1213the standard output. 1214 1215 The Autoconf macros are defined in several files. Some of the files 1216are distributed with Autoconf; `autoconf' reads them first. Then it 1217looks for the optional file `acsite.m4' in the directory that contains 1218the distributed Autoconf macro files, and for the optional file 1219`aclocal.m4' in the current directory. Those files can contain your 1220site's or the package's own Autoconf macro definitions (*note Writing 1221Autoconf Macros::, for more information). If a macro is defined in 1222more than one of the files that `autoconf' reads, the last definition 1223it reads overrides the earlier ones. 1224 1225 `autoconf' accepts the following options: 1226 1227`--help' 1228`-h' 1229 Print a summary of the command line options and exit. 1230 1231`--version' 1232`-V' 1233 Print the version number of Autoconf and exit. 1234 1235`--verbose' 1236`-v' 1237 Report processing steps. 1238 1239`--debug' 1240`-d' 1241 Don't remove the temporary files. 1242 1243`--force' 1244`-f' 1245 Remake `configure' even if newer than its input files. 1246 1247`--include=DIR' 1248`-I DIR' 1249 Append DIR to the include path. Multiple invocations accumulate. 1250 1251`--prepend-include=DIR' 1252`-B DIR' 1253 Prepend DIR to the include path. Multiple invocations accumulate. 1254 1255`--output=FILE' 1256`-o FILE' 1257 Save output (script or trace) to FILE. The file `-' stands for 1258 the standard output. 1259 1260`--warnings=CATEGORY' 1261`-W CATEGORY' 1262 Report the warnings related to CATEGORY (which can actually be a 1263 comma separated list). *Note Reporting Messages::, macro 1264 `AC_DIAGNOSE', for a comprehensive list of categories. Special 1265 values include: 1266 1267 `all' 1268 report all the warnings 1269 1270 `none' 1271 report none 1272 1273 `error' 1274 treats warnings as errors 1275 1276 `no-CATEGORY' 1277 disable warnings falling into CATEGORY 1278 1279 Warnings about `syntax' are enabled by default, and the environment 1280 variable `WARNINGS', a comma separated list of categories, is 1281 honored as well. Passing `-W CATEGORY' actually behaves as if you 1282 had passed `--warnings syntax,$WARNINGS,CATEGORY'. To disable the 1283 defaults and `WARNINGS', and then enable warnings about obsolete 1284 constructs, use `-W none,obsolete'. 1285 1286 Because `autoconf' uses `autom4te' behind the scenes, it displays 1287 a back trace for errors, but not for warnings; if you want them, 1288 just pass `-W error'. *Note autom4te Invocation::, for some 1289 examples. 1290 1291`--trace=MACRO[:FORMAT]' 1292`-t MACRO[:FORMAT]' 1293 Do not create the `configure' script, but list the calls to MACRO 1294 according to the FORMAT. Multiple `--trace' arguments can be used 1295 to list several macros. Multiple `--trace' arguments for a single 1296 macro are not cumulative; instead, you should just make FORMAT as 1297 long as needed. 1298 1299 The FORMAT is a regular string, with newlines if desired, and 1300 several special escape codes. It defaults to `$f:$l:$n:$%'; see 1301 *note autom4te Invocation::, for details on the FORMAT. 1302 1303`--initialization' 1304`-i' 1305 By default, `--trace' does not trace the initialization of the 1306 Autoconf macros (typically the `AC_DEFUN' definitions). This 1307 results in a noticeable speedup, but can be disabled by this 1308 option. 1309 1310 It is often necessary to check the content of a `configure.ac' file, 1311but parsing it yourself is extremely fragile and error-prone. It is 1312suggested that you rely upon `--trace' to scan `configure.ac'. For 1313instance, to find the list of variables that are substituted, use: 1314 1315 $ autoconf -t AC_SUBST 1316 configure.ac:2:AC_SUBST:ECHO_C 1317 configure.ac:2:AC_SUBST:ECHO_N 1318 configure.ac:2:AC_SUBST:ECHO_T 1319 More traces deleted 1320 1321The example below highlights the difference between `$@', `$*', and 1322`$%'. 1323 1324 $ cat configure.ac 1325 AC_DEFINE(This, is, [an 1326 [example]]) 1327 $ autoconf -t 'AC_DEFINE:@: $@ 1328 *: $* 1329 %: $%' 1330 @: [This],[is],[an 1331 [example]] 1332 *: This,is,an 1333 [example] 1334 %: This:is:an [example] 1335 1336The FORMAT gives you a lot of freedom: 1337 1338 $ autoconf -t 'AC_SUBST:$$ac_subst{"$1"} = "$f:$l";' 1339 $ac_subst{"ECHO_C"} = "configure.ac:2"; 1340 $ac_subst{"ECHO_N"} = "configure.ac:2"; 1341 $ac_subst{"ECHO_T"} = "configure.ac:2"; 1342 More traces deleted 1343 1344A long SEPARATOR can be used to improve the readability of complex 1345structures, and to ease their parsing (for instance when no single 1346character is suitable as a separator): 1347 1348 $ autoconf -t 'AM_MISSING_PROG:${|:::::|}*' 1349 ACLOCAL|:::::|aclocal|:::::|$missing_dir 1350 AUTOCONF|:::::|autoconf|:::::|$missing_dir 1351 AUTOMAKE|:::::|automake|:::::|$missing_dir 1352 More traces deleted 1353 1354 1355File: autoconf.info, Node: autoreconf Invocation, Prev: autoconf Invocation, Up: Making configure Scripts 1356 13573.5 Using `autoreconf' to Update `configure' Scripts 1358==================================================== 1359 1360Installing the various components of the GNU Build System can be 1361tedious: running `autopoint' for Gettext, `automake' for `Makefile.in' 1362etc. in each directory. It may be needed either because some tools 1363such as `automake' have been updated on your system, or because some of 1364the sources such as `configure.ac' have been updated, or finally, 1365simply in order to install the GNU Build System in a fresh tree. 1366 1367 `autoreconf' runs `autoconf', `autoheader', `aclocal', `automake', 1368`libtoolize', and `autopoint' (when appropriate) repeatedly to update 1369the GNU Build System in the specified directories and their 1370subdirectories (*note Subdirectories::). By default, it only remakes 1371those files that are older than their sources. The environment 1372variables `AUTOM4TE', `AUTOCONF', `AUTOHEADER', `AUTOMAKE', `ACLOCAL', 1373`AUTOPOINT', `LIBTOOLIZE', `M4', and `MAKE' may be used to override the 1374invocation of the respective tools. 1375 1376 If you install a new version of some tool, you can make `autoreconf' 1377remake _all_ of the files by giving it the `--force' option. 1378 1379 *Note Automatic Remaking::, for Make rules to automatically rebuild 1380`configure' scripts when their source files change. That method 1381handles the timestamps of configuration header templates properly, but 1382does not pass `--autoconf-dir=DIR' or `--localdir=DIR'. 1383 1384 Gettext supplies the `autopoint' command to add translation 1385infrastructure to a source package. If you use `autopoint', your 1386`configure.ac' should invoke both `AM_GNU_GETTEXT' and 1387`AM_GNU_GETTEXT_VERSION(GETTEXT-VERSION)'. *Note Invoking the 1388`autopoint' Program: (gettext)autopoint Invocation, for further details. 1389 1390`autoreconf' accepts the following options: 1391 1392`--help' 1393`-h' 1394 Print a summary of the command line options and exit. 1395 1396`--version' 1397`-V' 1398 Print the version number of Autoconf and exit. 1399 1400`--verbose' 1401`-v' 1402 Print the name of each directory `autoreconf' examines and the 1403 commands it runs. If given two or more times, pass `--verbose' to 1404 subordinate tools that support it. 1405 1406`--debug' 1407`-d' 1408 Don't remove the temporary files. 1409 1410`--force' 1411`-f' 1412 Remake even `configure' scripts and configuration headers that are 1413 newer than their input files (`configure.ac' and, if present, 1414 `aclocal.m4'). 1415 1416`--install' 1417`-i' 1418 Install the missing auxiliary files in the package. By default, 1419 files are copied; this can be changed with `--symlink'. 1420 1421 If deemed appropriate, this option triggers calls to `automake 1422 --add-missing', `libtoolize', `autopoint', etc. 1423 1424`--no-recursive' 1425 Do not rebuild files in subdirectories to configure (see *note 1426 Subdirectories::, macro `AC_CONFIG_SUBDIRS'). 1427 1428`--symlink' 1429`-s' 1430 When used with `--install', install symbolic links to the missing 1431 auxiliary files instead of copying them. 1432 1433`--make' 1434`-m' 1435 When the directories were configured, update the configuration by 1436 running `./config.status --recheck && ./config.status', and then 1437 run `make'. 1438 1439`--include=DIR' 1440`-I DIR' 1441 Append DIR to the include path. Multiple invocations accumulate. 1442 Passed on to `aclocal', `autoconf' and `autoheader' internally. 1443 1444`--prepend-include=DIR' 1445`-B DIR' 1446 Prepend DIR to the include path. Multiple invocations accumulate. 1447 Passed on to `autoconf' and `autoheader' internally. 1448 1449`--warnings=CATEGORY' 1450`-W CATEGORY' 1451 Report the warnings related to CATEGORY (which can actually be a 1452 comma separated list). 1453 1454 `cross' 1455 related to cross compilation issues. 1456 1457 `obsolete' 1458 report the uses of obsolete constructs. 1459 1460 `portability' 1461 portability issues 1462 1463 `syntax' 1464 dubious syntactic constructs. 1465 1466 `all' 1467 report all the warnings 1468 1469 `none' 1470 report none 1471 1472 `error' 1473 treats warnings as errors 1474 1475 `no-CATEGORY' 1476 disable warnings falling into CATEGORY 1477 1478 Warnings about `syntax' are enabled by default, and the environment 1479 variable `WARNINGS', a comma separated list of categories, is 1480 honored as well. Passing `-W CATEGORY' actually behaves as if you 1481 had passed `--warnings syntax,$WARNINGS,CATEGORY'. To disable the 1482 defaults and `WARNINGS', and then enable warnings about obsolete 1483 constructs, use `-W none,obsolete'. 1484 1485 If you want `autoreconf' to pass flags that are not listed here on 1486to `aclocal', set `ACLOCAL_AMFLAGS' in your `Makefile.am'. Due to a 1487limitation in the Autoconf implementation these flags currently must be 1488set on a single line in `Makefile.am', without any backslash-newlines. 1489 1490 1491File: autoconf.info, Node: Setup, Next: Existing Tests, Prev: Making configure Scripts, Up: Top 1492 14934 Initialization and Output Files 1494********************************* 1495 1496Autoconf-generated `configure' scripts need some information about how 1497to initialize, such as how to find the package's source files and about 1498the output files to produce. The following sections describe the 1499initialization and the creation of output files. 1500 1501* Menu: 1502 1503* Initializing configure:: Option processing etc. 1504* Versioning:: Dealing with Autoconf versions 1505* Notices:: Copyright, version numbers in `configure' 1506* Input:: Where Autoconf should find files 1507* Output:: Outputting results from the configuration 1508* Configuration Actions:: Preparing the output based on results 1509* Configuration Files:: Creating output files 1510* Makefile Substitutions:: Using output variables in makefiles 1511* Configuration Headers:: Creating a configuration header file 1512* Configuration Commands:: Running arbitrary instantiation commands 1513* Configuration Links:: Links depending on the configuration 1514* Subdirectories:: Configuring independent packages together 1515* Default Prefix:: Changing the default installation prefix 1516 1517 1518File: autoconf.info, Node: Initializing configure, Next: Versioning, Up: Setup 1519 15204.1 Initializing `configure' 1521============================ 1522 1523Every `configure' script must call `AC_INIT' before doing anything else 1524that produces output. Calls to silent macros, such as `AC_DEFUN', may 1525also occur prior to `AC_INIT', although these are generally used via 1526`aclocal.m4', since that is implicitly included before the start of 1527`configure.ac'. The only other required macro is `AC_OUTPUT' (*note 1528Output::). 1529 1530 -- Macro: AC_INIT (PACKAGE, VERSION, [BUG-REPORT], [TARNAME], [URL]) 1531 Process any command-line arguments and perform initialization and 1532 verification. 1533 1534 Set the name of the PACKAGE and its VERSION. These are typically 1535 used in `--version' support, including that of `configure'. The 1536 optional argument BUG-REPORT should be the email to which users 1537 should send bug reports. The package TARNAME differs from 1538 PACKAGE: the latter designates the full package name (e.g., `GNU 1539 Autoconf'), while the former is meant for distribution tar ball 1540 names (e.g., `autoconf'). It defaults to PACKAGE with `GNU ' 1541 stripped, lower-cased, and all characters other than alphanumerics 1542 and underscores are changed to `-'. If provided, URL should be 1543 the home page for the package. 1544 1545 The arguments of `AC_INIT' must be static, i.e., there should not 1546 be any shell computation, quotes, or newlines, but they can be 1547 computed by M4. This is because the package information strings 1548 are expanded at M4 time into several contexts, and must give the 1549 same text at shell time whether used in single-quoted strings, 1550 double-quoted strings, quoted here-documents, or unquoted 1551 here-documents. It is permissible to use `m4_esyscmd' or 1552 `m4_esyscmd_s' for computing a version string that changes with 1553 every commit to a version control system (in fact, Autoconf does 1554 just that, for all builds of the development tree made between 1555 releases). 1556 1557 The following M4 macros (e.g., `AC_PACKAGE_NAME'), output variables 1558 (e.g., `PACKAGE_NAME'), and preprocessor symbols (e.g., 1559 `PACKAGE_NAME'), are defined by `AC_INIT': 1560 1561 `AC_PACKAGE_NAME', `PACKAGE_NAME' 1562 Exactly PACKAGE. 1563 1564 `AC_PACKAGE_TARNAME', `PACKAGE_TARNAME' 1565 Exactly TARNAME, possibly generated from PACKAGE. 1566 1567 `AC_PACKAGE_VERSION', `PACKAGE_VERSION' 1568 Exactly VERSION. 1569 1570 `AC_PACKAGE_STRING', `PACKAGE_STRING' 1571 Exactly `PACKAGE VERSION'. 1572 1573 `AC_PACKAGE_BUGREPORT', `PACKAGE_BUGREPORT' 1574 Exactly BUG-REPORT, if one was provided. Typically an email 1575 address, or URL to a bug management web page. 1576 1577 `AC_PACKAGE_URL', `PACKAGE_URL' 1578 Exactly URL, if one was provided. If URL was empty, but 1579 PACKAGE begins with `GNU ', then this defaults to 1580 `http://www.gnu.org/software/TARNAME/', otherwise, no URL is 1581 assumed. 1582 1583 If your `configure' script does its own option processing, it should 1584inspect `$@' or `$*' immediately after calling `AC_INIT', because other 1585Autoconf macros liberally use the `set' command to process strings, and 1586this has the side effect of updating `$@' and `$*'. However, we 1587suggest that you use standard macros like `AC_ARG_ENABLE' instead of 1588attempting to implement your own option processing. *Note Site 1589Configuration::. 1590 1591 1592File: autoconf.info, Node: Versioning, Next: Notices, Prev: Initializing configure, Up: Setup 1593 15944.2 Dealing with Autoconf versions 1595================================== 1596 1597The following optional macros can be used to help choose the minimum 1598version of Autoconf that can successfully compile a given 1599`configure.ac'. 1600 1601 -- Macro: AC_PREREQ (VERSION) 1602 Ensure that a recent enough version of Autoconf is being used. If 1603 the version of Autoconf being used to create `configure' is 1604 earlier than VERSION, print an error message to the standard error 1605 output and exit with failure (exit status is 63). For example: 1606 1607 AC_PREREQ([2.69]) 1608 1609 This macro may be used before `AC_INIT'. 1610 1611 -- Macro: AC_AUTOCONF_VERSION 1612 This macro was introduced in Autoconf 2.62. It identifies the 1613 version of Autoconf that is currently parsing the input file, in a 1614 format suitable for `m4_version_compare' (*note 1615 m4_version_compare::); in other words, for this release of 1616 Autoconf, its value is `2.69'. One potential use of this macro is 1617 for writing conditional fallbacks based on when a feature was 1618 added to Autoconf, rather than using `AC_PREREQ' to require the 1619 newer version of Autoconf. However, remember that the Autoconf 1620 philosophy favors feature checks over version checks. 1621 1622 You should not expand this macro directly; use 1623 `m4_defn([AC_AUTOCONF_VERSION])' instead. This is because some 1624 users might have a beta version of Autoconf installed, with 1625 arbitrary letters included in its version string. This means it 1626 is possible for the version string to contain the name of a 1627 defined macro, such that expanding `AC_AUTOCONF_VERSION' would 1628 trigger the expansion of that macro during rescanning, and change 1629 the version string to be different than what you intended to check. 1630 1631 1632File: autoconf.info, Node: Notices, Next: Input, Prev: Versioning, Up: Setup 1633 16344.3 Notices in `configure' 1635========================== 1636 1637The following macros manage version numbers for `configure' scripts. 1638Using them is optional. 1639 1640 -- Macro: AC_COPYRIGHT (COPYRIGHT-NOTICE) 1641 State that, in addition to the Free Software Foundation's 1642 copyright on the Autoconf macros, parts of your `configure' are 1643 covered by the COPYRIGHT-NOTICE. 1644 1645 The COPYRIGHT-NOTICE shows up in both the head of `configure' and 1646 in `configure --version'. 1647 1648 -- Macro: AC_REVISION (REVISION-INFO) 1649 Copy revision stamp REVISION-INFO into the `configure' script, 1650 with any dollar signs or double-quotes removed. This macro lets 1651 you put a revision stamp from `configure.ac' into `configure' 1652 without RCS or CVS changing it when you check in `configure'. 1653 That way, you can determine easily which revision of 1654 `configure.ac' a particular `configure' corresponds to. 1655 1656 For example, this line in `configure.ac': 1657 1658 AC_REVISION([$Revision: 1.1.1.1 $]) 1659 1660 produces this in `configure': 1661 1662 #!/bin/sh 1663 # From configure.ac Revision: 1.30 1664 1665 1666File: autoconf.info, Node: Input, Next: Output, Prev: Notices, Up: Setup 1667 16684.4 Finding `configure' Input 1669============================= 1670 1671 -- Macro: AC_CONFIG_SRCDIR (UNIQUE-FILE-IN-SOURCE-DIR) 1672 UNIQUE-FILE-IN-SOURCE-DIR is some file that is in the package's 1673 source directory; `configure' checks for this file's existence to 1674 make sure that the directory that it is told contains the source 1675 code in fact does. Occasionally people accidentally specify the 1676 wrong directory with `--srcdir'; this is a safety check. *Note 1677 configure Invocation::, for more information. 1678 1679 Packages that do manual configuration or use the `install' program 1680might need to tell `configure' where to find some other shell scripts 1681by calling `AC_CONFIG_AUX_DIR', though the default places it looks are 1682correct for most cases. 1683 1684 -- Macro: AC_CONFIG_AUX_DIR (DIR) 1685 Use the auxiliary build tools (e.g., `install-sh', `config.sub', 1686 `config.guess', Cygnus `configure', Automake and Libtool scripts, 1687 etc.) that are in directory DIR. These are auxiliary files used 1688 in configuration. DIR can be either absolute or relative to 1689 `SRCDIR'. The default is `SRCDIR' or `SRCDIR/..' or 1690 `SRCDIR/../..', whichever is the first that contains `install-sh'. 1691 The other files are not checked for, so that using 1692 `AC_PROG_INSTALL' does not automatically require distributing the 1693 other auxiliary files. It checks for `install.sh' also, but that 1694 name is obsolete because some `make' have a rule that creates 1695 `install' from it if there is no makefile. 1696 1697 The auxiliary directory is commonly named `build-aux'. If you 1698 need portability to DOS variants, do not name the auxiliary 1699 directory `aux'. *Note File System Conventions::. 1700 1701 -- Macro: AC_REQUIRE_AUX_FILE (FILE) 1702 Declares that FILE is expected in the directory defined above. In 1703 Autoconf proper, this macro does nothing: its sole purpose is to be 1704 traced by third-party tools to produce a list of expected auxiliary 1705 files. For instance it is called by macros like `AC_PROG_INSTALL' 1706 (*note Particular Programs::) or `AC_CANONICAL_BUILD' (*note 1707 Canonicalizing::) to register the auxiliary files they need. 1708 1709 Similarly, packages that use `aclocal' should declare where local 1710macros can be found using `AC_CONFIG_MACRO_DIR'. 1711 1712 -- Macro: AC_CONFIG_MACRO_DIR (DIR) 1713 Specify DIR as the location of additional local Autoconf macros. 1714 This macro is intended for use by future versions of commands like 1715 `autoreconf' that trace macro calls. It should be called directly 1716 from `configure.ac' so that tools that install macros for 1717 `aclocal' can find the macros' declarations. 1718 1719 Note that if you use `aclocal' from Automake to generate 1720 `aclocal.m4', you must also set `ACLOCAL_AMFLAGS = -I DIR' in your 1721 top-level `Makefile.am'. Due to a limitation in the Autoconf 1722 implementation of `autoreconf', these include directives currently 1723 must be set on a single line in `Makefile.am', without any 1724 backslash-newlines. 1725 1726 1727File: autoconf.info, Node: Output, Next: Configuration Actions, Prev: Input, Up: Setup 1728 17294.5 Outputting Files 1730==================== 1731 1732Every Autoconf script, e.g., `configure.ac', should finish by calling 1733`AC_OUTPUT'. That is the macro that generates and runs 1734`config.status', which in turn creates the makefiles and any other 1735files resulting from configuration. This is the only required macro 1736besides `AC_INIT' (*note Input::). 1737 1738 -- Macro: AC_OUTPUT 1739 Generate `config.status' and launch it. Call this macro once, at 1740 the end of `configure.ac'. 1741 1742 `config.status' performs all the configuration actions: all the 1743 output files (see *note Configuration Files::, macro 1744 `AC_CONFIG_FILES'), header files (see *note Configuration 1745 Headers::, macro `AC_CONFIG_HEADERS'), commands (see *note 1746 Configuration Commands::, macro `AC_CONFIG_COMMANDS'), links (see 1747 *note Configuration Links::, macro `AC_CONFIG_LINKS'), 1748 subdirectories to configure (see *note Subdirectories::, macro 1749 `AC_CONFIG_SUBDIRS') are honored. 1750 1751 The location of your `AC_OUTPUT' invocation is the exact point 1752 where configuration actions are taken: any code afterwards is 1753 executed by `configure' once `config.status' was run. If you want 1754 to bind actions to `config.status' itself (independently of 1755 whether `configure' is being run), see *note Running Arbitrary 1756 Configuration Commands: Configuration Commands. 1757 1758 Historically, the usage of `AC_OUTPUT' was somewhat different. 1759*Note Obsolete Macros::, for a description of the arguments that 1760`AC_OUTPUT' used to support. 1761 1762 If you run `make' in subdirectories, you should run it using the 1763`make' variable `MAKE'. Most versions of `make' set `MAKE' to the name 1764of the `make' program plus any options it was given. (But many do not 1765include in it the values of any variables set on the command line, so 1766those are not passed on automatically.) Some old versions of `make' do 1767not set this variable. The following macro allows you to use it even 1768with those versions. 1769 1770 -- Macro: AC_PROG_MAKE_SET 1771 If the Make command, `$MAKE' if set or else `make', predefines 1772 `$(MAKE)', define output variable `SET_MAKE' to be empty. 1773 Otherwise, define `SET_MAKE' to a macro definition that sets 1774 `$(MAKE)', such as `MAKE=make'. Calls `AC_SUBST' for `SET_MAKE'. 1775 1776 If you use this macro, place a line like this in each `Makefile.in' 1777that runs `MAKE' on other directories: 1778 1779 @SET_MAKE@ 1780 1781 1782File: autoconf.info, Node: Configuration Actions, Next: Configuration Files, Prev: Output, Up: Setup 1783 17844.6 Performing Configuration Actions 1785==================================== 1786 1787`configure' is designed so that it appears to do everything itself, but 1788there is actually a hidden slave: `config.status'. `configure' is in 1789charge of examining your system, but it is `config.status' that 1790actually takes the proper actions based on the results of `configure'. 1791The most typical task of `config.status' is to _instantiate_ files. 1792 1793 This section describes the common behavior of the four standard 1794instantiating macros: `AC_CONFIG_FILES', `AC_CONFIG_HEADERS', 1795`AC_CONFIG_COMMANDS' and `AC_CONFIG_LINKS'. They all have this 1796prototype: 1797 1798 AC_CONFIG_ITEMS(TAG..., [COMMANDS], [INIT-CMDS]) 1799 1800where the arguments are: 1801 1802TAG... 1803 A blank-or-newline-separated list of tags, which are typically the 1804 names of the files to instantiate. 1805 1806 You are encouraged to use literals as TAGS. In particular, you 1807 should avoid 1808 1809 ... && my_foos="$my_foos fooo" 1810 ... && my_foos="$my_foos foooo" 1811 AC_CONFIG_ITEMS([$my_foos]) 1812 1813 and use this instead: 1814 1815 ... && AC_CONFIG_ITEMS([fooo]) 1816 ... && AC_CONFIG_ITEMS([foooo]) 1817 1818 The macros `AC_CONFIG_FILES' and `AC_CONFIG_HEADERS' use special 1819 TAG values: they may have the form `OUTPUT' or `OUTPUT:INPUTS'. 1820 The file OUTPUT is instantiated from its templates, INPUTS 1821 (defaulting to `OUTPUT.in'). 1822 1823 `AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk])', for 1824 example, asks for the creation of the file `Makefile' that 1825 contains the expansion of the output variables in the 1826 concatenation of `boiler/top.mk' and `boiler/bot.mk'. 1827 1828 The special value `-' might be used to denote the standard output 1829 when used in OUTPUT, or the standard input when used in the 1830 INPUTS. You most probably don't need to use this in 1831 `configure.ac', but it is convenient when using the command line 1832 interface of `./config.status', see *note config.status 1833 Invocation::, for more details. 1834 1835 The INPUTS may be absolute or relative file names. In the latter 1836 case they are first looked for in the build tree, and then in the 1837 source tree. Input files should be text files, and a line length 1838 below 2000 bytes should be safe. 1839 1840COMMANDS 1841 Shell commands output literally into `config.status', and 1842 associated with a tag that the user can use to tell `config.status' 1843 which commands to run. The commands are run each time a TAG 1844 request is given to `config.status', typically each time the file 1845 `TAG' is created. 1846 1847 The variables set during the execution of `configure' are _not_ 1848 available here: you first need to set them via the INIT-CMDS. 1849 Nonetheless the following variables are precomputed: 1850 1851 `srcdir' 1852 The name of the top source directory, assuming that the 1853 working directory is the top build directory. This is what 1854 the `configure' option `--srcdir' sets. 1855 1856 `ac_top_srcdir' 1857 The name of the top source directory, assuming that the 1858 working directory is the current build directory. 1859 1860 `ac_top_build_prefix' 1861 The name of the top build directory, assuming that the working 1862 directory is the current build directory. It can be empty, 1863 or else ends with a slash, so that you may concatenate it. 1864 1865 `ac_srcdir' 1866 The name of the corresponding source directory, assuming that 1867 the working directory is the current build directory. 1868 1869 `tmp' 1870 The name of a temporary directory within the build tree, 1871 which you can use if you need to create additional temporary 1872 files. The directory is cleaned up when `config.status' is 1873 done or interrupted. Please use package-specific file name 1874 prefixes to avoid clashing with files that `config.status' 1875 may use internally. 1876 1877 The "current" directory refers to the directory (or 1878 pseudo-directory) containing the input part of TAGS. For 1879 instance, running 1880 1881 AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [...], [...]) 1882 1883 with `--srcdir=../package' produces the following values: 1884 1885 # Argument of --srcdir 1886 srcdir='../package' 1887 # Reversing deep/dir 1888 ac_top_build_prefix='../../' 1889 # Concatenation of $ac_top_build_prefix and srcdir 1890 ac_top_srcdir='../../../package' 1891 # Concatenation of $ac_top_srcdir and deep/dir 1892 ac_srcdir='../../../package/deep/dir' 1893 1894 independently of `in/in.in'. 1895 1896INIT-CMDS 1897 Shell commands output _unquoted_ near the beginning of 1898 `config.status', and executed each time `config.status' runs 1899 (regardless of the tag). Because they are unquoted, for example, 1900 `$var' is output as the value of `var'. INIT-CMDS is typically 1901 used by `configure' to give `config.status' some variables it 1902 needs to run the COMMANDS. 1903 1904 You should be extremely cautious in your variable names: all the 1905 INIT-CMDS share the same name space and may overwrite each other 1906 in unpredictable ways. Sorry... 1907 1908 All these macros can be called multiple times, with different TAG 1909values, of course! 1910 1911 1912File: autoconf.info, Node: Configuration Files, Next: Makefile Substitutions, Prev: Configuration Actions, Up: Setup 1913 19144.7 Creating Configuration Files 1915================================ 1916 1917Be sure to read the previous section, *note Configuration Actions::. 1918 1919 -- Macro: AC_CONFIG_FILES (FILE..., [CMDS], [INIT-CMDS]) 1920 Make `AC_OUTPUT' create each `FILE' by copying an input file (by 1921 default `FILE.in'), substituting the output variable values. This 1922 macro is one of the instantiating macros; see *note Configuration 1923 Actions::. *Note Makefile Substitutions::, for more information 1924 on using output variables. *Note Setting Output Variables::, for 1925 more information on creating them. This macro creates the 1926 directory that the file is in if it doesn't exist. Usually, 1927 makefiles are created this way, but other files, such as 1928 `.gdbinit', can be specified as well. 1929 1930 Typical calls to `AC_CONFIG_FILES' look like this: 1931 1932 AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile]) 1933 AC_CONFIG_FILES([autoconf], [chmod +x autoconf]) 1934 1935 You can override an input file name by appending to FILE a 1936 colon-separated list of input files. Examples: 1937 1938 AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk] 1939 [lib/Makefile:boiler/lib.mk]) 1940 1941 Doing this allows you to keep your file names acceptable to DOS 1942 variants, or to prepend and/or append boilerplate to the file. 1943 1944 1945File: autoconf.info, Node: Makefile Substitutions, Next: Configuration Headers, Prev: Configuration Files, Up: Setup 1946 19474.8 Substitutions in Makefiles 1948============================== 1949 1950Each subdirectory in a distribution that contains something to be 1951compiled or installed should come with a file `Makefile.in', from which 1952`configure' creates a file `Makefile' in that directory. To create 1953`Makefile', `configure' performs a simple variable substitution, 1954replacing occurrences of `@VARIABLE@' in `Makefile.in' with the value 1955that `configure' has determined for that variable. Variables that are 1956substituted into output files in this way are called "output 1957variables". They are ordinary shell variables that are set in 1958`configure'. To make `configure' substitute a particular variable into 1959the output files, the macro `AC_SUBST' must be called with that 1960variable name as an argument. Any occurrences of `@VARIABLE@' for 1961other variables are left unchanged. *Note Setting Output Variables::, 1962for more information on creating output variables with `AC_SUBST'. 1963 1964 A software package that uses a `configure' script should be 1965distributed with a file `Makefile.in', but no makefile; that way, the 1966user has to properly configure the package for the local system before 1967compiling it. 1968 1969 *Note Makefile Conventions: (standards)Makefile Conventions, for 1970more information on what to put in makefiles. 1971 1972* Menu: 1973 1974* Preset Output Variables:: Output variables that are always set 1975* Installation Directory Variables:: Other preset output variables 1976* Changed Directory Variables:: Warnings about `datarootdir' 1977* Build Directories:: Supporting multiple concurrent compiles 1978* Automatic Remaking:: Makefile rules for configuring 1979 1980 1981File: autoconf.info, Node: Preset Output Variables, Next: Installation Directory Variables, Up: Makefile Substitutions 1982 19834.8.1 Preset Output Variables 1984----------------------------- 1985 1986Some output variables are preset by the Autoconf macros. Some of the 1987Autoconf macros set additional output variables, which are mentioned in 1988the descriptions for those macros. *Note Output Variable Index::, for a 1989complete list of output variables. *Note Installation Directory 1990Variables::, for the list of the preset ones related to installation 1991directories. Below are listed the other preset ones, many of which are 1992precious variables (*note Setting Output Variables::, `AC_ARG_VAR'). 1993 1994 The preset variables which are available during `config.status' 1995(*note Configuration Actions::) may also be used during `configure' 1996tests. For example, it is permissible to reference `$srcdir' when 1997constructing a list of directories to pass via option `-I' during a 1998compiler feature check. When used in this manner, coupled with the 1999fact that `configure' is always run from the top build directory, it is 2000sufficient to use just `$srcdir' instead of `$top_srcdir'. 2001 2002 -- Variable: CFLAGS 2003 Debugging and optimization options for the C compiler. If it is 2004 not set in the environment when `configure' runs, the default 2005 value is set when you call `AC_PROG_CC' (or empty if you don't). 2006 `configure' uses this variable when compiling or linking programs 2007 to test for C features. 2008 2009 If a compiler option affects only the behavior of the preprocessor 2010 (e.g., `-DNAME'), it should be put into `CPPFLAGS' instead. If it 2011 affects only the linker (e.g., `-LDIRECTORY'), it should be put 2012 into `LDFLAGS' instead. If it affects only the compiler proper, 2013 `CFLAGS' is the natural home for it. If an option affects 2014 multiple phases of the compiler, though, matters get tricky. One 2015 approach to put such options directly into `CC', e.g., `CC='gcc 2016 -m64''. Another is to put them into both `CPPFLAGS' and 2017 `LDFLAGS', but not into `CFLAGS'. 2018 2019 However, remember that some `Makefile' variables are reserved by 2020 the GNU Coding Standards for the use of the "user"--the person 2021 building the package. For instance, `CFLAGS' is one such variable. 2022 2023 Sometimes package developers are tempted to set user variables 2024 such as `CFLAGS' because it appears to make their job easier. 2025 However, the package itself should never set a user variable, 2026 particularly not to include switches that are required for proper 2027 compilation of the package. Since these variables are documented 2028 as being for the package builder, that person rightfully expects 2029 to be able to override any of these variables at build time. If 2030 the package developer needs to add switches without interfering 2031 with the user, the proper way to do that is to introduce an 2032 additional variable. Automake makes this easy by introducing 2033 `AM_CFLAGS' (*note Flag Variables Ordering: (automake)Flag 2034 Variables Ordering.), but the concept is the same even if Automake 2035 is not used. 2036 2037 -- Variable: configure_input 2038 A comment saying that the file was generated automatically by 2039 `configure' and giving the name of the input file. `AC_OUTPUT' 2040 adds a comment line containing this variable to the top of every 2041 makefile it creates. For other files, you should reference this 2042 variable in a comment at the top of each input file. For example, 2043 an input shell script should begin like this: 2044 2045 #!/bin/sh 2046 # @configure_input@ 2047 2048 The presence of that line also reminds people editing the file 2049 that it needs to be processed by `configure' in order to be used. 2050 2051 -- Variable: CPPFLAGS 2052 Preprocessor options for the C, C++, Objective C, and Objective C++ 2053 preprocessors and compilers. If it is not set in the environment 2054 when `configure' runs, the default value is empty. `configure' 2055 uses this variable when preprocessing or compiling programs to 2056 test for C, C++, Objective C, and Objective C++ features. 2057 2058 This variable's contents should contain options like `-I', `-D', 2059 and `-U' that affect only the behavior of the preprocessor. 2060 Please see the explanation of `CFLAGS' for what you can do if an 2061 option affects other phases of the compiler as well. 2062 2063 Currently, `configure' always links as part of a single invocation 2064 of the compiler that also preprocesses and compiles, so it uses 2065 this variable also when linking programs. However, it is unwise to 2066 depend on this behavior because the GNU Coding Standards do not 2067 require it and many packages do not use `CPPFLAGS' when linking 2068 programs. 2069 2070 *Note Special Chars in Variables::, for limitations that `CPPFLAGS' 2071 might run into. 2072 2073 -- Variable: CXXFLAGS 2074 Debugging and optimization options for the C++ compiler. It acts 2075 like `CFLAGS', but for C++ instead of C. 2076 2077 -- Variable: DEFS 2078 `-D' options to pass to the C compiler. If `AC_CONFIG_HEADERS' is 2079 called, `configure' replaces `@DEFS@' with `-DHAVE_CONFIG_H' 2080 instead (*note Configuration Headers::). This variable is not 2081 defined while `configure' is performing its tests, only when 2082 creating the output files. *Note Setting Output Variables::, for 2083 how to check the results of previous tests. 2084 2085 -- Variable: ECHO_C 2086 -- Variable: ECHO_N 2087 -- Variable: ECHO_T 2088 How does one suppress the trailing newline from `echo' for 2089 question-answer message pairs? These variables provide a way: 2090 2091 echo $ECHO_N "And the winner is... $ECHO_C" 2092 sleep 100000000000 2093 echo "${ECHO_T}dead." 2094 2095 Some old and uncommon `echo' implementations offer no means to 2096 achieve this, in which case `ECHO_T' is set to tab. You might not 2097 want to use it. 2098 2099 -- Variable: ERLCFLAGS 2100 Debugging and optimization options for the Erlang compiler. If it 2101 is not set in the environment when `configure' runs, the default 2102 value is empty. `configure' uses this variable when compiling 2103 programs to test for Erlang features. 2104 2105 -- Variable: FCFLAGS 2106 Debugging and optimization options for the Fortran compiler. If it 2107 is not set in the environment when `configure' runs, the default 2108 value is set when you call `AC_PROG_FC' (or empty if you don't). 2109 `configure' uses this variable when compiling or linking programs 2110 to test for Fortran features. 2111 2112 -- Variable: FFLAGS 2113 Debugging and optimization options for the Fortran 77 compiler. 2114 If it is not set in the environment when `configure' runs, the 2115 default value is set when you call `AC_PROG_F77' (or empty if you 2116 don't). `configure' uses this variable when compiling or linking 2117 programs to test for Fortran 77 features. 2118 2119 -- Variable: LDFLAGS 2120 Options for the linker. If it is not set in the environment when 2121 `configure' runs, the default value is empty. `configure' uses 2122 this variable when linking programs to test for C, C++, Objective 2123 C, Objective C++, Fortran, and Go features. 2124 2125 This variable's contents should contain options like `-s' and `-L' 2126 that affect only the behavior of the linker. Please see the 2127 explanation of `CFLAGS' for what you can do if an option also 2128 affects other phases of the compiler. 2129 2130 Don't use this variable to pass library names (`-l') to the 2131 linker; use `LIBS' instead. 2132 2133 -- Variable: LIBS 2134 `-l' options to pass to the linker. The default value is empty, 2135 but some Autoconf macros may prepend extra libraries to this 2136 variable if those libraries are found and provide necessary 2137 functions, see *note Libraries::. `configure' uses this variable 2138 when linking programs to test for C, C++, Objective C, Objective 2139 C++, Fortran, and Go features. 2140 2141 -- Variable: OBJCFLAGS 2142 Debugging and optimization options for the Objective C compiler. 2143 It acts like `CFLAGS', but for Objective C instead of C. 2144 2145 -- Variable: OBJCXXFLAGS 2146 Debugging and optimization options for the Objective C++ compiler. 2147 It acts like `CXXFLAGS', but for Objective C++ instead of C++. 2148 2149 -- Variable: GOFLAGS 2150 Debugging and optimization options for the Go compiler. It acts 2151 like `CFLAGS', but for Go instead of C. 2152 2153 -- Variable: builddir 2154 Rigorously equal to `.'. Added for symmetry only. 2155 2156 -- Variable: abs_builddir 2157 Absolute name of `builddir'. 2158 2159 -- Variable: top_builddir 2160 The relative name of the top level of the current build tree. In 2161 the top-level directory, this is the same as `builddir'. 2162 2163 -- Variable: top_build_prefix 2164 The relative name of the top level of the current build tree with 2165 final slash if nonempty. This is the same as `top_builddir', 2166 except that it contains zero or more runs of `../', so it should 2167 not be appended with a slash for concatenation. This helps for 2168 `make' implementations that otherwise do not treat `./file' and 2169 `file' as equal in the toplevel build directory. 2170 2171 -- Variable: abs_top_builddir 2172 Absolute name of `top_builddir'. 2173 2174 -- Variable: srcdir 2175 The name of the directory that contains the source code for that 2176 makefile. 2177 2178 -- Variable: abs_srcdir 2179 Absolute name of `srcdir'. 2180 2181 -- Variable: top_srcdir 2182 The name of the top-level source code directory for the package. 2183 In the top-level directory, this is the same as `srcdir'. 2184 2185 -- Variable: abs_top_srcdir 2186 Absolute name of `top_srcdir'. 2187 2188 2189File: autoconf.info, Node: Installation Directory Variables, Next: Changed Directory Variables, Prev: Preset Output Variables, Up: Makefile Substitutions 2190 21914.8.2 Installation Directory Variables 2192-------------------------------------- 2193 2194The following variables specify the directories for package 2195installation, see *note Variables for Installation Directories: 2196(standards)Directory Variables, for more information. Each variable 2197corresponds to an argument of `configure'; trailing slashes are 2198stripped so that expressions such as `${prefix}/lib' expand with only 2199one slash between directory names. See the end of this section for 2200details on when and how to use these variables. 2201 2202 -- Variable: bindir 2203 The directory for installing executables that users run. 2204 2205 -- Variable: datadir 2206 The directory for installing idiosyncratic read-only 2207 architecture-independent data. 2208 2209 -- Variable: datarootdir 2210 The root of the directory tree for read-only 2211 architecture-independent data files. 2212 2213 -- Variable: docdir 2214 The directory for installing documentation files (other than Info 2215 and man). 2216 2217 -- Variable: dvidir 2218 The directory for installing documentation files in DVI format. 2219 2220 -- Variable: exec_prefix 2221 The installation prefix for architecture-dependent files. By 2222 default it's the same as `prefix'. You should avoid installing 2223 anything directly to `exec_prefix'. However, the default value for 2224 directories containing architecture-dependent files should be 2225 relative to `exec_prefix'. 2226 2227 -- Variable: htmldir 2228 The directory for installing HTML documentation. 2229 2230 -- Variable: includedir 2231 The directory for installing C header files. 2232 2233 -- Variable: infodir 2234 The directory for installing documentation in Info format. 2235 2236 -- Variable: libdir 2237 The directory for installing object code libraries. 2238 2239 -- Variable: libexecdir 2240 The directory for installing executables that other programs run. 2241 2242 -- Variable: localedir 2243 The directory for installing locale-dependent but 2244 architecture-independent data, such as message catalogs. This 2245 directory usually has a subdirectory per locale. 2246 2247 -- Variable: localstatedir 2248 The directory for installing modifiable single-machine data. 2249 2250 -- Variable: mandir 2251 The top-level directory for installing documentation in man format. 2252 2253 -- Variable: oldincludedir 2254 The directory for installing C header files for non-GCC compilers. 2255 2256 -- Variable: pdfdir 2257 The directory for installing PDF documentation. 2258 2259 -- Variable: prefix 2260 The common installation prefix for all files. If `exec_prefix' is 2261 defined to a different value, `prefix' is used only for 2262 architecture-independent files. 2263 2264 -- Variable: psdir 2265 The directory for installing PostScript documentation. 2266 2267 -- Variable: sbindir 2268 The directory for installing executables that system 2269 administrators run. 2270 2271 -- Variable: sharedstatedir 2272 The directory for installing modifiable architecture-independent 2273 data. 2274 2275 -- Variable: sysconfdir 2276 The directory for installing read-only single-machine data. 2277 2278 Most of these variables have values that rely on `prefix' or 2279`exec_prefix'. It is deliberate that the directory output variables 2280keep them unexpanded: typically `@datarootdir@' is replaced by 2281`${prefix}/share', not `/usr/local/share', and `@datadir@' is replaced 2282by `${datarootdir}'. 2283 2284 This behavior is mandated by the GNU Coding Standards, so that when 2285the user runs: 2286 2287`make' 2288 she can still specify a different prefix from the one specified to 2289 `configure', in which case, if needed, the package should hard 2290 code dependencies corresponding to the make-specified prefix. 2291 2292`make install' 2293 she can specify a different installation location, in which case 2294 the package _must_ still depend on the location which was compiled 2295 in (i.e., never recompile when `make install' is run). This is an 2296 extremely important feature, as many people may decide to install 2297 all the files of a package grouped together, and then install 2298 links from the final locations to there. 2299 2300 In order to support these features, it is essential that 2301`datarootdir' remains defined as `${prefix}/share', so that its value 2302can be expanded based on the current value of `prefix'. 2303 2304 A corollary is that you should not use these variables except in 2305makefiles. For instance, instead of trying to evaluate `datadir' in 2306`configure' and hard-coding it in makefiles using e.g., 2307`AC_DEFINE_UNQUOTED([DATADIR], ["$datadir"], [Data directory.])', you 2308should add `-DDATADIR='$(datadir)'' to your makefile's definition of 2309`CPPFLAGS' (`AM_CPPFLAGS' if you are also using Automake). 2310 2311 Similarly, you should not rely on `AC_CONFIG_FILES' to replace 2312`bindir' and friends in your shell scripts and other files; instead, 2313let `make' manage their replacement. For instance Autoconf ships 2314templates of its shell scripts ending with `.in', and uses a makefile 2315snippet similar to the following to build scripts like `autoheader' and 2316`autom4te': 2317 2318 edit = sed \ 2319 -e 's|@bindir[@]|$(bindir)|g' \ 2320 -e 's|@pkgdatadir[@]|$(pkgdatadir)|g' \ 2321 -e 's|@prefix[@]|$(prefix)|g' 2322 2323 autoheader autom4te: Makefile 2324 rm -f $@ $@.tmp 2325 srcdir=''; \ 2326 test -f ./$@.in || srcdir=$(srcdir)/; \ 2327 $(edit) $${srcdir}$@.in >$@.tmp 2328 chmod +x $@.tmp 2329 chmod a-w $@.tmp 2330 mv $@.tmp $@ 2331 2332 autoheader: $(srcdir)/autoheader.in 2333 autom4te: $(srcdir)/autom4te.in 2334 2335 Some details are noteworthy: 2336 2337`@bindir[@]' 2338 The brackets prevent `configure' from replacing `@bindir@' in the 2339 Sed expression itself. Brackets are preferable to a backslash 2340 here, since Posix says `\@' is not portable. 2341 2342`$(bindir)' 2343 Don't use `@bindir@'! Use the matching makefile variable instead. 2344 2345`$(pkgdatadir)' 2346 The example takes advantage of the variable `$(pkgdatadir)' 2347 provided by Automake; it is equivalent to `$(datadir)/$(PACKAGE)'. 2348 2349`/' 2350 Don't use `/' in the Sed expressions that replace file names since 2351 most likely the variables you use, such as `$(bindir)', contain 2352 `/'. Use a shell metacharacter instead, such as `|'. 2353 2354special characters 2355 File names, file name components, and the value of `VPATH' should 2356 not contain shell metacharacters or white space. *Note Special 2357 Chars in Variables::. 2358 2359dependency on `Makefile' 2360 Since `edit' uses values that depend on the configuration specific 2361 values (`prefix', etc.) and not only on `VERSION' and so forth, 2362 the output depends on `Makefile', not `configure.ac'. 2363 2364`$@' 2365 The main rule is generic, and uses `$@' extensively to avoid the 2366 need for multiple copies of the rule. 2367 2368Separated dependencies and single suffix rules 2369 You can't use them! The above snippet cannot be (portably) 2370 rewritten as: 2371 2372 autoconf autoheader: Makefile 2373 .in: 2374 rm -f $@ $@.tmp 2375 $(edit) $< >$@.tmp 2376 chmod +x $@.tmp 2377 mv $@.tmp $@ 2378 2379 *Note Single Suffix Rules::, for details. 2380 2381`$(srcdir)' 2382 Be sure to specify the name of the source directory, otherwise the 2383 package won't support separated builds. 2384 2385 For the more specific installation of Erlang libraries, the 2386following variables are defined: 2387 2388 -- Variable: ERLANG_INSTALL_LIB_DIR 2389 The common parent directory of Erlang library installation 2390 directories. This variable is set by calling the 2391 `AC_ERLANG_SUBST_INSTALL_LIB_DIR' macro in `configure.ac'. 2392 2393 -- Variable: ERLANG_INSTALL_LIB_DIR_LIBRARY 2394 The installation directory for Erlang library LIBRARY. This 2395 variable is set by using the `AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR' 2396 macro in `configure.ac'. 2397 2398 *Note Erlang Libraries::, for details. 2399 2400 2401File: autoconf.info, Node: Changed Directory Variables, Next: Build Directories, Prev: Installation Directory Variables, Up: Makefile Substitutions 2402 24034.8.3 Changed Directory Variables 2404--------------------------------- 2405 2406In Autoconf 2.60, the set of directory variables has changed, and the 2407defaults of some variables have been adjusted (*note Installation 2408Directory Variables::) to changes in the GNU Coding Standards. 2409Notably, `datadir', `infodir', and `mandir' are now expressed in terms 2410of `datarootdir'. If you are upgrading from an earlier Autoconf 2411version, you may need to adjust your files to ensure that the directory 2412variables are substituted correctly (*note Defining Directories::), and 2413that a definition of `datarootdir' is in place. For example, in a 2414`Makefile.in', adding 2415 2416 datarootdir = @datarootdir@ 2417 2418is usually sufficient. If you use Automake to create `Makefile.in', it 2419will add this for you. 2420 2421 To help with the transition, Autoconf warns about files that seem to 2422use `datarootdir' without defining it. In some cases, it then expands 2423the value of `$datarootdir' in substitutions of the directory 2424variables. The following example shows such a warning: 2425 2426 $ cat configure.ac 2427 AC_INIT 2428 AC_CONFIG_FILES([Makefile]) 2429 AC_OUTPUT 2430 $ cat Makefile.in 2431 prefix = @prefix@ 2432 datadir = @datadir@ 2433 $ autoconf 2434 $ configure 2435 configure: creating ./config.status 2436 config.status: creating Makefile 2437 config.status: WARNING: 2438 Makefile.in seems to ignore the --datarootdir setting 2439 $ cat Makefile 2440 prefix = /usr/local 2441 datadir = ${prefix}/share 2442 2443 Usually one can easily change the file to accommodate both older and 2444newer Autoconf releases: 2445 2446 $ cat Makefile.in 2447 prefix = @prefix@ 2448 datarootdir = @datarootdir@ 2449 datadir = @datadir@ 2450 $ configure 2451 configure: creating ./config.status 2452 config.status: creating Makefile 2453 $ cat Makefile 2454 prefix = /usr/local 2455 datarootdir = ${prefix}/share 2456 datadir = ${datarootdir} 2457 2458 In some cases, however, the checks may not be able to detect that a 2459suitable initialization of `datarootdir' is in place, or they may fail 2460to detect that such an initialization is necessary in the output file. 2461If, after auditing your package, there are still spurious `configure' 2462warnings about `datarootdir', you may add the line 2463 2464 AC_DEFUN([AC_DATAROOTDIR_CHECKED]) 2465 2466to your `configure.ac' to disable the warnings. This is an exception 2467to the usual rule that you should not define a macro whose name begins 2468with `AC_' (*note Macro Names::). 2469 2470 2471File: autoconf.info, Node: Build Directories, Next: Automatic Remaking, Prev: Changed Directory Variables, Up: Makefile Substitutions 2472 24734.8.4 Build Directories 2474----------------------- 2475 2476You can support compiling a software package for several architectures 2477simultaneously from the same copy of the source code. The object files 2478for each architecture are kept in their own directory. 2479 2480 To support doing this, `make' uses the `VPATH' variable to find the 2481files that are in the source directory. GNU Make can do this. Most 2482other recent `make' programs can do this as well, though they may have 2483difficulties and it is often simpler to recommend GNU `make' (*note 2484VPATH and Make::). Older `make' programs do not support `VPATH'; when 2485using them, the source code must be in the same directory as the object 2486files. 2487 2488 If you are using GNU Automake, the remaining details in this section 2489are already covered for you, based on the contents of your 2490`Makefile.am'. But if you are using Autoconf in isolation, then 2491supporting `VPATH' requires the following in your `Makefile.in': 2492 2493 srcdir = @srcdir@ 2494 VPATH = @srcdir@ 2495 2496 Do not set `VPATH' to the value of another variable (*note Variables 2497listed in VPATH::. 2498 2499 `configure' substitutes the correct value for `srcdir' when it 2500produces `Makefile'. 2501 2502 Do not use the `make' variable `$<', which expands to the file name 2503of the file in the source directory (found with `VPATH'), except in 2504implicit rules. (An implicit rule is one such as `.c.o', which tells 2505how to create a `.o' file from a `.c' file.) Some versions of `make' 2506do not set `$<' in explicit rules; they expand it to an empty value. 2507 2508 Instead, Make command lines should always refer to source files by 2509prefixing them with `$(srcdir)/'. For example: 2510 2511 time.info: time.texinfo 2512 $(MAKEINFO) '$(srcdir)/time.texinfo' 2513 2514 2515File: autoconf.info, Node: Automatic Remaking, Prev: Build Directories, Up: Makefile Substitutions 2516 25174.8.5 Automatic Remaking 2518------------------------ 2519 2520You can put rules like the following in the top-level `Makefile.in' for 2521a package to automatically update the configuration information when 2522you change the configuration files. This example includes all of the 2523optional files, such as `aclocal.m4' and those related to configuration 2524header files. Omit from the `Makefile.in' rules for any of these files 2525that your package does not use. 2526 2527 The `$(srcdir)/' prefix is included because of limitations in the 2528`VPATH' mechanism. 2529 2530 The `stamp-' files are necessary because the timestamps of 2531`config.h.in' and `config.h' are not changed if remaking them does not 2532change their contents. This feature avoids unnecessary recompilation. 2533You should include the file `stamp-h.in' in your package's 2534distribution, so that `make' considers `config.h.in' up to date. Don't 2535use `touch' (*note Limitations of Usual Tools: touch.); instead, use 2536`echo' (using `date' would cause needless differences, hence CVS 2537conflicts, etc.). 2538 2539 $(srcdir)/configure: configure.ac aclocal.m4 2540 cd '$(srcdir)' && autoconf 2541 2542 # autoheader might not change config.h.in, so touch a stamp file. 2543 $(srcdir)/config.h.in: stamp-h.in 2544 $(srcdir)/stamp-h.in: configure.ac aclocal.m4 2545 cd '$(srcdir)' && autoheader 2546 echo timestamp > '$(srcdir)/stamp-h.in' 2547 2548 config.h: stamp-h 2549 stamp-h: config.h.in config.status 2550 ./config.status 2551 2552 Makefile: Makefile.in config.status 2553 ./config.status 2554 2555 config.status: configure 2556 ./config.status --recheck 2557 2558(Be careful if you copy these lines directly into your makefile, as you 2559need to convert the indented lines to start with the tab character.) 2560 2561 In addition, you should use 2562 2563 AC_CONFIG_FILES([stamp-h], [echo timestamp > stamp-h]) 2564 2565so `config.status' ensures that `config.h' is considered up to date. 2566*Note Output::, for more information about `AC_OUTPUT'. 2567 2568 *Note config.status Invocation::, for more examples of handling 2569configuration-related dependencies. 2570 2571 2572File: autoconf.info, Node: Configuration Headers, Next: Configuration Commands, Prev: Makefile Substitutions, Up: Setup 2573 25744.9 Configuration Header Files 2575============================== 2576 2577When a package contains more than a few tests that define C preprocessor 2578symbols, the command lines to pass `-D' options to the compiler can get 2579quite long. This causes two problems. One is that the `make' output 2580is hard to visually scan for errors. More seriously, the command lines 2581can exceed the length limits of some operating systems. As an 2582alternative to passing `-D' options to the compiler, `configure' 2583scripts can create a C header file containing `#define' directives. 2584The `AC_CONFIG_HEADERS' macro selects this kind of output. Though it 2585can be called anywhere between `AC_INIT' and `AC_OUTPUT', it is 2586customary to call it right after `AC_INIT'. 2587 2588 The package should `#include' the configuration header file before 2589any other header files, to prevent inconsistencies in declarations (for 2590example, if it redefines `const'). 2591 2592 To provide for VPATH builds, remember to pass the C compiler a `-I.' 2593option (or `-I..'; whichever directory contains `config.h'). Even if 2594you use `#include "config.h"', the preprocessor searches only the 2595directory of the currently read file, i.e., the source directory, not 2596the build directory. 2597 2598 With the appropriate `-I' option, you can use `#include <config.h>'. 2599Actually, it's a good habit to use it, because in the rare case when 2600the source directory contains another `config.h', the build directory 2601should be searched first. 2602 2603 -- Macro: AC_CONFIG_HEADERS (HEADER ..., [CMDS], [INIT-CMDS]) 2604 This macro is one of the instantiating macros; see *note 2605 Configuration Actions::. Make `AC_OUTPUT' create the file(s) in 2606 the blank-or-newline-separated list HEADER containing C 2607 preprocessor `#define' statements, and replace `@DEFS@' in 2608 generated files with `-DHAVE_CONFIG_H' instead of the value of 2609 `DEFS'. The usual name for HEADER is `config.h'. 2610 2611 If HEADER already exists and its contents are identical to what 2612 `AC_OUTPUT' would put in it, it is left alone. Doing this allows 2613 making some changes in the configuration without needlessly causing 2614 object files that depend on the header file to be recompiled. 2615 2616 Usually the input file is named `HEADER.in'; however, you can 2617 override the input file name by appending to HEADER a 2618 colon-separated list of input files. For example, you might need 2619 to make the input file name acceptable to DOS variants: 2620 2621 AC_CONFIG_HEADERS([config.h:config.hin]) 2622 2623 2624 -- Macro: AH_HEADER 2625 This macro is defined as the name of the first declared config 2626 header and undefined if no config headers have been declared up to 2627 this point. A third-party macro may, for example, require use of 2628 a config header without invoking AC_CONFIG_HEADERS twice, like 2629 this: 2630 2631 AC_CONFIG_COMMANDS_PRE( 2632 [m4_ifndef([AH_HEADER], [AC_CONFIG_HEADERS([config.h])])]) 2633 2634 2635 *Note Configuration Actions::, for more details on HEADER. 2636 2637* Menu: 2638 2639* Header Templates:: Input for the configuration headers 2640* autoheader Invocation:: How to create configuration templates 2641* Autoheader Macros:: How to specify CPP templates 2642 2643 2644File: autoconf.info, Node: Header Templates, Next: autoheader Invocation, Up: Configuration Headers 2645 26464.9.1 Configuration Header Templates 2647------------------------------------ 2648 2649Your distribution should contain a template file that looks as you want 2650the final header file to look, including comments, with `#undef' 2651statements which are used as hooks. For example, suppose your 2652`configure.ac' makes these calls: 2653 2654 AC_CONFIG_HEADERS([conf.h]) 2655 AC_CHECK_HEADERS([unistd.h]) 2656 2657Then you could have code like the following in `conf.h.in'. The 2658`conf.h' created by `configure' defines `HAVE_UNISTD_H' to 1, if and 2659only if the system has `unistd.h'. 2660 2661 /* Define as 1 if you have unistd.h. */ 2662 #undef HAVE_UNISTD_H 2663 2664 The format of the template file is stricter than what the C 2665preprocessor is required to accept. A directive line should contain 2666only whitespace, `#undef', and `HAVE_UNISTD_H'. The use of `#define' 2667instead of `#undef', or of comments on the same line as `#undef', is 2668strongly discouraged. Each hook should only be listed once. Other 2669preprocessor lines, such as `#ifdef' or `#include', are copied verbatim 2670from the template into the generated header. 2671 2672 Since it is a tedious task to keep a template header up to date, you 2673may use `autoheader' to generate it, see *note autoheader Invocation::. 2674 2675 During the instantiation of the header, each `#undef' line in the 2676template file for each symbol defined by `AC_DEFINE' is changed to an 2677appropriate `#define'. If the corresponding `AC_DEFINE' has not been 2678executed during the `configure' run, the `#undef' line is commented 2679out. (This is important, e.g., for `_POSIX_SOURCE': on many systems, 2680it can be implicitly defined by the compiler, and undefining it in the 2681header would then break compilation of subsequent headers.) 2682 2683 Currently, _all_ remaining `#undef' lines in the header template are 2684commented out, whether or not there was a corresponding `AC_DEFINE' for 2685the macro name; but this behavior is not guaranteed for future releases 2686of Autoconf. 2687 2688 Generally speaking, since you should not use `#define', and you 2689cannot guarantee whether a `#undef' directive in the header template 2690will be converted to a `#define' or commented out in the generated 2691header file, the template file cannot be used for conditional 2692definition effects. Consequently, if you need to use the construct 2693 2694 #ifdef THIS 2695 # define THAT 2696 #endif 2697 2698you must place it outside of the template. If you absolutely need to 2699hook it to the config header itself, please put the directives to a 2700separate file, and `#include' that file from the config header 2701template. If you are using `autoheader', you would probably use 2702`AH_BOTTOM' to append the `#include' directive. 2703 2704 2705File: autoconf.info, Node: autoheader Invocation, Next: Autoheader Macros, Prev: Header Templates, Up: Configuration Headers 2706 27074.9.2 Using `autoheader' to Create `config.h.in' 2708------------------------------------------------ 2709 2710The `autoheader' program can create a template file of C `#define' 2711statements for `configure' to use. It searches for the first 2712invocation of `AC_CONFIG_HEADERS' in `configure' sources to determine 2713the name of the template. (If the first call of `AC_CONFIG_HEADERS' 2714specifies more than one input file name, `autoheader' uses the first 2715one.) 2716 2717 It is recommended that only one input file is used. If you want to 2718append a boilerplate code, it is preferable to use `AH_BOTTOM([#include 2719<conf_post.h>])'. File `conf_post.h' is not processed during the 2720configuration then, which make things clearer. Analogically, `AH_TOP' 2721can be used to prepend a boilerplate code. 2722 2723 In order to do its job, `autoheader' needs you to document all of 2724the symbols that you might use. Typically this is done via an 2725`AC_DEFINE' or `AC_DEFINE_UNQUOTED' call whose first argument is a 2726literal symbol and whose third argument describes the symbol (*note 2727Defining Symbols::). Alternatively, you can use `AH_TEMPLATE' (*note 2728Autoheader Macros::), or you can supply a suitable input file for a 2729subsequent configuration header file. Symbols defined by Autoconf's 2730builtin tests are already documented properly; you need to document 2731only those that you define yourself. 2732 2733 You might wonder why `autoheader' is needed: after all, why would 2734`configure' need to "patch" a `config.h.in' to produce a `config.h' 2735instead of just creating `config.h' from scratch? Well, when 2736everything rocks, the answer is just that we are wasting our time 2737maintaining `autoheader': generating `config.h' directly is all that is 2738needed. When things go wrong, however, you'll be thankful for the 2739existence of `autoheader'. 2740 2741 The fact that the symbols are documented is important in order to 2742_check_ that `config.h' makes sense. The fact that there is a 2743well-defined list of symbols that should be defined (or not) is also 2744important for people who are porting packages to environments where 2745`configure' cannot be run: they just have to _fill in the blanks_. 2746 2747 But let's come back to the point: the invocation of `autoheader'... 2748 2749 If you give `autoheader' an argument, it uses that file instead of 2750`configure.ac' and writes the header file to the standard output 2751instead of to `config.h.in'. If you give `autoheader' an argument of 2752`-', it reads the standard input instead of `configure.ac' and writes 2753the header file to the standard output. 2754 2755 `autoheader' accepts the following options: 2756 2757`--help' 2758`-h' 2759 Print a summary of the command line options and exit. 2760 2761`--version' 2762`-V' 2763 Print the version number of Autoconf and exit. 2764 2765`--verbose' 2766`-v' 2767 Report processing steps. 2768 2769`--debug' 2770`-d' 2771 Don't remove the temporary files. 2772 2773`--force' 2774`-f' 2775 Remake the template file even if newer than its input files. 2776 2777`--include=DIR' 2778`-I DIR' 2779 Append DIR to the include path. Multiple invocations accumulate. 2780 2781`--prepend-include=DIR' 2782`-B DIR' 2783 Prepend DIR to the include path. Multiple invocations accumulate. 2784 2785`--warnings=CATEGORY' 2786`-W CATEGORY' 2787 Report the warnings related to CATEGORY (which can actually be a 2788 comma separated list). Current categories include: 2789 2790 `obsolete' 2791 report the uses of obsolete constructs 2792 2793 `all' 2794 report all the warnings 2795 2796 `none' 2797 report none 2798 2799 `error' 2800 treats warnings as errors 2801 2802 `no-CATEGORY' 2803 disable warnings falling into CATEGORY 2804 2805 2806 2807File: autoconf.info, Node: Autoheader Macros, Prev: autoheader Invocation, Up: Configuration Headers 2808 28094.9.3 Autoheader Macros 2810----------------------- 2811 2812`autoheader' scans `configure.ac' and figures out which C preprocessor 2813symbols it might define. It knows how to generate templates for 2814symbols defined by `AC_CHECK_HEADERS', `AC_CHECK_FUNCS' etc., but if 2815you `AC_DEFINE' any additional symbol, you must define a template for 2816it. If there are missing templates, `autoheader' fails with an error 2817message. 2818 2819 The template for a SYMBOL is created by `autoheader' from the 2820DESCRIPTION argument to an `AC_DEFINE'; see *note Defining Symbols::. 2821 2822 For special needs, you can use the following macros. 2823 2824 -- Macro: AH_TEMPLATE (KEY, DESCRIPTION) 2825 Tell `autoheader' to generate a template for KEY. This macro 2826 generates standard templates just like `AC_DEFINE' when a 2827 DESCRIPTION is given. 2828 2829 For example: 2830 2831 AH_TEMPLATE([CRAY_STACKSEG_END], 2832 [Define to one of _getb67, GETB67, getb67 2833 for Cray-2 and Cray-YMP systems. This 2834 function is required for alloca.c support 2835 on those systems.]) 2836 2837 generates the following template, with the description properly 2838 justified. 2839 2840 /* Define to one of _getb67, GETB67, getb67 for Cray-2 and 2841 Cray-YMP systems. This function is required for alloca.c 2842 support on those systems. */ 2843 #undef CRAY_STACKSEG_END 2844 2845 -- Macro: AH_VERBATIM (KEY, TEMPLATE) 2846 Tell `autoheader' to include the TEMPLATE as-is in the header 2847 template file. This TEMPLATE is associated with the KEY, which is 2848 used to sort all the different templates and guarantee their 2849 uniqueness. It should be a symbol that can be defined via 2850 `AC_DEFINE'. 2851 2852 -- Macro: AH_TOP (TEXT) 2853 Include TEXT at the top of the header template file. 2854 2855 -- Macro: AH_BOTTOM (TEXT) 2856 Include TEXT at the bottom of the header template file. 2857 2858 Please note that TEXT gets included "verbatim" to the template file, 2859not to the resulting config header, so it can easily get mangled when 2860the template is processed. There is rarely a need for something other 2861than 2862 2863 AH_BOTTOM([#include <custom.h>]) 2864 2865 2866File: autoconf.info, Node: Configuration Commands, Next: Configuration Links, Prev: Configuration Headers, Up: Setup 2867 28684.10 Running Arbitrary Configuration Commands 2869============================================= 2870 2871You can execute arbitrary commands before, during, and after 2872`config.status' is run. The three following macros accumulate the 2873commands to run when they are called multiple times. 2874`AC_CONFIG_COMMANDS' replaces the obsolete macro `AC_OUTPUT_COMMANDS'; 2875see *note Obsolete Macros::, for details. 2876 2877 -- Macro: AC_CONFIG_COMMANDS (TAG..., [CMDS], [INIT-CMDS]) 2878 Specify additional shell commands to run at the end of 2879 `config.status', and shell commands to initialize any variables 2880 from `configure'. Associate the commands with TAG. Since 2881 typically the CMDS create a file, TAG should naturally be the name 2882 of that file. If needed, the directory hosting TAG is created. 2883 This macro is one of the instantiating macros; see *note 2884 Configuration Actions::. 2885 2886 Here is an unrealistic example: 2887 fubar=42 2888 AC_CONFIG_COMMANDS([fubar], 2889 [echo this is extra $fubar, and so on.], 2890 [fubar=$fubar]) 2891 2892 Here is a better one: 2893 AC_CONFIG_COMMANDS([timestamp], [date >timestamp]) 2894 2895 The following two macros look similar, but in fact they are not of 2896the same breed: they are executed directly by `configure', so you 2897cannot use `config.status' to rerun them. 2898 2899 -- Macro: AC_CONFIG_COMMANDS_PRE (CMDS) 2900 Execute the CMDS right before creating `config.status'. 2901 2902 This macro presents the last opportunity to call `AC_SUBST', 2903 `AC_DEFINE', or `AC_CONFIG_ITEMS' macros. 2904 2905 -- Macro: AC_CONFIG_COMMANDS_POST (CMDS) 2906 Execute the CMDS right after creating `config.status'. 2907 2908 2909File: autoconf.info, Node: Configuration Links, Next: Subdirectories, Prev: Configuration Commands, Up: Setup 2910 29114.11 Creating Configuration Links 2912================================= 2913 2914You may find it convenient to create links whose destinations depend 2915upon results of tests. One can use `AC_CONFIG_COMMANDS' but the 2916creation of relative symbolic links can be delicate when the package is 2917built in a directory different from the source directory. 2918 2919 -- Macro: AC_CONFIG_LINKS (DEST:SOURCE..., [CMDS], [INIT-CMDS]) 2920 Make `AC_OUTPUT' link each of the existing files SOURCE to the 2921 corresponding link name DEST. Makes a symbolic link if possible, 2922 otherwise a hard link if possible, otherwise a copy. The DEST and 2923 SOURCE names should be relative to the top level source or build 2924 directory. This macro is one of the instantiating macros; see 2925 *note Configuration Actions::. 2926 2927 For example, this call: 2928 2929 AC_CONFIG_LINKS([host.h:config/$machine.h 2930 object.h:config/$obj_format.h]) 2931 2932 creates in the current directory `host.h' as a link to 2933 `SRCDIR/config/$machine.h', and `object.h' as a link to 2934 `SRCDIR/config/$obj_format.h'. 2935 2936 The tempting value `.' for DEST is invalid: it makes it impossible 2937 for `config.status' to guess the links to establish. 2938 2939 One can then run: 2940 ./config.status host.h object.h 2941 to create the links. 2942 2943 2944File: autoconf.info, Node: Subdirectories, Next: Default Prefix, Prev: Configuration Links, Up: Setup 2945 29464.12 Configuring Other Packages in Subdirectories 2947================================================= 2948 2949In most situations, calling `AC_OUTPUT' is sufficient to produce 2950makefiles in subdirectories. However, `configure' scripts that control 2951more than one independent package can use `AC_CONFIG_SUBDIRS' to run 2952`configure' scripts for other packages in subdirectories. 2953 2954 -- Macro: AC_CONFIG_SUBDIRS (DIR ...) 2955 Make `AC_OUTPUT' run `configure' in each subdirectory DIR in the 2956 given blank-or-newline-separated list. Each DIR should be a 2957 literal, i.e., please do not use: 2958 2959 if test "x$package_foo_enabled" = xyes; then 2960 my_subdirs="$my_subdirs foo" 2961 fi 2962 AC_CONFIG_SUBDIRS([$my_subdirs]) 2963 2964 because this prevents `./configure --help=recursive' from 2965 displaying the options of the package `foo'. Instead, you should 2966 write: 2967 2968 if test "x$package_foo_enabled" = xyes; then 2969 AC_CONFIG_SUBDIRS([foo]) 2970 fi 2971 2972 If a given DIR is not found at `configure' run time, a warning is 2973 reported; if the subdirectory is optional, write: 2974 2975 if test -d "$srcdir/foo"; then 2976 AC_CONFIG_SUBDIRS([foo]) 2977 fi 2978 2979 If a given DIR contains `configure.gnu', it is run instead of 2980 `configure'. This is for packages that might use a non-Autoconf 2981 script `Configure', which can't be called through a wrapper 2982 `configure' since it would be the same file on case-insensitive 2983 file systems. Likewise, if a DIR contains `configure.in' but no 2984 `configure', the Cygnus `configure' script found by 2985 `AC_CONFIG_AUX_DIR' is used. 2986 2987 The subdirectory `configure' scripts are given the same command 2988 line options that were given to this `configure' script, with minor 2989 changes if needed, which include: 2990 2991 - adjusting a relative name for the cache file; 2992 2993 - adjusting a relative name for the source directory; 2994 2995 - propagating the current value of `$prefix', including if it 2996 was defaulted, and if the default values of the top level and 2997 of the subdirectory `configure' differ. 2998 2999 This macro also sets the output variable `subdirs' to the list of 3000 directories `DIR ...'. Make rules can use this variable to 3001 determine which subdirectories to recurse into. 3002 3003 This macro may be called multiple times. 3004 3005 3006File: autoconf.info, Node: Default Prefix, Prev: Subdirectories, Up: Setup 3007 30084.13 Default Prefix 3009=================== 3010 3011By default, `configure' sets the prefix for files it installs to 3012`/usr/local'. The user of `configure' can select a different prefix 3013using the `--prefix' and `--exec-prefix' options. There are two ways 3014to change the default: when creating `configure', and when running it. 3015 3016 Some software packages might want to install in a directory other 3017than `/usr/local' by default. To accomplish that, use the 3018`AC_PREFIX_DEFAULT' macro. 3019 3020 -- Macro: AC_PREFIX_DEFAULT (PREFIX) 3021 Set the default installation prefix to PREFIX instead of 3022 `/usr/local'. 3023 3024 It may be convenient for users to have `configure' guess the 3025installation prefix from the location of a related program that they 3026have already installed. If you wish to do that, you can call 3027`AC_PREFIX_PROGRAM'. 3028 3029 -- Macro: AC_PREFIX_PROGRAM (PROGRAM) 3030 If the user did not specify an installation prefix (using the 3031 `--prefix' option), guess a value for it by looking for PROGRAM in 3032 `PATH', the way the shell does. If PROGRAM is found, set the 3033 prefix to the parent of the directory containing PROGRAM, else 3034 default the prefix as described above (`/usr/local' or 3035 `AC_PREFIX_DEFAULT'). For example, if PROGRAM is `gcc' and the 3036 `PATH' contains `/usr/local/gnu/bin/gcc', set the prefix to 3037 `/usr/local/gnu'. 3038 3039 3040File: autoconf.info, Node: Existing Tests, Next: Writing Tests, Prev: Setup, Up: Top 3041 30425 Existing Tests 3043**************** 3044 3045These macros test for particular system features that packages might 3046need or want to use. If you need to test for a kind of feature that 3047none of these macros check for, you can probably do it by calling 3048primitive test macros with appropriate arguments (*note Writing 3049Tests::). 3050 3051 These tests print messages telling the user which feature they're 3052checking for, and what they find. They cache their results for future 3053`configure' runs (*note Caching Results::). 3054 3055 Some of these macros set output variables. *Note Makefile 3056Substitutions::, for how to get their values. The phrase "define NAME" 3057is used below as a shorthand to mean "define the C preprocessor symbol 3058NAME to the value 1". *Note Defining Symbols::, for how to get those 3059symbol definitions into your program. 3060 3061* Menu: 3062 3063* Common Behavior:: Macros' standard schemes 3064* Alternative Programs:: Selecting between alternative programs 3065* Files:: Checking for the existence of files 3066* Libraries:: Library archives that might be missing 3067* Library Functions:: C library functions that might be missing 3068* Header Files:: Header files that might be missing 3069* Declarations:: Declarations that may be missing 3070* Structures:: Structures or members that might be missing 3071* Types:: Types that might be missing 3072* Compilers and Preprocessors:: Checking for compiling programs 3073* System Services:: Operating system services 3074* Posix Variants:: Special kludges for specific Posix variants 3075* Erlang Libraries:: Checking for the existence of Erlang libraries 3076 3077 3078File: autoconf.info, Node: Common Behavior, Next: Alternative Programs, Up: Existing Tests 3079 30805.1 Common Behavior 3081=================== 3082 3083Much effort has been expended to make Autoconf easy to learn. The most 3084obvious way to reach this goal is simply to enforce standard interfaces 3085and behaviors, avoiding exceptions as much as possible. Because of 3086history and inertia, unfortunately, there are still too many exceptions 3087in Autoconf; nevertheless, this section describes some of the common 3088rules. 3089 3090* Menu: 3091 3092* Standard Symbols:: Symbols defined by the macros 3093* Default Includes:: Includes used by the generic macros 3094 3095 3096File: autoconf.info, Node: Standard Symbols, Next: Default Includes, Up: Common Behavior 3097 30985.1.1 Standard Symbols 3099---------------------- 3100 3101All the generic macros that `AC_DEFINE' a symbol as a result of their 3102test transform their ARGUMENT values to a standard alphabet. First, 3103ARGUMENT is converted to upper case and any asterisks (`*') are each 3104converted to `P'. Any remaining characters that are not alphanumeric 3105are converted to underscores. 3106 3107 For instance, 3108 3109 AC_CHECK_TYPES([struct $Expensive*]) 3110 3111defines the symbol `HAVE_STRUCT__EXPENSIVEP' if the check succeeds. 3112 3113 3114File: autoconf.info, Node: Default Includes, Prev: Standard Symbols, Up: Common Behavior 3115 31165.1.2 Default Includes 3117---------------------- 3118 3119Several tests depend upon a set of header files. Since these headers 3120are not universally available, tests actually have to provide a set of 3121protected includes, such as: 3122 3123 #ifdef TIME_WITH_SYS_TIME 3124 # include <sys/time.h> 3125 # include <time.h> 3126 #else 3127 # ifdef HAVE_SYS_TIME_H 3128 # include <sys/time.h> 3129 # else 3130 # include <time.h> 3131 # endif 3132 #endif 3133 3134Unless you know exactly what you are doing, you should avoid using 3135unconditional includes, and check the existence of the headers you 3136include beforehand (*note Header Files::). 3137 3138 Most generic macros use the following macro to provide the default 3139set of includes: 3140 3141 -- Macro: AC_INCLUDES_DEFAULT ([INCLUDE-DIRECTIVES]) 3142 Expand to INCLUDE-DIRECTIVES if defined, otherwise to: 3143 3144 #include <stdio.h> 3145 #ifdef HAVE_SYS_TYPES_H 3146 # include <sys/types.h> 3147 #endif 3148 #ifdef HAVE_SYS_STAT_H 3149 # include <sys/stat.h> 3150 #endif 3151 #ifdef STDC_HEADERS 3152 # include <stdlib.h> 3153 # include <stddef.h> 3154 #else 3155 # ifdef HAVE_STDLIB_H 3156 # include <stdlib.h> 3157 # endif 3158 #endif 3159 #ifdef HAVE_STRING_H 3160 # if !defined STDC_HEADERS && defined HAVE_MEMORY_H 3161 # include <memory.h> 3162 # endif 3163 # include <string.h> 3164 #endif 3165 #ifdef HAVE_STRINGS_H 3166 # include <strings.h> 3167 #endif 3168 #ifdef HAVE_INTTYPES_H 3169 # include <inttypes.h> 3170 #endif 3171 #ifdef HAVE_STDINT_H 3172 # include <stdint.h> 3173 #endif 3174 #ifdef HAVE_UNISTD_H 3175 # include <unistd.h> 3176 #endif 3177 3178 If the default includes are used, then check for the presence of 3179 these headers and their compatibility, i.e., you don't need to run 3180 `AC_HEADER_STDC', nor check for `stdlib.h' etc. 3181 3182 These headers are checked for in the same order as they are 3183 included. For instance, on some systems `string.h' and 3184 `strings.h' both exist, but conflict. Then `HAVE_STRING_H' is 3185 defined, not `HAVE_STRINGS_H'. 3186 3187 3188File: autoconf.info, Node: Alternative Programs, Next: Files, Prev: Common Behavior, Up: Existing Tests 3189 31905.2 Alternative Programs 3191======================== 3192 3193These macros check for the presence or behavior of particular programs. 3194They are used to choose between several alternative programs and to 3195decide what to do once one has been chosen. If there is no macro 3196specifically defined to check for a program you need, and you don't need 3197to check for any special properties of it, then you can use one of the 3198general program-check macros. 3199 3200* Menu: 3201 3202* Particular Programs:: Special handling to find certain programs 3203* Generic Programs:: How to find other programs 3204 3205 3206File: autoconf.info, Node: Particular Programs, Next: Generic Programs, Up: Alternative Programs 3207 32085.2.1 Particular Program Checks 3209------------------------------- 3210 3211These macros check for particular programs--whether they exist, and in 3212some cases whether they support certain features. 3213 3214 -- Macro: AC_PROG_AWK 3215 Check for `gawk', `mawk', `nawk', and `awk', in that order, and 3216 set output variable `AWK' to the first one that is found. It 3217 tries `gawk' first because that is reported to be the best 3218 implementation. The result can be overridden by setting the 3219 variable `AWK' or the cache variable `ac_cv_prog_AWK'. 3220 3221 Using this macro is sufficient to avoid the pitfalls of traditional 3222 `awk' (*note Limitations of Usual Tools: awk.). 3223 3224 -- Macro: AC_PROG_GREP 3225 Look for the best available `grep' or `ggrep' that accepts the 3226 longest input lines possible, and that supports multiple `-e' 3227 options. Set the output variable `GREP' to whatever is chosen. 3228 *Note Limitations of Usual Tools: grep, for more information about 3229 portability problems with the `grep' command family. The result 3230 can be overridden by setting the `GREP' variable and is cached in 3231 the `ac_cv_path_GREP' variable. 3232 3233 -- Macro: AC_PROG_EGREP 3234 Check whether `$GREP -E' works, or else look for the best available 3235 `egrep' or `gegrep' that accepts the longest input lines possible. 3236 Set the output variable `EGREP' to whatever is chosen. The result 3237 can be overridden by setting the `EGREP' variable and is cached in 3238 the `ac_cv_path_EGREP' variable. 3239 3240 -- Macro: AC_PROG_FGREP 3241 Check whether `$GREP -F' works, or else look for the best available 3242 `fgrep' or `gfgrep' that accepts the longest input lines possible. 3243 Set the output variable `FGREP' to whatever is chosen. The result 3244 can be overridden by setting the `FGREP' variable and is cached in 3245 the `ac_cv_path_FGREP' variable. 3246 3247 -- Macro: AC_PROG_INSTALL 3248 Set output variable `INSTALL' to the name of a BSD-compatible 3249 `install' program, if one is found in the current `PATH'. 3250 Otherwise, set `INSTALL' to `DIR/install-sh -c', checking the 3251 directories specified to `AC_CONFIG_AUX_DIR' (or its default 3252 directories) to determine DIR (*note Output::). Also set the 3253 variables `INSTALL_PROGRAM' and `INSTALL_SCRIPT' to `${INSTALL}' 3254 and `INSTALL_DATA' to `${INSTALL} -m 644'. 3255 3256 `@INSTALL@' is special, as its value may vary for different 3257 configuration files. 3258 3259 This macro screens out various instances of `install' known not to 3260 work. It prefers to find a C program rather than a shell script, 3261 for speed. Instead of `install-sh', it can also use `install.sh', 3262 but that name is obsolete because some `make' programs have a rule 3263 that creates `install' from it if there is no makefile. Further, 3264 this macro requires `install' to be able to install multiple files 3265 into a target directory in a single invocation. 3266 3267 Autoconf comes with a copy of `install-sh' that you can use. If 3268 you use `AC_PROG_INSTALL', you must include either `install-sh' or 3269 `install.sh' in your distribution; otherwise `configure' produces 3270 an error message saying it can't find them--even if the system 3271 you're on has a good `install' program. This check is a safety 3272 measure to prevent you from accidentally leaving that file out, 3273 which would prevent your package from installing on systems that 3274 don't have a BSD-compatible `install' program. 3275 3276 If you need to use your own installation program because it has 3277 features not found in standard `install' programs, there is no 3278 reason to use `AC_PROG_INSTALL'; just put the file name of your 3279 program into your `Makefile.in' files. 3280 3281 The result of the test can be overridden by setting the variable 3282 `INSTALL' or the cache variable `ac_cv_path_install'. 3283 3284 -- Macro: AC_PROG_MKDIR_P 3285 Set output variable `MKDIR_P' to a program that ensures that for 3286 each argument, a directory named by this argument exists, creating 3287 it and its parent directories if needed, and without race 3288 conditions when two instances of the program attempt to make the 3289 same directory at nearly the same time. 3290 3291 This macro uses the `mkdir -p' command if possible. Otherwise, it 3292 falls back on invoking `install-sh' with the `-d' option, so your 3293 package should contain `install-sh' as described under 3294 `AC_PROG_INSTALL'. An `install-sh' file that predates Autoconf 3295 2.60 or Automake 1.10 is vulnerable to race conditions, so if you 3296 want to support parallel installs from different packages into the 3297 same directory you need to make sure you have an up-to-date 3298 `install-sh'. In particular, be careful about using `autoreconf 3299 -if' if your Automake predates Automake 1.10. 3300 3301 This macro is related to the `AS_MKDIR_P' macro (*note Programming 3302 in M4sh::), but it sets an output variable intended for use in 3303 other files, whereas `AS_MKDIR_P' is intended for use in scripts 3304 like `configure'. Also, `AS_MKDIR_P' does not accept options, but 3305 `MKDIR_P' supports the `-m' option, e.g., a makefile might invoke 3306 `$(MKDIR_P) -m 0 dir' to create an inaccessible directory, and 3307 conversely a makefile should use `$(MKDIR_P) -- $(FOO)' if FOO 3308 might yield a value that begins with `-'. Finally, `AS_MKDIR_P' 3309 does not check for race condition vulnerability, whereas 3310 `AC_PROG_MKDIR_P' does. 3311 3312 `@MKDIR_P@' is special, as its value may vary for different 3313 configuration files. 3314 3315 The result of the test can be overridden by setting the variable 3316 `MKDIR_P' or the cache variable `ac_cv_path_mkdir'. 3317 3318 -- Macro: AC_PROG_LEX 3319 If `flex' is found, set output variable `LEX' to `flex' and 3320 `LEXLIB' to `-lfl', if that library is in a standard place. 3321 Otherwise set `LEX' to `lex' and `LEXLIB' to `-ll', if found. If 3322 neither variant is available, set `LEX' to `:'; for packages that 3323 ship the generated `file.yy.c' alongside the source `file.l', this 3324 default allows users without a lexer generator to still build the 3325 package even if the timestamp for `file.l' is inadvertently 3326 changed. 3327 3328 Define `YYTEXT_POINTER' if `yytext' defaults to `char *' instead 3329 of to `char []'. Also set output variable `LEX_OUTPUT_ROOT' to 3330 the base of the file name that the lexer generates; usually 3331 `lex.yy', but sometimes something else. These results vary 3332 according to whether `lex' or `flex' is being used. 3333 3334 You are encouraged to use Flex in your sources, since it is both 3335 more pleasant to use than plain Lex and the C source it produces 3336 is portable. In order to ensure portability, however, you must 3337 either provide a function `yywrap' or, if you don't use it (e.g., 3338 your scanner has no `#include'-like feature), simply include a 3339 `%noyywrap' statement in the scanner's source. Once this done, 3340 the scanner is portable (unless _you_ felt free to use nonportable 3341 constructs) and does not depend on any library. In this case, and 3342 in this case only, it is suggested that you use this Autoconf 3343 snippet: 3344 3345 AC_PROG_LEX 3346 if test "x$LEX" != xflex; then 3347 LEX="$SHELL $missing_dir/missing flex" 3348 AC_SUBST([LEX_OUTPUT_ROOT], [lex.yy]) 3349 AC_SUBST([LEXLIB], ['']) 3350 fi 3351 3352 The shell script `missing' can be found in the Automake 3353 distribution. 3354 3355 Remember that the user may have supplied an alternate location in 3356 `LEX', so if Flex is required, it is better to check that the user 3357 provided something sufficient by parsing the output of `$LEX 3358 --version' than by simply relying on `test "x$LEX" = xflex'. 3359 3360 To ensure backward compatibility, Automake's `AM_PROG_LEX' invokes 3361 (indirectly) this macro twice, which causes an annoying but benign 3362 "`AC_PROG_LEX' invoked multiple times" warning. Future versions 3363 of Automake will fix this issue; meanwhile, just ignore this 3364 message. 3365 3366 As part of running the test, this macro may delete any file in the 3367 configuration directory named `lex.yy.c' or `lexyy.c'. 3368 3369 The result of this test can be influenced by setting the variable 3370 `LEX' or the cache variable `ac_cv_prog_LEX'. 3371 3372 -- Macro: AC_PROG_LN_S 3373 If `ln -s' works on the current file system (the operating system 3374 and file system support symbolic links), set the output variable 3375 `LN_S' to `ln -s'; otherwise, if `ln' works, set `LN_S' to `ln', 3376 and otherwise set it to `cp -pR'. 3377 3378 If you make a link in a directory other than the current 3379 directory, its meaning depends on whether `ln' or `ln -s' is used. 3380 To safely create links using `$(LN_S)', either find out which form 3381 is used and adjust the arguments, or always invoke `ln' in the 3382 directory where the link is to be created. 3383 3384 In other words, it does not work to do: 3385 $(LN_S) foo /x/bar 3386 3387 Instead, do: 3388 3389 (cd /x && $(LN_S) foo bar) 3390 3391 -- Macro: AC_PROG_RANLIB 3392 Set output variable `RANLIB' to `ranlib' if `ranlib' is found, and 3393 otherwise to `:' (do nothing). 3394 3395 -- Macro: AC_PROG_SED 3396 Set output variable `SED' to a Sed implementation that conforms to 3397 Posix and does not have arbitrary length limits. Report an error 3398 if no acceptable Sed is found. *Note Limitations of Usual Tools: 3399 sed, for more information about portability problems with Sed. 3400 3401 The result of this test can be overridden by setting the `SED' 3402 variable and is cached in the `ac_cv_path_SED' variable. 3403 3404 -- Macro: AC_PROG_YACC 3405 If `bison' is found, set output variable `YACC' to `bison -y'. 3406 Otherwise, if `byacc' is found, set `YACC' to `byacc'. Otherwise 3407 set `YACC' to `yacc'. The result of this test can be influenced 3408 by setting the variable `YACC' or the cache variable 3409 `ac_cv_prog_YACC'. 3410 3411 3412File: autoconf.info, Node: Generic Programs, Prev: Particular Programs, Up: Alternative Programs 3413 34145.2.2 Generic Program and File Checks 3415------------------------------------- 3416 3417These macros are used to find programs not covered by the "particular" 3418test macros. If you need to check the behavior of a program as well as 3419find out whether it is present, you have to write your own test for it 3420(*note Writing Tests::). By default, these macros use the environment 3421variable `PATH'. If you need to check for a program that might not be 3422in the user's `PATH', you can pass a modified path to use instead, like 3423this: 3424 3425 AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd], 3426 [$PATH$PATH_SEPARATOR/usr/libexec$PATH_SEPARATOR]dnl 3427 [/usr/sbin$PATH_SEPARATOR/usr/etc$PATH_SEPARATOR/etc]) 3428 3429 You are strongly encouraged to declare the VARIABLE passed to 3430`AC_CHECK_PROG' etc. as precious. *Note Setting Output Variables::, 3431`AC_ARG_VAR', for more details. 3432 3433 -- Macro: AC_CHECK_PROG (VARIABLE, PROG-TO-CHECK-FOR, VALUE-IF-FOUND, 3434 [VALUE-IF-NOT-FOUND], [PATH = `$PATH'], [REJECT]) 3435 Check whether program PROG-TO-CHECK-FOR exists in PATH. If it is 3436 found, set VARIABLE to VALUE-IF-FOUND, otherwise to 3437 VALUE-IF-NOT-FOUND, if given. Always pass over REJECT (an 3438 absolute file name) even if it is the first found in the search 3439 path; in that case, set VARIABLE using the absolute file name of 3440 the PROG-TO-CHECK-FOR found that is not REJECT. If VARIABLE was 3441 already set, do nothing. Calls `AC_SUBST' for VARIABLE. The 3442 result of this test can be overridden by setting the VARIABLE 3443 variable or the cache variable `ac_cv_prog_VARIABLE'. 3444 3445 -- Macro: AC_CHECK_PROGS (VARIABLE, PROGS-TO-CHECK-FOR, 3446 [VALUE-IF-NOT-FOUND], [PATH = `$PATH']) 3447 Check for each program in the blank-separated list 3448 PROGS-TO-CHECK-FOR existing in the PATH. If one is found, set 3449 VARIABLE to the name of that program. Otherwise, continue 3450 checking the next program in the list. If none of the programs in 3451 the list are found, set VARIABLE to VALUE-IF-NOT-FOUND; if 3452 VALUE-IF-NOT-FOUND is not specified, the value of VARIABLE is not 3453 changed. Calls `AC_SUBST' for VARIABLE. The result of this test 3454 can be overridden by setting the VARIABLE variable or the cache 3455 variable `ac_cv_prog_VARIABLE'. 3456 3457 -- Macro: AC_CHECK_TARGET_TOOL (VARIABLE, PROG-TO-CHECK-FOR, 3458 [VALUE-IF-NOT-FOUND], [PATH = `$PATH']) 3459 Like `AC_CHECK_PROG', but first looks for PROG-TO-CHECK-FOR with a 3460 prefix of the target type as determined by `AC_CANONICAL_TARGET', 3461 followed by a dash (*note Canonicalizing::). If the tool cannot 3462 be found with a prefix, and if the build and target types are 3463 equal, then it is also searched for without a prefix. 3464 3465 As noted in *note Specifying Target Triplets::, the target is 3466 rarely specified, because most of the time it is the same as the 3467 host: it is the type of system for which any compiler tool in the 3468 package produces code. What this macro looks for is, for example, 3469 _a tool (assembler, linker, etc.) that the compiler driver (`gcc' 3470 for the GNU C Compiler) uses to produce objects, archives or 3471 executables_. 3472 3473 -- Macro: AC_CHECK_TOOL (VARIABLE, PROG-TO-CHECK-FOR, 3474 [VALUE-IF-NOT-FOUND], [PATH = `$PATH']) 3475 Like `AC_CHECK_PROG', but first looks for PROG-TO-CHECK-FOR with a 3476 prefix of the host type as specified by `--host', followed by a 3477 dash. For example, if the user runs `configure --build=x86_64-gnu 3478 --host=i386-gnu', then this call: 3479 AC_CHECK_TOOL([RANLIB], [ranlib], [:]) 3480 sets `RANLIB' to `i386-gnu-ranlib' if that program exists in PATH, 3481 or otherwise to `ranlib' if that program exists in PATH, or to `:' 3482 if neither program exists. 3483 3484 When cross-compiling, this macro will issue a warning if no program 3485 prefixed with the host type could be found. For more information, 3486 see *note Specifying Target Triplets::. 3487 3488 -- Macro: AC_CHECK_TARGET_TOOLS (VARIABLE, PROGS-TO-CHECK-FOR, 3489 [VALUE-IF-NOT-FOUND], [PATH = `$PATH']) 3490 Like `AC_CHECK_TARGET_TOOL', each of the tools in the list 3491 PROGS-TO-CHECK-FOR are checked with a prefix of the target type as 3492 determined by `AC_CANONICAL_TARGET', followed by a dash (*note 3493 Canonicalizing::). If none of the tools can be found with a 3494 prefix, and if the build and target types are equal, then the 3495 first one without a prefix is used. If a tool is found, set 3496 VARIABLE to the name of that program. If none of the tools in the 3497 list are found, set VARIABLE to VALUE-IF-NOT-FOUND; if 3498 VALUE-IF-NOT-FOUND is not specified, the value of VARIABLE is not 3499 changed. Calls `AC_SUBST' for VARIABLE. 3500 3501 -- Macro: AC_CHECK_TOOLS (VARIABLE, PROGS-TO-CHECK-FOR, 3502 [VALUE-IF-NOT-FOUND], [PATH = `$PATH']) 3503 Like `AC_CHECK_TOOL', each of the tools in the list 3504 PROGS-TO-CHECK-FOR are checked with a prefix of the host type as 3505 determined by `AC_CANONICAL_HOST', followed by a dash (*note 3506 Canonicalizing::). If none of the tools can be found with a 3507 prefix, then the first one without a prefix is used. If a tool is 3508 found, set VARIABLE to the name of that program. If none of the 3509 tools in the list are found, set VARIABLE to VALUE-IF-NOT-FOUND; if 3510 VALUE-IF-NOT-FOUND is not specified, the value of VARIABLE is not 3511 changed. Calls `AC_SUBST' for VARIABLE. 3512 3513 When cross-compiling, this macro will issue a warning if no program 3514 prefixed with the host type could be found. For more information, 3515 see *note Specifying Target Triplets::. 3516 3517 -- Macro: AC_PATH_PROG (VARIABLE, PROG-TO-CHECK-FOR, 3518 [VALUE-IF-NOT-FOUND], [PATH = `$PATH']) 3519 Like `AC_CHECK_PROG', but set VARIABLE to the absolute name of 3520 PROG-TO-CHECK-FOR if found. The result of this test can be 3521 overridden by setting the VARIABLE variable. A positive result of 3522 this test is cached in the `ac_cv_path_VARIABLE' variable. 3523 3524 -- Macro: AC_PATH_PROGS (VARIABLE, PROGS-TO-CHECK-FOR, 3525 [VALUE-IF-NOT-FOUND], [PATH = `$PATH']) 3526 Like `AC_CHECK_PROGS', but if any of PROGS-TO-CHECK-FOR are found, 3527 set VARIABLE to the absolute name of the program found. The 3528 result of this test can be overridden by setting the VARIABLE 3529 variable. A positive result of this test is cached in the 3530 `ac_cv_path_VARIABLE' variable. 3531 3532 -- Macro: AC_PATH_PROGS_FEATURE_CHECK (VARIABLE, PROGS-TO-CHECK-FOR, 3533 FEATURE-TEST, [ACTION-IF-NOT-FOUND], [PATH = `$PATH']) 3534 This macro was introduced in Autoconf 2.62. If VARIABLE is not 3535 empty, then set the cache variable `ac_cv_path_VARIABLE' to its 3536 value. Otherwise, check for each program in the blank-separated 3537 list PROGS-TO-CHECK-FOR existing in PATH. For each program found, 3538 execute FEATURE-TEST with `ac_path_VARIABLE' set to the absolute 3539 name of the candidate program. If no invocation of FEATURE-TEST 3540 sets the shell variable `ac_cv_path_VARIABLE', then 3541 ACTION-IF-NOT-FOUND is executed. FEATURE-TEST will be run even 3542 when `ac_cv_path_VARIABLE' is set, to provide the ability to 3543 choose a better candidate found later in PATH; to accept the 3544 current setting and bypass all further checks, FEATURE-TEST can 3545 execute `ac_path_VARIABLE_found=:'. 3546 3547 Note that this macro has some subtle differences from 3548 `AC_CHECK_PROGS'. It is designed to be run inside `AC_CACHE_VAL', 3549 therefore, it should have no side effects. In particular, 3550 VARIABLE is not set to the final value of `ac_cv_path_VARIABLE', 3551 nor is `AC_SUBST' automatically run. Also, on failure, any action 3552 can be performed, whereas `AC_CHECK_PROGS' only performs 3553 `VARIABLE=VALUE-IF-NOT-FOUND'. 3554 3555 Here is an example, similar to what Autoconf uses in its own 3556 configure script. It will search for an implementation of `m4' 3557 that supports the `indir' builtin, even if it goes by the name 3558 `gm4' or is not the first implementation on `PATH'. 3559 3560 AC_CACHE_CHECK([for m4 that supports indir], [ac_cv_path_M4], 3561 [AC_PATH_PROGS_FEATURE_CHECK([M4], [m4 gm4], 3562 [[m4out=`echo 'changequote([,])indir([divnum])' | $ac_path_M4` 3563 test "x$m4out" = x0 \ 3564 && ac_cv_path_M4=$ac_path_M4 ac_path_M4_found=:]], 3565 [AC_MSG_ERROR([could not find m4 that supports indir])])]) 3566 AC_SUBST([M4], [$ac_cv_path_M4]) 3567 3568 -- Macro: AC_PATH_TARGET_TOOL (VARIABLE, PROG-TO-CHECK-FOR, 3569 [VALUE-IF-NOT-FOUND], [PATH = `$PATH']) 3570 Like `AC_CHECK_TARGET_TOOL', but set VARIABLE to the absolute name 3571 of the program if it is found. 3572 3573 -- Macro: AC_PATH_TOOL (VARIABLE, PROG-TO-CHECK-FOR, 3574 [VALUE-IF-NOT-FOUND], [PATH = `$PATH']) 3575 Like `AC_CHECK_TOOL', but set VARIABLE to the absolute name of the 3576 program if it is found. 3577 3578 When cross-compiling, this macro will issue a warning if no program 3579 prefixed with the host type could be found. For more information, 3580 see *note Specifying Target Triplets::. 3581 3582 3583File: autoconf.info, Node: Files, Next: Libraries, Prev: Alternative Programs, Up: Existing Tests 3584 35855.3 Files 3586========= 3587 3588You might also need to check for the existence of files. Before using 3589these macros, ask yourself whether a runtime test might not be a better 3590solution. Be aware that, like most Autoconf macros, they test a feature 3591of the host machine, and therefore, they die when cross-compiling. 3592 3593 -- Macro: AC_CHECK_FILE (FILE, [ACTION-IF-FOUND], 3594 [ACTION-IF-NOT-FOUND]) 3595 Check whether file FILE exists on the native system. If it is 3596 found, execute ACTION-IF-FOUND, otherwise do ACTION-IF-NOT-FOUND, 3597 if given. The result of this test is cached in the 3598 `ac_cv_file_FILE' variable, with characters not suitable for a 3599 variable name mapped to underscores. 3600 3601 -- Macro: AC_CHECK_FILES (FILES, [ACTION-IF-FOUND], 3602 [ACTION-IF-NOT-FOUND]) 3603 Executes `AC_CHECK_FILE' once for each file listed in FILES. 3604 Additionally, defines `HAVE_FILE' (*note Standard Symbols::) for 3605 each file found. The results of each test are cached in the 3606 `ac_cv_file_FILE' variable, with characters not suitable for a 3607 variable name mapped to underscores. 3608 3609 3610File: autoconf.info, Node: Libraries, Next: Library Functions, Prev: Files, Up: Existing Tests 3611 36125.4 Library Files 3613================= 3614 3615The following macros check for the presence of certain C, C++, Fortran, 3616or Go library archive files. 3617 3618 -- Macro: AC_CHECK_LIB (LIBRARY, FUNCTION, [ACTION-IF-FOUND], 3619 [ACTION-IF-NOT-FOUND], [OTHER-LIBRARIES]) 3620 Test whether the library LIBRARY is available by trying to link a 3621 test program that calls function FUNCTION with the library. 3622 FUNCTION should be a function provided by the library. Use the 3623 base name of the library; e.g., to check for `-lmp', use `mp' as 3624 the LIBRARY argument. 3625 3626 ACTION-IF-FOUND is a list of shell commands to run if the link 3627 with the library succeeds; ACTION-IF-NOT-FOUND is a list of shell 3628 commands to run if the link fails. If ACTION-IF-FOUND is not 3629 specified, the default action prepends `-lLIBRARY' to `LIBS' and 3630 defines `HAVE_LIBLIBRARY' (in all capitals). This macro is 3631 intended to support building `LIBS' in a right-to-left 3632 (least-dependent to most-dependent) fashion such that library 3633 dependencies are satisfied as a natural side effect of consecutive 3634 tests. Linkers are sensitive to library ordering so the order in 3635 which `LIBS' is generated is important to reliable detection of 3636 libraries. 3637 3638 If linking with LIBRARY results in unresolved symbols that would 3639 be resolved by linking with additional libraries, give those 3640 libraries as the OTHER-LIBRARIES argument, separated by spaces: 3641 e.g., `-lXt -lX11'. Otherwise, this macro may fail to detect that 3642 LIBRARY is present, because linking the test program can fail with 3643 unresolved symbols. The OTHER-LIBRARIES argument should be 3644 limited to cases where it is desirable to test for one library in 3645 the presence of another that is not already in `LIBS'. 3646 3647 `AC_CHECK_LIB' requires some care in usage, and should be avoided 3648 in some common cases. Many standard functions like `gethostbyname' 3649 appear in the standard C library on some hosts, and in special 3650 libraries like `nsl' on other hosts. On some hosts the special 3651 libraries contain variant implementations that you may not want to 3652 use. These days it is normally better to use 3653 `AC_SEARCH_LIBS([gethostbyname], [nsl])' instead of 3654 `AC_CHECK_LIB([nsl], [gethostbyname])'. 3655 3656 The result of this test is cached in the 3657 `ac_cv_lib_LIBRARY_FUNCTION' variable. 3658 3659 -- Macro: AC_SEARCH_LIBS (FUNCTION, SEARCH-LIBS, [ACTION-IF-FOUND], 3660 [ACTION-IF-NOT-FOUND], [OTHER-LIBRARIES]) 3661 Search for a library defining FUNCTION if it's not already 3662 available. This equates to calling 3663 `AC_LINK_IFELSE([AC_LANG_CALL([], [FUNCTION])])' first with no 3664 libraries, then for each library listed in SEARCH-LIBS. 3665 3666 Prepend `-lLIBRARY' to `LIBS' for the first library found to 3667 contain FUNCTION, and run ACTION-IF-FOUND. If the function is not 3668 found, run ACTION-IF-NOT-FOUND. 3669 3670 If linking with LIBRARY results in unresolved symbols that would 3671 be resolved by linking with additional libraries, give those 3672 libraries as the OTHER-LIBRARIES argument, separated by spaces: 3673 e.g., `-lXt -lX11'. Otherwise, this macro fails to detect that 3674 FUNCTION is present, because linking the test program always fails 3675 with unresolved symbols. 3676 3677 The result of this test is cached in the `ac_cv_search_FUNCTION' 3678 variable as `none required' if FUNCTION is already available, as 3679 `no' if no library containing FUNCTION was found, otherwise as the 3680 `-lLIBRARY' option that needs to be prepended to `LIBS'. 3681 3682 3683File: autoconf.info, Node: Library Functions, Next: Header Files, Prev: Libraries, Up: Existing Tests 3684 36855.5 Library Functions 3686===================== 3687 3688The following macros check for particular C library functions. If 3689there is no macro specifically defined to check for a function you need, 3690and you don't need to check for any special properties of it, then you 3691can use one of the general function-check macros. 3692 3693* Menu: 3694 3695* Function Portability:: Pitfalls with usual functions 3696* Particular Functions:: Special handling to find certain functions 3697* Generic Functions:: How to find other functions 3698 3699 3700File: autoconf.info, Node: Function Portability, Next: Particular Functions, Up: Library Functions 3701 37025.5.1 Portability of C Functions 3703-------------------------------- 3704 3705Most usual functions can either be missing, or be buggy, or be limited 3706on some architectures. This section tries to make an inventory of these 3707portability issues. By definition, this list always requires 3708additions. A much more complete list is maintained by the Gnulib 3709project (*note Gnulib::), covering *note Current Posix Functions: 3710(gnulib)Function Substitutes, *note Legacy Functions: (gnulib)Legacy 3711Function Substitutes, and *note Glibc Functions: (gnulib)Glibc Function 3712Substitutes. Please help us keep the gnulib list as complete as 3713possible. 3714 3715`exit' 3716 On ancient hosts, `exit' returned `int'. This is because `exit' 3717 predates `void', and there was a long tradition of it returning 3718 `int'. 3719 3720 On current hosts, the problem more likely is that `exit' is not 3721 declared, due to C++ problems of some sort or another. For this 3722 reason we suggest that test programs not invoke `exit', but return 3723 from `main' instead. 3724 3725`free' 3726 The C standard says a call `free (NULL)' does nothing, but some 3727 old systems don't support this (e.g., NextStep). 3728 3729`isinf' 3730`isnan' 3731 The C99 standard says that `isinf' and `isnan' are macros. On 3732 some systems just macros are available (e.g., HP-UX and Solaris 3733 10), on some systems both macros and functions (e.g., glibc 3734 2.3.2), and on some systems only functions (e.g., IRIX 6 and 3735 Solaris 9). In some cases these functions are declared in 3736 nonstandard headers like `<sunmath.h>' and defined in non-default 3737 libraries like `-lm' or `-lsunmath'. 3738 3739 The C99 `isinf' and `isnan' macros work correctly with `long 3740 double' arguments, but pre-C99 systems that use functions 3741 typically assume `double' arguments. On such a system, `isinf' 3742 incorrectly returns true for a finite `long double' argument that 3743 is outside the range of `double'. 3744 3745 The best workaround for these issues is to use gnulib modules 3746 `isinf' and `isnan' (*note Gnulib::). But a lighter weight 3747 solution involves code like the following. 3748 3749 #include <math.h> 3750 3751 #ifndef isnan 3752 # define isnan(x) \ 3753 (sizeof (x) == sizeof (long double) ? isnan_ld (x) \ 3754 : sizeof (x) == sizeof (double) ? isnan_d (x) \ 3755 : isnan_f (x)) 3756 static inline int isnan_f (float x) { return x != x; } 3757 static inline int isnan_d (double x) { return x != x; } 3758 static inline int isnan_ld (long double x) { return x != x; } 3759 #endif 3760 3761 #ifndef isinf 3762 # define isinf(x) \ 3763 (sizeof (x) == sizeof (long double) ? isinf_ld (x) \ 3764 : sizeof (x) == sizeof (double) ? isinf_d (x) \ 3765 : isinf_f (x)) 3766 static inline int isinf_f (float x) 3767 { return !isnan (x) && isnan (x - x); } 3768 static inline int isinf_d (double x) 3769 { return !isnan (x) && isnan (x - x); } 3770 static inline int isinf_ld (long double x) 3771 { return !isnan (x) && isnan (x - x); } 3772 #endif 3773 3774 Use `AC_C_INLINE' (*note C Compiler::) so that this code works on 3775 compilers that lack the `inline' keyword. Some optimizing 3776 compilers mishandle these definitions, but systems with that bug 3777 typically have many other floating point corner-case compliance 3778 problems anyway, so it's probably not worth worrying about. 3779 3780`malloc' 3781 The C standard says a call `malloc (0)' is implementation 3782 dependent. It can return either `NULL' or a new non-null pointer. 3783 The latter is more common (e.g., the GNU C Library) but is by no 3784 means universal. `AC_FUNC_MALLOC' can be used to insist on 3785 non-`NULL' (*note Particular Functions::). 3786 3787`putenv' 3788 Posix prefers `setenv' to `putenv'; among other things, `putenv' 3789 is not required of all Posix implementations, but `setenv' is. 3790 3791 Posix specifies that `putenv' puts the given string directly in 3792 `environ', but some systems make a copy of it instead (e.g., glibc 3793 2.0, or BSD). And when a copy is made, `unsetenv' might not free 3794 it, causing a memory leak (e.g., FreeBSD 4). 3795 3796 On some systems `putenv ("FOO")' removes `FOO' from the 3797 environment, but this is not standard usage and it dumps core on 3798 some systems (e.g., AIX). 3799 3800 On MinGW, a call `putenv ("FOO=")' removes `FOO' from the 3801 environment, rather than inserting it with an empty value. 3802 3803`realloc' 3804 The C standard says a call `realloc (NULL, size)' is equivalent to 3805 `malloc (size)', but some old systems don't support this (e.g., 3806 NextStep). 3807 3808`signal' handler 3809 Normally `signal' takes a handler function with a return type of 3810 `void', but some old systems required `int' instead. Any actual 3811 `int' value returned is not used; this is only a difference in the 3812 function prototype demanded. 3813 3814 All systems we know of in current use return `void'. The `int' 3815 was to support K&R C, where of course `void' is not available. 3816 The obsolete macro `AC_TYPE_SIGNAL' (*note AC_TYPE_SIGNAL::) can 3817 be used to establish the correct type in all cases. 3818 3819 In most cases, it is more robust to use `sigaction' when it is 3820 available, rather than `signal'. 3821 3822`snprintf' 3823 The C99 standard says that if the output array isn't big enough 3824 and if no other errors occur, `snprintf' and `vsnprintf' truncate 3825 the output and return the number of bytes that ought to have been 3826 produced. Some older systems return the truncated length (e.g., 3827 GNU C Library 2.0.x or IRIX 6.5), some a negative value (e.g., 3828 earlier GNU C Library versions), and some the buffer length 3829 without truncation (e.g., 32-bit Solaris 7). Also, some buggy 3830 older systems ignore the length and overrun the buffer (e.g., 3831 64-bit Solaris 7). 3832 3833`sprintf' 3834 The C standard says `sprintf' and `vsprintf' return the number of 3835 bytes written. On some ancient systems (SunOS 4 for instance) 3836 they return the buffer pointer instead, but these no longer need 3837 to be worried about. 3838 3839`sscanf' 3840 On various old systems, e.g., HP-UX 9, `sscanf' requires that its 3841 input string be writable (though it doesn't actually change it). 3842 This can be a problem when using `gcc' since it normally puts 3843 constant strings in read-only memory (*note Incompatibilities of 3844 GCC: (gcc)Incompatibilities.). Apparently in some cases even 3845 having format strings read-only can be a problem. 3846 3847`strerror_r' 3848 Posix specifies that `strerror_r' returns an `int', but many 3849 systems (e.g., GNU C Library version 2.2.4) provide a different 3850 version returning a `char *'. `AC_FUNC_STRERROR_R' can detect 3851 which is in use (*note Particular Functions::). 3852 3853`strnlen' 3854 AIX 4.3 provides a broken version which produces the following 3855 results: 3856 3857 strnlen ("foobar", 0) = 0 3858 strnlen ("foobar", 1) = 3 3859 strnlen ("foobar", 2) = 2 3860 strnlen ("foobar", 3) = 1 3861 strnlen ("foobar", 4) = 0 3862 strnlen ("foobar", 5) = 6 3863 strnlen ("foobar", 6) = 6 3864 strnlen ("foobar", 7) = 6 3865 strnlen ("foobar", 8) = 6 3866 strnlen ("foobar", 9) = 6 3867 3868`sysconf' 3869 `_SC_PAGESIZE' is standard, but some older systems (e.g., HP-UX 9) 3870 have `_SC_PAGE_SIZE' instead. This can be tested with `#ifdef'. 3871 3872`unlink' 3873 The Posix spec says that `unlink' causes the given file to be 3874 removed only after there are no more open file handles for it. 3875 Some non-Posix hosts have trouble with this requirement, though, 3876 and some DOS variants even corrupt the file system. 3877 3878`unsetenv' 3879 On MinGW, `unsetenv' is not available, but a variable `FOO' can be 3880 removed with a call `putenv ("FOO=")', as described under `putenv' 3881 above. 3882 3883`va_copy' 3884 The C99 standard provides `va_copy' for copying `va_list' 3885 variables. It may be available in older environments too, though 3886 possibly as `__va_copy' (e.g., `gcc' in strict pre-C99 mode). 3887 These can be tested with `#ifdef'. A fallback to `memcpy (&dst, 3888 &src, sizeof (va_list))' gives maximum portability. 3889 3890`va_list' 3891 `va_list' is not necessarily just a pointer. It can be a `struct' 3892 (e.g., `gcc' on Alpha), which means `NULL' is not portable. Or it 3893 can be an array (e.g., `gcc' in some PowerPC configurations), 3894 which means as a function parameter it can be effectively 3895 call-by-reference and library routines might modify the value back 3896 in the caller (e.g., `vsnprintf' in the GNU C Library 2.1). 3897 3898Signed `>>' 3899 Normally the C `>>' right shift of a signed type replicates the 3900 high bit, giving a so-called "arithmetic" shift. But care should 3901 be taken since Standard C doesn't require that behavior. On those 3902 few processors without a native arithmetic shift (for instance Cray 3903 vector systems) zero bits may be shifted in, the same as a shift 3904 of an unsigned type. 3905 3906Integer `/' 3907 C divides signed integers by truncating their quotient toward zero, 3908 yielding the same result as Fortran. However, before C99 the 3909 standard allowed C implementations to take the floor or ceiling of 3910 the quotient in some cases. Hardly any implementations took 3911 advantage of this freedom, though, and it's probably not worth 3912 worrying about this issue nowadays. 3913 3914 3915File: autoconf.info, Node: Particular Functions, Next: Generic Functions, Prev: Function Portability, Up: Library Functions 3916 39175.5.2 Particular Function Checks 3918-------------------------------- 3919 3920These macros check for particular C functions--whether they exist, and 3921in some cases how they respond when given certain arguments. 3922 3923 -- Macro: AC_FUNC_ALLOCA 3924 Check how to get `alloca'. Tries to get a builtin version by 3925 checking for `alloca.h' or the predefined C preprocessor macros 3926 `__GNUC__' and `_AIX'. If this macro finds `alloca.h', it defines 3927 `HAVE_ALLOCA_H'. 3928 3929 If those attempts fail, it looks for the function in the standard C 3930 library. If any of those methods succeed, it defines 3931 `HAVE_ALLOCA'. Otherwise, it sets the output variable `ALLOCA' to 3932 `${LIBOBJDIR}alloca.o' and defines `C_ALLOCA' (so programs can 3933 periodically call `alloca (0)' to garbage collect). This variable 3934 is separate from `LIBOBJS' so multiple programs can share the 3935 value of `ALLOCA' without needing to create an actual library, in 3936 case only some of them use the code in `LIBOBJS'. The 3937 `${LIBOBJDIR}' prefix serves the same purpose as in `LIBOBJS' 3938 (*note AC_LIBOBJ vs LIBOBJS::). 3939 3940 This macro does not try to get `alloca' from the System V R3 3941 `libPW' or the System V R4 `libucb' because those libraries 3942 contain some incompatible functions that cause trouble. Some 3943 versions do not even contain `alloca' or contain a buggy version. 3944 If you still want to use their `alloca', use `ar' to extract 3945 `alloca.o' from them instead of compiling `alloca.c'. 3946 3947 Source files that use `alloca' should start with a piece of code 3948 like the following, to declare it properly. 3949 3950 #ifdef STDC_HEADERS 3951 # include <stdlib.h> 3952 # include <stddef.h> 3953 #else 3954 # ifdef HAVE_STDLIB_H 3955 # include <stdlib.h> 3956 # endif 3957 #endif 3958 #ifdef HAVE_ALLOCA_H 3959 # include <alloca.h> 3960 #elif !defined alloca 3961 # ifdef __GNUC__ 3962 # define alloca __builtin_alloca 3963 # elif defined _AIX 3964 # define alloca __alloca 3965 # elif defined _MSC_VER 3966 # include <malloc.h> 3967 # define alloca _alloca 3968 # elif !defined HAVE_ALLOCA 3969 # ifdef __cplusplus 3970 extern "C" 3971 # endif 3972 void *alloca (size_t); 3973 # endif 3974 #endif 3975 3976 -- Macro: AC_FUNC_CHOWN 3977 If the `chown' function is available and works (in particular, it 3978 should accept `-1' for `uid' and `gid'), define `HAVE_CHOWN'. The 3979 result of this macro is cached in the `ac_cv_func_chown_works' 3980 variable. 3981 3982 -- Macro: AC_FUNC_CLOSEDIR_VOID 3983 If the `closedir' function does not return a meaningful value, 3984 define `CLOSEDIR_VOID'. Otherwise, callers ought to check its 3985 return value for an error indicator. 3986 3987 Currently this test is implemented by running a test program. When 3988 cross compiling the pessimistic assumption that `closedir' does not 3989 return a meaningful value is made. 3990 3991 The result of this macro is cached in the 3992 `ac_cv_func_closedir_void' variable. 3993 3994 This macro is obsolescent, as `closedir' returns a meaningful value 3995 on current systems. New programs need not use this macro. 3996 3997 -- Macro: AC_FUNC_ERROR_AT_LINE 3998 If the `error_at_line' function is not found, require an 3999 `AC_LIBOBJ' replacement of `error'. 4000 4001 The result of this macro is cached in the `ac_cv_lib_error_at_line' 4002 variable. 4003 4004 The `AC_FUNC_ERROR_AT_LINE' macro is obsolescent. New programs 4005 should use Gnulib's `error' module. *Note Gnulib::. 4006 4007 -- Macro: AC_FUNC_FNMATCH 4008 If the `fnmatch' function conforms to Posix, define 4009 `HAVE_FNMATCH'. Detect common implementation bugs, for example, 4010 the bugs in Solaris 2.4. 4011 4012 Unlike the other specific `AC_FUNC' macros, `AC_FUNC_FNMATCH' does 4013 not replace a broken/missing `fnmatch'. This is for historical 4014 reasons. See `AC_REPLACE_FNMATCH' below. 4015 4016 The result of this macro is cached in the 4017 `ac_cv_func_fnmatch_works' variable. 4018 4019 This macro is obsolescent. New programs should use Gnulib's 4020 `fnmatch-posix' module. *Note Gnulib::. 4021 4022 -- Macro: AC_FUNC_FNMATCH_GNU 4023 Behave like `AC_REPLACE_FNMATCH' (_replace_) but also test whether 4024 `fnmatch' supports GNU extensions. Detect common implementation 4025 bugs, for example, the bugs in the GNU C Library 2.1. 4026 4027 The result of this macro is cached in the `ac_cv_func_fnmatch_gnu' 4028 variable. 4029 4030 This macro is obsolescent. New programs should use Gnulib's 4031 `fnmatch-gnu' module. *Note Gnulib::. 4032 4033 -- Macro: AC_FUNC_FORK 4034 This macro checks for the `fork' and `vfork' functions. If a 4035 working `fork' is found, define `HAVE_WORKING_FORK'. This macro 4036 checks whether `fork' is just a stub by trying to run it. 4037 4038 If `vfork.h' is found, define `HAVE_VFORK_H'. If a working 4039 `vfork' is found, define `HAVE_WORKING_VFORK'. Otherwise, define 4040 `vfork' to be `fork' for backward compatibility with previous 4041 versions of `autoconf'. This macro checks for several known 4042 errors in implementations of `vfork' and considers the system to 4043 not have a working `vfork' if it detects any of them. It is not 4044 considered to be an implementation error if a child's invocation 4045 of `signal' modifies the parent's signal handler, since child 4046 processes rarely change their signal handlers. 4047 4048 Since this macro defines `vfork' only for backward compatibility 4049 with previous versions of `autoconf' you're encouraged to define it 4050 yourself in new code: 4051 #ifndef HAVE_WORKING_VFORK 4052 # define vfork fork 4053 #endif 4054 4055 The results of this macro are cached in the `ac_cv_func_fork_works' 4056 and `ac_cv_func_vfork_works' variables. In order to override the 4057 test, you also need to set the `ac_cv_func_fork' and 4058 `ac_cv_func_vfork' variables. 4059 4060 -- Macro: AC_FUNC_FSEEKO 4061 If the `fseeko' function is available, define `HAVE_FSEEKO'. 4062 Define `_LARGEFILE_SOURCE' if necessary to make the prototype 4063 visible on some systems (e.g., glibc 2.2). Otherwise linkage 4064 problems may occur when compiling with `AC_SYS_LARGEFILE' on 4065 largefile-sensitive systems where `off_t' does not default to a 4066 64bit entity. All systems with `fseeko' also supply `ftello'. 4067 4068 -- Macro: AC_FUNC_GETGROUPS 4069 If the `getgroups' function is available and works (unlike on 4070 Ultrix 4.3, where `getgroups (0, 0)' always fails), define 4071 `HAVE_GETGROUPS'. Set `GETGROUPS_LIBS' to any libraries needed to 4072 get that function. This macro runs `AC_TYPE_GETGROUPS'. 4073 4074 -- Macro: AC_FUNC_GETLOADAVG 4075 Check how to get the system load averages. To perform its tests 4076 properly, this macro needs the file `getloadavg.c'; therefore, be 4077 sure to set the `AC_LIBOBJ' replacement directory properly (see 4078 *note Generic Functions::, `AC_CONFIG_LIBOBJ_DIR'). 4079 4080 If the system has the `getloadavg' function, define 4081 `HAVE_GETLOADAVG', and set `GETLOADAVG_LIBS' to any libraries 4082 necessary to get that function. Also add `GETLOADAVG_LIBS' to 4083 `LIBS'. Otherwise, require an `AC_LIBOBJ' replacement for 4084 `getloadavg' with source code in `DIR/getloadavg.c', and possibly 4085 define several other C preprocessor macros and output variables: 4086 4087 1. Define `C_GETLOADAVG'. 4088 4089 2. Define `SVR4', `DGUX', `UMAX', or `UMAX4_3' if on those 4090 systems. 4091 4092 3. If `nlist.h' is found, define `HAVE_NLIST_H'. 4093 4094 4. If `struct nlist' has an `n_un.n_name' member, define 4095 `HAVE_STRUCT_NLIST_N_UN_N_NAME'. The obsolete symbol 4096 `NLIST_NAME_UNION' is still defined, but do not depend upon 4097 it. 4098 4099 5. Programs may need to be installed set-group-ID (or 4100 set-user-ID) for `getloadavg' to work. In this case, define 4101 `GETLOADAVG_PRIVILEGED', set the output variable `NEED_SETGID' 4102 to `true' (and otherwise to `false'), and set `KMEM_GROUP' to 4103 the name of the group that should own the installed program. 4104 4105 The `AC_FUNC_GETLOADAVG' macro is obsolescent. New programs should 4106 use Gnulib's `getloadavg' module. *Note Gnulib::. 4107 4108 -- Macro: AC_FUNC_GETMNTENT 4109 Check for `getmntent' in the standard C library, and then in the 4110 `sun', `seq', and `gen' libraries, for UNICOS, IRIX 4, PTX, and 4111 UnixWare, respectively. Then, if `getmntent' is available, define 4112 `HAVE_GETMNTENT' and set `ac_cv_func_getmntent' to `yes'. 4113 Otherwise set `ac_cv_func_getmntent' to `no'. 4114 4115 The result of this macro can be overridden by setting the cache 4116 variable `ac_cv_search_getmntent'. 4117 4118 -- Macro: AC_FUNC_GETPGRP 4119 Define `GETPGRP_VOID' if it is an error to pass 0 to `getpgrp'; 4120 this is the Posix behavior. On older BSD systems, you must pass 0 4121 to `getpgrp', as it takes an argument and behaves like Posix's 4122 `getpgid'. 4123 4124 #ifdef GETPGRP_VOID 4125 pid = getpgrp (); 4126 #else 4127 pid = getpgrp (0); 4128 #endif 4129 4130 This macro does not check whether `getpgrp' exists at all; if you 4131 need to work in that situation, first call `AC_CHECK_FUNC' for 4132 `getpgrp'. 4133 4134 The result of this macro is cached in the `ac_cv_func_getpgrp_void' 4135 variable. 4136 4137 This macro is obsolescent, as current systems have a `getpgrp' 4138 whose signature conforms to Posix. New programs need not use this 4139 macro. 4140 4141 -- Macro: AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK 4142 If `link' is a symbolic link, then `lstat' should treat `link/' 4143 the same as `link/.'. However, many older `lstat' implementations 4144 incorrectly ignore trailing slashes. 4145 4146 It is safe to assume that if `lstat' incorrectly ignores trailing 4147 slashes, then other symbolic-link-aware functions like `unlink' 4148 also incorrectly ignore trailing slashes. 4149 4150 If `lstat' behaves properly, define 4151 `LSTAT_FOLLOWS_SLASHED_SYMLINK', otherwise require an `AC_LIBOBJ' 4152 replacement of `lstat'. 4153 4154 The result of this macro is cached in the 4155 `ac_cv_func_lstat_dereferences_slashed_symlink' variable. 4156 4157 The `AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK' macro is obsolescent. 4158 New programs should use Gnulib's `lstat' module. *Note Gnulib::. 4159 4160 -- Macro: AC_FUNC_MALLOC 4161 If the `malloc' function is compatible with the GNU C library 4162 `malloc' (i.e., `malloc (0)' returns a valid pointer), define 4163 `HAVE_MALLOC' to 1. Otherwise define `HAVE_MALLOC' to 0, ask for 4164 an `AC_LIBOBJ' replacement for `malloc', and define `malloc' to 4165 `rpl_malloc' so that the native `malloc' is not used in the main 4166 project. 4167 4168 Typically, the replacement file `malloc.c' should look like (note 4169 the `#undef malloc'): 4170 4171 #include <config.h> 4172 #undef malloc 4173 4174 #include <sys/types.h> 4175 4176 void *malloc (); 4177 4178 /* Allocate an N-byte block of memory from the heap. 4179 If N is zero, allocate a 1-byte block. */ 4180 4181 void * 4182 rpl_malloc (size_t n) 4183 { 4184 if (n == 0) 4185 n = 1; 4186 return malloc (n); 4187 } 4188 4189 The result of this macro is cached in the 4190 `ac_cv_func_malloc_0_nonnull' variable. 4191 4192 -- Macro: AC_FUNC_MBRTOWC 4193 Define `HAVE_MBRTOWC' to 1 if the function `mbrtowc' and the type 4194 `mbstate_t' are properly declared. 4195 4196 The result of this macro is cached in the `ac_cv_func_mbrtowc' 4197 variable. 4198 4199 -- Macro: AC_FUNC_MEMCMP 4200 If the `memcmp' function is not available, or does not work on 4201 8-bit data (like the one on SunOS 4.1.3), or fails when comparing 4202 16 bytes or more and with at least one buffer not starting on a 4203 4-byte boundary (such as the one on NeXT x86 OpenStep), require an 4204 `AC_LIBOBJ' replacement for `memcmp'. 4205 4206 The result of this macro is cached in the 4207 `ac_cv_func_memcmp_working' variable. 4208 4209 This macro is obsolescent, as current systems have a working 4210 `memcmp'. New programs need not use this macro. 4211 4212 -- Macro: AC_FUNC_MKTIME 4213 If the `mktime' function is not available, or does not work 4214 correctly, require an `AC_LIBOBJ' replacement for `mktime'. For 4215 the purposes of this test, `mktime' should conform to the Posix 4216 standard and should be the inverse of `localtime'. 4217 4218 The result of this macro is cached in the 4219 `ac_cv_func_working_mktime' variable. 4220 4221 The `AC_FUNC_MKTIME' macro is obsolescent. New programs should 4222 use Gnulib's `mktime' module. *Note Gnulib::. 4223 4224 -- Macro: AC_FUNC_MMAP 4225 If the `mmap' function exists and works correctly, define 4226 `HAVE_MMAP'. This checks only private fixed mapping of 4227 already-mapped memory. 4228 4229 The result of this macro is cached in the 4230 `ac_cv_func_mmap_fixed_mapped' variable. 4231 4232 -- Macro: AC_FUNC_OBSTACK 4233 If the obstacks are found, define `HAVE_OBSTACK', else require an 4234 `AC_LIBOBJ' replacement for `obstack'. 4235 4236 The result of this macro is cached in the `ac_cv_func_obstack' 4237 variable. 4238 4239 -- Macro: AC_FUNC_REALLOC 4240 If the `realloc' function is compatible with the GNU C library 4241 `realloc' (i.e., `realloc (NULL, 0)' returns a valid pointer), 4242 define `HAVE_REALLOC' to 1. Otherwise define `HAVE_REALLOC' to 0, 4243 ask for an `AC_LIBOBJ' replacement for `realloc', and define 4244 `realloc' to `rpl_realloc' so that the native `realloc' is not 4245 used in the main project. See `AC_FUNC_MALLOC' for details. 4246 4247 The result of this macro is cached in the 4248 `ac_cv_func_realloc_0_nonnull' variable. 4249 4250 -- Macro: AC_FUNC_SELECT_ARGTYPES 4251 Determines the correct type to be passed for each of the `select' 4252 function's arguments, and defines those types in 4253 `SELECT_TYPE_ARG1', `SELECT_TYPE_ARG234', and `SELECT_TYPE_ARG5' 4254 respectively. `SELECT_TYPE_ARG1' defaults to `int', 4255 `SELECT_TYPE_ARG234' defaults to `int *', and `SELECT_TYPE_ARG5' 4256 defaults to `struct timeval *'. 4257 4258 This macro is obsolescent, as current systems have a `select' whose 4259 signature conforms to Posix. New programs need not use this macro. 4260 4261 -- Macro: AC_FUNC_SETPGRP 4262 If `setpgrp' takes no argument (the Posix version), define 4263 `SETPGRP_VOID'. Otherwise, it is the BSD version, which takes two 4264 process IDs as arguments. This macro does not check whether 4265 `setpgrp' exists at all; if you need to work in that situation, 4266 first call `AC_CHECK_FUNC' for `setpgrp'. 4267 4268 The result of this macro is cached in the `ac_cv_func_setpgrp_void' 4269 variable. 4270 4271 This macro is obsolescent, as current systems have a `setpgrp' 4272 whose signature conforms to Posix. New programs need not use this 4273 macro. 4274 4275 -- Macro: AC_FUNC_STAT 4276 -- Macro: AC_FUNC_LSTAT 4277 Determine whether `stat' or `lstat' have the bug that it succeeds 4278 when given the zero-length file name as argument. The `stat' and 4279 `lstat' from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do this. 4280 4281 If it does, then define `HAVE_STAT_EMPTY_STRING_BUG' (or 4282 `HAVE_LSTAT_EMPTY_STRING_BUG') and ask for an `AC_LIBOBJ' 4283 replacement of it. 4284 4285 The results of these macros are cached in the 4286 `ac_cv_func_stat_empty_string_bug' and the 4287 `ac_cv_func_lstat_empty_string_bug' variables, respectively. 4288 4289 These macros are obsolescent, as no current systems have the bug. 4290 New programs need not use these macros. 4291 4292 -- Macro: AC_FUNC_STRCOLL 4293 If the `strcoll' function exists and works correctly, define 4294 `HAVE_STRCOLL'. This does a bit more than 4295 `AC_CHECK_FUNCS(strcoll)', because some systems have incorrect 4296 definitions of `strcoll' that should not be used. 4297 4298 The result of this macro is cached in the 4299 `ac_cv_func_strcoll_works' variable. 4300 4301 -- Macro: AC_FUNC_STRERROR_R 4302 If `strerror_r' is available, define `HAVE_STRERROR_R', and if it 4303 is declared, define `HAVE_DECL_STRERROR_R'. If it returns a `char 4304 *' message, define `STRERROR_R_CHAR_P'; otherwise it returns an 4305 `int' error number. The Thread-Safe Functions option of Posix 4306 requires `strerror_r' to return `int', but many systems 4307 (including, for example, version 2.2.4 of the GNU C Library) 4308 return a `char *' value that is not necessarily equal to the 4309 buffer argument. 4310 4311 The result of this macro is cached in the 4312 `ac_cv_func_strerror_r_char_p' variable. 4313 4314 -- Macro: AC_FUNC_STRFTIME 4315 Check for `strftime' in the `intl' library, for SCO Unix. Then, 4316 if `strftime' is available, define `HAVE_STRFTIME'. 4317 4318 This macro is obsolescent, as no current systems require the `intl' 4319 library for `strftime'. New programs need not use this macro. 4320 4321 -- Macro: AC_FUNC_STRTOD 4322 If the `strtod' function does not exist or doesn't work correctly, 4323 ask for an `AC_LIBOBJ' replacement of `strtod'. In this case, 4324 because `strtod.c' is likely to need `pow', set the output 4325 variable `POW_LIB' to the extra library needed. 4326 4327 This macro caches its result in the `ac_cv_func_strtod' variable 4328 and depends upon the result in the `ac_cv_func_pow' variable. 4329 4330 The `AC_FUNC_STRTOD' macro is obsolescent. New programs should 4331 use Gnulib's `strtod' module. *Note Gnulib::. 4332 4333 -- Macro: AC_FUNC_STRTOLD 4334 If the `strtold' function exists and conforms to C99, define 4335 `HAVE_STRTOLD'. 4336 4337 This macro caches its result in the `ac_cv_func_strtold' variable. 4338 4339 -- Macro: AC_FUNC_STRNLEN 4340 If the `strnlen' function is not available, or is buggy (like the 4341 one from AIX 4.3), require an `AC_LIBOBJ' replacement for it. 4342 4343 This macro caches its result in the `ac_cv_func_strnlen_working' 4344 variable. 4345 4346 -- Macro: AC_FUNC_UTIME_NULL 4347 If `utime (FILE, NULL)' sets FILE's timestamp to the present, 4348 define `HAVE_UTIME_NULL'. 4349 4350 This macro caches its result in the `ac_cv_func_utime_null' 4351 variable. 4352 4353 This macro is obsolescent, as all current systems have a `utime' 4354 that behaves this way. New programs need not use this macro. 4355 4356 -- Macro: AC_FUNC_VPRINTF 4357 If `vprintf' is found, define `HAVE_VPRINTF'. Otherwise, if 4358 `_doprnt' is found, define `HAVE_DOPRNT'. (If `vprintf' is 4359 available, you may assume that `vfprintf' and `vsprintf' are also 4360 available.) 4361 4362 This macro is obsolescent, as all current systems have `vprintf'. 4363 New programs need not use this macro. 4364 4365 -- Macro: AC_REPLACE_FNMATCH 4366 If the `fnmatch' function does not conform to Posix (see 4367 `AC_FUNC_FNMATCH'), ask for its `AC_LIBOBJ' replacement. 4368 4369 The files `fnmatch.c', `fnmatch_loop.c', and `fnmatch_.h' in the 4370 `AC_LIBOBJ' replacement directory are assumed to contain a copy of 4371 the source code of GNU `fnmatch'. If necessary, this source code 4372 is compiled as an `AC_LIBOBJ' replacement, and the `fnmatch_.h' 4373 file is linked to `fnmatch.h' so that it can be included in place 4374 of the system `<fnmatch.h>'. 4375 4376 This macro caches its result in the `ac_cv_func_fnmatch_works' 4377 variable. 4378 4379 This macro is obsolescent, as it assumes the use of particular 4380 source files. New programs should use Gnulib's `fnmatch-posix' 4381 module, which provides this macro along with the source files. 4382 *Note Gnulib::. 4383 4384 4385File: autoconf.info, Node: Generic Functions, Prev: Particular Functions, Up: Library Functions 4386 43875.5.3 Generic Function Checks 4388----------------------------- 4389 4390These macros are used to find functions not covered by the "particular" 4391test macros. If the functions might be in libraries other than the 4392default C library, first call `AC_CHECK_LIB' for those libraries. If 4393you need to check the behavior of a function as well as find out 4394whether it is present, you have to write your own test for it (*note 4395Writing Tests::). 4396 4397 -- Macro: AC_CHECK_FUNC (FUNCTION, [ACTION-IF-FOUND], 4398 [ACTION-IF-NOT-FOUND]) 4399 If C function FUNCTION is available, run shell commands 4400 ACTION-IF-FOUND, otherwise ACTION-IF-NOT-FOUND. If you just want 4401 to define a symbol if the function is available, consider using 4402 `AC_CHECK_FUNCS' instead. This macro checks for functions with C 4403 linkage even when `AC_LANG(C++)' has been called, since C is more 4404 standardized than C++. (*note Language Choice::, for more 4405 information about selecting the language for checks.) 4406 4407 This macro caches its result in the `ac_cv_func_FUNCTION' variable. 4408 4409 -- Macro: AC_CHECK_FUNCS (FUNCTION..., [ACTION-IF-FOUND], 4410 [ACTION-IF-NOT-FOUND]) 4411 For each FUNCTION enumerated in the blank-or-newline-separated 4412 argument list, define `HAVE_FUNCTION' (in all capitals) if it is 4413 available. If ACTION-IF-FOUND is given, it is additional shell 4414 code to execute when one of the functions is found. You can give 4415 it a value of `break' to break out of the loop on the first match. 4416 If ACTION-IF-NOT-FOUND is given, it is executed when one of the 4417 functions is not found. 4418 4419 Results are cached for each FUNCTION as in `AC_CHECK_FUNC'. 4420 4421 -- Macro: AC_CHECK_FUNCS_ONCE (FUNCTION...) 4422 For each FUNCTION enumerated in the blank-or-newline-separated 4423 argument list, define `HAVE_FUNCTION' (in all capitals) if it is 4424 available. This is a once-only variant of `AC_CHECK_FUNCS'. It 4425 generates the checking code at most once, so that `configure' is 4426 smaller and faster; but the checks cannot be conditionalized and 4427 are always done once, early during the `configure' run. 4428 4429 4430 Autoconf follows a philosophy that was formed over the years by those 4431who have struggled for portability: isolate the portability issues in 4432specific files, and then program as if you were in a Posix environment. 4433Some functions may be missing or unfixable, and your package must be 4434ready to replace them. 4435 4436 Suitable replacements for many such problem functions are available 4437from Gnulib (*note Gnulib::). 4438 4439 -- Macro: AC_LIBOBJ (FUNCTION) 4440 Specify that `FUNCTION.c' must be included in the executables to 4441 replace a missing or broken implementation of FUNCTION. 4442 4443 Technically, it adds `FUNCTION.$ac_objext' to the output variable 4444 `LIBOBJS' if it is not already in, and calls `AC_LIBSOURCE' for 4445 `FUNCTION.c'. You should not directly change `LIBOBJS', since 4446 this is not traceable. 4447 4448 -- Macro: AC_LIBSOURCE (FILE) 4449 Specify that FILE might be needed to compile the project. If you 4450 need to know what files might be needed by a `configure.ac', you 4451 should trace `AC_LIBSOURCE'. FILE must be a literal. 4452 4453 This macro is called automatically from `AC_LIBOBJ', but you must 4454 call it explicitly if you pass a shell variable to `AC_LIBOBJ'. In 4455 that case, since shell variables cannot be traced statically, you 4456 must pass to `AC_LIBSOURCE' any possible files that the shell 4457 variable might cause `AC_LIBOBJ' to need. For example, if you 4458 want to pass a variable `$foo_or_bar' to `AC_LIBOBJ' that holds 4459 either `"foo"' or `"bar"', you should do: 4460 4461 AC_LIBSOURCE([foo.c]) 4462 AC_LIBSOURCE([bar.c]) 4463 AC_LIBOBJ([$foo_or_bar]) 4464 4465 There is usually a way to avoid this, however, and you are 4466 encouraged to simply call `AC_LIBOBJ' with literal arguments. 4467 4468 Note that this macro replaces the obsolete `AC_LIBOBJ_DECL', with 4469 slightly different semantics: the old macro took the function name, 4470 e.g., `foo', as its argument rather than the file name. 4471 4472 -- Macro: AC_LIBSOURCES (FILES) 4473 Like `AC_LIBSOURCE', but accepts one or more FILES in a 4474 comma-separated M4 list. Thus, the above example might be 4475 rewritten: 4476 4477 AC_LIBSOURCES([foo.c, bar.c]) 4478 AC_LIBOBJ([$foo_or_bar]) 4479 4480 -- Macro: AC_CONFIG_LIBOBJ_DIR (DIRECTORY) 4481 Specify that `AC_LIBOBJ' replacement files are to be found in 4482 DIRECTORY, a name relative to the top level of the source tree. 4483 The replacement directory defaults to `.', the top level 4484 directory, and the most typical value is `lib', corresponding to 4485 `AC_CONFIG_LIBOBJ_DIR([lib])'. 4486 4487 `configure' might need to know the replacement directory for the 4488 following reasons: (i) some checks use the replacement files, (ii) 4489 some macros bypass broken system headers by installing links to the 4490 replacement headers (iii) when used in conjunction with Automake, 4491 within each makefile, DIRECTORY is used as a relative path from 4492 `$(top_srcdir)' to each object named in `LIBOBJS' and `LTLIBOBJS', 4493 etc. 4494 4495 4496 It is common to merely check for the existence of a function, and ask 4497for its `AC_LIBOBJ' replacement if missing. The following macro is a 4498convenient shorthand. 4499 4500 -- Macro: AC_REPLACE_FUNCS (FUNCTION...) 4501 Like `AC_CHECK_FUNCS', but uses `AC_LIBOBJ(FUNCTION)' as 4502 ACTION-IF-NOT-FOUND. You can declare your replacement function by 4503 enclosing the prototype in `#ifndef HAVE_FUNCTION'. If the system 4504 has the function, it probably declares it in a header file you 4505 should be including, so you shouldn't redeclare it lest your 4506 declaration conflict. 4507 4508 4509File: autoconf.info, Node: Header Files, Next: Declarations, Prev: Library Functions, Up: Existing Tests 4510 45115.6 Header Files 4512================ 4513 4514The following macros check for the presence of certain C header files. 4515If there is no macro specifically defined to check for a header file 4516you need, and you don't need to check for any special properties of it, 4517then you can use one of the general header-file check macros. 4518 4519* Menu: 4520 4521* Header Portability:: Collected knowledge on common headers 4522* Particular Headers:: Special handling to find certain headers 4523* Generic Headers:: How to find other headers 4524 4525 4526File: autoconf.info, Node: Header Portability, Next: Particular Headers, Up: Header Files 4527 45285.6.1 Portability of Headers 4529---------------------------- 4530 4531This section documents some collected knowledge about common headers, 4532and the problems they cause. By definition, this list always requires 4533additions. A much more complete list is maintained by the Gnulib 4534project (*note Gnulib::), covering *note Posix Headers: (gnulib)Header 4535File Substitutes. and *note Glibc Headers: (gnulib)Glibc Header File 4536Substitutes. Please help us keep the gnulib list as complete as 4537possible. 4538 4539`limits.h' 4540 C99 says that `limits.h' defines `LLONG_MIN', `LLONG_MAX', and 4541 `ULLONG_MAX', but many almost-C99 environments (e.g., default GCC 4542 4.0.2 + glibc 2.4) do not define them. 4543 4544`inttypes.h' vs. `stdint.h' 4545 The C99 standard says that `inttypes.h' includes `stdint.h', so 4546 there's no need to include `stdint.h' separately in a standard 4547 environment. Some implementations have `inttypes.h' but not 4548 `stdint.h' (e.g., Solaris 7), but we don't know of any 4549 implementation that has `stdint.h' but not `inttypes.h'. 4550 4551`linux/irda.h' 4552 It requires `linux/types.h' and `sys/socket.h'. 4553 4554`linux/random.h' 4555 It requires `linux/types.h'. 4556 4557`net/if.h' 4558 On Darwin, this file requires that `sys/socket.h' be included 4559 beforehand. One should run: 4560 4561 AC_CHECK_HEADERS([sys/socket.h]) 4562 AC_CHECK_HEADERS([net/if.h], [], [], 4563 [#include <stdio.h> 4564 #ifdef STDC_HEADERS 4565 # include <stdlib.h> 4566 # include <stddef.h> 4567 #else 4568 # ifdef HAVE_STDLIB_H 4569 # include <stdlib.h> 4570 # endif 4571 #endif 4572 #ifdef HAVE_SYS_SOCKET_H 4573 # include <sys/socket.h> 4574 #endif 4575 ]) 4576 4577`netinet/if_ether.h' 4578 On Darwin, this file requires that `stdio.h' and `sys/socket.h' be 4579 included beforehand. One should run: 4580 4581 AC_CHECK_HEADERS([sys/socket.h]) 4582 AC_CHECK_HEADERS([netinet/if_ether.h], [], [], 4583 [#include <stdio.h> 4584 #ifdef STDC_HEADERS 4585 # include <stdlib.h> 4586 # include <stddef.h> 4587 #else 4588 # ifdef HAVE_STDLIB_H 4589 # include <stdlib.h> 4590 # endif 4591 #endif 4592 #ifdef HAVE_SYS_SOCKET_H 4593 # include <sys/socket.h> 4594 #endif 4595 ]) 4596 4597`stdint.h' 4598 See above, item `inttypes.h' vs. `stdint.h'. 4599 4600`stdlib.h' 4601 On many systems (e.g., Darwin), `stdio.h' is a prerequisite. 4602 4603`sys/mount.h' 4604 On FreeBSD 4.8 on ia32 and using gcc version 2.95.4, 4605 `sys/params.h' is a prerequisite. 4606 4607`sys/ptem.h' 4608 On Solaris 8, `sys/stream.h' is a prerequisite. 4609 4610`sys/socket.h' 4611 On Darwin, `stdlib.h' is a prerequisite. 4612 4613`sys/ucred.h' 4614 On Tru64 5.1, `sys/types.h' is a prerequisite. 4615 4616`X11/extensions/scrnsaver.h' 4617 Using XFree86, this header requires `X11/Xlib.h', which is probably 4618 so required that you might not even consider looking for it. 4619 4620 AC_CHECK_HEADERS([X11/extensions/scrnsaver.h], [], [], 4621 [[#include <X11/Xlib.h> 4622 ]]) 4623 4624 4625File: autoconf.info, Node: Particular Headers, Next: Generic Headers, Prev: Header Portability, Up: Header Files 4626 46275.6.2 Particular Header Checks 4628------------------------------ 4629 4630These macros check for particular system header files--whether they 4631exist, and in some cases whether they declare certain symbols. 4632 4633 -- Macro: AC_CHECK_HEADER_STDBOOL 4634 Check whether `stdbool.h' exists and conforms to C99, and cache the 4635 result in the `ac_cv_header_stdbool_h' variable. If the type 4636 `_Bool' is defined, define `HAVE__BOOL' to 1. 4637 4638 This macro is intended for use by Gnulib (*note Gnulib::) and other 4639 packages that supply a substitute `stdbool.h' on platforms lacking 4640 a conforming one. The `AC_HEADER_STDBOOL' macro is better for code 4641 that explicitly checks for `stdbool.h'. 4642 4643 -- Macro: AC_HEADER_ASSERT 4644 Check whether to enable assertions in the style of `assert.h'. 4645 Assertions are enabled by default, but the user can override this 4646 by invoking `configure' with the `--disable-assert' option. 4647 4648 -- Macro: AC_HEADER_DIRENT 4649 Check for the following header files. For the first one that is 4650 found and defines `DIR', define the listed C preprocessor macro: 4651 4652 `dirent.h' `HAVE_DIRENT_H' 4653 `sys/ndir.h' `HAVE_SYS_NDIR_H' 4654 `sys/dir.h' `HAVE_SYS_DIR_H' 4655 `ndir.h' `HAVE_NDIR_H' 4656 4657 The directory-library declarations in your source code should look 4658 something like the following: 4659 4660 #include <sys/types.h> 4661 #ifdef HAVE_DIRENT_H 4662 # include <dirent.h> 4663 # define NAMLEN(dirent) strlen ((dirent)->d_name) 4664 #else 4665 # define dirent direct 4666 # define NAMLEN(dirent) ((dirent)->d_namlen) 4667 # ifdef HAVE_SYS_NDIR_H 4668 # include <sys/ndir.h> 4669 # endif 4670 # ifdef HAVE_SYS_DIR_H 4671 # include <sys/dir.h> 4672 # endif 4673 # ifdef HAVE_NDIR_H 4674 # include <ndir.h> 4675 # endif 4676 #endif 4677 4678 Using the above declarations, the program would declare variables 4679 to be of type `struct dirent', not `struct direct', and would 4680 access the length of a directory entry name by passing a pointer 4681 to a `struct dirent' to the `NAMLEN' macro. 4682 4683 This macro also checks for the SCO Xenix `dir' and `x' libraries. 4684 4685 This macro is obsolescent, as all current systems with directory 4686 libraries have `<dirent.h>'. New programs need not use this macro. 4687 4688 Also see `AC_STRUCT_DIRENT_D_INO' and `AC_STRUCT_DIRENT_D_TYPE' 4689 (*note Particular Structures::). 4690 4691 -- Macro: AC_HEADER_MAJOR 4692 If `sys/types.h' does not define `major', `minor', and `makedev', 4693 but `sys/mkdev.h' does, define `MAJOR_IN_MKDEV'; otherwise, if 4694 `sys/sysmacros.h' does, define `MAJOR_IN_SYSMACROS'. 4695 4696 -- Macro: AC_HEADER_RESOLV 4697 Checks for header `resolv.h', checking for prerequisites first. 4698 To properly use `resolv.h', your code should contain something like 4699 the following: 4700 4701 #ifdef HAVE_SYS_TYPES_H 4702 # include <sys/types.h> 4703 #endif 4704 #ifdef HAVE_NETINET_IN_H 4705 # include <netinet/in.h> /* inet_ functions / structs */ 4706 #endif 4707 #ifdef HAVE_ARPA_NAMESER_H 4708 # include <arpa/nameser.h> /* DNS HEADER struct */ 4709 #endif 4710 #ifdef HAVE_NETDB_H 4711 # include <netdb.h> 4712 #endif 4713 #include <resolv.h> 4714 4715 -- Macro: AC_HEADER_STAT 4716 If the macros `S_ISDIR', `S_ISREG', etc. defined in `sys/stat.h' 4717 do not work properly (returning false positives), define 4718 `STAT_MACROS_BROKEN'. This is the case on Tektronix UTekV, Amdahl 4719 UTS and Motorola System V/88. 4720 4721 This macro is obsolescent, as no current systems have the bug. 4722 New programs need not use this macro. 4723 4724 -- Macro: AC_HEADER_STDBOOL 4725 If `stdbool.h' exists and conforms to C99, define `HAVE_STDBOOL_H' 4726 to 1; if the type `_Bool' is defined, define `HAVE__BOOL' to 1. 4727 To fulfill the C99 requirements, your program could contain the 4728 following code: 4729 4730 #ifdef HAVE_STDBOOL_H 4731 # include <stdbool.h> 4732 #else 4733 # ifndef HAVE__BOOL 4734 # ifdef __cplusplus 4735 typedef bool _Bool; 4736 # else 4737 # define _Bool signed char 4738 # endif 4739 # endif 4740 # define bool _Bool 4741 # define false 0 4742 # define true 1 4743 # define __bool_true_false_are_defined 1 4744 #endif 4745 4746 Alternatively you can use the `stdbool' package of Gnulib (*note 4747 Gnulib::). It simplifies your code so that it can say just 4748 `#include <stdbool.h>', and it adds support for less-common 4749 platforms. 4750 4751 This macro caches its result in the `ac_cv_header_stdbool_h' 4752 variable. 4753 4754 This macro differs from `AC_CHECK_HEADER_STDBOOL' only in that it 4755 defines `HAVE_STDBOOL_H' whereas `AC_CHECK_HEADER_STDBOOL' does 4756 not. 4757 4758 -- Macro: AC_HEADER_STDC 4759 Define `STDC_HEADERS' if the system has C header files conforming 4760 to ANSI C89 (ISO C90). Specifically, this macro checks for 4761 `stdlib.h', `stdarg.h', `string.h', and `float.h'; if the system 4762 has those, it probably has the rest of the C89 header files. This 4763 macro also checks whether `string.h' declares `memchr' (and thus 4764 presumably the other `mem' functions), whether `stdlib.h' declare 4765 `free' (and thus presumably `malloc' and other related functions), 4766 and whether the `ctype.h' macros work on characters with the high 4767 bit set, as the C standard requires. 4768 4769 If you use this macro, your code can refer to `STDC_HEADERS' to 4770 determine whether the system has conforming header files (and 4771 probably C library functions). 4772 4773 This macro caches its result in the `ac_cv_header_stdc' variable. 4774 4775 This macro is obsolescent, as current systems have conforming 4776 header files. New programs need not use this macro. 4777 4778 Nowadays `string.h' is part of the C standard and declares 4779 functions like `strcpy', and `strings.h' is standardized by Posix 4780 and declares BSD functions like `bcopy'; but historically, string 4781 functions were a major sticking point in this area. If you still 4782 want to worry about portability to ancient systems without 4783 standard headers, there is so much variation that it is probably 4784 easier to declare the functions you use than to figure out exactly 4785 what the system header files declare. Some ancient systems 4786 contained a mix of functions from the C standard and from BSD; 4787 some were mostly standard but lacked `memmove'; some defined the 4788 BSD functions as macros in `string.h' or `strings.h'; some had 4789 only the BSD functions but `string.h'; some declared the memory 4790 functions in `memory.h', some in `string.h'; etc. It is probably 4791 sufficient to check for one string function and one memory 4792 function; if the library had the standard versions of those then 4793 it probably had most of the others. If you put the following in 4794 `configure.ac': 4795 4796 # This example is obsolescent. 4797 # Nowadays you can omit these macro calls. 4798 AC_HEADER_STDC 4799 AC_CHECK_FUNCS([strchr memcpy]) 4800 4801 then, in your code, you can use declarations like this: 4802 4803 /* This example is obsolescent. 4804 Nowadays you can just #include <string.h>. */ 4805 #ifdef STDC_HEADERS 4806 # include <string.h> 4807 #else 4808 # ifndef HAVE_STRCHR 4809 # define strchr index 4810 # define strrchr rindex 4811 # endif 4812 char *strchr (), *strrchr (); 4813 # ifndef HAVE_MEMCPY 4814 # define memcpy(d, s, n) bcopy ((s), (d), (n)) 4815 # define memmove(d, s, n) bcopy ((s), (d), (n)) 4816 # endif 4817 #endif 4818 4819 If you use a function like `memchr', `memset', `strtok', or 4820 `strspn', which have no BSD equivalent, then macros don't suffice 4821 to port to ancient hosts; you must provide an implementation of 4822 each function. An easy way to incorporate your implementations 4823 only when needed (since the ones in system C libraries may be hand 4824 optimized) is to, taking `memchr' for example, put it in 4825 `memchr.c' and use `AC_REPLACE_FUNCS([memchr])'. 4826 4827 -- Macro: AC_HEADER_SYS_WAIT 4828 If `sys/wait.h' exists and is compatible with Posix, define 4829 `HAVE_SYS_WAIT_H'. Incompatibility can occur if `sys/wait.h' does 4830 not exist, or if it uses the old BSD `union wait' instead of `int' 4831 to store a status value. If `sys/wait.h' is not Posix compatible, 4832 then instead of including it, define the Posix macros with their 4833 usual interpretations. Here is an example: 4834 4835 #include <sys/types.h> 4836 #ifdef HAVE_SYS_WAIT_H 4837 # include <sys/wait.h> 4838 #endif 4839 #ifndef WEXITSTATUS 4840 # define WEXITSTATUS(stat_val) ((unsigned int) (stat_val) >> 8) 4841 #endif 4842 #ifndef WIFEXITED 4843 # define WIFEXITED(stat_val) (((stat_val) & 255) == 0) 4844 #endif 4845 4846 This macro caches its result in the `ac_cv_header_sys_wait_h' 4847 variable. 4848 4849 This macro is obsolescent, as current systems are compatible with 4850 Posix. New programs need not use this macro. 4851 4852 `_POSIX_VERSION' is defined when `unistd.h' is included on Posix 4853systems. If there is no `unistd.h', it is definitely not a Posix 4854system. However, some non-Posix systems do have `unistd.h'. 4855 4856 The way to check whether the system supports Posix is: 4857 4858 #ifdef HAVE_UNISTD_H 4859 # include <sys/types.h> 4860 # include <unistd.h> 4861 #endif 4862 4863 #ifdef _POSIX_VERSION 4864 /* Code for Posix systems. */ 4865 #endif 4866 4867 -- Macro: AC_HEADER_TIME 4868 If a program may include both `time.h' and `sys/time.h', define 4869 `TIME_WITH_SYS_TIME'. On some ancient systems, `sys/time.h' 4870 included `time.h', but `time.h' was not protected against multiple 4871 inclusion, so programs could not explicitly include both files. 4872 This macro is useful in programs that use, for example, `struct 4873 timeval' as well as `struct tm'. It is best used in conjunction 4874 with `HAVE_SYS_TIME_H', which can be checked for using 4875 `AC_CHECK_HEADERS([sys/time.h])'. 4876 4877 #ifdef TIME_WITH_SYS_TIME 4878 # include <sys/time.h> 4879 # include <time.h> 4880 #else 4881 # ifdef HAVE_SYS_TIME_H 4882 # include <sys/time.h> 4883 # else 4884 # include <time.h> 4885 # endif 4886 #endif 4887 4888 This macro caches its result in the `ac_cv_header_time' variable. 4889 4890 This macro is obsolescent, as current systems can include both 4891 files when they exist. New programs need not use this macro. 4892 4893 -- Macro: AC_HEADER_TIOCGWINSZ 4894 If the use of `TIOCGWINSZ' requires `<sys/ioctl.h>', then define 4895 `GWINSZ_IN_SYS_IOCTL'. Otherwise `TIOCGWINSZ' can be found in 4896 `<termios.h>'. 4897 4898 Use: 4899 4900 #ifdef HAVE_TERMIOS_H 4901 # include <termios.h> 4902 #endif 4903 4904 #ifdef GWINSZ_IN_SYS_IOCTL 4905 # include <sys/ioctl.h> 4906 #endif 4907 4908 4909File: autoconf.info, Node: Generic Headers, Prev: Particular Headers, Up: Header Files 4910 49115.6.3 Generic Header Checks 4912--------------------------- 4913 4914These macros are used to find system header files not covered by the 4915"particular" test macros. If you need to check the contents of a header 4916as well as find out whether it is present, you have to write your own 4917test for it (*note Writing Tests::). 4918 4919 -- Macro: AC_CHECK_HEADER (HEADER-FILE, [ACTION-IF-FOUND], 4920 [ACTION-IF-NOT-FOUND], [INCLUDES]) 4921 If the system header file HEADER-FILE is compilable, execute shell 4922 commands ACTION-IF-FOUND, otherwise execute ACTION-IF-NOT-FOUND. 4923 If you just want to define a symbol if the header file is 4924 available, consider using `AC_CHECK_HEADERS' instead. 4925 4926 INCLUDES is decoded to determine the appropriate include 4927 directives. If omitted or empty, `configure' will check for both 4928 header existence (with the preprocessor) and usability (with the 4929 compiler), using `AC_INCLUDES_DEFAULT' for the compile test. If 4930 there is a discrepancy between the results, a warning is issued to 4931 the user, and the compiler results are favored (*note Present But 4932 Cannot Be Compiled::). In general, favoring the compiler results 4933 means that a header will be treated as not found even though the 4934 file exists, because you did not provide enough prerequisites. 4935 4936 Providing a non-empty INCLUDES argument allows the code to provide 4937 any prerequisites prior to including the header under test; it is 4938 common to use the argument `AC_INCLUDES_DEFAULT' (*note Default 4939 Includes::). With an explicit fourth argument, no preprocessor 4940 test is needed. As a special case, an INCLUDES of exactly `-' 4941 triggers the older preprocessor check, which merely determines 4942 existence of the file in the preprocessor search path; this should 4943 only be used as a last resort (it is safer to determine the actual 4944 prerequisites and perform a compiler check, or else use 4945 `AC_PREPROC_IFELSE' to make it obvious that only a preprocessor 4946 check is desired). 4947 4948 This macro caches its result in the `ac_cv_header_HEADER-FILE' 4949 variable, with characters not suitable for a variable name mapped 4950 to underscores. 4951 4952 -- Macro: AC_CHECK_HEADERS (HEADER-FILE..., [ACTION-IF-FOUND], 4953 [ACTION-IF-NOT-FOUND], [INCLUDES]) 4954 For each given system header file HEADER-FILE in the 4955 blank-separated argument list that exists, define 4956 `HAVE_HEADER-FILE' (in all capitals). If ACTION-IF-FOUND is 4957 given, it is additional shell code to execute when one of the 4958 header files is found. You can give it a value of `break' to 4959 break out of the loop on the first match. If ACTION-IF-NOT-FOUND 4960 is given, it is executed when one of the header files is not found. 4961 4962 INCLUDES is interpreted as in `AC_CHECK_HEADER', in order to 4963 choose the set of preprocessor directives supplied before the 4964 header under test. 4965 4966 This macro caches its result in the `ac_cv_header_HEADER-FILE' 4967 variable, with characters not suitable for a variable name mapped 4968 to underscores. 4969 4970 Previous versions of Autoconf merely checked whether the header was 4971accepted by the preprocessor. This was changed because the old test was 4972inappropriate for typical uses. Headers are typically used to compile, 4973not merely to preprocess, and the old behavior sometimes accepted 4974headers that clashed at compile-time (*note Present But Cannot Be 4975Compiled::). If you need to check whether a header is preprocessable, 4976you can use `AC_PREPROC_IFELSE' (*note Running the Preprocessor::). 4977 4978 Actually requiring a header to compile improves the robustness of the 4979test, but it also requires that you make sure that headers that must be 4980included before the HEADER-FILE be part of the INCLUDES, (*note Default 4981Includes::). If looking for `bar.h', which requires that `foo.h' be 4982included before if it exists, we suggest the following scheme: 4983 4984AC_CHECK_HEADERS([foo.h]) 4985AC_CHECK_HEADERS([bar.h], [], [], 4986[#ifdef HAVE_FOO_H 4987# include <foo.h> 4988#endif 4989]) 4990 4991 The following variant generates smaller, faster `configure' files if 4992you do not need the full power of `AC_CHECK_HEADERS'. 4993 4994 -- Macro: AC_CHECK_HEADERS_ONCE (HEADER-FILE...) 4995 For each given system header file HEADER-FILE in the 4996 blank-separated argument list that exists, define 4997 `HAVE_HEADER-FILE' (in all capitals). This is a once-only variant 4998 of `AC_CHECK_HEADERS'. It generates the checking code at most 4999 once, so that `configure' is smaller and faster; but the checks 5000 cannot be conditionalized and are always done once, early during 5001 the `configure' run. Thus, this macro is only safe for checking 5002 headers that do not have prerequisites beyond what 5003 `AC_INCLUDES_DEFAULT' provides. 5004 5005 5006File: autoconf.info, Node: Declarations, Next: Structures, Prev: Header Files, Up: Existing Tests 5007 50085.7 Declarations 5009================ 5010 5011The following macros check for the declaration of variables and 5012functions. If there is no macro specifically defined to check for a 5013symbol you need, then you can use the general macros (*note Generic 5014Declarations::) or, for more complex tests, you may use 5015`AC_COMPILE_IFELSE' (*note Running the Compiler::). 5016 5017* Menu: 5018 5019* Particular Declarations:: Macros to check for certain declarations 5020* Generic Declarations:: How to find other declarations 5021 5022 5023File: autoconf.info, Node: Particular Declarations, Next: Generic Declarations, Up: Declarations 5024 50255.7.1 Particular Declaration Checks 5026----------------------------------- 5027 5028There are no specific macros for declarations. 5029 5030 5031File: autoconf.info, Node: Generic Declarations, Prev: Particular Declarations, Up: Declarations 5032 50335.7.2 Generic Declaration Checks 5034-------------------------------- 5035 5036These macros are used to find declarations not covered by the 5037"particular" test macros. 5038 5039 -- Macro: AC_CHECK_DECL (SYMBOL, [ACTION-IF-FOUND], 5040 [ACTION-IF-NOT-FOUND], [INCLUDES = `AC_INCLUDES_DEFAULT']) 5041 If SYMBOL (a function, variable, or constant) is not declared in 5042 INCLUDES and a declaration is needed, run the shell commands 5043 ACTION-IF-NOT-FOUND, otherwise ACTION-IF-FOUND. INCLUDES is a 5044 series of include directives, defaulting to `AC_INCLUDES_DEFAULT' 5045 (*note Default Includes::), which are used prior to the 5046 declaration under test. 5047 5048 This macro actually tests whether SYMBOL is defined as a macro or 5049 can be used as an r-value, not whether it is really declared, 5050 because it is much safer to avoid introducing extra declarations 5051 when they are not needed. In order to facilitate use of C++ and 5052 overloaded function declarations, it is possible to specify 5053 function argument types in parentheses for types which can be 5054 zero-initialized: 5055 5056 AC_CHECK_DECL([basename(char *)]) 5057 5058 This macro caches its result in the `ac_cv_have_decl_SYMBOL' 5059 variable, with characters not suitable for a variable name mapped 5060 to underscores. 5061 5062 -- Macro: AC_CHECK_DECLS (SYMBOLS, [ACTION-IF-FOUND], 5063 [ACTION-IF-NOT-FOUND], [INCLUDES = `AC_INCLUDES_DEFAULT']) 5064 For each of the SYMBOLS (_comma_-separated list with optional 5065 function argument types for C++ overloads), define 5066 `HAVE_DECL_SYMBOL' (in all capitals) to `1' if SYMBOL is declared, 5067 otherwise to `0'. If ACTION-IF-NOT-FOUND is given, it is 5068 additional shell code to execute when one of the function 5069 declarations is needed, otherwise ACTION-IF-FOUND is executed. 5070 5071 INCLUDES is a series of include directives, defaulting to 5072 `AC_INCLUDES_DEFAULT' (*note Default Includes::), which are used 5073 prior to the declarations under test. 5074 5075 This macro uses an M4 list as first argument: 5076 AC_CHECK_DECLS([strdup]) 5077 AC_CHECK_DECLS([strlen]) 5078 AC_CHECK_DECLS([malloc, realloc, calloc, free]) 5079 AC_CHECK_DECLS([j0], [], [], [[#include <math.h>]]) 5080 AC_CHECK_DECLS([[basename(char *)], [dirname(char *)]]) 5081 5082 Unlike the other `AC_CHECK_*S' macros, when a SYMBOL is not 5083 declared, `HAVE_DECL_SYMBOL' is defined to `0' instead of leaving 5084 `HAVE_DECL_SYMBOL' undeclared. When you are _sure_ that the check 5085 was performed, use `HAVE_DECL_SYMBOL' in `#if': 5086 5087 #if !HAVE_DECL_SYMBOL 5088 extern char *symbol; 5089 #endif 5090 5091 If the test may have not been performed, however, because it is 5092 safer _not_ to declare a symbol than to use a declaration that 5093 conflicts with the system's one, you should use: 5094 5095 #if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC 5096 void *malloc (size_t *s); 5097 #endif 5098 5099 You fall into the second category only in extreme situations: 5100 either your files may be used without being configured, or they 5101 are used during the configuration. In most cases the traditional 5102 approach is enough. 5103 5104 This macro caches its results in `ac_cv_have_decl_SYMBOL' 5105 variables, with characters not suitable for a variable name mapped 5106 to underscores. 5107 5108 -- Macro: AC_CHECK_DECLS_ONCE (SYMBOLS) 5109 For each of the SYMBOLS (_comma_-separated list), define 5110 `HAVE_DECL_SYMBOL' (in all capitals) to `1' if SYMBOL is declared 5111 in the default include files, otherwise to `0'. This is a 5112 once-only variant of `AC_CHECK_DECLS'. It generates the checking 5113 code at most once, so that `configure' is smaller and faster; but 5114 the checks cannot be conditionalized and are always done once, 5115 early during the `configure' run. 5116 5117 5118File: autoconf.info, Node: Structures, Next: Types, Prev: Declarations, Up: Existing Tests 5119 51205.8 Structures 5121============== 5122 5123The following macros check for the presence of certain members in C 5124structures. If there is no macro specifically defined to check for a 5125member you need, then you can use the general structure-member macros 5126(*note Generic Structures::) or, for more complex tests, you may use 5127`AC_COMPILE_IFELSE' (*note Running the Compiler::). 5128 5129* Menu: 5130 5131* Particular Structures:: Macros to check for certain structure members 5132* Generic Structures:: How to find other structure members 5133 5134 5135File: autoconf.info, Node: Particular Structures, Next: Generic Structures, Up: Structures 5136 51375.8.1 Particular Structure Checks 5138--------------------------------- 5139 5140The following macros check for certain structures or structure members. 5141 5142 -- Macro: AC_STRUCT_DIRENT_D_INO 5143 Perform all the actions of `AC_HEADER_DIRENT' (*note Particular 5144 Headers::). Then, if `struct dirent' contains a `d_ino' member, 5145 define `HAVE_STRUCT_DIRENT_D_INO'. 5146 5147 `HAVE_STRUCT_DIRENT_D_INO' indicates only the presence of `d_ino', 5148 not whether its contents are always reliable. Traditionally, a 5149 zero `d_ino' indicated a deleted directory entry, though current 5150 systems hide this detail from the user and never return zero 5151 `d_ino' values. Many current systems report an incorrect `d_ino' 5152 for a directory entry that is a mount point. 5153 5154 -- Macro: AC_STRUCT_DIRENT_D_TYPE 5155 Perform all the actions of `AC_HEADER_DIRENT' (*note Particular 5156 Headers::). Then, if `struct dirent' contains a `d_type' member, 5157 define `HAVE_STRUCT_DIRENT_D_TYPE'. 5158 5159 -- Macro: AC_STRUCT_ST_BLOCKS 5160 If `struct stat' contains an `st_blocks' member, define 5161 `HAVE_STRUCT_STAT_ST_BLOCKS'. Otherwise, require an `AC_LIBOBJ' 5162 replacement of `fileblocks'. The former name, `HAVE_ST_BLOCKS' is 5163 to be avoided, as its support will cease in the future. 5164 5165 This macro caches its result in the 5166 `ac_cv_member_struct_stat_st_blocks' variable. 5167 5168 -- Macro: AC_STRUCT_TM 5169 If `time.h' does not define `struct tm', define `TM_IN_SYS_TIME', 5170 which means that including `sys/time.h' had better define `struct 5171 tm'. 5172 5173 This macro is obsolescent, as `time.h' defines `struct tm' in 5174 current systems. New programs need not use this macro. 5175 5176 -- Macro: AC_STRUCT_TIMEZONE 5177 Figure out how to get the current timezone. If `struct tm' has a 5178 `tm_zone' member, define `HAVE_STRUCT_TM_TM_ZONE' (and the 5179 obsoleted `HAVE_TM_ZONE'). Otherwise, if the external array 5180 `tzname' is found, define `HAVE_TZNAME'; if it is declared, define 5181 `HAVE_DECL_TZNAME'. 5182 5183 5184File: autoconf.info, Node: Generic Structures, Prev: Particular Structures, Up: Structures 5185 51865.8.2 Generic Structure Checks 5187------------------------------ 5188 5189These macros are used to find structure members not covered by the 5190"particular" test macros. 5191 5192 -- Macro: AC_CHECK_MEMBER (AGGREGATE.MEMBER, [ACTION-IF-FOUND], 5193 [ACTION-IF-NOT-FOUND], [INCLUDES = `AC_INCLUDES_DEFAULT']) 5194 Check whether MEMBER is a member of the aggregate AGGREGATE. If 5195 no INCLUDES are specified, the default includes are used (*note 5196 Default Includes::). 5197 5198 AC_CHECK_MEMBER([struct passwd.pw_gecos], [], 5199 [AC_MSG_ERROR([we need `passwd.pw_gecos'])], 5200 [[#include <pwd.h>]]) 5201 5202 You can use this macro for submembers: 5203 5204 AC_CHECK_MEMBER(struct top.middle.bot) 5205 5206 This macro caches its result in the 5207 `ac_cv_member_AGGREGATE_MEMBER' variable, with characters not 5208 suitable for a variable name mapped to underscores. 5209 5210 -- Macro: AC_CHECK_MEMBERS (MEMBERS, [ACTION-IF-FOUND], 5211 [ACTION-IF-NOT-FOUND], [INCLUDES = `AC_INCLUDES_DEFAULT']) 5212 Check for the existence of each `AGGREGATE.MEMBER' of MEMBERS 5213 using the previous macro. When MEMBER belongs to AGGREGATE, 5214 define `HAVE_AGGREGATE_MEMBER' (in all capitals, with spaces and 5215 dots replaced by underscores). If ACTION-IF-FOUND is given, it is 5216 executed for each of the found members. If ACTION-IF-NOT-FOUND is 5217 given, it is executed for each of the members that could not be 5218 found. 5219 5220 INCLUDES is a series of include directives, defaulting to 5221 `AC_INCLUDES_DEFAULT' (*note Default Includes::), which are used 5222 prior to the members under test. 5223 5224 This macro uses M4 lists: 5225 AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize]) 5226 5227 5228File: autoconf.info, Node: Types, Next: Compilers and Preprocessors, Prev: Structures, Up: Existing Tests 5229 52305.9 Types 5231========= 5232 5233The following macros check for C types, either builtin or typedefs. If 5234there is no macro specifically defined to check for a type you need, and 5235you don't need to check for any special properties of it, then you can 5236use a general type-check macro. 5237 5238* Menu: 5239 5240* Particular Types:: Special handling to find certain types 5241* Generic Types:: How to find other types 5242 5243 5244File: autoconf.info, Node: Particular Types, Next: Generic Types, Up: Types 5245 52465.9.1 Particular Type Checks 5247---------------------------- 5248 5249These macros check for particular C types in `sys/types.h', `stdlib.h', 5250`stdint.h', `inttypes.h' and others, if they exist. 5251 5252 The Gnulib `stdint' module is an alternate way to define many of 5253these symbols; it is useful if you prefer your code to assume a 5254C99-or-better environment. *Note Gnulib::. 5255 5256 -- Macro: AC_TYPE_GETGROUPS 5257 Define `GETGROUPS_T' to be whichever of `gid_t' or `int' is the 5258 base type of the array argument to `getgroups'. 5259 5260 This macro caches the base type in the `ac_cv_type_getgroups' 5261 variable. 5262 5263 -- Macro: AC_TYPE_INT8_T 5264 If `stdint.h' or `inttypes.h' does not define the type `int8_t', 5265 define `int8_t' to a signed integer type that is exactly 8 bits 5266 wide and that uses two's complement representation, if such a type 5267 exists. If you are worried about porting to hosts that lack such 5268 a type, you can use the results of this macro in C89-or-later code 5269 as follows: 5270 5271 #if HAVE_STDINT_H 5272 # include <stdint.h> 5273 #endif 5274 #if defined INT8_MAX || defined int8_t 5275 _code using int8_t_ 5276 #else 5277 _complicated alternative using >8-bit 'signed char'_ 5278 #endif 5279 5280 This macro caches the type in the `ac_cv_c_int8_t' variable. 5281 5282 -- Macro: AC_TYPE_INT16_T 5283 This is like `AC_TYPE_INT8_T', except for 16-bit integers. 5284 5285 -- Macro: AC_TYPE_INT32_T 5286 This is like `AC_TYPE_INT8_T', except for 32-bit integers. 5287 5288 -- Macro: AC_TYPE_INT64_T 5289 This is like `AC_TYPE_INT8_T', except for 64-bit integers. 5290 5291 -- Macro: AC_TYPE_INTMAX_T 5292 If `stdint.h' or `inttypes.h' defines the type `intmax_t', define 5293 `HAVE_INTMAX_T'. Otherwise, define `intmax_t' to the widest 5294 signed integer type. 5295 5296 -- Macro: AC_TYPE_INTPTR_T 5297 If `stdint.h' or `inttypes.h' defines the type `intptr_t', define 5298 `HAVE_INTPTR_T'. Otherwise, define `intptr_t' to a signed integer 5299 type wide enough to hold a pointer, if such a type exists. 5300 5301 -- Macro: AC_TYPE_LONG_DOUBLE 5302 If the C compiler supports a working `long double' type, define 5303 `HAVE_LONG_DOUBLE'. The `long double' type might have the same 5304 range and precision as `double'. 5305 5306 This macro caches its result in the `ac_cv_type_long_double' 5307 variable. 5308 5309 This macro is obsolescent, as current C compilers support `long 5310 double'. New programs need not use this macro. 5311 5312 -- Macro: AC_TYPE_LONG_DOUBLE_WIDER 5313 If the C compiler supports a working `long double' type with more 5314 range or precision than the `double' type, define 5315 `HAVE_LONG_DOUBLE_WIDER'. 5316 5317 This macro caches its result in the `ac_cv_type_long_double_wider' 5318 variable. 5319 5320 -- Macro: AC_TYPE_LONG_LONG_INT 5321 If the C compiler supports a working `long long int' type, define 5322 `HAVE_LONG_LONG_INT'. However, this test does not test `long long 5323 int' values in preprocessor `#if' expressions, because too many 5324 compilers mishandle such expressions. *Note Preprocessor 5325 Arithmetic::. 5326 5327 This macro caches its result in the `ac_cv_type_long_long_int' 5328 variable. 5329 5330 -- Macro: AC_TYPE_MBSTATE_T 5331 Define `HAVE_MBSTATE_T' if `<wchar.h>' declares the `mbstate_t' 5332 type. Also, define `mbstate_t' to be a type if `<wchar.h>' does 5333 not declare it. 5334 5335 This macro caches its result in the `ac_cv_type_mbstate_t' 5336 variable. 5337 5338 -- Macro: AC_TYPE_MODE_T 5339 Define `mode_t' to a suitable type, if standard headers do not 5340 define it. 5341 5342 This macro caches its result in the `ac_cv_type_mode_t' variable. 5343 5344 -- Macro: AC_TYPE_OFF_T 5345 Define `off_t' to a suitable type, if standard headers do not 5346 define it. 5347 5348 This macro caches its result in the `ac_cv_type_off_t' variable. 5349 5350 -- Macro: AC_TYPE_PID_T 5351 Define `pid_t' to a suitable type, if standard headers do not 5352 define it. 5353 5354 This macro caches its result in the `ac_cv_type_pid_t' variable. 5355 5356 -- Macro: AC_TYPE_SIZE_T 5357 Define `size_t' to a suitable type, if standard headers do not 5358 define it. 5359 5360 This macro caches its result in the `ac_cv_type_size_t' variable. 5361 5362 -- Macro: AC_TYPE_SSIZE_T 5363 Define `ssize_t' to a suitable type, if standard headers do not 5364 define it. 5365 5366 This macro caches its result in the `ac_cv_type_ssize_t' variable. 5367 5368 -- Macro: AC_TYPE_UID_T 5369 Define `uid_t' and `gid_t' to suitable types, if standard headers 5370 do not define them. 5371 5372 This macro caches its result in the `ac_cv_type_uid_t' variable. 5373 5374 -- Macro: AC_TYPE_UINT8_T 5375 If `stdint.h' or `inttypes.h' does not define the type `uint8_t', 5376 define `uint8_t' to an unsigned integer type that is exactly 8 5377 bits wide, if such a type exists. This is like `AC_TYPE_INT8_T', 5378 except for unsigned integers. 5379 5380 -- Macro: AC_TYPE_UINT16_T 5381 This is like `AC_TYPE_UINT8_T', except for 16-bit integers. 5382 5383 -- Macro: AC_TYPE_UINT32_T 5384 This is like `AC_TYPE_UINT8_T', except for 32-bit integers. 5385 5386 -- Macro: AC_TYPE_UINT64_T 5387 This is like `AC_TYPE_UINT8_T', except for 64-bit integers. 5388 5389 -- Macro: AC_TYPE_UINTMAX_T 5390 If `stdint.h' or `inttypes.h' defines the type `uintmax_t', define 5391 `HAVE_UINTMAX_T'. Otherwise, define `uintmax_t' to the widest 5392 unsigned integer type. 5393 5394 -- Macro: AC_TYPE_UINTPTR_T 5395 If `stdint.h' or `inttypes.h' defines the type `uintptr_t', define 5396 `HAVE_UINTPTR_T'. Otherwise, define `uintptr_t' to an unsigned 5397 integer type wide enough to hold a pointer, if such a type exists. 5398 5399 -- Macro: AC_TYPE_UNSIGNED_LONG_LONG_INT 5400 If the C compiler supports a working `unsigned long long int' type, 5401 define `HAVE_UNSIGNED_LONG_LONG_INT'. However, this test does not 5402 test `unsigned long long int' values in preprocessor `#if' 5403 expressions, because too many compilers mishandle such expressions. 5404 *Note Preprocessor Arithmetic::. 5405 5406 This macro caches its result in the 5407 `ac_cv_type_unsigned_long_long_int' variable. 5408 5409 5410File: autoconf.info, Node: Generic Types, Prev: Particular Types, Up: Types 5411 54125.9.2 Generic Type Checks 5413------------------------- 5414 5415These macros are used to check for types not covered by the "particular" 5416test macros. 5417 5418 -- Macro: AC_CHECK_TYPE (TYPE, [ACTION-IF-FOUND], 5419 [ACTION-IF-NOT-FOUND], [INCLUDES = `AC_INCLUDES_DEFAULT']) 5420 Check whether TYPE is defined. It may be a compiler builtin type 5421 or defined by the INCLUDES. INCLUDES is a series of include 5422 directives, defaulting to `AC_INCLUDES_DEFAULT' (*note Default 5423 Includes::), which are used prior to the type under test. 5424 5425 In C, TYPE must be a type-name, so that the expression `sizeof 5426 (TYPE)' is valid (but `sizeof ((TYPE))' is not). The same test is 5427 applied when compiling for C++, which means that in C++ TYPE 5428 should be a type-id and should not be an anonymous `struct' or 5429 `union'. 5430 5431 This macro caches its result in the `ac_cv_type_TYPE' variable, 5432 with `*' mapped to `p' and other characters not suitable for a 5433 variable name mapped to underscores. 5434 5435 -- Macro: AC_CHECK_TYPES (TYPES, [ACTION-IF-FOUND], 5436 [ACTION-IF-NOT-FOUND], [INCLUDES = `AC_INCLUDES_DEFAULT']) 5437 For each TYPE of the TYPES that is defined, define `HAVE_TYPE' (in 5438 all capitals). Each TYPE must follow the rules of 5439 `AC_CHECK_TYPE'. If no INCLUDES are specified, the default 5440 includes are used (*note Default Includes::). If ACTION-IF-FOUND 5441 is given, it is additional shell code to execute when one of the 5442 types is found. If ACTION-IF-NOT-FOUND is given, it is executed 5443 when one of the types is not found. 5444 5445 This macro uses M4 lists: 5446 AC_CHECK_TYPES([ptrdiff_t]) 5447 AC_CHECK_TYPES([unsigned long long int, uintmax_t]) 5448 AC_CHECK_TYPES([float_t], [], [], [[#include <math.h>]]) 5449 5450 5451 Autoconf, up to 2.13, used to provide to another version of 5452`AC_CHECK_TYPE', broken by design. In order to keep backward 5453compatibility, a simple heuristic, quite safe but not totally, is 5454implemented. In case of doubt, read the documentation of the former 5455`AC_CHECK_TYPE', see *note Obsolete Macros::. 5456 5457 5458File: autoconf.info, Node: Compilers and Preprocessors, Next: System Services, Prev: Types, Up: Existing Tests 5459 54605.10 Compilers and Preprocessors 5461================================ 5462 5463All the tests for compilers (`AC_PROG_CC', `AC_PROG_CXX', 5464`AC_PROG_F77') define the output variable `EXEEXT' based on the output 5465of the compiler, typically to the empty string if Posix and `.exe' if a 5466DOS variant. 5467 5468 They also define the output variable `OBJEXT' based on the output of 5469the compiler, after `.c' files have been excluded, typically to `o' if 5470Posix, `obj' if a DOS variant. 5471 5472 If the compiler being used does not produce executables, the tests 5473fail. If the executables can't be run, and cross-compilation is not 5474enabled, they fail too. *Note Manual Configuration::, for more on 5475support for cross compiling. 5476 5477* Menu: 5478 5479* Specific Compiler Characteristics:: Some portability issues 5480* Generic Compiler Characteristics:: Language independent tests and features 5481* C Compiler:: Checking its characteristics 5482* C++ Compiler:: Likewise 5483* Objective C Compiler:: Likewise 5484* Objective C++ Compiler:: Likewise 5485* Erlang Compiler and Interpreter:: Likewise 5486* Fortran Compiler:: Likewise 5487* Go Compiler:: Likewise 5488 5489 5490File: autoconf.info, Node: Specific Compiler Characteristics, Next: Generic Compiler Characteristics, Up: Compilers and Preprocessors 5491 54925.10.1 Specific Compiler Characteristics 5493---------------------------------------- 5494 5495Some compilers exhibit different behaviors. 5496 5497Static/Dynamic Expressions 5498 Autoconf relies on a trick to extract one bit of information from 5499 the C compiler: using negative array sizes. For instance the 5500 following excerpt of a C source demonstrates how to test whether 5501 `int' objects are 4 bytes wide: 5502 5503 static int test_array[sizeof (int) == 4 ? 1 : -1]; 5504 5505 To our knowledge, there is a single compiler that does not support 5506 this trick: the HP C compilers (the real ones, not only the 5507 "bundled") on HP-UX 11.00. They incorrectly reject the above 5508 program with the diagnostic "Variable-length arrays cannot have 5509 static storage." This bug comes from HP compilers' mishandling of 5510 `sizeof (int)', not from the `? 1 : -1', and Autoconf works around 5511 this problem by casting `sizeof (int)' to `long int' before 5512 comparing it. 5513 5514 5515File: autoconf.info, Node: Generic Compiler Characteristics, Next: C Compiler, Prev: Specific Compiler Characteristics, Up: Compilers and Preprocessors 5516 55175.10.2 Generic Compiler Characteristics 5518--------------------------------------- 5519 5520 -- Macro: AC_CHECK_SIZEOF (TYPE-OR-EXPR, [UNUSED], [INCLUDES = 5521 `AC_INCLUDES_DEFAULT']) 5522 Define `SIZEOF_TYPE-OR-EXPR' (*note Standard Symbols::) to be the 5523 size in bytes of TYPE-OR-EXPR, which may be either a type or an 5524 expression returning a value that has a size. If the expression 5525 `sizeof (TYPE-OR-EXPR)' is invalid, the result is 0. INCLUDES is 5526 a series of include directives, defaulting to 5527 `AC_INCLUDES_DEFAULT' (*note Default Includes::), which are used 5528 prior to the expression under test. 5529 5530 This macro now works even when cross-compiling. The UNUSED 5531 argument was used when cross-compiling. 5532 5533 For example, the call 5534 5535 AC_CHECK_SIZEOF([int *]) 5536 5537 defines `SIZEOF_INT_P' to be 8 on DEC Alpha AXP systems. 5538 5539 This macro caches its result in the `ac_cv_sizeof_TYPE-OR-EXPR' 5540 variable, with `*' mapped to `p' and other characters not suitable 5541 for a variable name mapped to underscores. 5542 5543 -- Macro: AC_CHECK_ALIGNOF (TYPE, [INCLUDES = `AC_INCLUDES_DEFAULT']) 5544 Define `ALIGNOF_TYPE' (*note Standard Symbols::) to be the 5545 alignment in bytes of TYPE. `TYPE y;' must be valid as a 5546 structure member declaration. If `type' is unknown, the result is 5547 0. If no INCLUDES are specified, the default includes are used 5548 (*note Default Includes::). 5549 5550 This macro caches its result in the `ac_cv_alignof_TYPE-OR-EXPR' 5551 variable, with `*' mapped to `p' and other characters not suitable 5552 for a variable name mapped to underscores. 5553 5554 -- Macro: AC_COMPUTE_INT (VAR, EXPRESSION, [INCLUDES = 5555 `AC_INCLUDES_DEFAULT'], [ACTION-IF-FAILS]) 5556 Store into the shell variable VAR the value of the integer 5557 EXPRESSION. The value should fit in an initializer in a C 5558 variable of type `signed long'. To support cross compilation (in 5559 which case, the macro only works on hosts that use twos-complement 5560 arithmetic), it should be possible to evaluate the expression at 5561 compile-time. If no INCLUDES are specified, the default includes 5562 are used (*note Default Includes::). 5563 5564 Execute ACTION-IF-FAILS if the value cannot be determined 5565 correctly. 5566 5567 -- Macro: AC_LANG_WERROR 5568 Normally Autoconf ignores warnings generated by the compiler, 5569 linker, and preprocessor. If this macro is used, warnings count 5570 as fatal errors for the current language. This macro is useful 5571 when the results of configuration are used where warnings are 5572 unacceptable; for instance, if parts of a program are built with 5573 the GCC `-Werror' option. If the whole program is built using 5574 `-Werror' it is often simpler to put `-Werror' in the compiler 5575 flags (`CFLAGS', etc.). 5576 5577 -- Macro: AC_OPENMP 5578 OpenMP (http://www.openmp.org/) specifies extensions of C, C++, 5579 and Fortran that simplify optimization of shared memory 5580 parallelism, which is a common problem on multicore CPUs. 5581 5582 If the current language is C, the macro `AC_OPENMP' sets the 5583 variable `OPENMP_CFLAGS' to the C compiler flags needed for 5584 supporting OpenMP. `OPENMP_CFLAGS' is set to empty if the 5585 compiler already supports OpenMP, if it has no way to activate 5586 OpenMP support, or if the user rejects OpenMP support by invoking 5587 `configure' with the `--disable-openmp' option. 5588 5589 `OPENMP_CFLAGS' needs to be used when compiling programs, when 5590 preprocessing program source, and when linking programs. 5591 Therefore you need to add `$(OPENMP_CFLAGS)' to the `CFLAGS' of C 5592 programs that use OpenMP. If you preprocess OpenMP-specific C 5593 code, you also need to add `$(OPENMP_CFLAGS)' to `CPPFLAGS'. The 5594 presence of OpenMP support is revealed at compile time by the 5595 preprocessor macro `_OPENMP'. 5596 5597 Linking a program with `OPENMP_CFLAGS' typically adds one more 5598 shared library to the program's dependencies, so its use is 5599 recommended only on programs that actually require OpenMP. 5600 5601 If the current language is C++, `AC_OPENMP' sets the variable 5602 `OPENMP_CXXFLAGS', suitably for the C++ compiler. The same remarks 5603 hold as for C. 5604 5605 If the current language is Fortran 77 or Fortran, `AC_OPENMP' sets 5606 the variable `OPENMP_FFLAGS' or `OPENMP_FCFLAGS', respectively. 5607 Similar remarks as for C hold, except that `CPPFLAGS' is not used 5608 for Fortran, and no preprocessor macro signals OpenMP support. 5609 5610 For portability, it is best to avoid spaces between `#' and 5611 `pragma omp'. That is, write `#pragma omp', not `# pragma omp'. 5612 The Sun WorkShop 6.2 C compiler chokes on the latter. 5613 5614 This macro caches its result in the `ac_cv_prog_c_openmp', 5615 `ac_cv_prog_cxx_openmp', `ac_cv_prog_f77_openmp', or 5616 `ac_cv_prog_fc_openmp' variable, depending on the current language. 5617 5618 5619File: autoconf.info, Node: C Compiler, Next: C++ Compiler, Prev: Generic Compiler Characteristics, Up: Compilers and Preprocessors 5620 56215.10.3 C Compiler Characteristics 5622--------------------------------- 5623 5624The following macros provide ways to find and exercise a C Compiler. 5625There are a few constructs that ought to be avoided, but do not deserve 5626being checked for, since they can easily be worked around. 5627 5628Don't use lines containing solitary backslashes 5629 They tickle a bug in the HP-UX C compiler (checked on HP-UX 10.20, 5630 11.00, and 11i). When given the following source: 5631 5632 #ifdef __STDC__ 5633 /\ 5634 * A comment with backslash-newlines in it. %{ %} *\ 5635 \ 5636 / 5637 char str[] = "\\ 5638 " A string with backslash-newlines in it %{ %} \\ 5639 ""; 5640 char apostrophe = '\\ 5641 \ 5642 '\ 5643 '; 5644 #endif 5645 5646 the compiler incorrectly fails with the diagnostics 5647 "Non-terminating comment at end of file" and "Missing `#endif' at 5648 end of file." Removing the lines with solitary backslashes solves 5649 the problem. 5650 5651Don't compile several files at once if output matters to you 5652 Some compilers, such as HP's, report names of files being compiled 5653 when given more than one file operand. For instance: 5654 5655 $ cc a.c b.c 5656 a.c: 5657 b.c: 5658 5659 This can cause problems if you observe the output of the compiler 5660 to detect failures. Invoking `cc -c a.c && cc -c b.c && cc -o c 5661 a.o b.o' solves the issue. 5662 5663Don't rely on `#error' failing 5664 The IRIX C compiler does not fail when #error is preprocessed; it 5665 simply emits a diagnostic and continues, exiting successfully. So, 5666 instead of an error directive like `#error "Unsupported word size"' 5667 it is more portable to use an invalid directive like `#Unsupported 5668 word size' in Autoconf tests. In ordinary source code, `#error' is 5669 OK, since installers with inadequate compilers like IRIX can simply 5670 examine these compilers' diagnostic output. 5671 5672Don't rely on correct `#line' support 5673 On Solaris, `c89' (at least Sun C 5.3 through 5.8) diagnoses 5674 `#line' directives whose line numbers are greater than 32767. 5675 Nothing in Posix makes this invalid. That is why Autoconf stopped 5676 issuing `#line' directives. 5677 5678 -- Macro: AC_PROG_CC ([COMPILER-SEARCH-LIST]) 5679 Determine a C compiler to use. If `CC' is not already set in the 5680 environment, check for `gcc' and `cc', then for other C compilers. 5681 Set output variable `CC' to the name of the compiler found. 5682 5683 This macro may, however, be invoked with an optional first argument 5684 which, if specified, must be a blank-separated list of C compilers 5685 to search for. This just gives the user an opportunity to specify 5686 an alternative search list for the C compiler. For example, if 5687 you didn't like the default order, then you could invoke 5688 `AC_PROG_CC' like this: 5689 5690 AC_PROG_CC([gcc cl cc]) 5691 5692 If the C compiler does not handle function prototypes correctly by 5693 default, try to add an option to output variable `CC' to make it 5694 so. This macro tries various options that select 5695 standard-conformance modes on various systems. 5696 5697 After calling this macro you can check whether the C compiler has 5698 been set to accept ANSI C89 (ISO C90); if not, the shell variable 5699 `ac_cv_prog_cc_c89' is set to `no'. See also `AC_C_PROTOTYPES' 5700 below. 5701 5702 If using the GNU C compiler, set shell variable `GCC' to `yes'. 5703 If output variable `CFLAGS' was not already set, set it to `-g 5704 -O2' for the GNU C compiler (`-O2' on systems where GCC does not 5705 accept `-g'), or `-g' for other compilers. If your package does 5706 not like this default, then it is acceptable to insert the line `: 5707 ${CFLAGS=""}' after `AC_INIT' and before `AC_PROG_CC' to select an 5708 empty default instead. 5709 5710 Many Autoconf macros use a compiler, and thus call 5711 `AC_REQUIRE([AC_PROG_CC])' to ensure that the compiler has been 5712 determined before the body of the outermost `AC_DEFUN' macro. 5713 Although `AC_PROG_CC' is safe to directly expand multiple times, it 5714 performs certain checks (such as the proper value of `EXEEXT') only 5715 on the first invocation. Therefore, care must be used when 5716 invoking this macro from within another macro rather than at the 5717 top level (*note Expanded Before Required::). 5718 5719 -- Macro: AC_PROG_CC_C_O 5720 If the C compiler does not accept the `-c' and `-o' options 5721 simultaneously, define `NO_MINUS_C_MINUS_O'. This macro actually 5722 tests both the compiler found by `AC_PROG_CC', and, if different, 5723 the first `cc' in the path. The test fails if one fails. This 5724 macro was created for GNU Make to choose the default C compilation 5725 rule. 5726 5727 For the compiler COMPILER, this macro caches its result in the 5728 `ac_cv_prog_cc_COMPILER_c_o' variable. 5729 5730 -- Macro: AC_PROG_CPP 5731 Set output variable `CPP' to a command that runs the C 5732 preprocessor. If `$CC -E' doesn't work, `/lib/cpp' is used. It 5733 is only portable to run `CPP' on files with a `.c' extension. 5734 5735 Some preprocessors don't indicate missing include files by the 5736 error status. For such preprocessors an internal variable is set 5737 that causes other macros to check the standard error from the 5738 preprocessor and consider the test failed if any warnings have 5739 been reported. For most preprocessors, though, warnings do not 5740 cause include-file tests to fail unless `AC_PROG_CPP_WERROR' is 5741 also specified. 5742 5743 -- Macro: AC_PROG_CPP_WERROR 5744 This acts like `AC_PROG_CPP', except it treats warnings from the 5745 preprocessor as errors even if the preprocessor exit status 5746 indicates success. This is useful for avoiding headers that 5747 generate mandatory warnings, such as deprecation notices. 5748 5749 The following macros check for C compiler or machine architecture 5750features. To check for characteristics not listed here, use 5751`AC_COMPILE_IFELSE' (*note Running the Compiler::) or `AC_RUN_IFELSE' 5752(*note Runtime::). 5753 5754 -- Macro: AC_PROG_CC_STDC 5755 If the C compiler cannot compile ISO Standard C (currently C99), 5756 try to add an option to output variable `CC' to make it work. If 5757 the compiler does not support C99, fall back to supporting ANSI 5758 C89 (ISO C90). 5759 5760 After calling this macro you can check whether the C compiler has 5761 been set to accept Standard C; if not, the shell variable 5762 `ac_cv_prog_cc_stdc' is set to `no'. 5763 5764 -- Macro: AC_PROG_CC_C89 5765 If the C compiler is not in ANSI C89 (ISO C90) mode by default, 5766 try to add an option to output variable `CC' to make it so. This 5767 macro tries various options that select ANSI C89 on some system or 5768 another, preferring extended functionality modes over strict 5769 conformance modes. It considers the compiler to be in ANSI C89 5770 mode if it handles function prototypes correctly. 5771 5772 After calling this macro you can check whether the C compiler has 5773 been set to accept ANSI C89; if not, the shell variable 5774 `ac_cv_prog_cc_c89' is set to `no'. 5775 5776 This macro is called automatically by `AC_PROG_CC'. 5777 5778 -- Macro: AC_PROG_CC_C99 5779 If the C compiler is not in C99 mode by default, try to add an 5780 option to output variable `CC' to make it so. This macro tries 5781 various options that select C99 on some system or another, 5782 preferring extended functionality modes over strict conformance 5783 modes. It considers the compiler to be in C99 mode if it handles 5784 `_Bool', `//' comments, flexible array members, `inline', signed 5785 and unsigned `long long int', mixed code and declarations, named 5786 initialization of structs, `restrict', `va_copy', varargs macros, 5787 variable declarations in `for' loops, and variable length arrays. 5788 5789 After calling this macro you can check whether the C compiler has 5790 been set to accept C99; if not, the shell variable 5791 `ac_cv_prog_cc_c99' is set to `no'. 5792 5793 -- Macro: AC_C_BACKSLASH_A 5794 Define `HAVE_C_BACKSLASH_A' to 1 if the C compiler understands 5795 `\a'. 5796 5797 This macro is obsolescent, as current C compilers understand `\a'. 5798 New programs need not use this macro. 5799 5800 -- Macro: AC_C_BIGENDIAN ([ACTION-IF-TRUE], [ACTION-IF-FALSE], 5801 [ACTION-IF-UNKNOWN], [ACTION-IF-UNIVERSAL]) 5802 If words are stored with the most significant byte first (like 5803 Motorola and SPARC CPUs), execute ACTION-IF-TRUE. If words are 5804 stored with the least significant byte first (like Intel and VAX 5805 CPUs), execute ACTION-IF-FALSE. 5806 5807 This macro runs a test-case if endianness cannot be determined 5808 from the system header files. When cross-compiling, the test-case 5809 is not run but grep'ed for some magic values. ACTION-IF-UNKNOWN 5810 is executed if the latter case fails to determine the byte sex of 5811 the host system. 5812 5813 In some cases a single run of a compiler can generate code for 5814 multiple architectures. This can happen, for example, when 5815 generating Mac OS X universal binary files, which work on both 5816 PowerPC and Intel architectures. In this case, the different 5817 variants might be for different architectures whose endiannesses 5818 differ. If `configure' detects this, it executes 5819 ACTION-IF-UNIVERSAL instead of ACTION-IF-UNKNOWN. 5820 5821 The default for ACTION-IF-TRUE is to define `WORDS_BIGENDIAN'. 5822 The default for ACTION-IF-FALSE is to do nothing. The default for 5823 ACTION-IF-UNKNOWN is to abort configure and tell the installer how 5824 to bypass this test. And finally, the default for 5825 ACTION-IF-UNIVERSAL is to ensure that `WORDS_BIGENDIAN' is defined 5826 if and only if a universal build is detected and the current code 5827 is big-endian; this default works only if `autoheader' is used 5828 (*note autoheader Invocation::). 5829 5830 If you use this macro without specifying ACTION-IF-UNIVERSAL, you 5831 should also use `AC_CONFIG_HEADERS'; otherwise `WORDS_BIGENDIAN' 5832 may be set incorrectly for Mac OS X universal binary files. 5833 5834 -- Macro: AC_C_CONST 5835 If the C compiler does not fully support the `const' keyword, 5836 define `const' to be empty. Some C compilers that do not define 5837 `__STDC__' do support `const'; some compilers that define 5838 `__STDC__' do not completely support `const'. Programs can simply 5839 use `const' as if every C compiler supported it; for those that 5840 don't, the makefile or configuration header file defines it as 5841 empty. 5842 5843 Occasionally installers use a C++ compiler to compile C code, 5844 typically because they lack a C compiler. This causes problems 5845 with `const', because C and C++ treat `const' differently. For 5846 example: 5847 5848 const int foo; 5849 5850 is valid in C but not in C++. These differences unfortunately 5851 cannot be papered over by defining `const' to be empty. 5852 5853 If `autoconf' detects this situation, it leaves `const' alone, as 5854 this generally yields better results in practice. However, using a 5855 C++ compiler to compile C code is not recommended or supported, and 5856 installers who run into trouble in this area should get a C 5857 compiler like GCC to compile their C code. 5858 5859 This macro caches its result in the `ac_cv_c_const' variable. 5860 5861 This macro is obsolescent, as current C compilers support `const'. 5862 New programs need not use this macro. 5863 5864 -- Macro: AC_C_RESTRICT 5865 If the C compiler recognizes a variant spelling for the `restrict' 5866 keyword (`__restrict', `__restrict__', or `_Restrict'), then 5867 define `restrict' to that; this is more likely to do the right 5868 thing with compilers that support language variants where plain 5869 `restrict' is not a keyword. Otherwise, if the C compiler 5870 recognizes the `restrict' keyword, don't do anything. Otherwise, 5871 define `restrict' to be empty. Thus, programs may simply use 5872 `restrict' as if every C compiler supported it; for those that do 5873 not, the makefile or configuration header defines it away. 5874 5875 Although support in C++ for the `restrict' keyword is not 5876 required, several C++ compilers do accept the keyword. This macro 5877 works for them, too. 5878 5879 This macro caches `no' in the `ac_cv_c_restrict' variable if 5880 `restrict' is not supported, and a supported spelling otherwise. 5881 5882 -- Macro: AC_C_VOLATILE 5883 If the C compiler does not understand the keyword `volatile', 5884 define `volatile' to be empty. Programs can simply use `volatile' 5885 as if every C compiler supported it; for those that do not, the 5886 makefile or configuration header defines it as empty. 5887 5888 If the correctness of your program depends on the semantics of 5889 `volatile', simply defining it to be empty does, in a sense, break 5890 your code. However, given that the compiler does not support 5891 `volatile', you are at its mercy anyway. At least your program 5892 compiles, when it wouldn't before. *Note Volatile Objects::, for 5893 more about `volatile'. 5894 5895 In general, the `volatile' keyword is a standard C feature, so you 5896 might expect that `volatile' is available only when `__STDC__' is 5897 defined. However, Ultrix 4.3's native compiler does support 5898 volatile, but does not define `__STDC__'. 5899 5900 This macro is obsolescent, as current C compilers support 5901 `volatile'. New programs need not use this macro. 5902 5903 -- Macro: AC_C_INLINE 5904 If the C compiler supports the keyword `inline', do nothing. 5905 Otherwise define `inline' to `__inline__' or `__inline' if it 5906 accepts one of those, otherwise define `inline' to be empty. 5907 5908 -- Macro: AC_C_CHAR_UNSIGNED 5909 If the C type `char' is unsigned, define `__CHAR_UNSIGNED__', 5910 unless the C compiler predefines it. 5911 5912 These days, using this macro is not necessary. The same 5913 information can be determined by this portable alternative, thus 5914 avoiding the use of preprocessor macros in the namespace reserved 5915 for the implementation. 5916 5917 #include <limits.h> 5918 #if CHAR_MIN == 0 5919 # define CHAR_UNSIGNED 1 5920 #endif 5921 5922 -- Macro: AC_C_STRINGIZE 5923 If the C preprocessor supports the stringizing operator, define 5924 `HAVE_STRINGIZE'. The stringizing operator is `#' and is found in 5925 macros such as this: 5926 5927 #define x(y) #y 5928 5929 This macro is obsolescent, as current C compilers support the 5930 stringizing operator. New programs need not use this macro. 5931 5932 -- Macro: AC_C_FLEXIBLE_ARRAY_MEMBER 5933 If the C compiler supports flexible array members, define 5934 `FLEXIBLE_ARRAY_MEMBER' to nothing; otherwise define it to 1. 5935 That way, a declaration like this: 5936 5937 struct s 5938 { 5939 size_t n_vals; 5940 double val[FLEXIBLE_ARRAY_MEMBER]; 5941 }; 5942 5943 will let applications use the "struct hack" even with compilers 5944 that do not support flexible array members. To allocate and use 5945 such an object, you can use code like this: 5946 5947 size_t i; 5948 size_t n = compute_value_count (); 5949 struct s *p = 5950 malloc (offsetof (struct s, val) 5951 + n * sizeof (double)); 5952 p->n_vals = n; 5953 for (i = 0; i < n; i++) 5954 p->val[i] = compute_value (i); 5955 5956 -- Macro: AC_C_VARARRAYS 5957 If the C compiler supports variable-length arrays, define 5958 `HAVE_C_VARARRAYS'. A variable-length array is an array of 5959 automatic storage duration whose length is determined at run time, 5960 when the array is declared. 5961 5962 -- Macro: AC_C_TYPEOF 5963 If the C compiler supports GCC's `typeof' syntax either directly or 5964 through a different spelling of the keyword (e.g., `__typeof__'), 5965 define `HAVE_TYPEOF'. If the support is available only through a 5966 different spelling, define `typeof' to that spelling. 5967 5968 -- Macro: AC_C_PROTOTYPES 5969 If function prototypes are understood by the compiler (as 5970 determined by `AC_PROG_CC'), define `PROTOTYPES' and 5971 `__PROTOTYPES'. Defining `__PROTOTYPES' is for the benefit of 5972 header files that cannot use macros that infringe on user name 5973 space. 5974 5975 This macro is obsolescent, as current C compilers support 5976 prototypes. New programs need not use this macro. 5977 5978 -- Macro: AC_PROG_GCC_TRADITIONAL 5979 Add `-traditional' to output variable `CC' if using the GNU C 5980 compiler and `ioctl' does not work properly without 5981 `-traditional'. That usually happens when the fixed header files 5982 have not been installed on an old system. 5983 5984 This macro is obsolescent, since current versions of the GNU C 5985 compiler fix the header files automatically when installed. 5986 5987 5988File: autoconf.info, Node: C++ Compiler, Next: Objective C Compiler, Prev: C Compiler, Up: Compilers and Preprocessors 5989 59905.10.4 C++ Compiler Characteristics 5991----------------------------------- 5992 5993 -- Macro: AC_PROG_CXX ([COMPILER-SEARCH-LIST]) 5994 Determine a C++ compiler to use. Check whether the environment 5995 variable `CXX' or `CCC' (in that order) is set; if so, then set 5996 output variable `CXX' to its value. 5997 5998 Otherwise, if the macro is invoked without an argument, then 5999 search for a C++ compiler under the likely names (first `g++' and 6000 `c++' then other names). If none of those checks succeed, then as 6001 a last resort set `CXX' to `g++'. 6002 6003 This macro may, however, be invoked with an optional first argument 6004 which, if specified, must be a blank-separated list of C++ 6005 compilers to search for. This just gives the user an opportunity 6006 to specify an alternative search list for the C++ compiler. For 6007 example, if you didn't like the default order, then you could 6008 invoke `AC_PROG_CXX' like this: 6009 6010 AC_PROG_CXX([gcc cl KCC CC cxx cc++ xlC aCC c++ g++]) 6011 6012 If using the GNU C++ compiler, set shell variable `GXX' to `yes'. 6013 If output variable `CXXFLAGS' was not already set, set it to `-g 6014 -O2' for the GNU C++ compiler (`-O2' on systems where G++ does not 6015 accept `-g'), or `-g' for other compilers. If your package does 6016 not like this default, then it is acceptable to insert the line `: 6017 ${CXXFLAGS=""}' after `AC_INIT' and before `AC_PROG_CXX' to select 6018 an empty default instead. 6019 6020 6021 -- Macro: AC_PROG_CXXCPP 6022 Set output variable `CXXCPP' to a command that runs the C++ 6023 preprocessor. If `$CXX -E' doesn't work, `/lib/cpp' is used. It 6024 is portable to run `CXXCPP' only on files with a `.c', `.C', 6025 `.cc', or `.cpp' extension. 6026 6027 Some preprocessors don't indicate missing include files by the 6028 error status. For such preprocessors an internal variable is set 6029 that causes other macros to check the standard error from the 6030 preprocessor and consider the test failed if any warnings have 6031 been reported. However, it is not known whether such broken 6032 preprocessors exist for C++. 6033 6034 -- Macro: AC_PROG_CXX_C_O 6035 Test whether the C++ compiler accepts the options `-c' and `-o' 6036 simultaneously, and define `CXX_NO_MINUS_C_MINUS_O', if it does 6037 not. 6038 6039 6040File: autoconf.info, Node: Objective C Compiler, Next: Objective C++ Compiler, Prev: C++ Compiler, Up: Compilers and Preprocessors 6041 60425.10.5 Objective C Compiler Characteristics 6043------------------------------------------- 6044 6045 -- Macro: AC_PROG_OBJC ([COMPILER-SEARCH-LIST]) 6046 Determine an Objective C compiler to use. If `OBJC' is not already 6047 set in the environment, check for Objective C compilers. Set 6048 output variable `OBJC' to the name of the compiler found. 6049 6050 This macro may, however, be invoked with an optional first argument 6051 which, if specified, must be a blank-separated list of Objective C 6052 compilers to search for. This just gives the user an opportunity 6053 to specify an alternative search list for the Objective C 6054 compiler. For example, if you didn't like the default order, then 6055 you could invoke `AC_PROG_OBJC' like this: 6056 6057 AC_PROG_OBJC([gcc objcc objc]) 6058 6059 If using the GNU Objective C compiler, set shell variable `GOBJC' 6060 to `yes'. If output variable `OBJCFLAGS' was not already set, set 6061 it to `-g -O2' for the GNU Objective C compiler (`-O2' on systems 6062 where `gcc' does not accept `-g'), or `-g' for other compilers. 6063 6064 -- Macro: AC_PROG_OBJCPP 6065 Set output variable `OBJCPP' to a command that runs the Objective C 6066 preprocessor. If `$OBJC -E' doesn't work, `/lib/cpp' is used. 6067 6068 6069File: autoconf.info, Node: Objective C++ Compiler, Next: Erlang Compiler and Interpreter, Prev: Objective C Compiler, Up: Compilers and Preprocessors 6070 60715.10.6 Objective C++ Compiler Characteristics 6072--------------------------------------------- 6073 6074 -- Macro: AC_PROG_OBJCXX ([COMPILER-SEARCH-LIST]) 6075 Determine an Objective C++ compiler to use. If `OBJCXX' is not 6076 already set in the environment, check for Objective C++ compilers. 6077 Set output variable `OBJCXX' to the name of the compiler found. 6078 6079 This macro may, however, be invoked with an optional first argument 6080 which, if specified, must be a blank-separated list of Objective 6081 C++ compilers to search for. This just gives the user an 6082 opportunity to specify an alternative search list for the 6083 Objective C++ compiler. For example, if you didn't like the 6084 default order, then you could invoke `AC_PROG_OBJCXX' like this: 6085 6086 AC_PROG_OBJCXX([gcc g++ objcc++ objcxx]) 6087 6088 If using the GNU Objective C++ compiler, set shell variable 6089 `GOBJCXX' to `yes'. If output variable `OBJCXXFLAGS' was not 6090 already set, set it to `-g -O2' for the GNU Objective C++ compiler 6091 (`-O2' on systems where `gcc' does not accept `-g'), or `-g' for 6092 other compilers. 6093 6094 -- Macro: AC_PROG_OBJCXXCPP 6095 Set output variable `OBJCXXCPP' to a command that runs the 6096 Objective C++ preprocessor. If `$OBJCXX -E' doesn't work, 6097 `/lib/cpp' is used. 6098 6099 6100File: autoconf.info, Node: Erlang Compiler and Interpreter, Next: Fortran Compiler, Prev: Objective C++ Compiler, Up: Compilers and Preprocessors 6101 61025.10.7 Erlang Compiler and Interpreter Characteristics 6103------------------------------------------------------ 6104 6105Autoconf defines the following macros for determining paths to the 6106essential Erlang/OTP programs: 6107 6108 -- Macro: AC_ERLANG_PATH_ERLC ([VALUE-IF-NOT-FOUND], [PATH = `$PATH']) 6109 Determine an Erlang compiler to use. If `ERLC' is not already set 6110 in the environment, check for `erlc'. Set output variable `ERLC' 6111 to the complete path of the compiler command found. In addition, 6112 if `ERLCFLAGS' is not set in the environment, set it to an empty 6113 value. 6114 6115 The two optional arguments have the same meaning as the two last 6116 arguments of macro `AC_PATH_PROG' for looking for the `erlc' 6117 program. For example, to look for `erlc' only in the 6118 `/usr/lib/erlang/bin' directory: 6119 6120 AC_ERLANG_PATH_ERLC([not found], [/usr/lib/erlang/bin]) 6121 6122 -- Macro: AC_ERLANG_NEED_ERLC ([PATH = `$PATH']) 6123 A simplified variant of the `AC_ERLANG_PATH_ERLC' macro, that 6124 prints an error message and exits the `configure' script if the 6125 `erlc' program is not found. 6126 6127 -- Macro: AC_ERLANG_PATH_ERL ([VALUE-IF-NOT-FOUND], [PATH = `$PATH']) 6128 Determine an Erlang interpreter to use. If `ERL' is not already 6129 set in the environment, check for `erl'. Set output variable 6130 `ERL' to the complete path of the interpreter command found. 6131 6132 The two optional arguments have the same meaning as the two last 6133 arguments of macro `AC_PATH_PROG' for looking for the `erl' 6134 program. For example, to look for `erl' only in the 6135 `/usr/lib/erlang/bin' directory: 6136 6137 AC_ERLANG_PATH_ERL([not found], [/usr/lib/erlang/bin]) 6138 6139 -- Macro: AC_ERLANG_NEED_ERL ([PATH = `$PATH']) 6140 A simplified variant of the `AC_ERLANG_PATH_ERL' macro, that 6141 prints an error message and exits the `configure' script if the 6142 `erl' program is not found. 6143 6144 6145File: autoconf.info, Node: Fortran Compiler, Next: Go Compiler, Prev: Erlang Compiler and Interpreter, Up: Compilers and Preprocessors 6146 61475.10.8 Fortran Compiler Characteristics 6148--------------------------------------- 6149 6150The Autoconf Fortran support is divided into two categories: legacy 6151Fortran 77 macros (`F77'), and modern Fortran macros (`FC'). The 6152former are intended for traditional Fortran 77 code, and have output 6153variables like `F77', `FFLAGS', and `FLIBS'. The latter are for newer 6154programs that can (or must) compile under the newer Fortran standards, 6155and have output variables like `FC', `FCFLAGS', and `FCLIBS'. 6156 6157 Except for the macros `AC_FC_SRCEXT', `AC_FC_FREEFORM', 6158`AC_FC_FIXEDFORM', and `AC_FC_LINE_LENGTH' (see below), the `FC' and 6159`F77' macros behave almost identically, and so they are documented 6160together in this section. 6161 6162 -- Macro: AC_PROG_F77 ([COMPILER-SEARCH-LIST]) 6163 Determine a Fortran 77 compiler to use. If `F77' is not already 6164 set in the environment, then check for `g77' and `f77', and then 6165 some other names. Set the output variable `F77' to the name of 6166 the compiler found. 6167 6168 This macro may, however, be invoked with an optional first argument 6169 which, if specified, must be a blank-separated list of Fortran 77 6170 compilers to search for. This just gives the user an opportunity 6171 to specify an alternative search list for the Fortran 77 compiler. 6172 For example, if you didn't like the default order, then you could 6173 invoke `AC_PROG_F77' like this: 6174 6175 AC_PROG_F77([fl32 f77 fort77 xlf g77 f90 xlf90]) 6176 6177 If using `g77' (the GNU Fortran 77 compiler), then set the shell 6178 variable `G77' to `yes'. If the output variable `FFLAGS' was not 6179 already set in the environment, then set it to `-g -02' for `g77' 6180 (or `-O2' where `g77' does not accept `-g'). Otherwise, set 6181 `FFLAGS' to `-g' for all other Fortran 77 compilers. 6182 6183 The result of the GNU test is cached in the 6184 `ac_cv_f77_compiler_gnu' variable, acceptance of `-g' in the 6185 `ac_cv_prog_f77_g' variable. 6186 6187 -- Macro: AC_PROG_FC ([COMPILER-SEARCH-LIST], [DIALECT]) 6188 Determine a Fortran compiler to use. If `FC' is not already set in 6189 the environment, then `dialect' is a hint to indicate what Fortran 6190 dialect to search for; the default is to search for the newest 6191 available dialect. Set the output variable `FC' to the name of 6192 the compiler found. 6193 6194 By default, newer dialects are preferred over older dialects, but 6195 if `dialect' is specified then older dialects are preferred 6196 starting with the specified dialect. `dialect' can currently be 6197 one of Fortran 77, Fortran 90, or Fortran 95. However, this is 6198 only a hint of which compiler _name_ to prefer (e.g., `f90' or 6199 `f95'), and no attempt is made to guarantee that a particular 6200 language standard is actually supported. Thus, it is preferable 6201 that you avoid the `dialect' option, and use AC_PROG_FC only for 6202 code compatible with the latest Fortran standard. 6203 6204 This macro may, alternatively, be invoked with an optional first 6205 argument which, if specified, must be a blank-separated list of 6206 Fortran compilers to search for, just as in `AC_PROG_F77'. 6207 6208 If using `gfortran' or `g77' (the GNU Fortran compilers), then set 6209 the shell variable `GFC' to `yes'. If the output variable 6210 `FCFLAGS' was not already set in the environment, then set it to 6211 `-g -02' for GNU `g77' (or `-O2' where `g77' does not accept 6212 `-g'). Otherwise, set `FCFLAGS' to `-g' for all other Fortran 6213 compilers. 6214 6215 The result of the GNU test is cached in the `ac_cv_fc_compiler_gnu' 6216 variable, acceptance of `-g' in the `ac_cv_prog_fc_g' variable. 6217 6218 -- Macro: AC_PROG_F77_C_O 6219 -- Macro: AC_PROG_FC_C_O 6220 Test whether the Fortran compiler accepts the options `-c' and 6221 `-o' simultaneously, and define `F77_NO_MINUS_C_MINUS_O' or 6222 `FC_NO_MINUS_C_MINUS_O', respectively, if it does not. 6223 6224 The result of the test is cached in the `ac_cv_prog_f77_c_o' or 6225 `ac_cv_prog_fc_c_o' variable, respectively. 6226 6227 The following macros check for Fortran compiler characteristics. To 6228check for characteristics not listed here, use `AC_COMPILE_IFELSE' 6229(*note Running the Compiler::) or `AC_RUN_IFELSE' (*note Runtime::), 6230making sure to first set the current language to Fortran 77 or Fortran 6231via `AC_LANG([Fortran 77])' or `AC_LANG(Fortran)' (*note Language 6232Choice::). 6233 6234 -- Macro: AC_F77_LIBRARY_LDFLAGS 6235 -- Macro: AC_FC_LIBRARY_LDFLAGS 6236 Determine the linker flags (e.g., `-L' and `-l') for the "Fortran 6237 intrinsic and runtime libraries" that are required to successfully 6238 link a Fortran program or shared library. The output variable 6239 `FLIBS' or `FCLIBS' is set to these flags (which should be 6240 included after `LIBS' when linking). 6241 6242 This macro is intended to be used in those situations when it is 6243 necessary to mix, e.g., C++ and Fortran source code in a single 6244 program or shared library (*note Mixing Fortran 77 With C and C++: 6245 (automake)Mixing Fortran 77 With C and C++.). 6246 6247 For example, if object files from a C++ and Fortran compiler must 6248 be linked together, then the C++ compiler/linker must be used for 6249 linking (since special C++-ish things need to happen at link time 6250 like calling global constructors, instantiating templates, 6251 enabling exception support, etc.). 6252 6253 However, the Fortran intrinsic and runtime libraries must be 6254 linked in as well, but the C++ compiler/linker doesn't know by 6255 default how to add these Fortran 77 libraries. Hence, this macro 6256 was created to determine these Fortran libraries. 6257 6258 The macros `AC_F77_DUMMY_MAIN' and `AC_FC_DUMMY_MAIN' or 6259 `AC_F77_MAIN' and `AC_FC_MAIN' are probably also necessary to link 6260 C/C++ with Fortran; see below. Further, it is highly recommended 6261 that you use `AC_CONFIG_HEADERS' (*note Configuration Headers::) 6262 because the complex defines that the function wrapper macros create 6263 may not work with C/C++ compiler drivers. 6264 6265 These macros internally compute the flag needed to verbose linking 6266 output and cache it in `ac_cv_prog_f77_v' or `ac_cv_prog_fc_v' 6267 variables, respectively. The computed linker flags are cached in 6268 `ac_cv_f77_libs' or `ac_cv_fc_libs', respectively. 6269 6270 -- Macro: AC_F77_DUMMY_MAIN ([ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND = 6271 `AC_MSG_FAILURE']) 6272 -- Macro: AC_FC_DUMMY_MAIN ([ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND = 6273 `AC_MSG_FAILURE']) 6274 With many compilers, the Fortran libraries detected by 6275 `AC_F77_LIBRARY_LDFLAGS' or `AC_FC_LIBRARY_LDFLAGS' provide their 6276 own `main' entry function that initializes things like Fortran 6277 I/O, and which then calls a user-provided entry function named 6278 (say) `MAIN__' to run the user's program. The `AC_F77_DUMMY_MAIN' 6279 and `AC_FC_DUMMY_MAIN' or `AC_F77_MAIN' and `AC_FC_MAIN' macros 6280 figure out how to deal with this interaction. 6281 6282 When using Fortran for purely numerical functions (no I/O, etc.) 6283 often one prefers to provide one's own `main' and skip the Fortran 6284 library initializations. In this case, however, one may still 6285 need to provide a dummy `MAIN__' routine in order to prevent 6286 linking errors on some systems. `AC_F77_DUMMY_MAIN' or 6287 `AC_FC_DUMMY_MAIN' detects whether any such routine is _required_ 6288 for linking, and what its name is; the shell variable 6289 `F77_DUMMY_MAIN' or `FC_DUMMY_MAIN' holds this name, `unknown' 6290 when no solution was found, and `none' when no such dummy main is 6291 needed. 6292 6293 By default, ACTION-IF-FOUND defines `F77_DUMMY_MAIN' or 6294 `FC_DUMMY_MAIN' to the name of this routine (e.g., `MAIN__') _if_ 6295 it is required. ACTION-IF-NOT-FOUND defaults to exiting with an 6296 error. 6297 6298 In order to link with Fortran routines, the user's C/C++ program 6299 should then include the following code to define the dummy main if 6300 it is needed: 6301 6302 #ifdef F77_DUMMY_MAIN 6303 # ifdef __cplusplus 6304 extern "C" 6305 # endif 6306 int F77_DUMMY_MAIN () { return 1; } 6307 #endif 6308 6309 (Replace `F77' with `FC' for Fortran instead of Fortran 77.) 6310 6311 Note that this macro is called automatically from `AC_F77_WRAPPERS' 6312 or `AC_FC_WRAPPERS'; there is generally no need to call it 6313 explicitly unless one wants to change the default actions. 6314 6315 The result of this macro is cached in the `ac_cv_f77_dummy_main' or 6316 `ac_cv_fc_dummy_main' variable, respectively. 6317 6318 -- Macro: AC_F77_MAIN 6319 -- Macro: AC_FC_MAIN 6320 As discussed above, many Fortran libraries allow you to provide an 6321 entry point called (say) `MAIN__' instead of the usual `main', 6322 which is then called by a `main' function in the Fortran libraries 6323 that initializes things like Fortran I/O. The `AC_F77_MAIN' and 6324 `AC_FC_MAIN' macros detect whether it is _possible_ to utilize 6325 such an alternate main function, and defines `F77_MAIN' and 6326 `FC_MAIN' to the name of the function. (If no alternate main 6327 function name is found, `F77_MAIN' and `FC_MAIN' are simply 6328 defined to `main'.) 6329 6330 Thus, when calling Fortran routines from C that perform things 6331 like I/O, one should use this macro and declare the "main" 6332 function like so: 6333 6334 #ifdef __cplusplus 6335 extern "C" 6336 #endif 6337 int F77_MAIN (int argc, char *argv[]); 6338 6339 (Again, replace `F77' with `FC' for Fortran instead of Fortran 77.) 6340 6341 The result of this macro is cached in the `ac_cv_f77_main' or 6342 `ac_cv_fc_main' variable, respectively. 6343 6344 -- Macro: AC_F77_WRAPPERS 6345 -- Macro: AC_FC_WRAPPERS 6346 Defines C macros `F77_FUNC (name, NAME)', `FC_FUNC (name, NAME)', 6347 `F77_FUNC_(name, NAME)', and `FC_FUNC_(name, NAME)' to properly 6348 mangle the names of C/C++ identifiers, and identifiers with 6349 underscores, respectively, so that they match the name-mangling 6350 scheme used by the Fortran compiler. 6351 6352 Fortran is case-insensitive, and in order to achieve this the 6353 Fortran compiler converts all identifiers into a canonical case 6354 and format. To call a Fortran subroutine from C or to write a C 6355 function that is callable from Fortran, the C program must 6356 explicitly use identifiers in the format expected by the Fortran 6357 compiler. In order to do this, one simply wraps all C identifiers 6358 in one of the macros provided by `AC_F77_WRAPPERS' or 6359 `AC_FC_WRAPPERS'. For example, suppose you have the following 6360 Fortran 77 subroutine: 6361 6362 subroutine foobar (x, y) 6363 double precision x, y 6364 y = 3.14159 * x 6365 return 6366 end 6367 6368 You would then declare its prototype in C or C++ as: 6369 6370 #define FOOBAR_F77 F77_FUNC (foobar, FOOBAR) 6371 #ifdef __cplusplus 6372 extern "C" /* prevent C++ name mangling */ 6373 #endif 6374 void FOOBAR_F77 (double *x, double *y); 6375 6376 Note that we pass both the lowercase and uppercase versions of the 6377 function name to `F77_FUNC' so that it can select the right one. 6378 Note also that all parameters to Fortran 77 routines are passed as 6379 pointers (*note Mixing Fortran 77 With C and C++: (automake)Mixing 6380 Fortran 77 With C and C++.). 6381 6382 (Replace `F77' with `FC' for Fortran instead of Fortran 77.) 6383 6384 Although Autoconf tries to be intelligent about detecting the 6385 name-mangling scheme of the Fortran compiler, there may be Fortran 6386 compilers that it doesn't support yet. In this case, the above 6387 code generates a compile-time error, but some other behavior 6388 (e.g., disabling Fortran-related features) can be induced by 6389 checking whether `F77_FUNC' or `FC_FUNC' is defined. 6390 6391 Now, to call that routine from a C program, we would do something 6392 like: 6393 6394 { 6395 double x = 2.7183, y; 6396 FOOBAR_F77 (&x, &y); 6397 } 6398 6399 If the Fortran identifier contains an underscore (e.g., `foo_bar'), 6400 you should use `F77_FUNC_' or `FC_FUNC_' instead of `F77_FUNC' or 6401 `FC_FUNC' (with the same arguments). This is because some Fortran 6402 compilers mangle names differently if they contain an underscore. 6403 6404 The name mangling scheme is encoded in the `ac_cv_f77_mangling' or 6405 `ac_cv_fc_mangling' cache variable, respectively, and also used for 6406 the `AC_F77_FUNC' and `AC_FC_FUNC' macros described below. 6407 6408 -- Macro: AC_F77_FUNC (NAME, [SHELLVAR]) 6409 -- Macro: AC_FC_FUNC (NAME, [SHELLVAR]) 6410 Given an identifier NAME, set the shell variable SHELLVAR to hold 6411 the mangled version NAME according to the rules of the Fortran 6412 linker (see also `AC_F77_WRAPPERS' or `AC_FC_WRAPPERS'). SHELLVAR 6413 is optional; if it is not supplied, the shell variable is simply 6414 NAME. The purpose of this macro is to give the caller a way to 6415 access the name-mangling information other than through the C 6416 preprocessor as above, for example, to call Fortran routines from 6417 some language other than C/C++. 6418 6419 -- Macro: AC_FC_SRCEXT (EXT, [ACTION-IF-SUCCESS], [ACTION-IF-FAILURE = 6420 `AC_MSG_FAILURE']) 6421 -- Macro: AC_FC_PP_SRCEXT (EXT, [ACTION-IF-SUCCESS], 6422 [ACTION-IF-FAILURE = `AC_MSG_FAILURE']) 6423 By default, the `FC' macros perform their tests using a `.f' 6424 extension for source-code files. Some compilers, however, only 6425 enable newer language features for appropriately named files, 6426 e.g., Fortran 90 features only for `.f90' files, or preprocessing 6427 only with `.F' files or maybe other upper-case extensions. On the 6428 other hand, some other compilers expect all source files to end in 6429 `.f' and require special flags to support other file name 6430 extensions. The `AC_FC_SRCEXT' and `AC_FC_PP_SRCEXT' macros deal 6431 with these issues. 6432 6433 The `AC_FC_SRCEXT' macro tries to get the `FC' compiler to accept 6434 files ending with the extension `.EXT' (i.e., EXT does _not_ 6435 contain the dot). If any special compiler flags are needed for 6436 this, it stores them in the output variable `FCFLAGS_EXT'. This 6437 extension and these flags are then used for all subsequent `FC' 6438 tests (until `AC_FC_SRCEXT' or `AC_FC_PP_SRCEXT' is called another 6439 time). 6440 6441 For example, you would use `AC_FC_SRCEXT(f90)' to employ the 6442 `.f90' extension in future tests, and it would set the 6443 `FCFLAGS_f90' output variable with any extra flags that are needed 6444 to compile such files. 6445 6446 Similarly, the `AC_FC_PP_SRCEXT' macro tries to get the `FC' 6447 compiler to preprocess and compile files with the extension 6448 `.EXT'. When both `fpp' and `cpp' style preprocessing are 6449 provided, the former is preferred, as the latter may treat 6450 continuation lines, `//' tokens, and white space differently from 6451 what some Fortran dialects expect. Conversely, if you do not want 6452 files to be preprocessed, use only lower-case characters in the 6453 file name extension. Like with `AC_FC_SRCEXT(f90)', any needed 6454 flags are stored in the `FCFLAGS_EXT' variable. 6455 6456 The `FCFLAGS_EXT' flags can _not_ be simply absorbed into 6457 `FCFLAGS', for two reasons based on the limitations of some 6458 compilers. First, only one `FCFLAGS_EXT' can be used at a time, 6459 so files with different extensions must be compiled separately. 6460 Second, `FCFLAGS_EXT' must appear _immediately_ before the 6461 source-code file name when compiling. So, continuing the example 6462 above, you might compile a `foo.f90' file in your makefile with the 6463 command: 6464 6465 foo.o: foo.f90 6466 $(FC) -c $(FCFLAGS) $(FCFLAGS_f90) '$(srcdir)/foo.f90' 6467 6468 If `AC_FC_SRCEXT' or `AC_FC_PP_SRCEXT' succeeds in compiling files 6469 with the EXT extension, it calls ACTION-IF-SUCCESS (defaults to 6470 nothing). If it fails, and cannot find a way to make the `FC' 6471 compiler accept such files, it calls ACTION-IF-FAILURE (defaults 6472 to exiting with an error message). 6473 6474 The `AC_FC_SRCEXT' and `AC_FC_PP_SRCEXT' macros cache their 6475 results in `ac_cv_fc_srcext_EXT' and `ac_cv_fc_pp_srcext_EXT' 6476 variables, respectively. 6477 6478 -- Macro: AC_FC_PP_DEFINE ([ACTION-IF-SUCCESS], [ACTION-IF-FAILURE = 6479 `AC_MSG_FAILURE']) 6480 Find a flag to specify defines for preprocessed Fortran. Not all 6481 Fortran compilers use `-D'. Substitute `FC_DEFINE' with the 6482 result and call ACTION-IF-SUCCESS (defaults to nothing) if 6483 successful, and ACTION-IF-FAILURE (defaults to failing with an 6484 error message) if not. 6485 6486 This macro calls `AC_FC_PP_SRCEXT([F])' in order to learn how to 6487 preprocess a `conftest.F' file, but restores a previously used 6488 Fortran source file extension afterwards again. 6489 6490 The result of this test is cached in the `ac_cv_fc_pp_define' 6491 variable. 6492 6493 -- Macro: AC_FC_FREEFORM ([ACTION-IF-SUCCESS], [ACTION-IF-FAILURE = 6494 `AC_MSG_FAILURE']) 6495 Try to ensure that the Fortran compiler (`$FC') allows free-format 6496 source code (as opposed to the older fixed-format style from 6497 Fortran 77). If necessary, it may add some additional flags to 6498 `FCFLAGS'. 6499 6500 This macro is most important if you are using the default `.f' 6501 extension, since many compilers interpret this extension as 6502 indicating fixed-format source unless an additional flag is 6503 supplied. If you specify a different extension with 6504 `AC_FC_SRCEXT', such as `.f90', then `AC_FC_FREEFORM' ordinarily 6505 succeeds without modifying `FCFLAGS'. For extensions which the 6506 compiler does not know about, the flag set by the `AC_FC_SRCEXT' 6507 macro might let the compiler assume Fortran 77 by default, however. 6508 6509 If `AC_FC_FREEFORM' succeeds in compiling free-form source, it 6510 calls ACTION-IF-SUCCESS (defaults to nothing). If it fails, it 6511 calls ACTION-IF-FAILURE (defaults to exiting with an error 6512 message). 6513 6514 The result of this test, or `none' or `unknown', is cached in the 6515 `ac_cv_fc_freeform' variable. 6516 6517 -- Macro: AC_FC_FIXEDFORM ([ACTION-IF-SUCCESS], [ACTION-IF-FAILURE = 6518 `AC_MSG_FAILURE']) 6519 Try to ensure that the Fortran compiler (`$FC') allows the old 6520 fixed-format source code (as opposed to free-format style). If 6521 necessary, it may add some additional flags to `FCFLAGS'. 6522 6523 This macro is needed for some compilers alias names like `xlf95' 6524 which assume free-form source code by default, and in case you 6525 want to use fixed-form source with an extension like `.f90' which 6526 many compilers interpret as free-form by default. If you specify 6527 a different extension with `AC_FC_SRCEXT', such as `.f', then 6528 `AC_FC_FIXEDFORM' ordinarily succeeds without modifying `FCFLAGS'. 6529 6530 If `AC_FC_FIXEDFORM' succeeds in compiling fixed-form source, it 6531 calls ACTION-IF-SUCCESS (defaults to nothing). If it fails, it 6532 calls ACTION-IF-FAILURE (defaults to exiting with an error 6533 message). 6534 6535 The result of this test, or `none' or `unknown', is cached in the 6536 `ac_cv_fc_fixedform' variable. 6537 6538 -- Macro: AC_FC_LINE_LENGTH ([LENGTH], [ACTION-IF-SUCCESS], 6539 [ACTION-IF-FAILURE = `AC_MSG_FAILURE']) 6540 Try to ensure that the Fortran compiler (`$FC') accepts long source 6541 code lines. The LENGTH argument may be given as 80, 132, or 6542 unlimited, and defaults to 132. Note that line lengths above 254 6543 columns are not portable, and some compilers do not accept more 6544 than 132 columns at least for fixed format source. If necessary, 6545 it may add some additional flags to `FCFLAGS'. 6546 6547 If `AC_FC_LINE_LENGTH' succeeds in compiling fixed-form source, it 6548 calls ACTION-IF-SUCCESS (defaults to nothing). If it fails, it 6549 calls ACTION-IF-FAILURE (defaults to exiting with an error 6550 message). 6551 6552 The result of this test, or `none' or `unknown', is cached in the 6553 `ac_cv_fc_line_length' variable. 6554 6555 -- Macro: AC_FC_CHECK_BOUNDS ([ACTION-IF-SUCCESS], [ACTION-IF-FAILURE 6556 = `AC_MSG_FAILURE']) 6557 The `AC_FC_CHECK_BOUNDS' macro tries to enable array bounds 6558 checking in the Fortran compiler. If successful, the 6559 ACTION-IF-SUCCESS is called and any needed flags are added to 6560 `FCFLAGS'. Otherwise, ACTION-IF-FAILURE is called, which defaults 6561 to failing with an error message. The macro currently requires 6562 Fortran 90 or a newer dialect. 6563 6564 The result of the macro is cached in the `ac_cv_fc_check_bounds' 6565 variable. 6566 6567 -- Macro: AC_F77_IMPLICIT_NONE ([ACTION-IF-SUCCESS], 6568 [ACTION-IF-FAILURE = `AC_MSG_FAILURE']) 6569 -- Macro: AC_FC_IMPLICIT_NONE ([ACTION-IF-SUCCESS], [ACTION-IF-FAILURE 6570 = `AC_MSG_FAILURE']) 6571 Try to disallow implicit declarations in the Fortran compiler. If 6572 successful, ACTION-IF-SUCCESS is called and any needed flags are 6573 added to `FFLAGS' or `FCFLAGS', respectively. Otherwise, 6574 ACTION-IF-FAILURE is called, which defaults to failing with an 6575 error message. 6576 6577 The result of these macros are cached in the 6578 `ac_cv_f77_implicit_none' and `ac_cv_fc_implicit_none' variables, 6579 respectively. 6580 6581 -- Macro: AC_FC_MODULE_EXTENSION 6582 Find the Fortran 90 module file name extension. Most Fortran 90 6583 compilers store module information in files separate from the 6584 object files. The module files are usually named after the name 6585 of the module rather than the source file name, with characters 6586 possibly turned to upper case, plus an extension, often `.mod'. 6587 6588 Not all compilers use module files at all, or by default. The Cray 6589 Fortran compiler requires `-e m' in order to store and search 6590 module information in `.mod' files rather than in object files. 6591 Likewise, the Fujitsu Fortran compilers uses the `-Am' option to 6592 indicate how module information is stored. 6593 6594 The `AC_FC_MODULE_EXTENSION' macro computes the module extension 6595 without the leading dot, and stores that in the `FC_MODEXT' 6596 variable. If the compiler does not produce module files, or the 6597 extension cannot be determined, `FC_MODEXT' is empty. Typically, 6598 the result of this macro may be used in cleanup `make' rules as 6599 follows: 6600 6601 clean-modules: 6602 -test -z "$(FC_MODEXT)" || rm -f *.$(FC_MODEXT) 6603 6604 The extension, or `unknown', is cached in the 6605 `ac_cv_fc_module_ext' variable. 6606 6607 -- Macro: AC_FC_MODULE_FLAG ([ACTION-IF-SUCCESS], [ACTION-IF-FAILURE = 6608 `AC_MSG_FAILURE']) 6609 Find the compiler flag to include Fortran 90 module information 6610 from another directory, and store that in the `FC_MODINC' variable. 6611 Call ACTION-IF-SUCCESS (defaults to nothing) if successful, and 6612 set `FC_MODINC' to empty and call ACTION-IF-FAILURE (defaults to 6613 exiting with an error message) if not. 6614 6615 Most Fortran 90 compilers provide a way to specify module 6616 directories. Some have separate flags for the directory to write 6617 module files to, and directories to search them in, whereas others 6618 only allow writing to the current directory or to the first 6619 directory specified in the include path. Further, with some 6620 compilers, the module search path and the preprocessor search path 6621 can only be modified with the same flag. Thus, for portability, 6622 write module files to the current directory only and list that as 6623 first directory in the search path. 6624 6625 There may be no whitespace between `FC_MODINC' and the following 6626 directory name, but `FC_MODINC' may contain trailing white space. 6627 For example, if you use Automake and would like to search `../lib' 6628 for module files, you can use the following: 6629 6630 AM_FCFLAGS = $(FC_MODINC). $(FC_MODINC)../lib 6631 6632 Inside `configure' tests, you can use: 6633 6634 if test -n "$FC_MODINC"; then 6635 FCFLAGS="$FCFLAGS $FC_MODINC. $FC_MODINC../lib" 6636 fi 6637 6638 The flag is cached in the `ac_cv_fc_module_flag' variable. The 6639 substituted value of `FC_MODINC' may refer to the `ac_empty' dummy 6640 placeholder empty variable, to avoid losing the significant 6641 trailing whitespace in a `Makefile'. 6642 6643 -- Macro: AC_FC_MODULE_OUTPUT_FLAG ([ACTION-IF-SUCCESS], 6644 [ACTION-IF-FAILURE = `AC_MSG_FAILURE']) 6645 Find the compiler flag to write Fortran 90 module information to 6646 another directory, and store that in the `FC_MODOUT' variable. 6647 Call ACTION-IF-SUCCESS (defaults to nothing) if successful, and 6648 set `FC_MODOUT' to empty and call ACTION-IF-FAILURE (defaults to 6649 exiting with an error message) if not. 6650 6651 Not all Fortran 90 compilers write module files, and of those that 6652 do, not all allow writing to a directory other than the current 6653 one, nor do all have separate flags for writing and reading; see 6654 the description of `AC_FC_MODULE_FLAG' above. If you need to be 6655 able to write to another directory, for maximum portability use 6656 `FC_MODOUT' before any `FC_MODINC' and include both the current 6657 directory and the one you write to in the search path: 6658 6659 AM_FCFLAGS = $(FC_MODOUT)../mod $(FC_MODINC)../mod $(FC_MODINC). ... 6660 6661 The flag is cached in the `ac_cv_fc_module_output_flag' variable. 6662 The substituted value of `FC_MODOUT' may refer to the `ac_empty' 6663 dummy placeholder empty variable, to avoid losing the significant 6664 trailing whitespace in a `Makefile'. 6665 6666 6667File: autoconf.info, Node: Go Compiler, Prev: Fortran Compiler, Up: Compilers and Preprocessors 6668 66695.10.9 Go Compiler Characteristics 6670---------------------------------- 6671 6672Autoconf provides basic support for the Go programming language when 6673using the `gccgo' compiler (there is currently no support for the `6g' 6674and `8g' compilers). 6675 6676 -- Macro: AC_PROG_GO ([COMPILER-SEARCH-LIST]) 6677 Find the Go compiler to use. Check whether the environment 6678 variable `GOC' is set; if so, then set output variable `GOC' to its 6679 value. 6680 6681 Otherwise, if the macro is invoked without an argument, then 6682 search for a Go compiler named `gccgo'. If it is not found, then 6683 as a last resort set `GOC' to `gccgo'. 6684 6685 This macro may be invoked with an optional first argument which, if 6686 specified, must be a blank-separated list of Go compilers to 6687 search for. 6688 6689 If output variable `GOFLAGS' was not already set, set it to `-g 6690 -O2'. If your package does not like this default, `GOFLAGS' may 6691 be set before `AC_PROG_GO'. 6692 6693 6694File: autoconf.info, Node: System Services, Next: Posix Variants, Prev: Compilers and Preprocessors, Up: Existing Tests 6695 66965.11 System Services 6697==================== 6698 6699The following macros check for operating system services or 6700capabilities. 6701 6702 -- Macro: AC_PATH_X 6703 Try to locate the X Window System include files and libraries. If 6704 the user gave the command line options `--x-includes=DIR' and 6705 `--x-libraries=DIR', use those directories. 6706 6707 If either or both were not given, get the missing values by running 6708 `xmkmf' (or an executable pointed to by the `XMKMF' environment 6709 variable) on a trivial `Imakefile' and examining the makefile that 6710 it produces. Setting `XMKMF' to `false' disables this method. 6711 6712 If this method fails to find the X Window System, `configure' 6713 looks for the files in several directories where they often reside. 6714 If either method is successful, set the shell variables 6715 `x_includes' and `x_libraries' to their locations, unless they are 6716 in directories the compiler searches by default. 6717 6718 If both methods fail, or the user gave the command line option 6719 `--without-x', set the shell variable `no_x' to `yes'; otherwise 6720 set it to the empty string. 6721 6722 -- Macro: AC_PATH_XTRA 6723 An enhanced version of `AC_PATH_X'. It adds the C compiler flags 6724 that X needs to output variable `X_CFLAGS', and the X linker flags 6725 to `X_LIBS'. Define `X_DISPLAY_MISSING' if X is not available. 6726 6727 This macro also checks for special libraries that some systems 6728 need in order to compile X programs. It adds any that the system 6729 needs to output variable `X_EXTRA_LIBS'. And it checks for 6730 special X11R6 libraries that need to be linked with before 6731 `-lX11', and adds any found to the output variable `X_PRE_LIBS'. 6732 6733 6734 -- Macro: AC_SYS_INTERPRETER 6735 Check whether the system supports starting scripts with a line of 6736 the form `#!/bin/sh' to select the interpreter to use for the 6737 script. After running this macro, shell code in `configure.ac' 6738 can check the shell variable `interpval'; it is set to `yes' if 6739 the system supports `#!', `no' if not. 6740 6741 -- Macro: AC_SYS_LARGEFILE 6742 Arrange for 64-bit file offsets, known as large-file support 6743 (http://www.unix-systems.org/version2/whatsnew/lfs20mar.html). On 6744 some hosts, one must use special compiler options to build 6745 programs that can access large files. Append any such options to 6746 the output variable `CC'. Define `_FILE_OFFSET_BITS' and 6747 `_LARGE_FILES' if necessary. 6748 6749 Large-file support can be disabled by configuring with the 6750 `--disable-largefile' option. 6751 6752 If you use this macro, check that your program works even when 6753 `off_t' is wider than `long int', since this is common when 6754 large-file support is enabled. For example, it is not correct to 6755 print an arbitrary `off_t' value `X' with `printf ("%ld", (long 6756 int) X)'. 6757 6758 The LFS introduced the `fseeko' and `ftello' functions to replace 6759 their C counterparts `fseek' and `ftell' that do not use `off_t'. 6760 Take care to use `AC_FUNC_FSEEKO' to make their prototypes 6761 available when using them and large-file support is enabled. 6762 6763 -- Macro: AC_SYS_LONG_FILE_NAMES 6764 If the system supports file names longer than 14 characters, define 6765 `HAVE_LONG_FILE_NAMES'. 6766 6767 -- Macro: AC_SYS_POSIX_TERMIOS 6768 Check to see if the Posix termios headers and functions are 6769 available on the system. If so, set the shell variable 6770 `ac_cv_sys_posix_termios' to `yes'. If not, set the variable to 6771 `no'. 6772 6773 6774File: autoconf.info, Node: Posix Variants, Next: Erlang Libraries, Prev: System Services, Up: Existing Tests 6775 67765.12 Posix Variants 6777=================== 6778 6779The following macro makes it possible to use features of Posix that are 6780extensions to C, as well as platform extensions not defined by Posix. 6781 6782 -- Macro: AC_USE_SYSTEM_EXTENSIONS 6783 This macro was introduced in Autoconf 2.60. If possible, enable 6784 extensions to C or Posix on hosts that normally disable the 6785 extensions, typically due to standards-conformance namespace 6786 issues. This should be called before any macros that run the C 6787 compiler. The following preprocessor macros are defined where 6788 appropriate: 6789 6790 `_GNU_SOURCE' 6791 Enable extensions on GNU/Linux. 6792 6793 `__EXTENSIONS__' 6794 Enable general extensions on Solaris. 6795 6796 `_POSIX_PTHREAD_SEMANTICS' 6797 Enable threading extensions on Solaris. 6798 6799 `_TANDEM_SOURCE' 6800 Enable extensions for the HP NonStop platform. 6801 6802 `_ALL_SOURCE' 6803 Enable extensions for AIX 3, and for Interix. 6804 6805 `_POSIX_SOURCE' 6806 Enable Posix functions for Minix. 6807 6808 `_POSIX_1_SOURCE' 6809 Enable additional Posix functions for Minix. 6810 6811 `_MINIX' 6812 Identify Minix platform. This particular preprocessor macro 6813 is obsolescent, and may be removed in a future release of 6814 Autoconf. 6815 6816 6817File: autoconf.info, Node: Erlang Libraries, Prev: Posix Variants, Up: Existing Tests 6818 68195.13 Erlang Libraries 6820===================== 6821 6822The following macros check for an installation of Erlang/OTP, and for 6823the presence of certain Erlang libraries. All those macros require the 6824configuration of an Erlang interpreter and an Erlang compiler (*note 6825Erlang Compiler and Interpreter::). 6826 6827 -- Macro: AC_ERLANG_SUBST_ERTS_VER 6828 Set the output variable `ERLANG_ERTS_VER' to the version of the 6829 Erlang runtime system (as returned by Erlang's 6830 `erlang:system_info(version)' function). The result of this test 6831 is cached if caching is enabled when running `configure'. The 6832 `ERLANG_ERTS_VER' variable is not intended to be used for testing 6833 for features of specific ERTS versions, but to be used for 6834 substituting the ERTS version in Erlang/OTP release resource files 6835 (`.rel' files), as shown below. 6836 6837 -- Macro: AC_ERLANG_SUBST_ROOT_DIR 6838 Set the output variable `ERLANG_ROOT_DIR' to the path to the base 6839 directory in which Erlang/OTP is installed (as returned by Erlang's 6840 `code:root_dir/0' function). The result of this test is cached if 6841 caching is enabled when running `configure'. 6842 6843 -- Macro: AC_ERLANG_SUBST_LIB_DIR 6844 Set the output variable `ERLANG_LIB_DIR' to the path of the library 6845 directory of Erlang/OTP (as returned by Erlang's `code:lib_dir/0' 6846 function), which subdirectories each contain an installed 6847 Erlang/OTP library. The result of this test is cached if caching 6848 is enabled when running `configure'. 6849 6850 -- Macro: AC_ERLANG_CHECK_LIB (LIBRARY, [ACTION-IF-FOUND], 6851 [ACTION-IF-NOT-FOUND]) 6852 Test whether the Erlang/OTP library LIBRARY is installed by 6853 calling Erlang's `code:lib_dir/1' function. The result of this 6854 test is cached if caching is enabled when running `configure'. 6855 ACTION-IF-FOUND is a list of shell commands to run if the library 6856 is installed; ACTION-IF-NOT-FOUND is a list of shell commands to 6857 run if it is not. Additionally, if the library is installed, the 6858 output variable `ERLANG_LIB_DIR_LIBRARY' is set to the path to the 6859 library installation directory, and the output variable 6860 `ERLANG_LIB_VER_LIBRARY' is set to the version number that is part 6861 of the subdirectory name, if it is in the standard form 6862 (`LIBRARY-VERSION'). If the directory name does not have a 6863 version part, `ERLANG_LIB_VER_LIBRARY' is set to the empty string. 6864 If the library is not installed, `ERLANG_LIB_DIR_LIBRARY' and 6865 `ERLANG_LIB_VER_LIBRARY' are set to `"not found"'. For example, 6866 to check if library `stdlib' is installed: 6867 6868 AC_ERLANG_CHECK_LIB([stdlib], 6869 [echo "stdlib version \"$ERLANG_LIB_VER_stdlib\"" 6870 echo "is installed in \"$ERLANG_LIB_DIR_stdlib\""], 6871 [AC_MSG_ERROR([stdlib was not found!])]) 6872 6873 The `ERLANG_LIB_VER_LIBRARY' variables (set by 6874 `AC_ERLANG_CHECK_LIB') and the `ERLANG_ERTS_VER' variable (set by 6875 `AC_ERLANG_SUBST_ERTS_VER') are not intended to be used for 6876 testing for features of specific versions of libraries or of the 6877 Erlang runtime system. Those variables are intended to be 6878 substituted in Erlang release resource files (`.rel' files). For 6879 instance, to generate a `example.rel' file for an application 6880 depending on the `stdlib' library, `configure.ac' could contain: 6881 6882 AC_ERLANG_SUBST_ERTS_VER 6883 AC_ERLANG_CHECK_LIB([stdlib], 6884 [], 6885 [AC_MSG_ERROR([stdlib was not found!])]) 6886 AC_CONFIG_FILES([example.rel]) 6887 6888 The `example.rel.in' file used to generate `example.rel' should 6889 contain: 6890 6891 {release, 6892 {"@PACKAGE@", "@VERSION@"}, 6893 {erts, "@ERLANG_ERTS_VER@"}, 6894 [{stdlib, "@ERLANG_LIB_VER_stdlib@"}, 6895 {@PACKAGE@, "@VERSION@"}]}. 6896 6897 In addition to the above macros, which test installed Erlang 6898libraries, the following macros determine the paths to the directories 6899into which newly built Erlang libraries are to be installed: 6900 6901 -- Macro: AC_ERLANG_SUBST_INSTALL_LIB_DIR 6902 Set the `ERLANG_INSTALL_LIB_DIR' output variable to the directory 6903 into which every built Erlang library should be installed in a 6904 separate subdirectory. If this variable is not set in the 6905 environment when `configure' runs, its default value is 6906 `${libdir}/erlang/lib'. 6907 6908 -- Macro: AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR (LIBRARY, VERSION) 6909 Set the `ERLANG_INSTALL_LIB_DIR_LIBRARY' output variable to the 6910 directory into which the built Erlang library LIBRARY version 6911 VERSION should be installed. If this variable is not set in the 6912 environment when `configure' runs, its default value is 6913 `$ERLANG_INSTALL_LIB_DIR/LIBRARY-VERSION', the value of the 6914 `ERLANG_INSTALL_LIB_DIR' variable being set by the 6915 `AC_ERLANG_SUBST_INSTALL_LIB_DIR' macro. 6916 6917 6918File: autoconf.info, Node: Writing Tests, Next: Results, Prev: Existing Tests, Up: Top 6919 69206 Writing Tests 6921*************** 6922 6923If the existing feature tests don't do something you need, you have to 6924write new ones. These macros are the building blocks. They provide 6925ways for other macros to check whether various kinds of features are 6926available and report the results. 6927 6928 This chapter contains some suggestions and some of the reasons why 6929the existing tests are written the way they are. You can also learn a 6930lot about how to write Autoconf tests by looking at the existing ones. 6931If something goes wrong in one or more of the Autoconf tests, this 6932information can help you understand the assumptions behind them, which 6933might help you figure out how to best solve the problem. 6934 6935 These macros check the output of the compiler system of the current 6936language (*note Language Choice::). They do not cache the results of 6937their tests for future use (*note Caching Results::), because they don't 6938know enough about the information they are checking for to generate a 6939cache variable name. They also do not print any messages, for the same 6940reason. The checks for particular kinds of features call these macros 6941and do cache their results and print messages about what they're 6942checking for. 6943 6944 When you write a feature test that could be applicable to more than 6945one software package, the best thing to do is encapsulate it in a new 6946macro. *Note Writing Autoconf Macros::, for how to do that. 6947 6948* Menu: 6949 6950* Language Choice:: Selecting which language to use for testing 6951* Writing Test Programs:: Forging source files for compilers 6952* Running the Preprocessor:: Detecting preprocessor symbols 6953* Running the Compiler:: Detecting language or header features 6954* Running the Linker:: Detecting library features 6955* Runtime:: Testing for runtime features 6956* Systemology:: A zoology of operating systems 6957* Multiple Cases:: Tests for several possible values 6958 6959 6960File: autoconf.info, Node: Language Choice, Next: Writing Test Programs, Up: Writing Tests 6961 69626.1 Language Choice 6963=================== 6964 6965Autoconf-generated `configure' scripts check for the C compiler and its 6966features by default. Packages that use other programming languages 6967(maybe more than one, e.g., C and C++) need to test features of the 6968compilers for the respective languages. The following macros determine 6969which programming language is used in the subsequent tests in 6970`configure.ac'. 6971 6972 -- Macro: AC_LANG (LANGUAGE) 6973 Do compilation tests using the compiler, preprocessor, and file 6974 extensions for the specified LANGUAGE. 6975 6976 Supported languages are: 6977 6978 `C' 6979 Do compilation tests using `CC' and `CPP' and use extension 6980 `.c' for test programs. Use compilation flags: `CPPFLAGS' 6981 with `CPP', and both `CPPFLAGS' and `CFLAGS' with `CC'. 6982 6983 `C++' 6984 Do compilation tests using `CXX' and `CXXCPP' and use 6985 extension `.C' for test programs. Use compilation flags: 6986 `CPPFLAGS' with `CXXCPP', and both `CPPFLAGS' and `CXXFLAGS' 6987 with `CXX'. 6988 6989 `Fortran 77' 6990 Do compilation tests using `F77' and use extension `.f' for 6991 test programs. Use compilation flags: `FFLAGS'. 6992 6993 `Fortran' 6994 Do compilation tests using `FC' and use extension `.f' (or 6995 whatever has been set by `AC_FC_SRCEXT') for test programs. 6996 Use compilation flags: `FCFLAGS'. 6997 6998 `Erlang' 6999 Compile and execute tests using `ERLC' and `ERL' and use 7000 extension `.erl' for test Erlang modules. Use compilation 7001 flags: `ERLCFLAGS'. 7002 7003 `Objective C' 7004 Do compilation tests using `OBJC' and `OBJCPP' and use 7005 extension `.m' for test programs. Use compilation flags: 7006 `CPPFLAGS' with `OBJCPP', and both `CPPFLAGS' and `OBJCFLAGS' 7007 with `OBJC'. 7008 7009 `Objective C++' 7010 Do compilation tests using `OBJCXX' and `OBJCXXCPP' and use 7011 extension `.mm' for test programs. Use compilation flags: 7012 `CPPFLAGS' with `OBJCXXCPP', and both `CPPFLAGS' and 7013 `OBJCXXFLAGS' with `OBJCXX'. 7014 7015 `Go' 7016 Do compilation tests using `GOC' and use extension `.go' for 7017 test programs. Use compilation flags `GOFLAGS'. 7018 7019 -- Macro: AC_LANG_PUSH (LANGUAGE) 7020 Remember the current language (as set by `AC_LANG') on a stack, and 7021 then select the LANGUAGE. Use this macro and `AC_LANG_POP' in 7022 macros that need to temporarily switch to a particular language. 7023 7024 -- Macro: AC_LANG_POP ([LANGUAGE]) 7025 Select the language that is saved on the top of the stack, as set 7026 by `AC_LANG_PUSH', and remove it from the stack. 7027 7028 If given, LANGUAGE specifies the language we just _quit_. It is a 7029 good idea to specify it when it's known (which should be the 7030 case...), since Autoconf detects inconsistencies. 7031 7032 AC_LANG_PUSH([Fortran 77]) 7033 # Perform some tests on Fortran 77. 7034 # ... 7035 AC_LANG_POP([Fortran 77]) 7036 7037 -- Macro: AC_LANG_ASSERT (LANGUAGE) 7038 Check statically that the current language is LANGUAGE. You 7039 should use this in your language specific macros to avoid that 7040 they be called with an inappropriate language. 7041 7042 This macro runs only at `autoconf' time, and incurs no cost at 7043 `configure' time. Sadly enough and because Autoconf is a two 7044 layer language (1), the macros `AC_LANG_PUSH' and `AC_LANG_POP' 7045 cannot be "optimizing", therefore as much as possible you ought to 7046 avoid using them to wrap your code, rather, require from the user 7047 to run the macro with a correct current language, and check it 7048 with `AC_LANG_ASSERT'. And anyway, that may help the user 7049 understand she is running a Fortran macro while expecting a result 7050 about her Fortran 77 compiler... 7051 7052 -- Macro: AC_REQUIRE_CPP 7053 Ensure that whichever preprocessor would currently be used for 7054 tests has been found. Calls `AC_REQUIRE' (*note Prerequisite 7055 Macros::) with an argument of either `AC_PROG_CPP' or 7056 `AC_PROG_CXXCPP', depending on which language is current. 7057 7058 ---------- Footnotes ---------- 7059 7060 (1) Because M4 is not aware of Sh code, especially conditionals, 7061some optimizations that look nice statically may produce incorrect 7062results at runtime. 7063 7064 7065File: autoconf.info, Node: Writing Test Programs, Next: Running the Preprocessor, Prev: Language Choice, Up: Writing Tests 7066 70676.2 Writing Test Programs 7068========================= 7069 7070Autoconf tests follow a common scheme: feed some program with some 7071input, and most of the time, feed a compiler with some source file. 7072This section is dedicated to these source samples. 7073 7074* Menu: 7075 7076* Guidelines:: General rules for writing test programs 7077* Test Functions:: Avoiding pitfalls in test programs 7078* Generating Sources:: Source program boilerplate 7079 7080 7081File: autoconf.info, Node: Guidelines, Next: Test Functions, Up: Writing Test Programs 7082 70836.2.1 Guidelines for Test Programs 7084---------------------------------- 7085 7086The most important rule to follow when writing testing samples is: 7087 7088 _Look for realism._ 7089 7090 This motto means that testing samples must be written with the same 7091strictness as real programs are written. In particular, you should 7092avoid "shortcuts" and simplifications. 7093 7094 Don't just play with the preprocessor if you want to prepare a 7095compilation. For instance, using `cpp' to check whether a header is 7096functional might let your `configure' accept a header which causes some 7097_compiler_ error. Do not hesitate to check a header with other headers 7098included before, especially required headers. 7099 7100 Make sure the symbols you use are properly defined, i.e., refrain 7101from simply declaring a function yourself instead of including the 7102proper header. 7103 7104 Test programs should not write to standard output. They should exit 7105with status 0 if the test succeeds, and with status 1 otherwise, so 7106that success can be distinguished easily from a core dump or other 7107failure; segmentation violations and other failures produce a nonzero 7108exit status. Unless you arrange for `exit' to be declared, test 7109programs should `return', not `exit', from `main', because on many 7110systems `exit' is not declared by default. 7111 7112 Test programs can use `#if' or `#ifdef' to check the values of 7113preprocessor macros defined by tests that have already run. For 7114example, if you call `AC_HEADER_STDBOOL', then later on in 7115`configure.ac' you can have a test program that includes `stdbool.h' 7116conditionally: 7117 7118 #ifdef HAVE_STDBOOL_H 7119 # include <stdbool.h> 7120 #endif 7121 7122 Both `#if HAVE_STDBOOL_H' and `#ifdef HAVE_STDBOOL_H' will work with 7123any standard C compiler. Some developers prefer `#if' because it is 7124easier to read, while others prefer `#ifdef' because it avoids 7125diagnostics with picky compilers like GCC with the `-Wundef' option. 7126 7127 If a test program needs to use or create a data file, give it a name 7128that starts with `conftest', such as `conftest.data'. The `configure' 7129script cleans up by running `rm -f -r conftest*' after running test 7130programs and if the script is interrupted. 7131 7132 7133File: autoconf.info, Node: Test Functions, Next: Generating Sources, Prev: Guidelines, Up: Writing Test Programs 7134 71356.2.2 Test Functions 7136-------------------- 7137 7138These days it's safe to assume support for function prototypes 7139(introduced in C89). 7140 7141 Functions that test programs declare should also be conditionalized 7142for C++, which requires `extern "C"' prototypes. Make sure to not 7143include any header files containing clashing prototypes. 7144 7145 #ifdef __cplusplus 7146 extern "C" 7147 #endif 7148 void *valloc (size_t); 7149 7150 If a test program calls a function with invalid parameters (just to 7151see whether it exists), organize the program to ensure that it never 7152invokes that function. You can do this by calling it in another 7153function that is never invoked. You can't do it by putting it after a 7154call to `exit', because GCC version 2 knows that `exit' never returns 7155and optimizes out any code that follows it in the same block. 7156 7157 If you include any header files, be sure to call the functions 7158relevant to them with the correct number of arguments, even if they are 7159just 0, to avoid compilation errors due to prototypes. GCC version 2 7160has internal prototypes for several functions that it automatically 7161inlines; for example, `memcpy'. To avoid errors when checking for 7162them, either pass them the correct number of arguments or redeclare them 7163with a different return type (such as `char'). 7164 7165 7166File: autoconf.info, Node: Generating Sources, Prev: Test Functions, Up: Writing Test Programs 7167 71686.2.3 Generating Sources 7169------------------------ 7170 7171Autoconf provides a set of macros that can be used to generate test 7172source files. They are written to be language generic, i.e., they 7173actually depend on the current language (*note Language Choice::) to 7174"format" the output properly. 7175 7176 -- Macro: AC_LANG_CONFTEST (SOURCE) 7177 Save the SOURCE text in the current test source file: 7178 `conftest.EXTENSION' where the EXTENSION depends on the current 7179 language. As of Autoconf 2.63b, the source file also contains the 7180 results of all of the `AC_DEFINE' performed so far. 7181 7182 Note that the SOURCE is evaluated exactly once, like regular 7183 Autoconf macro arguments, and therefore (i) you may pass a macro 7184 invocation, (ii) if not, be sure to double quote if needed. 7185 7186 This macro issues a warning during `autoconf' processing if SOURCE 7187 does not include an expansion of the macro 7188 `AC_LANG_DEFINES_PROVIDED' (note that both `AC_LANG_SOURCE' and 7189 `AC_LANG_PROGRAM' call this macro, and thus avoid the warning). 7190 7191 This macro is seldom called directly, but is used under the hood 7192 by more common macros such as `AC_COMPILE_IFELSE' and 7193 `AC_RUN_IFELSE'. 7194 7195 -- Macro: AC_LANG_DEFINES_PROVIDED 7196 This macro is called as a witness that the file 7197 `conftest.EXTENSION' appropriate for the current language is 7198 complete, including all previously determined results from 7199 `AC_DEFINE'. This macro is seldom called directly, but exists if 7200 you have a compelling reason to write a conftest file without using 7201 `AC_LANG_SOURCE', yet still want to avoid a syntax warning from 7202 `AC_LANG_CONFTEST'. 7203 7204 -- Macro: AC_LANG_SOURCE (SOURCE) 7205 Expands into the SOURCE, with the definition of all the 7206 `AC_DEFINE' performed so far. This macro includes an expansion of 7207 `AC_LANG_DEFINES_PROVIDED'. 7208 7209 In many cases, you may find it more convenient to use the wrapper 7210 `AC_LANG_PROGRAM'. 7211 7212 For instance, executing (observe the double quotation!): 7213 7214 AC_INIT([Hello], [1.0], [bug-hello@example.org], [], 7215 [http://www.example.org/]) 7216 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"], 7217 [Greetings string.]) 7218 AC_LANG([C]) 7219 AC_LANG_CONFTEST( 7220 [AC_LANG_SOURCE([[const char hw[] = "Hello, World\n";]])]) 7221 gcc -E -dD conftest.c 7222 7223on a system with `gcc' installed, results in: 7224 7225 ... 7226 # 1 "conftest.c" 7227 7228 #define PACKAGE_NAME "Hello" 7229 #define PACKAGE_TARNAME "hello" 7230 #define PACKAGE_VERSION "1.0" 7231 #define PACKAGE_STRING "Hello 1.0" 7232 #define PACKAGE_BUGREPORT "bug-hello@example.org" 7233 #define PACKAGE_URL "http://www.example.org/" 7234 #define HELLO_WORLD "Hello, World\n" 7235 7236 const char hw[] = "Hello, World\n"; 7237 7238 When the test language is Fortran, Erlang, or Go, the `AC_DEFINE' 7239definitions are not automatically translated into constants in the 7240source code by this macro. 7241 7242 -- Macro: AC_LANG_PROGRAM (PROLOGUE, BODY) 7243 Expands into a source file which consists of the PROLOGUE, and 7244 then BODY as body of the main function (e.g., `main' in C). Since 7245 it uses `AC_LANG_SOURCE', the features of the latter are available. 7246 7247 For instance: 7248 7249 AC_INIT([Hello], [1.0], [bug-hello@example.org], [], 7250 [http://www.example.org/]) 7251 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"], 7252 [Greetings string.]) 7253 AC_LANG_CONFTEST( 7254 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]], 7255 [[fputs (hw, stdout);]])]) 7256 gcc -E -dD conftest.c 7257 7258on a system with `gcc' installed, results in: 7259 7260 ... 7261 # 1 "conftest.c" 7262 7263 #define PACKAGE_NAME "Hello" 7264 #define PACKAGE_TARNAME "hello" 7265 #define PACKAGE_VERSION "1.0" 7266 #define PACKAGE_STRING "Hello 1.0" 7267 #define PACKAGE_BUGREPORT "bug-hello@example.org" 7268 #define PACKAGE_URL "http://www.example.org/" 7269 #define HELLO_WORLD "Hello, World\n" 7270 7271 const char hw[] = "Hello, World\n"; 7272 int 7273 main () 7274 { 7275 fputs (hw, stdout); 7276 ; 7277 return 0; 7278 } 7279 7280 In Erlang tests, the created source file is that of an Erlang module 7281called `conftest' (`conftest.erl'). This module defines and exports at 7282least one `start/0' function, which is called to perform the test. The 7283PROLOGUE is optional code that is inserted between the module header and 7284the `start/0' function definition. BODY is the body of the `start/0' 7285function without the final period (*note Runtime::, about constraints 7286on this function's behavior). 7287 7288 For instance: 7289 7290 AC_INIT([Hello], [1.0], [bug-hello@example.org]) 7291 AC_LANG(Erlang) 7292 AC_LANG_CONFTEST( 7293 [AC_LANG_PROGRAM([[-define(HELLO_WORLD, "Hello, world!").]], 7294 [[io:format("~s~n", [?HELLO_WORLD])]])]) 7295 cat conftest.erl 7296 7297results in: 7298 7299 -module(conftest). 7300 -export([start/0]). 7301 -define(HELLO_WORLD, "Hello, world!"). 7302 start() -> 7303 io:format("~s~n", [?HELLO_WORLD]) 7304 . 7305 7306 -- Macro: AC_LANG_CALL (PROLOGUE, FUNCTION) 7307 Expands into a source file which consists of the PROLOGUE, and 7308 then a call to the FUNCTION as body of the main function (e.g., 7309 `main' in C). Since it uses `AC_LANG_PROGRAM', the feature of the 7310 latter are available. 7311 7312 This function will probably be replaced in the future by a version 7313 which would enable specifying the arguments. The use of this 7314 macro is not encouraged, as it violates strongly the typing system. 7315 7316 This macro cannot be used for Erlang tests. 7317 7318 -- Macro: AC_LANG_FUNC_LINK_TRY (FUNCTION) 7319 Expands into a source file which uses the FUNCTION in the body of 7320 the main function (e.g., `main' in C). Since it uses 7321 `AC_LANG_PROGRAM', the features of the latter are available. 7322 7323 As `AC_LANG_CALL', this macro is documented only for completeness. 7324 It is considered to be severely broken, and in the future will be 7325 removed in favor of actual function calls (with properly typed 7326 arguments). 7327 7328 This macro cannot be used for Erlang tests. 7329 7330 7331File: autoconf.info, Node: Running the Preprocessor, Next: Running the Compiler, Prev: Writing Test Programs, Up: Writing Tests 7332 73336.3 Running the Preprocessor 7334============================ 7335 7336Sometimes one might need to run the preprocessor on some source file. 7337_Usually it is a bad idea_, as you typically need to _compile_ your 7338project, not merely run the preprocessor on it; therefore you certainly 7339want to run the compiler, not the preprocessor. Resist the temptation 7340of following the easiest path. 7341 7342 Nevertheless, if you need to run the preprocessor, then use 7343`AC_PREPROC_IFELSE'. 7344 7345 The macros described in this section cannot be used for tests in 7346Erlang, Fortran, or Go, since those languages require no preprocessor. 7347 7348 -- Macro: AC_PREPROC_IFELSE (INPUT, [ACTION-IF-TRUE], 7349 [ACTION-IF-FALSE]) 7350 Run the preprocessor of the current language (*note Language 7351 Choice::) on the INPUT, run the shell commands ACTION-IF-TRUE on 7352 success, ACTION-IF-FALSE otherwise. The INPUT can be made by 7353 `AC_LANG_PROGRAM' and friends. 7354 7355 This macro uses `CPPFLAGS', but not `CFLAGS', because `-g', `-O', 7356 etc. are not valid options to many C preprocessors. 7357 7358 It is customary to report unexpected failures with 7359 `AC_MSG_FAILURE'. If needed, ACTION-IF-TRUE can further access 7360 the preprocessed output in the file `conftest.i'. 7361 7362 For instance: 7363 7364 AC_INIT([Hello], [1.0], [bug-hello@example.org]) 7365 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"], 7366 [Greetings string.]) 7367 AC_PREPROC_IFELSE( 7368 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]], 7369 [[fputs (hw, stdout);]])], 7370 [AC_MSG_RESULT([OK])], 7371 [AC_MSG_FAILURE([unexpected preprocessor failure])]) 7372 7373results in: 7374 7375 checking for gcc... gcc 7376 checking for C compiler default output file name... a.out 7377 checking whether the C compiler works... yes 7378 checking whether we are cross compiling... no 7379 checking for suffix of executables... 7380 checking for suffix of object files... o 7381 checking whether we are using the GNU C compiler... yes 7382 checking whether gcc accepts -g... yes 7383 checking for gcc option to accept ISO C89... none needed 7384 checking how to run the C preprocessor... gcc -E 7385 OK 7386 7387 7388 The macro `AC_TRY_CPP' (*note Obsolete Macros::) used to play the 7389role of `AC_PREPROC_IFELSE', but double quotes its argument, making it 7390impossible to use it to elaborate sources. You are encouraged to get 7391rid of your old use of the macro `AC_TRY_CPP' in favor of 7392`AC_PREPROC_IFELSE', but, in the first place, are you sure you need to 7393run the _preprocessor_ and not the compiler? 7394 7395 -- Macro: AC_EGREP_HEADER (PATTERN, HEADER-FILE, ACTION-IF-FOUND, 7396 [ACTION-IF-NOT-FOUND]) 7397 If the output of running the preprocessor on the system header file 7398 HEADER-FILE matches the extended regular expression PATTERN, 7399 execute shell commands ACTION-IF-FOUND, otherwise execute 7400 ACTION-IF-NOT-FOUND. 7401 7402 -- Macro: AC_EGREP_CPP (PATTERN, PROGRAM, [ACTION-IF-FOUND], 7403 [ACTION-IF-NOT-FOUND]) 7404 PROGRAM is the text of a C or C++ program, on which shell 7405 variable, back quote, and backslash substitutions are performed. 7406 If the output of running the preprocessor on PROGRAM matches the 7407 extended regular expression PATTERN, execute shell commands 7408 ACTION-IF-FOUND, otherwise execute ACTION-IF-NOT-FOUND. 7409 7410 7411File: autoconf.info, Node: Running the Compiler, Next: Running the Linker, Prev: Running the Preprocessor, Up: Writing Tests 7412 74136.4 Running the Compiler 7414======================== 7415 7416To check for a syntax feature of the current language's (*note Language 7417Choice::) compiler, such as whether it recognizes a certain keyword, or 7418simply to try some library feature, use `AC_COMPILE_IFELSE' to try to 7419compile a small program that uses that feature. 7420 7421 -- Macro: AC_COMPILE_IFELSE (INPUT, [ACTION-IF-TRUE], 7422 [ACTION-IF-FALSE]) 7423 Run the compiler and compilation flags of the current language 7424 (*note Language Choice::) on the INPUT, run the shell commands 7425 ACTION-IF-TRUE on success, ACTION-IF-FALSE otherwise. The INPUT 7426 can be made by `AC_LANG_PROGRAM' and friends. 7427 7428 It is customary to report unexpected failures with 7429 `AC_MSG_FAILURE'. This macro does not try to link; use 7430 `AC_LINK_IFELSE' if you need to do that (*note Running the 7431 Linker::). If needed, ACTION-IF-TRUE can further access the 7432 just-compiled object file `conftest.$OBJEXT'. 7433 7434 This macro uses `AC_REQUIRE' for the compiler associated with the 7435 current language, which means that if the compiler has not yet been 7436 determined, the compiler determination will be made prior to the 7437 body of the outermost `AC_DEFUN' macro that triggered this macro to 7438 expand (*note Expanded Before Required::). 7439 7440 For tests in Erlang, the INPUT must be the source code of a module 7441named `conftest'. `AC_COMPILE_IFELSE' generates a `conftest.beam' file 7442that can be interpreted by the Erlang virtual machine (`ERL'). It is 7443recommended to use `AC_LANG_PROGRAM' to specify the test program, to 7444ensure that the Erlang module has the right name. 7445 7446 7447File: autoconf.info, Node: Running the Linker, Next: Runtime, Prev: Running the Compiler, Up: Writing Tests 7448 74496.5 Running the Linker 7450====================== 7451 7452To check for a library, a function, or a global variable, Autoconf 7453`configure' scripts try to compile and link a small program that uses 7454it. This is unlike Metaconfig, which by default uses `nm' or `ar' on 7455the C library to try to figure out which functions are available. 7456Trying to link with the function is usually a more reliable approach 7457because it avoids dealing with the variations in the options and output 7458formats of `nm' and `ar' and in the location of the standard libraries. 7459It also allows configuring for cross-compilation or checking a 7460function's runtime behavior if needed. On the other hand, it can be 7461slower than scanning the libraries once, but accuracy is more important 7462than speed. 7463 7464 `AC_LINK_IFELSE' is used to compile test programs to test for 7465functions and global variables. It is also used by `AC_CHECK_LIB' to 7466check for libraries (*note Libraries::), by adding the library being 7467checked for to `LIBS' temporarily and trying to link a small program. 7468 7469 -- Macro: AC_LINK_IFELSE (INPUT, [ACTION-IF-TRUE], [ACTION-IF-FALSE]) 7470 Run the compiler (and compilation flags) and the linker of the 7471 current language (*note Language Choice::) on the INPUT, run the 7472 shell commands ACTION-IF-TRUE on success, ACTION-IF-FALSE 7473 otherwise. The INPUT can be made by `AC_LANG_PROGRAM' and 7474 friends. If needed, ACTION-IF-TRUE can further access the 7475 just-linked program file `conftest$EXEEXT'. 7476 7477 `LDFLAGS' and `LIBS' are used for linking, in addition to the 7478 current compilation flags. 7479 7480 It is customary to report unexpected failures with 7481 `AC_MSG_FAILURE'. This macro does not try to execute the program; 7482 use `AC_RUN_IFELSE' if you need to do that (*note Runtime::). 7483 7484 The `AC_LINK_IFELSE' macro cannot be used for Erlang tests, since 7485Erlang programs are interpreted and do not require linking. 7486 7487 7488File: autoconf.info, Node: Runtime, Next: Systemology, Prev: Running the Linker, Up: Writing Tests 7489 74906.6 Checking Runtime Behavior 7491============================= 7492 7493Sometimes you need to find out how a system performs at runtime, such 7494as whether a given function has a certain capability or bug. If you 7495can, make such checks when your program runs instead of when it is 7496configured. You can check for things like the machine's endianness when 7497your program initializes itself. 7498 7499 If you really need to test for a runtime behavior while configuring, 7500you can write a test program to determine the result, and compile and 7501run it using `AC_RUN_IFELSE'. Avoid running test programs if possible, 7502because this prevents people from configuring your package for 7503cross-compiling. 7504 7505 -- Macro: AC_RUN_IFELSE (INPUT, [ACTION-IF-TRUE], [ACTION-IF-FALSE], 7506 [ACTION-IF-CROSS-COMPILING = `AC_MSG_FAILURE']) 7507 Run the compiler (and compilation flags) and the linker of the 7508 current language (*note Language Choice::) on the INPUT, then 7509 execute the resulting program. If the program returns an exit 7510 status of 0 when executed, run shell commands ACTION-IF-TRUE. 7511 Otherwise, run shell commands ACTION-IF-FALSE. 7512 7513 The INPUT can be made by `AC_LANG_PROGRAM' and friends. `LDFLAGS' 7514 and `LIBS' are used for linking, in addition to the compilation 7515 flags of the current language (*note Language Choice::). 7516 Additionally, ACTION-IF-TRUE can run `./conftest$EXEEXT' for 7517 further testing. 7518 7519 In the ACTION-IF-FALSE section, the failing exit status is 7520 available in the shell variable `$?'. This exit status might be 7521 that of a failed compilation, or it might be that of a failed 7522 program execution. 7523 7524 If cross-compilation mode is enabled (this is the case if either 7525 the compiler being used does not produce executables that run on 7526 the system where `configure' is being run, or if the options 7527 `--build' and `--host' were both specified and their values are 7528 different), then the test program is not run. If the optional 7529 shell commands ACTION-IF-CROSS-COMPILING are given, those commands 7530 are run instead; typically these commands provide pessimistic 7531 defaults that allow cross-compilation to work even if the guess 7532 was wrong. If the fourth argument is empty or omitted, but 7533 cross-compilation is detected, then `configure' prints an error 7534 message and exits. If you want your package to be useful in a 7535 cross-compilation scenario, you _should_ provide a non-empty 7536 ACTION-IF-CROSS-COMPILING clause, as well as wrap the 7537 `AC_RUN_IFELSE' compilation inside an `AC_CACHE_CHECK' (*note 7538 Caching Results::) which allows the user to override the 7539 pessimistic default if needed. 7540 7541 It is customary to report unexpected failures with 7542 `AC_MSG_FAILURE'. 7543 7544 `autoconf' prints a warning message when creating `configure' each 7545time it encounters a call to `AC_RUN_IFELSE' with no 7546ACTION-IF-CROSS-COMPILING argument given. If you are not concerned 7547about users configuring your package for cross-compilation, you may 7548ignore the warning. A few of the macros distributed with Autoconf 7549produce this warning message; but if this is a problem for you, please 7550report it as a bug, along with an appropriate pessimistic guess to use 7551instead. 7552 7553 To configure for cross-compiling you can also choose a value for 7554those parameters based on the canonical system name (*note Manual 7555Configuration::). Alternatively, set up a test results cache file with 7556the correct values for the host system (*note Caching Results::). 7557 7558 To provide a default for calls of `AC_RUN_IFELSE' that are embedded 7559in other macros, including a few of the ones that come with Autoconf, 7560you can test whether the shell variable `cross_compiling' is set to 7561`yes', and then use an alternate method to get the results instead of 7562calling the macros. 7563 7564 It is also permissible to temporarily assign to `cross_compiling' in 7565order to force tests to behave as though they are in a 7566cross-compilation environment, particularly since this provides a way to 7567test your ACTION-IF-CROSS-COMPILING even when you are not using a 7568cross-compiler. 7569 7570 # We temporarily set cross-compile mode to force AC_COMPUTE_INT 7571 # to use the slow link-only method 7572 save_cross_compiling=$cross_compiling 7573 cross_compiling=yes 7574 AC_COMPUTE_INT([...]) 7575 cross_compiling=$save_cross_compiling 7576 7577 A C or C++ runtime test should be portable. *Note Portable C and 7578C++::. 7579 7580 Erlang tests must exit themselves the Erlang VM by calling the 7581`halt/1' function: the given status code is used to determine the 7582success of the test (status is `0') or its failure (status is different 7583than `0'), as explained above. It must be noted that data output 7584through the standard output (e.g., using `io:format/2') may be 7585truncated when halting the VM. Therefore, if a test must output 7586configuration information, it is recommended to create and to output 7587data into the temporary file named `conftest.out', using the functions 7588of module `file'. The `conftest.out' file is automatically deleted by 7589the `AC_RUN_IFELSE' macro. For instance, a simplified implementation 7590of Autoconf's `AC_ERLANG_SUBST_LIB_DIR' macro is: 7591 7592 AC_INIT([LibdirTest], [1.0], [bug-libdirtest@example.org]) 7593 AC_ERLANG_NEED_ERL 7594 AC_LANG(Erlang) 7595 AC_RUN_IFELSE( 7596 [AC_LANG_PROGRAM([], [dnl 7597 file:write_file("conftest.out", code:lib_dir()), 7598 halt(0)])], 7599 [echo "code:lib_dir() returned: `cat conftest.out`"], 7600 [AC_MSG_FAILURE([test Erlang program execution failed])]) 7601 7602 7603File: autoconf.info, Node: Systemology, Next: Multiple Cases, Prev: Runtime, Up: Writing Tests 7604 76056.7 Systemology 7606=============== 7607 7608This section aims at presenting some systems and pointers to 7609documentation. It may help you addressing particular problems reported 7610by users. 7611 7612 Posix-conforming systems (http://www.opengroup.org/susv3) are 7613derived from the Unix operating system 7614(http://www.bell-labs.com/history/unix/). 7615 7616 The Rosetta Stone for Unix (http://bhami.com/rosetta.html) contains 7617a table correlating the features of various Posix-conforming systems. 7618Unix History (http://www.levenez.com/unix/) is a simplified diagram of 7619how many Unix systems were derived from each other. 7620 7621 The Heirloom Project (http://heirloom.sourceforge.net/) provides 7622some variants of traditional implementations of Unix utilities. 7623 7624Darwin 7625 Darwin is also known as Mac OS X. Beware that the file system 7626 _can_ be case-preserving, but case insensitive. This can cause 7627 nasty problems, since for instance the installation attempt for a 7628 package having an `INSTALL' file can result in `make install' 7629 report that nothing was to be done! 7630 7631 That's all dependent on whether the file system is a UFS (case 7632 sensitive) or HFS+ (case preserving). By default Apple wants you 7633 to install the OS on HFS+. Unfortunately, there are some pieces of 7634 software which really need to be built on UFS. We may want to 7635 rebuild Darwin to have both UFS and HFS+ available (and put the 7636 /local/build tree on the UFS). 7637 7638QNX 4.25 7639 QNX is a realtime operating system running on Intel architecture 7640 meant to be scalable from the small embedded systems to the hundred 7641 processor super-computer. It claims to be Posix certified. More 7642 information is available on the QNX home page 7643 (http://www.qnx.com/). 7644 7645Tru64 7646 Documentation of several versions of Tru64 7647 (http://h30097.www3.hp.com/docs/) is available in different 7648 formats. 7649 7650Unix version 7 7651 Officially this was called the "Seventh Edition" of "the UNIX 7652 time-sharing system" but we use the more-common name "Unix version 7653 7". Documentation is available in the Unix Seventh Edition Manual 7654 (http://plan9.bell-labs.com/7thEdMan/). Previous versions of Unix 7655 are called "Unix version 6", etc., but they were not as widely 7656 used. 7657 7658 7659File: autoconf.info, Node: Multiple Cases, Prev: Systemology, Up: Writing Tests 7660 76616.8 Multiple Cases 7662================== 7663 7664Some operations are accomplished in several possible ways, depending on 7665the OS variant. Checking for them essentially requires a "case 7666statement". Autoconf does not directly provide one; however, it is 7667easy to simulate by using a shell variable to keep track of whether a 7668way to perform the operation has been found yet. 7669 7670 Here is an example that uses the shell variable `fstype' to keep 7671track of whether the remaining cases need to be checked. Note that 7672since the value of `fstype' is under our control, we don't have to use 7673the longer `test "x$fstype" = xno'. 7674 7675 AC_MSG_CHECKING([how to get file system type]) 7676 fstype=no 7677 # The order of these tests is important. 7678 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statvfs.h> 7679 #include <sys/fstyp.h>]])], 7680 [AC_DEFINE([FSTYPE_STATVFS], [1], 7681 [Define if statvfs exists.]) 7682 fstype=SVR4]) 7683 if test $fstype = no; then 7684 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h> 7685 #include <sys/fstyp.h>]])], 7686 [AC_DEFINE([FSTYPE_USG_STATFS], [1], 7687 [Define if USG statfs.]) 7688 fstype=SVR3]) 7689 fi 7690 if test $fstype = no; then 7691 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h> 7692 #include <sys/vmount.h>]])]), 7693 [AC_DEFINE([FSTYPE_AIX_STATFS], [1], 7694 [Define if AIX statfs.]) 7695 fstype=AIX]) 7696 fi 7697 # (more cases omitted here) 7698 AC_MSG_RESULT([$fstype]) 7699 7700 7701File: autoconf.info, Node: Results, Next: Programming in M4, Prev: Writing Tests, Up: Top 7702 77037 Results of Tests 7704****************** 7705 7706Once `configure' has determined whether a feature exists, what can it 7707do to record that information? There are four sorts of things it can 7708do: define a C preprocessor symbol, set a variable in the output files, 7709save the result in a cache file for future `configure' runs, and print 7710a message letting the user know the result of the test. 7711 7712* Menu: 7713 7714* Defining Symbols:: Defining C preprocessor symbols 7715* Setting Output Variables:: Replacing variables in output files 7716* Special Chars in Variables:: Characters to beware of in variables 7717* Caching Results:: Speeding up subsequent `configure' runs 7718* Printing Messages:: Notifying `configure' users 7719 7720 7721File: autoconf.info, Node: Defining Symbols, Next: Setting Output Variables, Up: Results 7722 77237.1 Defining C Preprocessor Symbols 7724=================================== 7725 7726A common action to take in response to a feature test is to define a C 7727preprocessor symbol indicating the results of the test. That is done by 7728calling `AC_DEFINE' or `AC_DEFINE_UNQUOTED'. 7729 7730 By default, `AC_OUTPUT' places the symbols defined by these macros 7731into the output variable `DEFS', which contains an option 7732`-DSYMBOL=VALUE' for each symbol defined. Unlike in Autoconf version 77331, there is no variable `DEFS' defined while `configure' is running. 7734To check whether Autoconf macros have already defined a certain C 7735preprocessor symbol, test the value of the appropriate cache variable, 7736as in this example: 7737 7738 AC_CHECK_FUNC([vprintf], [AC_DEFINE([HAVE_VPRINTF], [1], 7739 [Define if vprintf exists.])]) 7740 if test "x$ac_cv_func_vprintf" != xyes; then 7741 AC_CHECK_FUNC([_doprnt], [AC_DEFINE([HAVE_DOPRNT], [1], 7742 [Define if _doprnt exists.])]) 7743 fi 7744 7745 If `AC_CONFIG_HEADERS' has been called, then instead of creating 7746`DEFS', `AC_OUTPUT' creates a header file by substituting the correct 7747values into `#define' statements in a template file. *Note 7748Configuration Headers::, for more information about this kind of output. 7749 7750 -- Macro: AC_DEFINE (VARIABLE, VALUE, [DESCRIPTION]) 7751 -- Macro: AC_DEFINE (VARIABLE) 7752 Define VARIABLE to VALUE (verbatim), by defining a C preprocessor 7753 macro for VARIABLE. VARIABLE should be a C identifier, optionally 7754 suffixed by a parenthesized argument list to define a C 7755 preprocessor macro with arguments. The macro argument list, if 7756 present, should be a comma-separated list of C identifiers, 7757 possibly terminated by an ellipsis `...' if C99 syntax is employed. 7758 VARIABLE should not contain comments, white space, trigraphs, 7759 backslash-newlines, universal character names, or non-ASCII 7760 characters. 7761 7762 VALUE may contain backslash-escaped newlines, which will be 7763 preserved if you use `AC_CONFIG_HEADERS' but flattened if passed 7764 via `@DEFS@' (with no effect on the compilation, since the 7765 preprocessor sees only one line in the first place). VALUE should 7766 not contain raw newlines. If you are not using 7767 `AC_CONFIG_HEADERS', VALUE should not contain any `#' characters, 7768 as `make' tends to eat them. To use a shell variable, use 7769 `AC_DEFINE_UNQUOTED' instead. 7770 7771 DESCRIPTION is only useful if you are using `AC_CONFIG_HEADERS'. 7772 In this case, DESCRIPTION is put into the generated `config.h.in' 7773 as the comment before the macro define. The following example 7774 defines the C preprocessor variable `EQUATION' to be the string 7775 constant `"$a > $b"': 7776 7777 AC_DEFINE([EQUATION], ["$a > $b"], 7778 [Equation string.]) 7779 7780 If neither VALUE nor DESCRIPTION are given, then VALUE defaults to 7781 1 instead of to the empty string. This is for backwards 7782 compatibility with older versions of Autoconf, but this usage is 7783 obsolescent and may be withdrawn in future versions of Autoconf. 7784 7785 If the VARIABLE is a literal string, it is passed to 7786 `m4_pattern_allow' (*note Forbidden Patterns::). 7787 7788 If multiple `AC_DEFINE' statements are executed for the same 7789 VARIABLE name (not counting any parenthesized argument list), the 7790 last one wins. 7791 7792 -- Macro: AC_DEFINE_UNQUOTED (VARIABLE, VALUE, [DESCRIPTION]) 7793 -- Macro: AC_DEFINE_UNQUOTED (VARIABLE) 7794 Like `AC_DEFINE', but three shell expansions are 7795 performed--once--on VARIABLE and VALUE: variable expansion (`$'), 7796 command substitution (``'), and backslash escaping (`\'), as if in 7797 an unquoted here-document. Single and double quote characters in 7798 the value have no special meaning. Use this macro instead of 7799 `AC_DEFINE' when VARIABLE or VALUE is a shell variable. Examples: 7800 7801 AC_DEFINE_UNQUOTED([config_machfile], ["$machfile"], 7802 [Configuration machine file.]) 7803 AC_DEFINE_UNQUOTED([GETGROUPS_T], [$ac_cv_type_getgroups], 7804 [getgroups return type.]) 7805 AC_DEFINE_UNQUOTED([$ac_tr_hdr], [1], 7806 [Translated header name.]) 7807 7808 Due to a syntactical bizarreness of the Bourne shell, do not use 7809semicolons to separate `AC_DEFINE' or `AC_DEFINE_UNQUOTED' calls from 7810other macro calls or shell code; that can cause syntax errors in the 7811resulting `configure' script. Use either blanks or newlines. That is, 7812do this: 7813 7814 AC_CHECK_HEADER([elf.h], 7815 [AC_DEFINE([SVR4], [1], [System V Release 4]) LIBS="-lelf $LIBS"]) 7816 7817or this: 7818 7819 AC_CHECK_HEADER([elf.h], 7820 [AC_DEFINE([SVR4], [1], [System V Release 4]) 7821 LIBS="-lelf $LIBS"]) 7822 7823instead of this: 7824 7825 AC_CHECK_HEADER([elf.h], 7826 [AC_DEFINE([SVR4], [1], [System V Release 4]); LIBS="-lelf $LIBS"]) 7827 7828 7829File: autoconf.info, Node: Setting Output Variables, Next: Special Chars in Variables, Prev: Defining Symbols, Up: Results 7830 78317.2 Setting Output Variables 7832============================ 7833 7834Another way to record the results of tests is to set "output 7835variables", which are shell variables whose values are substituted into 7836files that `configure' outputs. The two macros below create new output 7837variables. *Note Preset Output Variables::, for a list of output 7838variables that are always available. 7839 7840 -- Macro: AC_SUBST (VARIABLE, [VALUE]) 7841 Create an output variable from a shell variable. Make `AC_OUTPUT' 7842 substitute the variable VARIABLE into output files (typically one 7843 or more makefiles). This means that `AC_OUTPUT' replaces 7844 instances of `@VARIABLE@' in input files with the value that the 7845 shell variable VARIABLE has when `AC_OUTPUT' is called. The value 7846 can contain any non-`NUL' character, including newline. If you 7847 are using Automake 1.11 or newer, for newlines in values you might 7848 want to consider using `AM_SUBST_NOTMAKE' to prevent `automake' 7849 from adding a line `VARIABLE = @VARIABLE@' to the `Makefile.in' 7850 files (*note Automake: (automake)Optional.). 7851 7852 Variable occurrences should not overlap: e.g., an input file should 7853 not contain `@VAR1@VAR2@' if VAR1 and VAR2 are variable names. 7854 The substituted value is not rescanned for more output variables; 7855 occurrences of `@VARIABLE@' in the value are inserted literally 7856 into the output file. (The algorithm uses the special marker 7857 `|#_!!_#|' internally, so neither the substituted value nor the 7858 output file may contain `|#_!!_#|'.) 7859 7860 If VALUE is given, in addition assign it to VARIABLE. 7861 7862 The string VARIABLE is passed to `m4_pattern_allow' (*note 7863 Forbidden Patterns::). 7864 7865 -- Macro: AC_SUBST_FILE (VARIABLE) 7866 Another way to create an output variable from a shell variable. 7867 Make `AC_OUTPUT' insert (without substitutions) the contents of 7868 the file named by shell variable VARIABLE into output files. This 7869 means that `AC_OUTPUT' replaces instances of `@VARIABLE@' in 7870 output files (such as `Makefile.in') with the contents of the file 7871 that the shell variable VARIABLE names when `AC_OUTPUT' is called. 7872 Set the variable to `/dev/null' for cases that do not have a file 7873 to insert. This substitution occurs only when the `@VARIABLE@' is 7874 on a line by itself, optionally surrounded by spaces and tabs. The 7875 substitution replaces the whole line, including the spaces, tabs, 7876 and the terminating newline. 7877 7878 This macro is useful for inserting makefile fragments containing 7879 special dependencies or other `make' directives for particular host 7880 or target types into makefiles. For example, `configure.ac' could 7881 contain: 7882 7883 AC_SUBST_FILE([host_frag]) 7884 host_frag=$srcdir/conf/sun4.mh 7885 7886 and then a `Makefile.in' could contain: 7887 7888 @host_frag@ 7889 7890 The string VARIABLE is passed to `m4_pattern_allow' (*note 7891 Forbidden Patterns::). 7892 7893 Running `configure' in varying environments can be extremely 7894dangerous. If for instance the user runs `CC=bizarre-cc ./configure', 7895then the cache, `config.h', and many other output files depend upon 7896`bizarre-cc' being the C compiler. If for some reason the user runs 7897`./configure' again, or if it is run via `./config.status --recheck', 7898(*Note Automatic Remaking::, and *note config.status Invocation::), 7899then the configuration can be inconsistent, composed of results 7900depending upon two different compilers. 7901 7902 Environment variables that affect this situation, such as `CC' 7903above, are called "precious variables", and can be declared as such by 7904`AC_ARG_VAR'. 7905 7906 -- Macro: AC_ARG_VAR (VARIABLE, DESCRIPTION) 7907 Declare VARIABLE is a precious variable, and include its 7908 DESCRIPTION in the variable section of `./configure --help'. 7909 7910 Being precious means that 7911 - VARIABLE is substituted via `AC_SUBST'. 7912 7913 - The value of VARIABLE when `configure' was launched is saved 7914 in the cache, including if it was not specified on the command 7915 line but via the environment. Indeed, while `configure' can 7916 notice the definition of `CC' in `./configure CC=bizarre-cc', 7917 it is impossible to notice it in `CC=bizarre-cc ./configure', 7918 which, unfortunately, is what most users do. 7919 7920 We emphasize that it is the _initial_ value of VARIABLE which 7921 is saved, not that found during the execution of `configure'. 7922 Indeed, specifying `./configure FOO=foo' and letting 7923 `./configure' guess that `FOO' is `foo' can be two different 7924 things. 7925 7926 - VARIABLE is checked for consistency between two `configure' 7927 runs. For instance: 7928 7929 $ ./configure --silent --config-cache 7930 $ CC=cc ./configure --silent --config-cache 7931 configure: error: `CC' was not set in the previous run 7932 configure: error: changes in the environment can compromise \ 7933 the build 7934 configure: error: run `make distclean' and/or \ 7935 `rm config.cache' and start over 7936 7937 and similarly if the variable is unset, or if its content is 7938 changed. If the content has white space changes only, then 7939 the error is degraded to a warning only, but the old value is 7940 reused. 7941 7942 - VARIABLE is kept during automatic reconfiguration (*note 7943 config.status Invocation::) as if it had been passed as a 7944 command line argument, including when no cache is used: 7945 7946 $ CC=/usr/bin/cc ./configure var=raboof --silent 7947 $ ./config.status --recheck 7948 running CONFIG_SHELL=/bin/sh /bin/sh ./configure var=raboof \ 7949 CC=/usr/bin/cc --no-create --no-recursion 7950 7951 7952File: autoconf.info, Node: Special Chars in Variables, Next: Caching Results, Prev: Setting Output Variables, Up: Results 7953 79547.3 Special Characters in Output Variables 7955========================================== 7956 7957Many output variables are intended to be evaluated both by `make' and 7958by the shell. Some characters are expanded differently in these two 7959contexts, so to avoid confusion these variables' values should not 7960contain any of the following characters: 7961 7962 " # $ & ' ( ) * ; < > ? [ \ ^ ` | 7963 7964 Also, these variables' values should neither contain newlines, nor 7965start with `~', nor contain white space or `:' immediately followed by 7966`~'. The values can contain nonempty sequences of white space 7967characters like tabs and spaces, but each such sequence might 7968arbitrarily be replaced by a single space during substitution. 7969 7970 These restrictions apply both to the values that `configure' 7971computes, and to the values set directly by the user. For example, the 7972following invocations of `configure' are problematic, since they 7973attempt to use special characters within `CPPFLAGS' and white space 7974within `$(srcdir)': 7975 7976 CPPFLAGS='-DOUCH="&\"#$*?"' '../My Source/ouch-1.0/configure' 7977 7978 '../My Source/ouch-1.0/configure' CPPFLAGS='-DOUCH="&\"#$*?"' 7979 7980 7981File: autoconf.info, Node: Caching Results, Next: Printing Messages, Prev: Special Chars in Variables, Up: Results 7982 79837.4 Caching Results 7984=================== 7985 7986To avoid checking for the same features repeatedly in various 7987`configure' scripts (or in repeated runs of one script), `configure' 7988can optionally save the results of many checks in a "cache file" (*note 7989Cache Files::). If a `configure' script runs with caching enabled and 7990finds a cache file, it reads the results of previous runs from the 7991cache and avoids rerunning those checks. As a result, `configure' can 7992then run much faster than if it had to perform all of the checks every 7993time. 7994 7995 -- Macro: AC_CACHE_VAL (CACHE-ID, COMMANDS-TO-SET-IT) 7996 Ensure that the results of the check identified by CACHE-ID are 7997 available. If the results of the check were in the cache file 7998 that was read, and `configure' was not given the `--quiet' or 7999 `--silent' option, print a message saying that the result was 8000 cached; otherwise, run the shell commands COMMANDS-TO-SET-IT. If 8001 the shell commands are run to determine the value, the value is 8002 saved in the cache file just before `configure' creates its output 8003 files. *Note Cache Variable Names::, for how to choose the name 8004 of the CACHE-ID variable. 8005 8006 The COMMANDS-TO-SET-IT _must have no side effects_ except for 8007 setting the variable CACHE-ID, see below. 8008 8009 -- Macro: AC_CACHE_CHECK (MESSAGE, CACHE-ID, COMMANDS-TO-SET-IT) 8010 A wrapper for `AC_CACHE_VAL' that takes care of printing the 8011 messages. This macro provides a convenient shorthand for the most 8012 common way to use these macros. It calls `AC_MSG_CHECKING' for 8013 MESSAGE, then `AC_CACHE_VAL' with the CACHE-ID and COMMANDS 8014 arguments, and `AC_MSG_RESULT' with CACHE-ID. 8015 8016 The COMMANDS-TO-SET-IT _must have no side effects_ except for 8017 setting the variable CACHE-ID, see below. 8018 8019 It is common to find buggy macros using `AC_CACHE_VAL' or 8020`AC_CACHE_CHECK', because people are tempted to call `AC_DEFINE' in the 8021COMMANDS-TO-SET-IT. Instead, the code that _follows_ the call to 8022`AC_CACHE_VAL' should call `AC_DEFINE', by examining the value of the 8023cache variable. For instance, the following macro is broken: 8024 8025 AC_DEFUN([AC_SHELL_TRUE], 8026 [AC_CACHE_CHECK([whether true(1) works], [my_cv_shell_true_works], 8027 [my_cv_shell_true_works=no 8028 (true) 2>/dev/null && my_cv_shell_true_works=yes 8029 if test "x$my_cv_shell_true_works" = xyes; then 8030 AC_DEFINE([TRUE_WORKS], [1], 8031 [Define if `true(1)' works properly.]) 8032 fi]) 8033 ]) 8034 8035This fails if the cache is enabled: the second time this macro is run, 8036`TRUE_WORKS' _will not be defined_. The proper implementation is: 8037 8038 AC_DEFUN([AC_SHELL_TRUE], 8039 [AC_CACHE_CHECK([whether true(1) works], [my_cv_shell_true_works], 8040 [my_cv_shell_true_works=no 8041 (true) 2>/dev/null && my_cv_shell_true_works=yes]) 8042 if test "x$my_cv_shell_true_works" = xyes; then 8043 AC_DEFINE([TRUE_WORKS], [1], 8044 [Define if `true(1)' works properly.]) 8045 fi 8046 ]) 8047 8048 Also, COMMANDS-TO-SET-IT should not print any messages, for example 8049with `AC_MSG_CHECKING'; do that before calling `AC_CACHE_VAL', so the 8050messages are printed regardless of whether the results of the check are 8051retrieved from the cache or determined by running the shell commands. 8052 8053* Menu: 8054 8055* Cache Variable Names:: Shell variables used in caches 8056* Cache Files:: Files `configure' uses for caching 8057* Cache Checkpointing:: Loading and saving the cache file 8058 8059 8060File: autoconf.info, Node: Cache Variable Names, Next: Cache Files, Up: Caching Results 8061 80627.4.1 Cache Variable Names 8063-------------------------- 8064 8065The names of cache variables should have the following format: 8066 8067 PACKAGE-PREFIX_cv_VALUE-TYPE_SPECIFIC-VALUE_[ADDITIONAL-OPTIONS] 8068 8069for example, `ac_cv_header_stat_broken' or 8070`ac_cv_prog_gcc_traditional'. The parts of the variable name are: 8071 8072PACKAGE-PREFIX 8073 An abbreviation for your package or organization; the same prefix 8074 you begin local Autoconf macros with, except lowercase by 8075 convention. For cache values used by the distributed Autoconf 8076 macros, this value is `ac'. 8077 8078`_cv_' 8079 Indicates that this shell variable is a cache value. This string 8080 _must_ be present in the variable name, including the leading 8081 underscore. 8082 8083VALUE-TYPE 8084 A convention for classifying cache values, to produce a rational 8085 naming system. The values used in Autoconf are listed in *note 8086 Macro Names::. 8087 8088SPECIFIC-VALUE 8089 Which member of the class of cache values this test applies to. 8090 For example, which function (`alloca'), program (`gcc'), or output 8091 variable (`INSTALL'). 8092 8093ADDITIONAL-OPTIONS 8094 Any particular behavior of the specific member that this test 8095 applies to. For example, `broken' or `set'. This part of the 8096 name may be omitted if it does not apply. 8097 8098 The values assigned to cache variables may not contain newlines. 8099Usually, their values are Boolean (`yes' or `no') or the names of files 8100or functions; so this is not an important restriction. *note Cache 8101Variable Index:: for an index of cache variables with documented 8102semantics. 8103 8104 8105File: autoconf.info, Node: Cache Files, Next: Cache Checkpointing, Prev: Cache Variable Names, Up: Caching Results 8106 81077.4.2 Cache Files 8108----------------- 8109 8110A cache file is a shell script that caches the results of configure 8111tests run on one system so they can be shared between configure scripts 8112and configure runs. It is not useful on other systems. If its contents 8113are invalid for some reason, the user may delete or edit it, or override 8114documented cache variables on the `configure' command line. 8115 8116 By default, `configure' uses no cache file, to avoid problems caused 8117by accidental use of stale cache files. 8118 8119 To enable caching, `configure' accepts `--config-cache' (or `-C') to 8120cache results in the file `config.cache'. Alternatively, 8121`--cache-file=FILE' specifies that FILE be the cache file. The cache 8122file is created if it does not exist already. When `configure' calls 8123`configure' scripts in subdirectories, it uses the `--cache-file' 8124argument so that they share the same cache. *Note Subdirectories::, 8125for information on configuring subdirectories with the 8126`AC_CONFIG_SUBDIRS' macro. 8127 8128 `config.status' only pays attention to the cache file if it is given 8129the `--recheck' option, which makes it rerun `configure'. 8130 8131 It is wrong to try to distribute cache files for particular system 8132types. There is too much room for error in doing that, and too much 8133administrative overhead in maintaining them. For any features that 8134can't be guessed automatically, use the standard method of the canonical 8135system type and linking files (*note Manual Configuration::). 8136 8137 The site initialization script can specify a site-wide cache file to 8138use, instead of the usual per-program cache. In this case, the cache 8139file gradually accumulates information whenever someone runs a new 8140`configure' script. (Running `configure' merges the new cache results 8141with the existing cache file.) This may cause problems, however, if 8142the system configuration (e.g., the installed libraries or compilers) 8143changes and the stale cache file is not deleted. 8144 8145 If `configure' is interrupted at the right time when it updates a 8146cache file outside of the build directory where the `configure' script 8147is run, it may leave behind a temporary file named after the cache file 8148with digits following it. You may safely delete such a file. 8149 8150 8151File: autoconf.info, Node: Cache Checkpointing, Prev: Cache Files, Up: Caching Results 8152 81537.4.3 Cache Checkpointing 8154------------------------- 8155 8156If your configure script, or a macro called from `configure.ac', happens 8157to abort the configure process, it may be useful to checkpoint the cache 8158a few times at key points using `AC_CACHE_SAVE'. Doing so reduces the 8159amount of time it takes to rerun the configure script with (hopefully) 8160the error that caused the previous abort corrected. 8161 8162 -- Macro: AC_CACHE_LOAD 8163 Loads values from existing cache file, or creates a new cache file 8164 if a cache file is not found. Called automatically from `AC_INIT'. 8165 8166 -- Macro: AC_CACHE_SAVE 8167 Flushes all cached values to the cache file. Called automatically 8168 from `AC_OUTPUT', but it can be quite useful to call 8169 `AC_CACHE_SAVE' at key points in `configure.ac'. 8170 8171 For instance: 8172 8173 ... AC_INIT, etc. ... 8174 # Checks for programs. 8175 AC_PROG_CC 8176 AC_PROG_AWK 8177 ... more program checks ... 8178 AC_CACHE_SAVE 8179 8180 # Checks for libraries. 8181 AC_CHECK_LIB([nsl], [gethostbyname]) 8182 AC_CHECK_LIB([socket], [connect]) 8183 ... more lib checks ... 8184 AC_CACHE_SAVE 8185 8186 # Might abort... 8187 AM_PATH_GTK([1.0.2], [], [AC_MSG_ERROR([GTK not in path])]) 8188 AM_PATH_GTKMM([0.9.5], [], [AC_MSG_ERROR([GTK not in path])]) 8189 ... AC_OUTPUT, etc. ... 8190 8191 8192File: autoconf.info, Node: Printing Messages, Prev: Caching Results, Up: Results 8193 81947.5 Printing Messages 8195===================== 8196 8197`configure' scripts need to give users running them several kinds of 8198information. The following macros print messages in ways appropriate 8199for each kind. The arguments to all of them get enclosed in shell 8200double quotes, so the shell performs variable and back-quote 8201substitution on them. 8202 8203 These macros are all wrappers around the `echo' shell command. They 8204direct output to the appropriate file descriptor (*note File Descriptor 8205Macros::). `configure' scripts should rarely need to run `echo' 8206directly to print messages for the user. Using these macros makes it 8207easy to change how and when each kind of message is printed; such 8208changes need only be made to the macro definitions and all the callers 8209change automatically. 8210 8211 To diagnose static issues, i.e., when `autoconf' is run, see *note 8212Diagnostic Macros::. 8213 8214 -- Macro: AC_MSG_CHECKING (FEATURE-DESCRIPTION) 8215 Notify the user that `configure' is checking for a particular 8216 feature. This macro prints a message that starts with `checking ' 8217 and ends with `...' and no newline. It must be followed by a call 8218 to `AC_MSG_RESULT' to print the result of the check and the 8219 newline. The FEATURE-DESCRIPTION should be something like 8220 `whether the Fortran compiler accepts C++ comments' or `for c89'. 8221 8222 This macro prints nothing if `configure' is run with the `--quiet' 8223 or `--silent' option. 8224 8225 -- Macro: AC_MSG_RESULT (RESULT-DESCRIPTION) 8226 Notify the user of the results of a check. RESULT-DESCRIPTION is 8227 almost always the value of the cache variable for the check, 8228 typically `yes', `no', or a file name. This macro should follow a 8229 call to `AC_MSG_CHECKING', and the RESULT-DESCRIPTION should be 8230 the completion of the message printed by the call to 8231 `AC_MSG_CHECKING'. 8232 8233 This macro prints nothing if `configure' is run with the `--quiet' 8234 or `--silent' option. 8235 8236 -- Macro: AC_MSG_NOTICE (MESSAGE) 8237 Deliver the MESSAGE to the user. It is useful mainly to print a 8238 general description of the overall purpose of a group of feature 8239 checks, e.g., 8240 8241 AC_MSG_NOTICE([checking if stack overflow is detectable]) 8242 8243 This macro prints nothing if `configure' is run with the `--quiet' 8244 or `--silent' option. 8245 8246 -- Macro: AC_MSG_ERROR (ERROR-DESCRIPTION, [EXIT-STATUS = `$?/1']) 8247 Notify the user of an error that prevents `configure' from 8248 completing. This macro prints an error message to the standard 8249 error output and exits `configure' with EXIT-STATUS (`$?' by 8250 default, except that `0' is converted to `1'). ERROR-DESCRIPTION 8251 should be something like `invalid value $HOME for \$HOME'. 8252 8253 The ERROR-DESCRIPTION should start with a lower-case letter, and 8254 "cannot" is preferred to "can't". 8255 8256 -- Macro: AC_MSG_FAILURE (ERROR-DESCRIPTION, [EXIT-STATUS]) 8257 This `AC_MSG_ERROR' wrapper notifies the user of an error that 8258 prevents `configure' from completing _and_ that additional details 8259 are provided in `config.log'. This is typically used when 8260 abnormal results are found during a compilation. 8261 8262 -- Macro: AC_MSG_WARN (PROBLEM-DESCRIPTION) 8263 Notify the `configure' user of a possible problem. This macro 8264 prints the message to the standard error output; `configure' 8265 continues running afterward, so macros that call `AC_MSG_WARN' 8266 should provide a default (back-up) behavior for the situations 8267 they warn about. PROBLEM-DESCRIPTION should be something like `ln 8268 -s seems to make hard links'. 8269 8270 8271File: autoconf.info, Node: Programming in M4, Next: Programming in M4sh, Prev: Results, Up: Top 8272 82738 Programming in M4 8274******************* 8275 8276Autoconf is written on top of two layers: "M4sugar", which provides 8277convenient macros for pure M4 programming, and "M4sh", which provides 8278macros dedicated to shell script generation. 8279 8280 As of this version of Autoconf, these two layers still contain 8281experimental macros, whose interface might change in the future. As a 8282matter of fact, _anything that is not documented must not be used_. 8283 8284* Menu: 8285 8286* M4 Quotation:: Protecting macros from unwanted expansion 8287* Using autom4te:: The Autoconf executables backbone 8288* Programming in M4sugar:: Convenient pure M4 macros 8289* Debugging via autom4te:: Figuring out what M4 was doing 8290 8291 8292File: autoconf.info, Node: M4 Quotation, Next: Using autom4te, Up: Programming in M4 8293 82948.1 M4 Quotation 8295================ 8296 8297The most common problem with existing macros is an improper quotation. 8298This section, which users of Autoconf can skip, but which macro writers 8299_must_ read, first justifies the quotation scheme that was chosen for 8300Autoconf and then ends with a rule of thumb. Understanding the former 8301helps one to follow the latter. 8302 8303* Menu: 8304 8305* Active Characters:: Characters that change the behavior of M4 8306* One Macro Call:: Quotation and one macro call 8307* Quoting and Parameters:: M4 vs. shell parameters 8308* Quotation and Nested Macros:: Macros calling macros 8309* Changequote is Evil:: Worse than INTERCAL: M4 + changequote 8310* Quadrigraphs:: Another way to escape special characters 8311* Balancing Parentheses:: Dealing with unbalanced parentheses 8312* Quotation Rule Of Thumb:: One parenthesis, one quote 8313 8314 8315File: autoconf.info, Node: Active Characters, Next: One Macro Call, Up: M4 Quotation 8316 83178.1.1 Active Characters 8318----------------------- 8319 8320To fully understand where proper quotation is important, you first need 8321to know what the special characters are in Autoconf: `#' introduces a 8322comment inside which no macro expansion is performed, `,' separates 8323arguments, `[' and `]' are the quotes themselves(1), `(' and `)' (which 8324M4 tries to match by pairs), and finally `$' inside a macro definition. 8325 8326 In order to understand the delicate case of macro calls, we first 8327have to present some obvious failures. Below they are "obvious-ified", 8328but when you find them in real life, they are usually in disguise. 8329 8330 Comments, introduced by a hash and running up to the newline, are 8331opaque tokens to the top level: active characters are turned off, and 8332there is no macro expansion: 8333 8334 # define([def], ine) 8335 =># define([def], ine) 8336 8337 Each time there can be a macro expansion, there is a quotation 8338expansion, i.e., one level of quotes is stripped: 8339 8340 int tab[10]; 8341 =>int tab10; 8342 [int tab[10];] 8343 =>int tab[10]; 8344 8345 Without this in mind, the reader might try hopelessly to use her 8346macro `array': 8347 8348 define([array], [int tab[10];]) 8349 array 8350 =>int tab10; 8351 [array] 8352 =>array 8353 8354How can you correctly output the intended results(2)? 8355 8356 ---------- Footnotes ---------- 8357 8358 (1) By itself, M4 uses ``' and `''; it is the M4sugar layer that 8359sets up the preferred quotes of `[' and `]'. 8360 8361 (2) Using `defn'. 8362 8363 8364File: autoconf.info, Node: One Macro Call, Next: Quoting and Parameters, Prev: Active Characters, Up: M4 Quotation 8365 83668.1.2 One Macro Call 8367-------------------- 8368 8369Let's proceed on the interaction between active characters and macros 8370with this small macro, which just returns its first argument: 8371 8372 define([car], [$1]) 8373 8374The two pairs of quotes above are not part of the arguments of 8375`define'; rather, they are understood by the top level when it tries to 8376find the arguments of `define'. Therefore, assuming `car' is not 8377already defined, it is equivalent to write: 8378 8379 define(car, $1) 8380 8381But, while it is acceptable for a `configure.ac' to avoid unnecessary 8382quotes, it is bad practice for Autoconf macros which must both be more 8383robust and also advocate perfect style. 8384 8385 At the top level, there are only two possibilities: either you quote 8386or you don't: 8387 8388 car(foo, bar, baz) 8389 =>foo 8390 [car(foo, bar, baz)] 8391 =>car(foo, bar, baz) 8392 8393 Let's pay attention to the special characters: 8394 8395 car(#) 8396 error-->EOF in argument list 8397 8398 The closing parenthesis is hidden in the comment; with a hypothetical 8399quoting, the top level understood it this way: 8400 8401 car([#)] 8402 8403Proper quotation, of course, fixes the problem: 8404 8405 car([#]) 8406 =># 8407 8408 Here are more examples: 8409 8410 car(foo, bar) 8411 =>foo 8412 car([foo, bar]) 8413 =>foo, bar 8414 car((foo, bar)) 8415 =>(foo, bar) 8416 car([(foo], [bar)]) 8417 =>(foo 8418 define([a], [b]) 8419 => 8420 car(a) 8421 =>b 8422 car([a]) 8423 =>b 8424 car([[a]]) 8425 =>a 8426 car([[[a]]]) 8427 =>[a] 8428 8429 8430File: autoconf.info, Node: Quoting and Parameters, Next: Quotation and Nested Macros, Prev: One Macro Call, Up: M4 Quotation 8431 84328.1.3 Quoting and Parameters 8433---------------------------- 8434 8435When M4 encounters `$' within a macro definition, followed immediately 8436by a character it recognizes (`0'...`9', `#', `@', or `*'), it will 8437perform M4 parameter expansion. This happens regardless of how many 8438layers of quotes the parameter expansion is nested within, or even if 8439it occurs in text that will be rescanned as a comment. 8440 8441 define([none], [$1]) 8442 => 8443 define([one], [[$1]]) 8444 => 8445 define([two], [[[$1]]]) 8446 => 8447 define([comment], [# $1]) 8448 => 8449 define([active], [ACTIVE]) 8450 => 8451 none([active]) 8452 =>ACTIVE 8453 one([active]) 8454 =>active 8455 two([active]) 8456 =>[active] 8457 comment([active]) 8458 =># active 8459 8460 On the other hand, since autoconf generates shell code, you often 8461want to output shell variable expansion, rather than performing M4 8462parameter expansion. To do this, you must use M4 quoting to separate 8463the `$' from the next character in the definition of your macro. If 8464the macro definition occurs in single-quoted text, then insert another 8465level of quoting; if the usage is already inside a double-quoted 8466string, then split it into concatenated strings. 8467 8468 define([single], [a single-quoted $[]1 definition]) 8469 => 8470 define([double], [[a double-quoted $][1 definition]]) 8471 => 8472 single 8473 =>a single-quoted $1 definition 8474 double 8475 =>a double-quoted $1 definition 8476 8477 Posix states that M4 implementations are free to provide 8478implementation extensions when `${' is encountered in a macro 8479definition. Autoconf reserves the longer sequence `${{' for use with 8480planned extensions that will be available in the future GNU M4 2.0, but 8481guarantees that all other instances of `${' will be output literally. 8482Therefore, this idiom can also be used to output shell code parameter 8483references: 8484 8485 define([first], [${1}])first 8486 =>${1} 8487 8488 Posix also states that `$11' should expand to the first parameter 8489concatenated with a literal `1', although some versions of GNU M4 8490expand the eleventh parameter instead. For portability, you should 8491only use single-digit M4 parameter expansion. 8492 8493 With this in mind, we can explore the cases where macros invoke 8494macros... 8495 8496 8497File: autoconf.info, Node: Quotation and Nested Macros, Next: Changequote is Evil, Prev: Quoting and Parameters, Up: M4 Quotation 8498 84998.1.4 Quotation and Nested Macros 8500--------------------------------- 8501 8502The examples below use the following macros: 8503 8504 define([car], [$1]) 8505 define([active], [ACT, IVE]) 8506 define([array], [int tab[10]]) 8507 8508 Each additional embedded macro call introduces other possible 8509interesting quotations: 8510 8511 car(active) 8512 =>ACT 8513 car([active]) 8514 =>ACT, IVE 8515 car([[active]]) 8516 =>active 8517 8518 In the first case, the top level looks for the arguments of `car', 8519and finds `active'. Because M4 evaluates its arguments before applying 8520the macro, `active' is expanded, which results in: 8521 8522 car(ACT, IVE) 8523 =>ACT 8524 8525In the second case, the top level gives `active' as first and only 8526argument of `car', which results in: 8527 8528 active 8529 =>ACT, IVE 8530 8531i.e., the argument is evaluated _after_ the macro that invokes it. In 8532the third case, `car' receives `[active]', which results in: 8533 8534 [active] 8535 =>active 8536 8537exactly as we already saw above. 8538 8539 The example above, applied to a more realistic example, gives: 8540 8541 car(int tab[10];) 8542 =>int tab10; 8543 car([int tab[10];]) 8544 =>int tab10; 8545 car([[int tab[10];]]) 8546 =>int tab[10]; 8547 8548Huh? The first case is easily understood, but why is the second wrong, 8549and the third right? To understand that, you must know that after M4 8550expands a macro, the resulting text is immediately subjected to macro 8551expansion and quote removal. This means that the quote removal occurs 8552twice--first before the argument is passed to the `car' macro, and 8553second after the `car' macro expands to the first argument. 8554 8555 As the author of the Autoconf macro `car', you then consider it to 8556be incorrect that your users have to double-quote the arguments of 8557`car', so you "fix" your macro. Let's call it `qar' for quoted car: 8558 8559 define([qar], [[$1]]) 8560 8561and check that `qar' is properly fixed: 8562 8563 qar([int tab[10];]) 8564 =>int tab[10]; 8565 8566Ahhh! That's much better. 8567 8568 But note what you've done: now that the result of `qar' is always a 8569literal string, the only time a user can use nested macros is if she 8570relies on an _unquoted_ macro call: 8571 8572 qar(active) 8573 =>ACT 8574 qar([active]) 8575 =>active 8576 8577leaving no way for her to reproduce what she used to do with `car': 8578 8579 car([active]) 8580 =>ACT, IVE 8581 8582Worse yet: she wants to use a macro that produces a set of `cpp' macros: 8583 8584 define([my_includes], [#include <stdio.h>]) 8585 car([my_includes]) 8586 =>#include <stdio.h> 8587 qar(my_includes) 8588 error-->EOF in argument list 8589 8590 This macro, `qar', because it double quotes its arguments, forces 8591its users to leave their macro calls unquoted, which is dangerous. 8592Commas and other active symbols are interpreted by M4 before they are 8593given to the macro, often not in the way the users expect. Also, 8594because `qar' behaves differently from the other macros, it's an 8595exception that should be avoided in Autoconf. 8596 8597 8598File: autoconf.info, Node: Changequote is Evil, Next: Quadrigraphs, Prev: Quotation and Nested Macros, Up: M4 Quotation 8599 86008.1.5 `changequote' is Evil 8601--------------------------- 8602 8603The temptation is often high to bypass proper quotation, in particular 8604when it's late at night. Then, many experienced Autoconf hackers 8605finally surrender to the dark side of the force and use the ultimate 8606weapon: `changequote'. 8607 8608 The M4 builtin `changequote' belongs to a set of primitives that 8609allow one to adjust the syntax of the language to adjust it to one's 8610needs. For instance, by default M4 uses ``' and `'' as quotes, but in 8611the context of shell programming (and actually of most programming 8612languages), that's about the worst choice one can make: because of 8613strings and back-quoted expressions in shell code (such as `'this'' and 8614``that`'), and because of literal characters in usual programming 8615languages (as in `'0''), there are many unbalanced ``' and `''. Proper 8616M4 quotation then becomes a nightmare, if not impossible. In order to 8617make M4 useful in such a context, its designers have equipped it with 8618`changequote', which makes it possible to choose another pair of 8619quotes. M4sugar, M4sh, Autoconf, and Autotest all have chosen to use 8620`[' and `]'. Not especially because they are unlikely characters, but 8621_because they are characters unlikely to be unbalanced_. 8622 8623 There are other magic primitives, such as `changecom' to specify 8624what syntactic forms are comments (it is common to see `changecom(<!--, 8625-->)' when M4 is used to produce HTML pages), `changeword' and 8626`changesyntax' to change other syntactic details (such as the character 8627to denote the Nth argument, `$' by default, the parentheses around 8628arguments, etc.). 8629 8630 These primitives are really meant to make M4 more useful for specific 8631domains: they should be considered like command line options: 8632`--quotes', `--comments', `--words', and `--syntax'. Nevertheless, 8633they are implemented as M4 builtins, as it makes M4 libraries self 8634contained (no need for additional options). 8635 8636 There lies the problem... 8637 8638 8639 The problem is that it is then tempting to use them in the middle of 8640an M4 script, as opposed to its initialization. This, if not carefully 8641thought out, can lead to disastrous effects: _you are changing the 8642language in the middle of the execution_. Changing and restoring the 8643syntax is often not enough: if you happened to invoke macros in between, 8644these macros are lost, as the current syntax is probably not the one 8645they were implemented with. 8646 8647 8648File: autoconf.info, Node: Quadrigraphs, Next: Balancing Parentheses, Prev: Changequote is Evil, Up: M4 Quotation 8649 86508.1.6 Quadrigraphs 8651------------------ 8652 8653When writing an Autoconf macro you may occasionally need to generate 8654special characters that are difficult to express with the standard 8655Autoconf quoting rules. For example, you may need to output the regular 8656expression `[^[]', which matches any character other than `['. This 8657expression contains unbalanced brackets so it cannot be put easily into 8658an M4 macro. 8659 8660 Additionally, there are a few m4sugar macros (such as `m4_split' and 8661`m4_expand') which internally use special markers in addition to the 8662regular quoting characters. If the arguments to these macros contain 8663the literal strings `-=<{(' or `)}>=-', the macros might behave 8664incorrectly. 8665 8666 You can work around these problems by using one of the following 8667"quadrigraphs": 8668 8669`@<:@' 8670 `[' 8671 8672`@:>@' 8673 `]' 8674 8675`@S|@' 8676 `$' 8677 8678`@%:@' 8679 `#' 8680 8681`@{:@' 8682 `(' 8683 8684`@:}@' 8685 `)' 8686 8687`@&t@' 8688 Expands to nothing. 8689 8690 Quadrigraphs are replaced at a late stage of the translation process, 8691after `m4' is run, so they do not get in the way of M4 quoting. For 8692example, the string `^@<:@', independently of its quotation, appears as 8693`^[' in the output. 8694 8695 The empty quadrigraph can be used: 8696 8697 - to mark trailing spaces explicitly 8698 8699 Trailing spaces are smashed by `autom4te'. This is a feature. 8700 8701 - to produce quadrigraphs and other strings reserved by m4sugar 8702 8703 For instance `@<@&t@:@' produces `@<:@'. For a more contrived 8704 example: 8705 8706 m4_define([a], [A])m4_define([b], [B])m4_define([c], [C])dnl 8707 m4_split([a )}>=- b -=<{( c]) 8708 =>[a], [], [B], [], [c] 8709 m4_split([a )}@&t@>=- b -=<@&t@{( c]) 8710 =>[a], [)}>=-], [b], [-=<{(], [c] 8711 8712 - to escape _occurrences_ of forbidden patterns 8713 8714 For instance you might want to mention `AC_FOO' in a comment, while 8715 still being sure that `autom4te' still catches unexpanded `AC_*'. 8716 Then write `AC@&t@_FOO'. 8717 8718 The name `@&t@' was suggested by Paul Eggert: 8719 8720 I should give some credit to the `@&t@' pun. The `&' is my own 8721 invention, but the `t' came from the source code of the ALGOL68C 8722 compiler, written by Steve Bourne (of Bourne shell fame), and 8723 which used `mt' to denote the empty string. In C, it would have 8724 looked like something like: 8725 8726 char const mt[] = ""; 8727 8728 but of course the source code was written in Algol 68. 8729 8730 I don't know where he got `mt' from: it could have been his own 8731 invention, and I suppose it could have been a common pun around the 8732 Cambridge University computer lab at the time. 8733 8734 8735File: autoconf.info, Node: Balancing Parentheses, Next: Quotation Rule Of Thumb, Prev: Quadrigraphs, Up: M4 Quotation 8736 87378.1.7 Dealing with unbalanced parentheses 8738----------------------------------------- 8739 8740One of the pitfalls of portable shell programming is that `case' 8741statements require unbalanced parentheses (*note Limitations of Shell 8742Builtins: case.). With syntax highlighting editors, the presence of 8743unbalanced `)' can interfere with editors that perform syntax 8744highlighting of macro contents based on finding the matching `('. 8745Another concern is how much editing must be done when transferring code 8746snippets between shell scripts and macro definitions. But most 8747importantly, the presence of unbalanced parentheses can introduce 8748expansion bugs. 8749 8750 For an example, here is an underquoted attempt to use the macro 8751`my_case', which happens to expand to a portable `case' statement: 8752 8753 AC_DEFUN([my_case], 8754 [case $file_name in 8755 *.c) echo "C source code";; 8756 esac]) 8757 AS_IF(:, my_case) 8758 8759In the above example, the `AS_IF' call underquotes its arguments. As a 8760result, the unbalanced `)' generated by the premature expansion of 8761`my_case' results in expanding `AS_IF' with a truncated parameter, and 8762the expansion is syntactically invalid: 8763 8764 if :; then 8765 case $file_name in 8766 *.c 8767 fi echo "C source code";; 8768 esac) 8769 8770 If nothing else, this should emphasize the importance of the quoting 8771arguments to macro calls. On the other hand, there are several 8772variations for defining `my_case' to be more robust, even when used 8773without proper quoting, each with some benefits and some drawbacks. 8774 8775 Creative literal shell comment 8776 AC_DEFUN([my_case], 8777 [case $file_name in #( 8778 *.c) echo "C source code";; 8779 esac]) 8780 This version provides balanced parentheses to several editors, and 8781 can be copied and pasted into a terminal as is. Unfortunately, it 8782 is still unbalanced as an Autoconf argument, since `#(' is an M4 8783 comment that masks the normal properties of `('. 8784 8785 Quadrigraph shell comment 8786 AC_DEFUN([my_case], 8787 [case $file_name in @%:@( 8788 *.c) echo "C source code";; 8789 esac]) 8790 This version provides balanced parentheses to even more editors, 8791 and can be used as a balanced Autoconf argument. Unfortunately, 8792 it requires some editing before it can be copied and pasted into a 8793 terminal, and the use of the quadrigraph `@%:@' for `#' reduces 8794 readability. 8795 8796 Quoting just the parenthesis 8797 AC_DEFUN([my_case], 8798 [case $file_name in 8799 *.c[)] echo "C source code";; 8800 esac]) 8801 This version quotes the `)', so that it can be used as a balanced 8802 Autoconf argument. As written, this is not balanced to an editor, 8803 but it can be coupled with `[#(]' to meet that need, too. 8804 However, it still requires some edits before it can be copied and 8805 pasted into a terminal. 8806 8807 Double-quoting the entire statement 8808 AC_DEFUN([my_case], 8809 [[case $file_name in #( 8810 *.c) echo "C source code";; 8811 esac]]) 8812 Since the entire macro is double-quoted, there is no problem with 8813 using this as an Autoconf argument; and since the double-quoting 8814 is over the entire statement, this code can be easily copied and 8815 pasted into a terminal. However, the double quoting prevents the 8816 expansion of any macros inside the case statement, which may cause 8817 its own set of problems. 8818 8819 Using `AS_CASE' 8820 AC_DEFUN([my_case], 8821 [AS_CASE([$file_name], 8822 [*.c], [echo "C source code"])]) 8823 This version avoids the balancing issue altogether, by relying on 8824 `AS_CASE' (*note Common Shell Constructs::); it also allows for the 8825 expansion of `AC_REQUIRE' to occur prior to the entire case 8826 statement, rather than within a branch of the case statement that 8827 might not be taken. However, the abstraction comes with a penalty 8828 that it is no longer a quick copy, paste, and edit to get back to 8829 shell code. 8830 8831 8832File: autoconf.info, Node: Quotation Rule Of Thumb, Prev: Balancing Parentheses, Up: M4 Quotation 8833 88348.1.8 Quotation Rule Of Thumb 8835----------------------------- 8836 8837To conclude, the quotation rule of thumb is: 8838 8839 _One pair of quotes per pair of parentheses._ 8840 8841 Never over-quote, never under-quote, in particular in the definition 8842of macros. In the few places where the macros need to use brackets 8843(usually in C program text or regular expressions), properly quote _the 8844arguments_! 8845 8846 It is common to read Autoconf programs with snippets like: 8847 8848 AC_TRY_LINK( 8849 changequote(<<, >>)dnl 8850 <<#include <time.h> 8851 #ifndef tzname /* For SGI. */ 8852 extern char *tzname[]; /* RS6000 and others reject char **tzname. */ 8853 #endif>>, 8854 changequote([, ])dnl 8855 [atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no) 8856 8857which is incredibly useless since `AC_TRY_LINK' is _already_ double 8858quoting, so you just need: 8859 8860 AC_TRY_LINK( 8861 [#include <time.h> 8862 #ifndef tzname /* For SGI. */ 8863 extern char *tzname[]; /* RS6000 and others reject char **tzname. */ 8864 #endif], 8865 [atoi (*tzname);], 8866 [ac_cv_var_tzname=yes], 8867 [ac_cv_var_tzname=no]) 8868 8869The M4-fluent reader might note that these two examples are rigorously 8870equivalent, since M4 swallows both the `changequote(<<, >>)' and `<<' 8871`>>' when it "collects" the arguments: these quotes are not part of the 8872arguments! 8873 8874 Simplified, the example above is just doing this: 8875 8876 changequote(<<, >>)dnl 8877 <<[]>> 8878 changequote([, ])dnl 8879 8880instead of simply: 8881 8882 [[]] 8883 8884 With macros that do not double quote their arguments (which is the 8885rule), double-quote the (risky) literals: 8886 8887 AC_LINK_IFELSE([AC_LANG_PROGRAM( 8888 [[#include <time.h> 8889 #ifndef tzname /* For SGI. */ 8890 extern char *tzname[]; /* RS6000 and others reject char **tzname. */ 8891 #endif]], 8892 [atoi (*tzname);])], 8893 [ac_cv_var_tzname=yes], 8894 [ac_cv_var_tzname=no]) 8895 8896 Please note that the macro `AC_TRY_LINK' is obsolete, so you really 8897should be using `AC_LINK_IFELSE' instead. 8898 8899 *Note Quadrigraphs::, for what to do if you run into a hopeless case 8900where quoting does not suffice. 8901 8902 When you create a `configure' script using newly written macros, 8903examine it carefully to check whether you need to add more quotes in 8904your macros. If one or more words have disappeared in the M4 output, 8905you need more quotes. When in doubt, quote. 8906 8907 However, it's also possible to put on too many layers of quotes. If 8908this happens, the resulting `configure' script may contain unexpanded 8909macros. The `autoconf' program checks for this problem by looking for 8910the string `AC_' in `configure'. However, this heuristic does not work 8911in general: for example, it does not catch overquoting in `AC_DEFINE' 8912descriptions. 8913 8914 8915File: autoconf.info, Node: Using autom4te, Next: Programming in M4sugar, Prev: M4 Quotation, Up: Programming in M4 8916 89178.2 Using `autom4te' 8918==================== 8919 8920The Autoconf suite, including M4sugar, M4sh, and Autotest, in addition 8921to Autoconf per se, heavily rely on M4. All these different uses 8922revealed common needs factored into a layer over M4: `autom4te'(1). 8923 8924 `autom4te' is a preprocessor that is like `m4'. It supports M4 8925extensions designed for use in tools like Autoconf. 8926 8927* Menu: 8928 8929* autom4te Invocation:: A GNU M4 wrapper 8930* Customizing autom4te:: Customizing the Autoconf package 8931 8932 ---------- Footnotes ---------- 8933 8934 (1) Yet another great name from Lars J. Aas. 8935 8936 8937File: autoconf.info, Node: autom4te Invocation, Next: Customizing autom4te, Up: Using autom4te 8938 89398.2.1 Invoking `autom4te' 8940------------------------- 8941 8942The command line arguments are modeled after M4's: 8943 8944 autom4te OPTIONS FILES 8945 8946where the FILES are directly passed to `m4'. By default, GNU M4 is 8947found during configuration, but the environment variable `M4' can be 8948set to tell `autom4te' where to look. In addition to the regular 8949expansion, it handles the replacement of the quadrigraphs (*note 8950Quadrigraphs::), and of `__oline__', the current line in the output. 8951It supports an extended syntax for the FILES: 8952 8953`FILE.m4f' 8954 This file is an M4 frozen file. Note that _all the previous files 8955 are ignored_. See the option `--melt' for the rationale. 8956 8957`FILE?' 8958 If found in the library path, the FILE is included for expansion, 8959 otherwise it is ignored instead of triggering a failure. 8960 8961 8962 Of course, it supports the Autoconf common subset of options: 8963 8964`--help' 8965`-h' 8966 Print a summary of the command line options and exit. 8967 8968`--version' 8969`-V' 8970 Print the version number of Autoconf and exit. 8971 8972`--verbose' 8973`-v' 8974 Report processing steps. 8975 8976`--debug' 8977`-d' 8978 Don't remove the temporary files and be even more verbose. 8979 8980`--include=DIR' 8981`-I DIR' 8982 Also look for input files in DIR. Multiple invocations accumulate. 8983 8984`--output=FILE' 8985`-o FILE' 8986 Save output (script or trace) to FILE. The file `-' stands for 8987 the standard output. 8988 8989 8990 As an extension of `m4', it includes the following options: 8991 8992`--warnings=CATEGORY' 8993`-W CATEGORY' 8994 Report the warnings related to CATEGORY (which can actually be a 8995 comma separated list). *Note Reporting Messages::, macro 8996 `AC_DIAGNOSE', for a comprehensive list of categories. Special 8997 values include: 8998 8999 `all' 9000 report all the warnings 9001 9002 `none' 9003 report none 9004 9005 `error' 9006 treats warnings as errors 9007 9008 `no-CATEGORY' 9009 disable warnings falling into CATEGORY 9010 9011 Warnings about `syntax' are enabled by default, and the environment 9012 variable `WARNINGS', a comma separated list of categories, is 9013 honored. `autom4te -W CATEGORY' actually behaves as if you had 9014 run: 9015 9016 autom4te --warnings=syntax,$WARNINGS,CATEGORY 9017 9018 For example, if you want to disable defaults and `WARNINGS' of 9019 `autom4te', but enable the warnings about obsolete constructs, you 9020 would use `-W none,obsolete'. 9021 9022 `autom4te' displays a back trace for errors, but not for warnings; 9023 if you want them, just pass `-W error'. 9024 9025`--melt' 9026`-M' 9027 Do not use frozen files. Any argument `FILE.m4f' is replaced by 9028 `FILE.m4'. This helps tracing the macros which are executed only 9029 when the files are frozen, typically `m4_define'. For instance, 9030 running: 9031 9032 autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4 9033 9034 is roughly equivalent to running: 9035 9036 m4 1.m4 2.m4 3.m4 4.m4 input.m4 9037 9038 while 9039 9040 autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4 9041 9042 is equivalent to: 9043 9044 m4 --reload-state=4.m4f input.m4 9045 9046`--freeze' 9047`-F' 9048 Produce a frozen state file. `autom4te' freezing is stricter than 9049 M4's: it must produce no warnings, and no output other than empty 9050 lines (a line with white space is _not_ empty) and comments 9051 (starting with `#'). Unlike `m4''s similarly-named option, this 9052 option takes no argument: 9053 9054 autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f 9055 9056 corresponds to 9057 9058 m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f 9059 9060`--mode=OCTAL-MODE' 9061`-m OCTAL-MODE' 9062 Set the mode of the non-traces output to OCTAL-MODE; by default 9063 `0666'. 9064 9065 9066 As another additional feature over `m4', `autom4te' caches its 9067results. GNU M4 is able to produce a regular output and traces at the 9068same time. Traces are heavily used in the GNU Build System: 9069`autoheader' uses them to build `config.h.in', `autoreconf' to 9070determine what GNU Build System components are used, `automake' to 9071"parse" `configure.ac' etc. To avoid recomputation, traces are cached 9072while performing regular expansion, and conversely. This cache is 9073(actually, the caches are) stored in the directory `autom4te.cache'. 9074_It can safely be removed_ at any moment (especially if for some reason 9075`autom4te' considers it trashed). 9076 9077`--cache=DIRECTORY' 9078`-C DIRECTORY' 9079 Specify the name of the directory where the result should be 9080 cached. Passing an empty value disables caching. Be sure to pass 9081 a relative file name, as for the time being, global caches are not 9082 supported. 9083 9084`--no-cache' 9085 Don't cache the results. 9086 9087`--force' 9088`-f' 9089 If a cache is used, consider it obsolete (but update it anyway). 9090 9091 9092 Because traces are so important to the GNU Build System, `autom4te' 9093provides high level tracing features as compared to M4, and helps 9094exploiting the cache: 9095 9096`--trace=MACRO[:FORMAT]' 9097`-t MACRO[:FORMAT]' 9098 Trace the invocations of MACRO according to the FORMAT. Multiple 9099 `--trace' arguments can be used to list several macros. Multiple 9100 `--trace' arguments for a single macro are not cumulative; 9101 instead, you should just make FORMAT as long as needed. 9102 9103 The FORMAT is a regular string, with newlines if desired, and 9104 several special escape codes. It defaults to `$f:$l:$n:$%'. It 9105 can use the following special escapes: 9106 9107 `$$' 9108 The character `$'. 9109 9110 `$f' 9111 The file name from which MACRO is called. 9112 9113 `$l' 9114 The line number from which MACRO is called. 9115 9116 `$d' 9117 The depth of the MACRO call. This is an M4 technical detail 9118 that you probably don't want to know about. 9119 9120 `$n' 9121 The name of the MACRO. 9122 9123 `$NUM' 9124 The NUMth argument of the call to MACRO. 9125 9126 `$@' 9127 `$SEP@' 9128 `${SEPARATOR}@' 9129 All the arguments passed to MACRO, separated by the character 9130 SEP or the string SEPARATOR (`,' by default). Each argument 9131 is quoted, i.e., enclosed in a pair of square brackets. 9132 9133 `$*' 9134 `$SEP*' 9135 `${SEPARATOR}*' 9136 As above, but the arguments are not quoted. 9137 9138 `$%' 9139 `$SEP%' 9140 `${SEPARATOR}%' 9141 As above, but the arguments are not quoted, all new line 9142 characters in the arguments are smashed, and the default 9143 separator is `:'. 9144 9145 The escape `$%' produces single-line trace outputs (unless 9146 you put newlines in the `separator'), while `$@' and `$*' do 9147 not. 9148 9149 *Note autoconf Invocation::, for examples of trace uses. 9150 9151`--preselect=MACRO' 9152`-p MACRO' 9153 Cache the traces of MACRO, but do not enable traces. This is 9154 especially important to save CPU cycles in the future. For 9155 instance, when invoked, `autoconf' preselects all the macros that 9156 `autoheader', `automake', `autoreconf', etc., trace, so that 9157 running `m4' is not needed to trace them: the cache suffices. 9158 This results in a huge speed-up. 9159 9160 9161 Finally, `autom4te' introduces the concept of "Autom4te libraries". 9162They consists in a powerful yet extremely simple feature: sets of 9163combined command line arguments: 9164 9165`--language=LANGUAGE' 9166`-l LANGUAGE' 9167 Use the LANGUAGE Autom4te library. Current languages include: 9168 9169 `M4sugar' 9170 create M4sugar output. 9171 9172 `M4sh' 9173 create M4sh executable shell scripts. 9174 9175 `Autotest' 9176 create Autotest executable test suites. 9177 9178 `Autoconf-without-aclocal-m4' 9179 create Autoconf executable configure scripts without reading 9180 `aclocal.m4'. 9181 9182 `Autoconf' 9183 create Autoconf executable configure scripts. This language 9184 inherits all the characteristics of 9185 `Autoconf-without-aclocal-m4' and additionally reads 9186 `aclocal.m4'. 9187 9188`--prepend-include=DIR' 9189`-B DIR' 9190 Prepend directory DIR to the search path. This is used to include 9191 the language-specific files before any third-party macros. 9192 9193 9194 As an example, if Autoconf is installed in its default location, 9195`/usr/local', the command `autom4te -l m4sugar foo.m4' is strictly 9196equivalent to the command: 9197 9198 autom4te --prepend-include /usr/local/share/autoconf \ 9199 m4sugar/m4sugar.m4f --warnings syntax foo.m4 9200 9201Recursive expansion applies here: the command `autom4te -l m4sh foo.m4' 9202is the same as `autom4te --language M4sugar m4sugar/m4sh.m4f foo.m4', 9203i.e.: 9204 9205 autom4te --prepend-include /usr/local/share/autoconf \ 9206 m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4 9207 9208The definition of the languages is stored in `autom4te.cfg'. 9209 9210 9211File: autoconf.info, Node: Customizing autom4te, Prev: autom4te Invocation, Up: Using autom4te 9212 92138.2.2 Customizing `autom4te' 9214---------------------------- 9215 9216One can customize `autom4te' via `~/.autom4te.cfg' (i.e., as found in 9217the user home directory), and `./.autom4te.cfg' (i.e., as found in the 9218directory from which `autom4te' is run). The order is first reading 9219`autom4te.cfg', then `~/.autom4te.cfg', then `./.autom4te.cfg', and 9220finally the command line arguments. 9221 9222 In these text files, comments are introduced with `#', and empty 9223lines are ignored. Customization is performed on a per-language basis, 9224wrapped in between a `begin-language: "LANGUAGE"', `end-language: 9225"LANGUAGE"' pair. 9226 9227 Customizing a language stands for appending options (*note autom4te 9228Invocation::) to the current definition of the language. Options, and 9229more generally arguments, are introduced by `args: ARGUMENTS'. You may 9230use the traditional shell syntax to quote the ARGUMENTS. 9231 9232 As an example, to disable Autoconf caches (`autom4te.cache') 9233globally, include the following lines in `~/.autom4te.cfg': 9234 9235## ------------------ ## 9236## User Preferences. ## 9237## ------------------ ## 9238 9239begin-language: "Autoconf-without-aclocal-m4" 9240args: --no-cache 9241end-language: "Autoconf-without-aclocal-m4" 9242 9243 9244File: autoconf.info, Node: Programming in M4sugar, Next: Debugging via autom4te, Prev: Using autom4te, Up: Programming in M4 9245 92468.3 Programming in M4sugar 9247========================== 9248 9249M4 by itself provides only a small, but sufficient, set of all-purpose 9250macros. M4sugar introduces additional generic macros. Its name was 9251coined by Lars J. Aas: "Readability And Greater Understanding Stands 4 9252M4sugar". 9253 9254 M4sugar reserves the macro namespace `^_m4_' for internal use, and 9255the macro namespace `^m4_' for M4sugar macros. You should not define 9256your own macros into these namespaces. 9257 9258* Menu: 9259 9260* Redefined M4 Macros:: M4 builtins changed in M4sugar 9261* Diagnostic Macros:: Diagnostic messages from M4sugar 9262* Diversion support:: Diversions in M4sugar 9263* Conditional constructs:: Conditions in M4 9264* Looping constructs:: Iteration in M4 9265* Evaluation Macros:: More quotation and evaluation control 9266* Text processing Macros:: String manipulation in M4 9267* Number processing Macros:: Arithmetic computation in M4 9268* Set manipulation Macros:: Set manipulation in M4 9269* Forbidden Patterns:: Catching unexpanded macros 9270 9271 9272File: autoconf.info, Node: Redefined M4 Macros, Next: Diagnostic Macros, Up: Programming in M4sugar 9273 92748.3.1 Redefined M4 Macros 9275------------------------- 9276 9277With a few exceptions, all the M4 native macros are moved in the `m4_' 9278pseudo-namespace, e.g., M4sugar renames `define' as `m4_define' etc. 9279 9280 The list of macros unchanged from M4, except for their name, is: 9281 - m4_builtin 9282 9283 - m4_changecom 9284 9285 - m4_changequote 9286 9287 - m4_debugfile 9288 9289 - m4_debugmode 9290 9291 - m4_decr 9292 9293 - m4_define 9294 9295 - m4_divnum 9296 9297 - m4_errprint 9298 9299 - m4_esyscmd 9300 9301 - m4_eval 9302 9303 - m4_format 9304 9305 - m4_ifdef 9306 9307 - m4_incr 9308 9309 - m4_index 9310 9311 - m4_indir 9312 9313 - m4_len 9314 9315 - m4_pushdef 9316 9317 - m4_shift 9318 9319 - m4_substr 9320 9321 - m4_syscmd 9322 9323 - m4_sysval 9324 9325 - m4_traceoff 9326 9327 - m4_traceon 9328 9329 - m4_translit 9330 9331 Some M4 macros are redefined, and are slightly incompatible with 9332their native equivalent. 9333 9334 -- Macro: __file__ 9335 -- Macro: __line__ 9336 All M4 macros starting with `__' retain their original name: for 9337 example, no `m4__file__' is defined. 9338 9339 -- Macro: __oline__ 9340 This is not technically a macro, but a feature of Autom4te. The 9341 sequence `__oline__' can be used similarly to the other m4sugar 9342 location macros, but rather than expanding to the location of the 9343 input file, it is translated to the line number where it appears 9344 in the output file after all other M4 expansions. 9345 9346 -- Macro: dnl 9347 This macro kept its original name: no `m4_dnl' is defined. 9348 9349 -- Macro: m4_bpatsubst (STRING, REGEXP, [REPLACEMENT]) 9350 This macro corresponds to `patsubst'. The name `m4_patsubst' is 9351 kept for future versions of M4sugar, once GNU M4 2.0 is released 9352 and supports extended regular expression syntax. 9353 9354 -- Macro: m4_bregexp (STRING, REGEXP, [REPLACEMENT]) 9355 This macro corresponds to `regexp'. The name `m4_regexp' is kept 9356 for future versions of M4sugar, once GNU M4 2.0 is released and 9357 supports extended regular expression syntax. 9358 9359 -- Macro: m4_copy (SOURCE, DEST) 9360 -- Macro: m4_copy_force (SOURCE, DEST) 9361 -- Macro: m4_rename (SOURCE, DEST) 9362 -- Macro: m4_rename_force (SOURCE, DEST) 9363 These macros aren't directly builtins, but are closely related to 9364 `m4_pushdef' and `m4_defn'. `m4_copy' and `m4_rename' ensure that 9365 DEST is undefined, while `m4_copy_force' and `m4_rename_force' 9366 overwrite any existing definition. All four macros then proceed 9367 to copy the entire pushdef stack of definitions of SOURCE over to 9368 DEST. `m4_copy' and `m4_copy_force' preserve the source 9369 (including in the special case where SOURCE is undefined), while 9370 `m4_rename' and `m4_rename_force' undefine the original macro name 9371 (making it an error to rename an undefined SOURCE). 9372 9373 Note that attempting to invoke a renamed macro might not work, 9374 since the macro may have a dependence on helper macros accessed 9375 via composition of `$0' but that were not also renamed; likewise, 9376 other macros may have a hard-coded dependence on SOURCE and could 9377 break if SOURCE has been deleted. On the other hand, it is always 9378 safe to rename a macro to temporarily move it out of the way, then 9379 rename it back later to restore original semantics. 9380 9381 -- Macro: m4_defn (MACRO...) 9382 This macro fails if MACRO is not defined, even when using older 9383 versions of M4 that did not warn. See `m4_undefine'. 9384 Unfortunately, in order to support these older versions of M4, 9385 there are some situations involving unbalanced quotes where 9386 concatenating multiple macros together will work in newer M4 but 9387 not in m4sugar; use quadrigraphs to work around this. 9388 9389 -- Macro: m4_divert (DIVERSION) 9390 M4sugar relies heavily on diversions, so rather than behaving as a 9391 primitive, `m4_divert' behaves like: 9392 m4_divert_pop()m4_divert_push([DIVERSION]) 9393 *Note Diversion support::, for more details about the use of the 9394 diversion stack. In particular, this implies that DIVERSION 9395 should be a named diversion rather than a raw number. But be 9396 aware that it is seldom necessary to explicitly change the 9397 diversion stack, and that when done incorrectly, it can lead to 9398 syntactically invalid scripts. 9399 9400 -- Macro: m4_dumpdef (NAME...) 9401 -- Macro: m4_dumpdefs (NAME...) 9402 `m4_dumpdef' is like the M4 builtin, except that this version 9403 requires at least one argument, output always goes to standard 9404 error rather than the current debug file, no sorting is done on 9405 multiple arguments, and an error is issued if any NAME is 9406 undefined. `m4_dumpdefs' is a convenience macro that calls 9407 `m4_dumpdef' for all of the `m4_pushdef' stack of definitions, 9408 starting with the current, and silently does nothing if NAME is 9409 undefined. 9410 9411 Unfortunately, due to a limitation in M4 1.4.x, any macro defined 9412 as a builtin is output as the empty string. This behavior is 9413 rectified by using M4 1.6 or newer. However, this behavior 9414 difference means that `m4_dumpdef' should only be used while 9415 developing m4sugar macros, and never in the final published form 9416 of a macro. 9417 9418 -- Macro: m4_esyscmd_s (COMMAND) 9419 Like `m4_esyscmd', this macro expands to the result of running 9420 COMMAND in a shell. The difference is that any trailing newlines 9421 are removed, so that the output behaves more like shell command 9422 substitution. 9423 9424 -- Macro: m4_exit (EXIT-STATUS) 9425 This macro corresponds to `m4exit'. 9426 9427 -- Macro: m4_if (COMMENT) 9428 -- Macro: m4_if (STRING-1, STRING-2, EQUAL, [NOT-EQUAL]) 9429 -- Macro: m4_if (STRING-1, STRING-2, EQUAL-1, STRING-3, STRING-4, 9430 EQUAL-2, ..., [NOT-EQUAL]) 9431 This macro corresponds to `ifelse'. STRING-1 and STRING-2 are 9432 compared literally, so usually one of the two arguments is passed 9433 unquoted. *Note Conditional constructs::, for more conditional 9434 idioms. 9435 9436 -- Macro: m4_include (FILE) 9437 -- Macro: m4_sinclude (FILE) 9438 Like the M4 builtins, but warn against multiple inclusions of FILE. 9439 9440 -- Macro: m4_mkstemp (TEMPLATE) 9441 -- Macro: m4_maketemp (TEMPLATE) 9442 Posix requires `maketemp' to replace the trailing `X' characters 9443 in TEMPLATE with the process id, without regards to the existence 9444 of a file by that name, but this a security hole. When this was 9445 pointed out to the Posix folks, they agreed to invent a new macro 9446 `mkstemp' that always creates a uniquely named file, but not all 9447 versions of GNU M4 support the new macro. In M4sugar, 9448 `m4_maketemp' and `m4_mkstemp' are synonyms for each other, and 9449 both have the secure semantics regardless of which macro the 9450 underlying M4 provides. 9451 9452 -- Macro: m4_popdef (MACRO...) 9453 This macro fails if MACRO is not defined, even when using older 9454 versions of M4 that did not warn. See `m4_undefine'. 9455 9456 -- Macro: m4_undefine (MACRO...) 9457 This macro fails if MACRO is not defined, even when using older 9458 versions of M4 that did not warn. Use 9459 9460 m4_ifdef([MACRO], [m4_undefine([MACRO])]) 9461 9462 if you are not sure whether MACRO is defined. 9463 9464 -- Macro: m4_undivert (DIVERSION...) 9465 Unlike the M4 builtin, at least one DIVERSION must be specified. 9466 Also, since the M4sugar diversion stack prefers named diversions, 9467 the use of `m4_undivert' to include files is risky. *Note 9468 Diversion support::, for more details about the use of the 9469 diversion stack. But be aware that it is seldom necessary to 9470 explicitly change the diversion stack, and that when done 9471 incorrectly, it can lead to syntactically invalid scripts. 9472 9473 -- Macro: m4_wrap (TEXT) 9474 -- Macro: m4_wrap_lifo (TEXT) 9475 These macros correspond to `m4wrap'. Posix requires arguments of 9476 multiple wrap calls to be reprocessed at EOF in the same order as 9477 the original calls (first-in, first-out). GNU M4 versions through 9478 1.4.10, however, reprocess them in reverse order (last-in, 9479 first-out). Both orders are useful, therefore, you can rely on 9480 `m4_wrap' to provide FIFO semantics and `m4_wrap_lifo' for LIFO 9481 semantics, regardless of the underlying GNU M4 version. 9482 9483 Unlike the GNU M4 builtin, these macros only recognize one 9484 argument, and avoid token pasting between consecutive invocations. 9485 On the other hand, nested calls to `m4_wrap' from within wrapped 9486 text work just as in the builtin. 9487 9488 9489File: autoconf.info, Node: Diagnostic Macros, Next: Diversion support, Prev: Redefined M4 Macros, Up: Programming in M4sugar 9490 94918.3.2 Diagnostic messages from M4sugar 9492-------------------------------------- 9493 9494When macros statically diagnose abnormal situations, benign or fatal, 9495they should report them using these macros. For issuing dynamic issues, 9496i.e., when `configure' is run, see *note Printing Messages::. 9497 9498 -- Macro: m4_assert (EXPRESSION, [EXIT-STATUS = `1']) 9499 Assert that the arithmetic EXPRESSION evaluates to non-zero. 9500 Otherwise, issue a fatal error, and exit `autom4te' with 9501 EXIT-STATUS. 9502 9503 -- Macro: m4_errprintn (MESSAGE) 9504 Similar to the builtin `m4_errprint', except that a newline is 9505 guaranteed after MESSAGE. 9506 9507 -- Macro: m4_fatal (MESSAGE) 9508 Report a severe error MESSAGE prefixed with the current location, 9509 and have `autom4te' die. 9510 9511 -- Macro: m4_location 9512 Useful as a prefix in a message line. Short for: 9513 __file__:__line__ 9514 9515 -- Macro: m4_warn (CATEGORY, MESSAGE) 9516 Report MESSAGE as a warning (or as an error if requested by the 9517 user) if warnings of the CATEGORY are turned on. If the message 9518 is emitted, it is prefixed with the current location, and followed 9519 by a call trace of all macros defined via `AC_DEFUN' used to get 9520 to the current expansion. You are encouraged to use standard 9521 categories, which currently include: 9522 9523 `all' 9524 messages that don't fall into one of the following 9525 categories. Use of an empty CATEGORY is equivalent. 9526 9527 `cross' 9528 related to cross compilation issues. 9529 9530 `obsolete' 9531 use of an obsolete construct. 9532 9533 `syntax' 9534 dubious syntactic constructs, incorrectly ordered macro calls. 9535 9536 9537File: autoconf.info, Node: Diversion support, Next: Conditional constructs, Prev: Diagnostic Macros, Up: Programming in M4sugar 9538 95398.3.3 Diversion support 9540----------------------- 9541 9542M4sugar makes heavy use of diversions under the hood, because it is 9543often the case that text that must appear early in the output is not 9544discovered until late in the input. Additionally, some of the 9545topological sorting algorithms used in resolving macro dependencies use 9546diversions. However, most macros should not need to change diversions 9547directly, but rather rely on higher-level M4sugar macros to manage 9548diversions transparently. If you change diversions improperly, you 9549risk generating a syntactically invalid script, because an incorrect 9550diversion will violate assumptions made by many macros about whether 9551prerequisite text has been previously output. In short, if you 9552manually change the diversion, you should not expect any macros 9553provided by the Autoconf package to work until you have restored the 9554diversion stack back to its original state. 9555 9556 In the rare case that it is necessary to write a macro that 9557explicitly outputs text to a different diversion, it is important to be 9558aware of an M4 limitation regarding diversions: text only goes to a 9559diversion if it is not part of argument collection. Therefore, any 9560macro that changes the current diversion cannot be used as an unquoted 9561argument to another macro, but must be expanded at the top level. The 9562macro `m4_expand' will diagnose any attempt to change diversions, since 9563it is generally useful only as an argument to another macro. The 9564following example shows what happens when diversion manipulation is 9565attempted within macro arguments: 9566 9567 m4_do([normal text] 9568 m4_divert_push([KILL])unwanted[]m4_divert_pop([KILL]) 9569 [m4_divert_push([KILL])discarded[]m4_divert_pop([KILL])])dnl 9570 =>normal text 9571 =>unwanted 9572 9573Notice that the unquoted text `unwanted' is output, even though it was 9574processed while the current diversion was `KILL', because it was 9575collected as part of the argument to `m4_do'. However, the text 9576`discarded' disappeared as desired, because the diversion changes were 9577single-quoted, and were not expanded until the top-level rescan of the 9578output of `m4_do'. 9579 9580 To make diversion management easier, M4sugar uses the concept of 9581named diversions. Rather than using diversion numbers directly, it is 9582nicer to associate a name with each diversion. The diversion number 9583associated with a particular diversion name is an implementation 9584detail, and a syntax warning is issued if a diversion number is used 9585instead of a name. In general, you should not output text to a named 9586diversion until after calling the appropriate initialization routine 9587for your language (`m4_init', `AS_INIT', `AT_INIT', ...), although 9588there are some exceptions documented below. 9589 9590 M4sugar defines two named diversions. 9591`KILL' 9592 Text written to this diversion is discarded. This is the default 9593 diversion once M4sugar is initialized. 9594 9595`GROW' 9596 This diversion is used behind the scenes by topological sorting 9597 macros, such as `AC_REQUIRE'. 9598 9599 M4sh adds several more named diversions. 9600`BINSH' 9601 This diversion is reserved for the `#!' interpreter line. 9602 9603`HEADER-REVISION' 9604 This diversion holds text from `AC_REVISION'. 9605 9606`HEADER-COMMENT' 9607 This diversion holds comments about the purpose of a file. 9608 9609`HEADER-COPYRIGHT' 9610 This diversion is managed by `AC_COPYRIGHT'. 9611 9612`M4SH-SANITIZE' 9613 This diversion contains M4sh sanitization code, used to ensure 9614 M4sh is executing in a reasonable shell environment. 9615 9616`M4SH-INIT' 9617 This diversion contains M4sh initialization code, initializing 9618 variables that are required by other M4sh macros. 9619 9620`BODY' 9621 This diversion contains the body of the shell code, and is the 9622 default diversion once M4sh is initialized. 9623 9624 Autotest inherits diversions from M4sh, and changes the default 9625diversion from `BODY' back to `KILL'. It also adds several more named 9626diversions, with the following subset designed for developer use. 9627`PREPARE_TESTS' 9628 This diversion contains initialization sequences which are executed 9629 after `atconfig' and `atlocal', and after all command line 9630 arguments have been parsed, but prior to running any tests. It 9631 can be used to set up state that is required across all tests. 9632 This diversion will work even before `AT_INIT'. 9633 9634 Autoconf inherits diversions from M4sh, and adds the following named 9635diversions which developers can utilize. 9636`DEFAULTS' 9637 This diversion contains shell variable assignments to set defaults 9638 that must be in place before arguments are parsed. This diversion 9639 is placed early enough in `configure' that it is unsafe to expand 9640 any autoconf macros into this diversion. 9641 9642`HELP_ENABLE' 9643 If `AC_PRESERVE_HELP_ORDER' was used, then text placed in this 9644 diversion will be included as part of a quoted here-doc providing 9645 all of the `--help' output of `configure' related to options 9646 created by `AC_ARG_WITH' and `AC_ARG_ENABLE'. 9647 9648`INIT_PREPARE' 9649 This diversion occurs after all command line options have been 9650 parsed, but prior to the main body of the `configure' script. This 9651 diversion is the last chance to insert shell code such as variable 9652 assignments or shell function declarations that will used by the 9653 expansion of other macros. 9654 9655 For now, the remaining named diversions of Autoconf, Autoheader, and 9656Autotest are not documented. In other words, intentionally outputting 9657text into an undocumented diversion is subject to breakage in a future 9658release of Autoconf. 9659 9660 -- Macro: m4_cleardivert (DIVERSION...) 9661 Permanently discard any text that has been diverted into DIVERSION. 9662 9663 -- Macro: m4_divert_once (DIVERSION, [CONTENT]) 9664 Similar to `m4_divert_text', except that CONTENT is only output to 9665 DIVERSION if this is the first time that `m4_divert_once' has been 9666 called with its particular arguments. 9667 9668 -- Macro: m4_divert_pop ([DIVERSION]) 9669 If provided, check that the current diversion is indeed DIVERSION. 9670 Then change to the diversion located earlier on the stack, giving 9671 an error if an attempt is made to pop beyond the initial m4sugar 9672 diversion of `KILL'. 9673 9674 -- Macro: m4_divert_push (DIVERSION) 9675 Remember the former diversion on the diversion stack, and output 9676 subsequent text into DIVERSION. M4sugar maintains a diversion 9677 stack, and issues an error if there is not a matching pop for every 9678 push. 9679 9680 -- Macro: m4_divert_text (DIVERSION, [CONTENT]) 9681 Output CONTENT and a newline into DIVERSION, without affecting the 9682 current diversion. Shorthand for: 9683 m4_divert_push([DIVERSION])CONTENT 9684 m4_divert_pop([DIVERSION])dnl 9685 9686 One use of `m4_divert_text' is to develop two related macros, where 9687 macro `MY_A' does the work, but adjusts what work is performed 9688 based on whether the optional macro `MY_B' has also been expanded. 9689 Of course, it is possible to use `AC_BEFORE' within `MY_A' to 9690 require that `MY_B' occurs first, if it occurs at all. But this 9691 imposes an ordering restriction on the user; it would be nicer if 9692 macros `MY_A' and `MY_B' can be invoked in either order. The trick 9693 is to let `MY_B' leave a breadcrumb in an early diversion, which 9694 `MY_A' can then use to determine whether `MY_B' has been expanded. 9695 9696 AC_DEFUN([MY_A], 9697 [# various actions 9698 if test -n "$b_was_used"; then 9699 # extra action 9700 fi]) 9701 AC_DEFUN([MY_B], 9702 [AC_REQUIRE([MY_A])dnl 9703 m4_divert_text([INIT_PREPARE], [b_was_used=true])]) 9704 9705 9706 -- Macro: m4_init 9707 Initialize the M4sugar environment, setting up the default named 9708 diversion to be `KILL'. 9709 9710 9711File: autoconf.info, Node: Conditional constructs, Next: Looping constructs, Prev: Diversion support, Up: Programming in M4sugar 9712 97138.3.4 Conditional constructs 9714---------------------------- 9715 9716The following macros provide additional conditional constructs as 9717convenience wrappers around `m4_if'. 9718 9719 -- Macro: m4_bmatch (STRING, REGEX-1, VALUE-1, [REGEX-2], [VALUE-2], 9720 ..., [DEFAULT]) 9721 The string STRING is repeatedly compared against a series of REGEX 9722 arguments; if a match is found, the expansion is the corresponding 9723 VALUE, otherwise, the macro moves on to the next REGEX. If no 9724 REGEX match, then the result is the optional DEFAULT, or nothing. 9725 9726 -- Macro: m4_bpatsubsts (STRING, REGEX-1, SUBST-1, [REGEX-2], 9727 [SUBST-2], ...) 9728 The string STRING is altered by REGEX-1 and SUBST-1, as if by: 9729 m4_bpatsubst([[STRING]], [REGEX], [SUBST]) 9730 9731 The result of the substitution is then passed through the next set 9732 of REGEX and SUBST, and so forth. An empty SUBST implies deletion 9733 of any matched portions in the current string. Note that this 9734 macro over-quotes STRING; this behavior is intentional, so that 9735 the result of each step of the recursion remains as a quoted 9736 string. However, it means that anchors (`^' and `$' in the REGEX 9737 will line up with the extra quotations, and not the characters of 9738 the original string. The overquoting is removed after the final 9739 substitution. 9740 9741 -- Macro: m4_case (STRING, VALUE-1, IF-VALUE-1, [VALUE-2], 9742 [IF-VALUE-2], ..., [DEFAULT]) 9743 Test STRING against multiple VALUE possibilities, resulting in the 9744 first IF-VALUE for a match, or in the optional DEFAULT. This is 9745 shorthand for: 9746 m4_if([STRING], [VALUE-1], [IF-VALUE-1], 9747 [STRING], [VALUE-2], [IF-VALUE-2], ..., 9748 [DEFAULT]) 9749 9750 -- Macro: m4_cond (TEST-1, VALUE-1, IF-VALUE-1, [TEST-2], [VALUE-2], 9751 [IF-VALUE-2], ..., [DEFAULT]) 9752 This macro was introduced in Autoconf 2.62. Similar to `m4_if', 9753 except that each TEST is expanded only when it is encountered. 9754 This is useful for short-circuiting expensive tests; while `m4_if' 9755 requires all its strings to be expanded up front before doing 9756 comparisons, `m4_cond' only expands a TEST when all earlier tests 9757 have failed. 9758 9759 For an example, these two sequences give the same result, but in 9760 the case where `$1' does not contain a backslash, the `m4_cond' 9761 version only expands `m4_index' once, instead of five times, for 9762 faster computation if this is a common case for `$1'. Notice that 9763 every third argument is unquoted for `m4_if', and quoted for 9764 `m4_cond': 9765 9766 m4_if(m4_index([$1], [\]), [-1], [$2], 9767 m4_eval(m4_index([$1], [\\]) >= 0), [1], [$2], 9768 m4_eval(m4_index([$1], [\$]) >= 0), [1], [$2], 9769 m4_eval(m4_index([$1], [\`]) >= 0), [1], [$3], 9770 m4_eval(m4_index([$1], [\"]) >= 0), [1], [$3], 9771 [$2]) 9772 m4_cond([m4_index([$1], [\])], [-1], [$2], 9773 [m4_eval(m4_index([$1], [\\]) >= 0)], [1], [$2], 9774 [m4_eval(m4_index([$1], [\$]) >= 0)], [1], [$2], 9775 [m4_eval(m4_index([$1], [\`]) >= 0)], [1], [$3], 9776 [m4_eval(m4_index([$1], [\"]) >= 0)], [1], [$3], 9777 [$2]) 9778 9779 -- Macro: m4_default (EXPR-1, EXPR-2) 9780 -- Macro: m4_default_quoted (EXPR-1, EXPR-2) 9781 -- Macro: m4_default_nblank (EXPR-1, [EXPR-2]) 9782 -- Macro: m4_default_nblank_quoted (EXPR-1, [EXPR-2]) 9783 If EXPR-1 contains text, use it. Otherwise, select EXPR-2. 9784 `m4_default' expands the result, while `m4_default_quoted' does 9785 not. Useful for providing a fixed default if the expression that 9786 results in EXPR-1 would otherwise be empty. The difference 9787 between `m4_default' and `m4_default_nblank' is whether an 9788 argument consisting of just blanks (space, tab, newline) is 9789 significant. When using the expanding versions, note that an 9790 argument may contain text but still expand to an empty string. 9791 9792 m4_define([active], [ACTIVE])dnl 9793 m4_define([empty], [])dnl 9794 m4_define([demo1], [m4_default([$1], [$2])])dnl 9795 m4_define([demo2], [m4_default_quoted([$1], [$2])])dnl 9796 m4_define([demo3], [m4_default_nblank([$1], [$2])])dnl 9797 m4_define([demo4], [m4_default_nblank_quoted([$1], [$2])])dnl 9798 demo1([active], [default]) 9799 =>ACTIVE 9800 demo1([], [active]) 9801 =>ACTIVE 9802 demo1([empty], [text]) 9803 => 9804 -demo1([ ], [active])- 9805 =>- - 9806 demo2([active], [default]) 9807 =>active 9808 demo2([], [active]) 9809 =>active 9810 demo2([empty], [text]) 9811 =>empty 9812 -demo2([ ], [active])- 9813 =>- - 9814 demo3([active], [default]) 9815 =>ACTIVE 9816 demo3([], [active]) 9817 =>ACTIVE 9818 demo3([empty], [text]) 9819 => 9820 -demo3([ ], [active])- 9821 =>-ACTIVE- 9822 demo4([active], [default]) 9823 =>active 9824 demo4([], [active]) 9825 =>active 9826 demo4([empty], [text]) 9827 =>empty 9828 -demo4([ ], [active])- 9829 =>-active- 9830 9831 -- Macro: m4_define_default (MACRO, [DEFAULT-DEFINITION]) 9832 If MACRO does not already have a definition, then define it to 9833 DEFAULT-DEFINITION. 9834 9835 -- Macro: m4_ifblank (COND, [IF-BLANK], [IF-TEXT]) 9836 -- Macro: m4_ifnblank (COND, [IF-TEXT], [IF-BLANK]) 9837 If COND is empty or consists only of blanks (space, tab, newline), 9838 then expand IF-BLANK; otherwise, expand IF-TEXT. Two variants 9839 exist, in order to make it easier to select the correct logical 9840 sense when using only two parameters. Note that this is more 9841 efficient than the equivalent behavior of: 9842 m4_ifval(m4_normalize([COND]), IF-TEXT, IF-BLANK) 9843 9844 -- Macro: m4_ifndef (MACRO, IF-NOT-DEFINED, [IF-DEFINED]) 9845 This is shorthand for: 9846 m4_ifdef([MACRO], [IF-DEFINED], [IF-NOT-DEFINED]) 9847 9848 -- Macro: m4_ifset (MACRO, [IF-TRUE], [IF-FALSE]) 9849 If MACRO is undefined, or is defined as the empty string, expand 9850 to IF-FALSE. Otherwise, expands to IF-TRUE. Similar to: 9851 m4_ifval(m4_defn([MACRO]), [IF-TRUE], [IF-FALSE]) 9852 except that it is not an error if MACRO is undefined. 9853 9854 -- Macro: m4_ifval (COND, [IF-TRUE], [IF-FALSE]) 9855 Expands to IF-TRUE if COND is not empty, otherwise to IF-FALSE. 9856 This is shorthand for: 9857 m4_if([COND], [], [IF-FALSE], [IF-TRUE]) 9858 9859 -- Macro: m4_ifvaln (COND, [IF-TRUE], [IF-FALSE]) 9860 Similar to `m4_ifval', except guarantee that a newline is present 9861 after any non-empty expansion. Often followed by `dnl'. 9862 9863 -- Macro: m4_n (TEXT) 9864 Expand to TEXT, and add a newline if TEXT is not empty. Often 9865 followed by `dnl'. 9866 9867 9868File: autoconf.info, Node: Looping constructs, Next: Evaluation Macros, Prev: Conditional constructs, Up: Programming in M4sugar 9869 98708.3.5 Looping constructs 9871------------------------ 9872 9873The following macros are useful in implementing recursive algorithms in 9874M4, including loop operations. An M4 list is formed by quoting a list 9875of quoted elements; generally the lists are comma-separated, although 9876`m4_foreach_w' is whitespace-separated. For example, the list `[[a], 9877[b,c]]' contains two elements: `[a]' and `[b,c]'. It is common to see 9878lists with unquoted elements when those elements are not likely to be 9879macro names, as in `[fputc_unlocked, fgetc_unlocked]'. 9880 9881 Although not generally recommended, it is possible for quoted lists 9882to have side effects; all side effects are expanded only once, and 9883prior to visiting any list element. On the other hand, the fact that 9884unquoted macros are expanded exactly once means that macros without 9885side effects can be used to generate lists. For example, 9886 9887 m4_foreach([i], [[1], [2], [3]m4_errprintn([hi])], [i]) 9888 error-->hi 9889 =>123 9890 m4_define([list], [[1], [2], [3]]) 9891 => 9892 m4_foreach([i], [list], [i]) 9893 =>123 9894 9895 -- Macro: m4_argn (N, [ARG]...) 9896 Extracts argument N (larger than 0) from the remaining arguments. 9897 If there are too few arguments, the empty string is used. For any 9898 N besides 1, this is more efficient than the similar 9899 `m4_car(m4_shiftn([N], [], [ARG...]))'. 9900 9901 -- Macro: m4_car (ARG...) 9902 Expands to the quoted first ARG. Can be used with `m4_cdr' to 9903 recursively iterate through a list. Generally, when using quoted 9904 lists of quoted elements, `m4_car' should be called without any 9905 extra quotes. 9906 9907 -- Macro: m4_cdr (ARG...) 9908 Expands to a quoted list of all but the first ARG, or the empty 9909 string if there was only one argument. Generally, when using 9910 quoted lists of quoted elements, `m4_cdr' should be called without 9911 any extra quotes. 9912 9913 For example, this is a simple implementation of `m4_map'; note how 9914 each iteration checks for the end of recursion, then merely 9915 applies the first argument to the first element of the list, then 9916 repeats with the rest of the list. (The actual implementation in 9917 M4sugar is a bit more involved, to gain some speed and share code 9918 with `m4_map_sep', and also to avoid expanding side effects in 9919 `$2' twice). 9920 m4_define([m4_map], [m4_ifval([$2], 9921 [m4_apply([$1], m4_car($2))[]$0([$1], m4_cdr($2))])])dnl 9922 m4_map([ m4_eval], [[[1]], [[1+1]], [[10],[16]]]) 9923 => 1 2 a 9924 9925 -- Macro: m4_for (VAR, FIRST, LAST, [STEP], EXPRESSION) 9926 Loop over the numeric values between FIRST and LAST including 9927 bounds by increments of STEP. For each iteration, expand 9928 EXPRESSION with the numeric value assigned to VAR. If STEP is 9929 omitted, it defaults to `1' or `-1' depending on the order of the 9930 limits. If given, STEP has to match this order. The number of 9931 iterations is determined independently from definition of VAR; 9932 iteration cannot be short-circuited or lengthened by modifying VAR 9933 from within EXPRESSION. 9934 9935 -- Macro: m4_foreach (VAR, LIST, EXPRESSION) 9936 Loop over the comma-separated M4 list LIST, assigning each value 9937 to VAR, and expand EXPRESSION. The following example outputs two 9938 lines: 9939 9940 m4_foreach([myvar], [[foo], [bar, baz]], 9941 [echo myvar 9942 ])dnl 9943 =>echo foo 9944 =>echo bar, baz 9945 9946 Note that for some forms of EXPRESSION, it may be faster to use 9947 `m4_map_args'. 9948 9949 -- Macro: m4_foreach_w (VAR, LIST, EXPRESSION) 9950 Loop over the white-space-separated list LIST, assigning each value 9951 to VAR, and expand EXPRESSION. If VAR is only referenced once in 9952 EXPRESSION, it is more efficient to use `m4_map_args_w'. 9953 9954 The deprecated macro `AC_FOREACH' is an alias of `m4_foreach_w'. 9955 9956 -- Macro: m4_map (MACRO, LIST) 9957 -- Macro: m4_mapall (MACRO, LIST) 9958 -- Macro: m4_map_sep (MACRO, SEPARATOR, LIST) 9959 -- Macro: m4_mapall_sep (MACRO, SEPARATOR, LIST) 9960 Loop over the comma separated quoted list of argument descriptions 9961 in LIST, and invoke MACRO with the arguments. An argument 9962 description is in turn a comma-separated quoted list of quoted 9963 elements, suitable for `m4_apply'. The macros `m4_map' and 9964 `m4_map_sep' ignore empty argument descriptions, while `m4_mapall' 9965 and `m4_mapall_sep' invoke MACRO with no arguments. The macros 9966 `m4_map_sep' and `m4_mapall_sep' additionally expand SEPARATOR 9967 between invocations of MACRO. 9968 9969 Note that SEPARATOR is expanded, unlike in `m4_join'. When 9970 separating output with commas, this means that the map result can 9971 be used as a series of arguments, by using a single-quoted comma as 9972 SEPARATOR, or as a single string, by using a double-quoted comma. 9973 9974 m4_map([m4_count], []) 9975 => 9976 m4_map([ m4_count], [[], 9977 [[1]], 9978 [[1], [2]]]) 9979 => 1 2 9980 m4_mapall([ m4_count], [[], 9981 [[1]], 9982 [[1], [2]]]) 9983 => 0 1 2 9984 m4_map_sep([m4_eval], [,], [[[1+2]], 9985 [[10], [16]]]) 9986 =>3,a 9987 m4_map_sep([m4_echo], [,], [[[a]], [[b]]]) 9988 =>a,b 9989 m4_count(m4_map_sep([m4_echo], [,], [[[a]], [[b]]])) 9990 =>2 9991 m4_map_sep([m4_echo], [[,]], [[[a]], [[b]]]) 9992 =>a,b 9993 m4_count(m4_map_sep([m4_echo], [[,]], [[[a]], [[b]]])) 9994 =>1 9995 9996 -- Macro: m4_map_args (MACRO, ARG...) 9997 Repeatedly invoke MACRO with each successive ARG as its only 9998 argument. In the following example, three solutions are presented 9999 with the same expansion; the solution using `m4_map_args' is the 10000 most efficient. 10001 m4_define([active], [ACTIVE])dnl 10002 m4_foreach([var], [[plain], [active]], [ m4_echo(m4_defn([var]))]) 10003 => plain active 10004 m4_map([ m4_echo], [[[plain]], [[active]]]) 10005 => plain active 10006 m4_map_args([ m4_echo], [plain], [active]) 10007 => plain active 10008 10009 In cases where it is useful to operate on additional parameters 10010 besides the list elements, the macro `m4_curry' can be used in 10011 MACRO to supply the argument currying necessary to generate the 10012 desired argument list. In the following example, `list_add_n' is 10013 more efficient than `list_add_x'. On the other hand, using 10014 `m4_map_args_sep' can be even more efficient. 10015 10016 m4_define([list], [[1], [2], [3]])dnl 10017 m4_define([add], [m4_eval(([$1]) + ([$2]))])dnl 10018 dnl list_add_n(N, ARG...) 10019 dnl Output a list consisting of each ARG added to N 10020 m4_define([list_add_n], 10021 [m4_shift(m4_map_args([,m4_curry([add], [$1])], m4_shift($@)))])dnl 10022 list_add_n([1], list) 10023 =>2,3,4 10024 list_add_n([2], list) 10025 =>3,4,5 10026 m4_define([list_add_x], 10027 [m4_shift(m4_foreach([var], m4_dquote(m4_shift($@)), 10028 [,add([$1],m4_defn([var]))]))])dnl 10029 list_add_x([1], list) 10030 =>2,3,4 10031 10032 -- Macro: m4_map_args_pair (MACRO, [MACRO-END = `macro'], ARG...) 10033 For every pair of arguments ARG, invoke MACRO with two arguments. 10034 If there is an odd number of arguments, invoke MACRO-END, which 10035 defaults to MACRO, with the remaining argument. 10036 10037 m4_map_args_pair([, m4_reverse], [], [1], [2], [3]) 10038 =>, 2, 1, 3 10039 m4_map_args_pair([, m4_reverse], [, m4_dquote], [1], [2], [3]) 10040 =>, 2, 1, [3] 10041 m4_map_args_pair([, m4_reverse], [, m4_dquote], [1], [2], [3], [4]) 10042 =>, 2, 1, 4, 3 10043 10044 -- Macro: m4_map_args_sep ([PRE], [POST], [SEP], ARG...) 10045 Expand the sequence `PRE[ARG]POST' for each argument, additionally 10046 expanding SEP between arguments. One common use of this macro is 10047 constructing a macro call, where the opening and closing 10048 parentheses are split between PRE and POST; in particular, 10049 `m4_map_args([MACRO], [ARG])' is equivalent to 10050 `m4_map_args_sep([MACRO(], [)], [], [ARG])'. This macro provides 10051 the most efficient means for iterating over an arbitrary list of 10052 arguments, particularly when repeatedly constructing a macro call 10053 with more arguments than ARG. 10054 10055 -- Macro: m4_map_args_w (STRING, [PRE], [POST], [SEP]) 10056 Expand the sequence `PRE[word]POST' for each word in the 10057 whitespace-separated STRING, additionally expanding SEP between 10058 words. This macro provides the most efficient means for iterating 10059 over a whitespace-separated string. In particular, 10060 `m4_map_args_w([STRING], [ACTION(], [)])' is more efficient than 10061 `m4_foreach_w([var], [STRING], [ACTION(m4_defn([var]))])'. 10062 10063 -- Macro: m4_shiftn (COUNT, ...) 10064 -- Macro: m4_shift2 (...) 10065 -- Macro: m4_shift3 (...) 10066 `m4_shiftn' performs COUNT iterations of `m4_shift', along with 10067 validation that enough arguments were passed in to match the shift 10068 count, and that the count is positive. `m4_shift2' and 10069 `m4_shift3' are specializations of `m4_shiftn', introduced in 10070 Autoconf 2.62, and are more efficient for two and three shifts, 10071 respectively. 10072 10073 -- Macro: m4_stack_foreach (MACRO, ACTION) 10074 -- Macro: m4_stack_foreach_lifo (MACRO, ACTION) 10075 For each of the `m4_pushdef' definitions of MACRO, expand ACTION 10076 with the single argument of a definition of MACRO. 10077 `m4_stack_foreach' starts with the oldest definition, while 10078 `m4_stack_foreach_lifo' starts with the current definition. 10079 ACTION should not push or pop definitions of MACRO, nor is there 10080 any guarantee that the current definition of MACRO matches the 10081 argument that was passed to ACTION. The macro `m4_curry' can be 10082 used if ACTION needs more than one argument, although in that case 10083 it is more efficient to use M4_STACK_FOREACH_SEP. 10084 10085 Due to technical limitations, there are a few low-level m4sugar 10086 functions, such as `m4_pushdef', that cannot be used as the MACRO 10087 argument. 10088 10089 m4_pushdef([a], [1])m4_pushdef([a], [2])dnl 10090 m4_stack_foreach([a], [ m4_incr]) 10091 => 2 3 10092 m4_stack_foreach_lifo([a], [ m4_curry([m4_substr], [abcd])]) 10093 => cd bcd 10094 10095 -- Macro: m4_stack_foreach_sep (MACRO, [PRE], [POST], [SEP]) 10096 -- Macro: m4_stack_foreach_sep_lifo (MACRO, [PRE], [POST], [SEP]) 10097 Expand the sequence `PRE[definition]POST' for each `m4_pushdef' 10098 definition of MACRO, additionally expanding SEP between 10099 definitions. `m4_stack_foreach_sep' visits the oldest definition 10100 first, while `m4_stack_foreach_sep_lifo' visits the current 10101 definition first. This macro provides the most efficient means 10102 for iterating over a pushdef stack. In particular, 10103 `m4_stack_foreach([MACRO], [ACTION])' is short for 10104 `m4_stack_foreach_sep([MACRO], [ACTION(], [)])'. 10105 10106 10107File: autoconf.info, Node: Evaluation Macros, Next: Text processing Macros, Prev: Looping constructs, Up: Programming in M4sugar 10108 101098.3.6 Evaluation Macros 10110----------------------- 10111 10112The following macros give some control over the order of the evaluation 10113by adding or removing levels of quotes. 10114 10115 -- Macro: m4_apply (MACRO, LIST) 10116 Apply the elements of the quoted, comma-separated LIST as the 10117 arguments to MACRO. If LIST is empty, invoke MACRO without 10118 arguments. Note the difference between `m4_indir', which expects 10119 its first argument to be a macro name but can use names that are 10120 otherwise invalid, and `m4_apply', where MACRO can contain other 10121 text, but must end in a valid macro name. 10122 m4_apply([m4_count], []) 10123 =>0 10124 m4_apply([m4_count], [[]]) 10125 =>1 10126 m4_apply([m4_count], [[1], [2]]) 10127 =>2 10128 m4_apply([m4_join], [[|], [1], [2]]) 10129 =>1|2 10130 10131 -- Macro: m4_count (ARG, ...) 10132 This macro returns the decimal count of the number of arguments it 10133 was passed. 10134 10135 -- Macro: m4_curry (MACRO, ARG...) 10136 This macro performs argument currying. The expansion of this 10137 macro is another macro name that expects exactly one argument; 10138 that argument is then appended to the ARG list, and then MACRO is 10139 expanded with the resulting argument list. 10140 10141 m4_curry([m4_curry], [m4_reverse], [1])([2])([3]) 10142 =>3, 2, 1 10143 10144 Unfortunately, due to a limitation in M4 1.4.x, it is not possible 10145 to pass the definition of a builtin macro as the argument to the 10146 output of `m4_curry'; the empty string is used instead of the 10147 builtin token. This behavior is rectified by using M4 1.6 or 10148 newer. 10149 10150 -- Macro: m4_do (ARG, ...) 10151 This macro loops over its arguments and expands each ARG in 10152 sequence. Its main use is for readability; it allows the use of 10153 indentation and fewer `dnl' to result in the same expansion. This 10154 macro guarantees that no expansion will be concatenated with 10155 subsequent text; to achieve full concatenation, use 10156 `m4_unquote(m4_join([], ARG...))'. 10157 10158 m4_define([ab],[1])m4_define([bc],[2])m4_define([abc],[3])dnl 10159 m4_do([a],[b])c 10160 =>abc 10161 m4_unquote(m4_join([],[a],[b]))c 10162 =>3 10163 m4_define([a],[A])m4_define([b],[B])m4_define([c],[C])dnl 10164 m4_define([AB],[4])m4_define([BC],[5])m4_define([ABC],[6])dnl 10165 m4_do([a],[b])c 10166 =>ABC 10167 m4_unquote(m4_join([],[a],[b]))c 10168 =>3 10169 10170 -- Macro: m4_dquote (ARG, ...) 10171 Return the arguments as a quoted list of quoted arguments. 10172 Conveniently, if there is just one ARG, this effectively adds a 10173 level of quoting. 10174 10175 -- Macro: m4_dquote_elt (ARG, ...) 10176 Return the arguments as a series of double-quoted arguments. 10177 Whereas `m4_dquote' returns a single argument, `m4_dquote_elt' 10178 returns as many arguments as it was passed. 10179 10180 -- Macro: m4_echo (ARG, ...) 10181 Return the arguments, with the same level of quoting. Other than 10182 discarding whitespace after unquoted commas, this macro is a no-op. 10183 10184 -- Macro: m4_expand (ARG) 10185 Return the expansion of ARG as a quoted string. Whereas 10186 `m4_quote' is designed to collect expanded text into a single 10187 argument, `m4_expand' is designed to perform one level of expansion 10188 on quoted text. One distinction is in the treatment of whitespace 10189 following a comma in the original ARG. Any time multiple 10190 arguments are collected into one with `m4_quote', the M4 argument 10191 collection rules discard the whitespace. However, with 10192 `m4_expand', whitespace is preserved, even after the expansion of 10193 macros contained in ARG. Additionally, `m4_expand' is able to 10194 expand text that would involve an unterminated comment, whereas 10195 expanding that same text as the argument to `m4_quote' runs into 10196 difficulty in finding the end of the argument. Since manipulating 10197 diversions during argument collection is inherently unsafe, 10198 `m4_expand' issues an error if ARG attempts to change the current 10199 diversion (*note Diversion support::). 10200 10201 m4_define([active], [ACT, IVE])dnl 10202 m4_define([active2], [[ACT, IVE]])dnl 10203 m4_quote(active, active) 10204 =>ACT,IVE,ACT,IVE 10205 m4_expand([active, active]) 10206 =>ACT, IVE, ACT, IVE 10207 m4_quote(active2, active2) 10208 =>ACT, IVE,ACT, IVE 10209 m4_expand([active2, active2]) 10210 =>ACT, IVE, ACT, IVE 10211 m4_expand([# m4_echo]) 10212 =># m4_echo 10213 m4_quote(# m4_echo) 10214 ) 10215 =># m4_echo) 10216 => 10217 10218 Note that `m4_expand' cannot handle an ARG that expands to literal 10219 unbalanced quotes, but that quadrigraphs can be used when 10220 unbalanced output is necessary. Likewise, unbalanced parentheses 10221 should be supplied with double quoting or a quadrigraph. 10222 10223 m4_define([pattern], [[!@<:@]])dnl 10224 m4_define([bar], [BAR])dnl 10225 m4_expand([case $foo in 10226 m4_defn([pattern])@:}@ bar ;; 10227 *[)] blah ;; 10228 esac]) 10229 =>case $foo in 10230 => [![]) BAR ;; 10231 => *) blah ;; 10232 =>esac 10233 10234 -- Macro: m4_ignore (...) 10235 This macro was introduced in Autoconf 2.62. Expands to nothing, 10236 ignoring all of its arguments. By itself, this isn't very useful. 10237 However, it can be used to conditionally ignore an arbitrary 10238 number of arguments, by deciding which macro name to apply to a 10239 list of arguments. 10240 dnl foo outputs a message only if [debug] is defined. 10241 m4_define([foo], 10242 [m4_ifdef([debug],[AC_MSG_NOTICE],[m4_ignore])([debug message])]) 10243 10244 Note that for earlier versions of Autoconf, the macro `__gnu__' can 10245 serve the same purpose, although it is less readable. 10246 10247 -- Macro: m4_make_list (ARG, ...) 10248 This macro exists to aid debugging of M4sugar algorithms. Its net 10249 effect is similar to `m4_dquote'--it produces a quoted list of 10250 quoted arguments, for each ARG. The difference is that this 10251 version uses a comma-newline separator instead of just comma, to 10252 improve readability of the list; with the result that it is less 10253 efficient than `m4_dquote'. 10254 m4_define([zero],[0])m4_define([one],[1])m4_define([two],[2])dnl 10255 m4_dquote(zero, [one], [[two]]) 10256 =>[0],[one],[[two]] 10257 m4_make_list(zero, [one], [[two]]) 10258 =>[0], 10259 =>[one], 10260 =>[[two]] 10261 m4_foreach([number], m4_dquote(zero, [one], [[two]]), [ number]) 10262 => 0 1 two 10263 m4_foreach([number], m4_make_list(zero, [one], [[two]]), [ number]) 10264 => 0 1 two 10265 10266 -- Macro: m4_quote (ARG, ...) 10267 Return the arguments as a single entity, i.e., wrap them into a 10268 pair of quotes. This effectively collapses multiple arguments 10269 into one, although it loses whitespace after unquoted commas in 10270 the process. 10271 10272 -- Macro: m4_reverse (ARG, ...) 10273 Outputs each argument with the same level of quoting, but in 10274 reverse order, and with space following each comma for readability. 10275 10276 m4_define([active], [ACT,IVE]) 10277 => 10278 m4_reverse(active, [active]) 10279 =>active, IVE, ACT 10280 10281 -- Macro: m4_unquote (ARG, ...) 10282 This macro was introduced in Autoconf 2.62. Expand each argument, 10283 separated by commas. For a single ARG, this effectively removes a 10284 layer of quoting, and `m4_unquote([ARG])' is more efficient than 10285 the equivalent `m4_do([ARG])'. For multiple arguments, this 10286 results in an unquoted list of expansions. This is commonly used 10287 with `m4_split', in order to convert a single quoted list into a 10288 series of quoted elements. 10289 10290 The following example aims at emphasizing the difference between 10291several scenarios: not using these macros, using `m4_defn', using 10292`m4_quote', using `m4_dquote', and using `m4_expand'. 10293 10294 $ cat example.m4 10295 dnl Overquote, so that quotes are visible. 10296 m4_define([show], [$[]1 = [$1], $[]@ = [$@]]) 10297 m4_define([a], [A]) 10298 m4_define([mkargs], [1, 2[,] 3]) 10299 m4_define([arg1], [[$1]]) 10300 m4_divert([0])dnl 10301 show(a, b) 10302 show([a, b]) 10303 show(m4_quote(a, b)) 10304 show(m4_dquote(a, b)) 10305 show(m4_expand([a, b])) 10306 10307 arg1(mkargs) 10308 arg1([mkargs]) 10309 arg1(m4_defn([mkargs])) 10310 arg1(m4_quote(mkargs)) 10311 arg1(m4_dquote(mkargs)) 10312 arg1(m4_expand([mkargs])) 10313 $ autom4te -l m4sugar example.m4 10314 $1 = A, $@ = [A],[b] 10315 $1 = a, b, $@ = [a, b] 10316 $1 = A,b, $@ = [A,b] 10317 $1 = [A],[b], $@ = [[A],[b]] 10318 $1 = A, b, $@ = [A, b] 10319 10320 1 10321 mkargs 10322 1, 2[,] 3 10323 1,2, 3 10324 [1],[2, 3] 10325 1, 2, 3 10326 10327 10328File: autoconf.info, Node: Text processing Macros, Next: Number processing Macros, Prev: Evaluation Macros, Up: Programming in M4sugar 10329 103308.3.7 String manipulation in M4 10331------------------------------- 10332 10333The following macros may be used to manipulate strings in M4. Many of 10334the macros in this section intentionally result in quoted strings as 10335output, rather than subjecting the arguments to further expansions. As 10336a result, if you are manipulating text that contains active M4 10337characters, the arguments are passed with single quoting rather than 10338double. 10339 10340 -- Macro: m4_append (MACRO-NAME, STRING, [SEPARATOR]) 10341 -- Macro: m4_append_uniq (MACRO-NAME, STRING, [SEPARATOR] [IF-UNIQ], 10342 [IF-DUPLICATE]) 10343 Redefine MACRO-NAME to its former contents with SEPARATOR and 10344 STRING added at the end. If MACRO-NAME was undefined before (but 10345 not if it was defined but empty), then no SEPARATOR is added. As 10346 of Autoconf 2.62, neither STRING nor SEPARATOR are expanded during 10347 this macro; instead, they are expanded when MACRO-NAME is invoked. 10348 10349 `m4_append' can be used to grow strings, and `m4_append_uniq' to 10350 grow strings without duplicating substrings. Additionally, 10351 `m4_append_uniq' takes two optional parameters as of Autoconf 2.62; 10352 IF-UNIQ is expanded if STRING was appended, and IF-DUPLICATE is 10353 expanded if STRING was already present. Also, `m4_append_uniq' 10354 warns if SEPARATOR is not empty, but occurs within STRING, since 10355 that can lead to duplicates. 10356 10357 Note that `m4_append' can scale linearly in the length of the final 10358 string, depending on the quality of the underlying M4 10359 implementation, while `m4_append_uniq' has an inherent quadratic 10360 scaling factor. If an algorithm can tolerate duplicates in the 10361 final string, use the former for speed. If duplicates must be 10362 avoided, consider using `m4_set_add' instead (*note Set 10363 manipulation Macros::). 10364 10365 m4_define([active], [ACTIVE])dnl 10366 m4_append([sentence], [This is an])dnl 10367 m4_append([sentence], [ active ])dnl 10368 m4_append([sentence], [symbol.])dnl 10369 sentence 10370 =>This is an ACTIVE symbol. 10371 m4_undefine([active])dnl 10372 =>This is an active symbol. 10373 m4_append_uniq([list], [one], [, ], [new], [existing]) 10374 =>new 10375 m4_append_uniq([list], [one], [, ], [new], [existing]) 10376 =>existing 10377 m4_append_uniq([list], [two], [, ], [new], [existing]) 10378 =>new 10379 m4_append_uniq([list], [three], [, ], [new], [existing]) 10380 =>new 10381 m4_append_uniq([list], [two], [, ], [new], [existing]) 10382 =>existing 10383 list 10384 =>one, two, three 10385 m4_dquote(list) 10386 =>[one],[two],[three] 10387 m4_append([list2], [one], [[, ]])dnl 10388 m4_append_uniq([list2], [two], [[, ]])dnl 10389 m4_append([list2], [three], [[, ]])dnl 10390 list2 10391 =>one, two, three 10392 m4_dquote(list2) 10393 =>[one, two, three] 10394 10395 -- Macro: m4_append_uniq_w (MACRO-NAME, STRINGS) 10396 This macro was introduced in Autoconf 2.62. It is similar to 10397 `m4_append_uniq', but treats STRINGS as a whitespace separated 10398 list of words to append, and only appends unique words. 10399 MACRO-NAME is updated with a single space between new words. 10400 m4_append_uniq_w([numbers], [1 1 2])dnl 10401 m4_append_uniq_w([numbers], [ 2 3 ])dnl 10402 numbers 10403 =>1 2 3 10404 10405 -- Macro: m4_chomp (STRING) 10406 -- Macro: m4_chomp_all (STRING) 10407 Output STRING in quotes, but without a trailing newline. The 10408 macro `m4_chomp' is slightly faster, and removes at most one 10409 newline; the macro `m4_chomp_all' removes all consecutive trailing 10410 newlines. Unlike `m4_flatten', embedded newlines are left intact, 10411 and backslash does not influence the result. 10412 10413 -- Macro: m4_combine ([SEPARATOR], PREFIX-LIST, [INFIX], SUFFIX-1, 10414 [SUFFIX-2], ...) 10415 This macro produces a quoted string containing the pairwise 10416 combination of every element of the quoted, comma-separated 10417 PREFIX-LIST, and every element from the SUFFIX arguments. Each 10418 pairwise combination is joined with INFIX in the middle, and 10419 successive pairs are joined by SEPARATOR. No expansion occurs on 10420 any of the arguments. No output occurs if either the PREFIX or 10421 SUFFIX list is empty, but the lists can contain empty elements. 10422 m4_define([a], [oops])dnl 10423 m4_combine([, ], [[a], [b], [c]], [-], [1], [2], [3]) 10424 =>a-1, a-2, a-3, b-1, b-2, b-3, c-1, c-2, c-3 10425 m4_combine([, ], [[a], [b]], [-]) 10426 => 10427 m4_combine([, ], [[a], [b]], [-], []) 10428 =>a-, b- 10429 m4_combine([, ], [], [-], [1], [2]) 10430 => 10431 m4_combine([, ], [[]], [-], [1], [2]) 10432 =>-1, -2 10433 10434 -- Macro: m4_escape (STRING) 10435 Convert all instances of `[', `]', `#', and `$' within STRING into 10436 their respective quadrigraphs. The result is still a quoted 10437 string. 10438 10439 -- Macro: m4_flatten (STRING) 10440 Flatten STRING into a single line. Delete all backslash-newline 10441 pairs, and replace all remaining newlines with a space. The 10442 result is still a quoted string. 10443 10444 -- Macro: m4_join ([SEPARATOR], ARGS...) 10445 -- Macro: m4_joinall ([SEPARATOR], ARGS...) 10446 Concatenate each ARG, separated by SEPARATOR. `joinall' uses 10447 every argument, while `join' omits empty arguments so that there 10448 are no back-to-back separators in the output. The result is a 10449 quoted string. 10450 m4_define([active], [ACTIVE])dnl 10451 m4_join([|], [one], [], [active], [two]) 10452 =>one|active|two 10453 m4_joinall([|], [one], [], [active], [two]) 10454 =>one||active|two 10455 10456 Note that if all you intend to do is join ARGS with commas between 10457 them, to form a quoted list suitable for `m4_foreach', it is more 10458 efficient to use `m4_dquote'. 10459 10460 -- Macro: m4_newline ([TEXT]) 10461 This macro was introduced in Autoconf 2.62, and expands to a 10462 newline, followed by any TEXT. It is primarily useful for 10463 maintaining macro formatting, and ensuring that M4 does not 10464 discard leading whitespace during argument collection. 10465 10466 -- Macro: m4_normalize (STRING) 10467 Remove leading and trailing spaces and tabs, sequences of 10468 backslash-then-newline, and replace multiple spaces, tabs, and 10469 newlines with a single space. This is a combination of 10470 `m4_flatten' and `m4_strip'. To determine if STRING consists only 10471 of bytes that would be removed by `m4_normalize', you can use 10472 `m4_ifblank'. 10473 10474 -- Macro: m4_re_escape (STRING) 10475 Backslash-escape all characters in STRING that are active in 10476 regexps. 10477 10478 -- Macro: m4_split (STRING, [REGEXP = `[\t ]+']) 10479 Split STRING into an M4 list of elements quoted by `[' and `]', 10480 while keeping white space at the beginning and at the end. If 10481 REGEXP is given, use it instead of `[\t ]+' for splitting. If 10482 STRING is empty, the result is an empty list. 10483 10484 -- Macro: m4_strip (STRING) 10485 Strip whitespace from STRING. Sequences of spaces and tabs are 10486 reduced to a single space, then leading and trailing spaces are 10487 removed. The result is still a quoted string. Note that this 10488 does not interfere with newlines; if you want newlines stripped as 10489 well, consider `m4_flatten', or do it all at once with 10490 `m4_normalize'. To quickly test if STRING has only whitespace, 10491 use `m4_ifblank'. 10492 10493 -- Macro: m4_text_box (MESSAGE, [FRAME = `-']) 10494 Add a text box around MESSAGE, using FRAME as the border character 10495 above and below the message. The FRAME argument must be a single 10496 byte, and does not support quadrigraphs. The frame correctly 10497 accounts for the subsequent expansion of MESSAGE. For example: 10498 m4_define([macro], [abc])dnl 10499 m4_text_box([macro]) 10500 =>## --- ## 10501 =>## abc ## 10502 =>## --- ## 10503 10504 The MESSAGE must contain balanced quotes and parentheses, although 10505 quadrigraphs can be used to work around this. 10506 10507 -- Macro: m4_text_wrap (STRING, [PREFIX], [PREFIX1 = `PREFIX'], [WIDTH 10508 = `79']) 10509 Break STRING into a series of whitespace-separated words, then 10510 output those words separated by spaces, and wrapping lines any 10511 time the output would exceed WIDTH columns. If given, PREFIX1 10512 begins the first line, and PREFIX begins all wrapped lines. If 10513 PREFIX1 is longer than PREFIX, then the first line consists of 10514 just PREFIX1. If PREFIX is longer than PREFIX1, padding is 10515 inserted so that the first word of STRING begins at the same 10516 indentation as all wrapped lines. Note that using literal tab 10517 characters in any of the arguments will interfere with the 10518 calculation of width. No expansions occur on PREFIX, PREFIX1, or 10519 the words of STRING, although quadrigraphs are recognized. 10520 10521 For some examples: 10522 m4_text_wrap([Short string */], [ ], [/* ], [20]) 10523 =>/* Short string */ 10524 m4_text_wrap([Much longer string */], [ ], [/* ], [20]) 10525 =>/* Much longer 10526 => string */ 10527 m4_text_wrap([Short doc.], [ ], [ --short ], [30]) 10528 => --short Short doc. 10529 m4_text_wrap([Short doc.], [ ], [ --too-wide ], [30]) 10530 => --too-wide 10531 => Short doc. 10532 m4_text_wrap([Super long documentation.], [ ], 10533 [ --too-wide ], 30) 10534 => --too-wide 10535 => Super long 10536 => documentation. 10537 10538 -- Macro: m4_tolower (STRING) 10539 -- Macro: m4_toupper (STRING) 10540 Return STRING with letters converted to upper or lower case, 10541 respectively. 10542 10543 10544File: autoconf.info, Node: Number processing Macros, Next: Set manipulation Macros, Prev: Text processing Macros, Up: Programming in M4sugar 10545 105468.3.8 Arithmetic computation in M4 10547---------------------------------- 10548 10549The following macros facilitate integer arithmetic operations. Where a 10550parameter is documented as taking an arithmetic expression, you can use 10551anything that can be parsed by `m4_eval'. 10552 10553 -- Macro: m4_cmp (EXPR-1, EXPR-2) 10554 Compare the arithmetic expressions EXPR-1 and EXPR-2, and expand 10555 to `-1' if EXPR-1 is smaller, `0' if they are equal, and `1' if 10556 EXPR-1 is larger. 10557 10558 -- Macro: m4_list_cmp (LIST-1, LIST-2) 10559 Compare the two M4 lists consisting of comma-separated arithmetic 10560 expressions, left to right. Expand to `-1' for the first element 10561 pairing where the value from LIST-1 is smaller, `1' where the 10562 value from LIST-2 is smaller, or `0' if both lists have the same 10563 values. If one list is shorter than the other, the remaining 10564 elements of the longer list are compared against zero. 10565 m4_list_cmp([1, 0], [1]) 10566 =>0 10567 m4_list_cmp([1, [1 * 0]], [1, 0]) 10568 =>0 10569 m4_list_cmp([1, 2], [1, 0]) 10570 =>1 10571 m4_list_cmp([1, [1+1], 3],[1, 2]) 10572 =>1 10573 m4_list_cmp([1, 2, -3], [1, 2]) 10574 =>-1 10575 m4_list_cmp([1, 0], [1, 2]) 10576 =>-1 10577 m4_list_cmp([1], [1, 2]) 10578 =>-1 10579 10580 -- Macro: m4_max (ARG, ...) 10581 This macro was introduced in Autoconf 2.62. Expand to the decimal 10582 value of the maximum arithmetic expression among all the arguments. 10583 10584 -- Macro: m4_min (ARG, ...) 10585 This macro was introduced in Autoconf 2.62. Expand to the decimal 10586 value of the minimum arithmetic expression among all the arguments. 10587 10588 -- Macro: m4_sign (EXPR) 10589 Expand to `-1' if the arithmetic expression EXPR is negative, `1' 10590 if it is positive, and `0' if it is zero. 10591 10592 -- Macro: m4_version_compare (VERSION-1, VERSION-2) 10593 This macro was introduced in Autoconf 2.53, but had a number of 10594 usability limitations that were not lifted until Autoconf 2.62. 10595 Compare the version strings VERSION-1 and VERSION-2, and expand to 10596 `-1' if VERSION-1 is smaller, `0' if they are the same, or `1' 10597 VERSION-2 is smaller. Version strings must be a list of elements 10598 separated by `.', `,' or `-', where each element is a number along 10599 with optional case-insensitive letters designating beta releases. 10600 The comparison stops at the leftmost element that contains a 10601 difference, although a 0 element compares equal to a missing 10602 element. 10603 10604 It is permissible to include commit identifiers in VERSION, such 10605 as an abbreviated SHA1 of the commit, provided there is still a 10606 monotonically increasing prefix to allow for accurate version-based 10607 comparisons. For example, this paragraph was written when the 10608 development snapshot of autoconf claimed to be at version 10609 `2.61a-248-dc51', or 248 commits after the 2.61a release, with an 10610 abbreviated commit identification of `dc51'. 10611 10612 m4_version_compare([1.1], [2.0]) 10613 =>-1 10614 m4_version_compare([2.0b], [2.0a]) 10615 =>1 10616 m4_version_compare([1.1.1], [1.1.1a]) 10617 =>-1 10618 m4_version_compare([1.2], [1.1.1a]) 10619 =>1 10620 m4_version_compare([1.0], [1]) 10621 =>0 10622 m4_version_compare([1.1pre], [1.1PRE]) 10623 =>0 10624 m4_version_compare([1.1a], [1,10]) 10625 =>-1 10626 m4_version_compare([2.61a], [2.61a-248-dc51]) 10627 =>-1 10628 m4_version_compare([2.61b], [2.61a-248-dc51]) 10629 =>1 10630 10631 -- Macro: m4_version_prereq (VERSION, [IF-NEW-ENOUGH], [IF-OLD = 10632 `m4_fatal']) 10633 Compares VERSION against the version of Autoconf currently 10634 running. If the running version is at VERSION or newer, expand 10635 IF-NEW-ENOUGH, but if VERSION is larger than the version currently 10636 executing, expand IF-OLD, which defaults to printing an error 10637 message and exiting m4sugar with status 63. When given only one 10638 argument, this behaves like `AC_PREREQ' (*note Versioning::). 10639 Remember that the autoconf philosophy favors feature checks over 10640 version checks. 10641 10642 10643File: autoconf.info, Node: Set manipulation Macros, Next: Forbidden Patterns, Prev: Number processing Macros, Up: Programming in M4sugar 10644 106458.3.9 Set manipulation in M4 10646---------------------------- 10647 10648Sometimes, it is necessary to track a set of data, where the order does 10649not matter and where there are no duplicates in the set. The following 10650macros facilitate set manipulations. Each set is an opaque object, 10651which can only be accessed via these basic operations. The underlying 10652implementation guarantees linear scaling for set creation, which is more 10653efficient than using the quadratic `m4_append_uniq'. Both set names 10654and values can be arbitrary strings, except for unbalanced quotes. 10655This implementation ties up memory for removed elements until the next 10656operation that must traverse all the elements of a set; and although 10657that may slow down some operations until the memory for removed elements 10658is pruned, it still guarantees linear performance. 10659 10660 -- Macro: m4_set_add (SET, VALUE, [IF-UNIQ], [IF-DUP]) 10661 Adds the string VALUE as a member of set SET. Expand IF-UNIQ if 10662 the element was added, or IF-DUP if it was previously in the set. 10663 Operates in amortized constant time, so that set creation scales 10664 linearly. 10665 10666 -- Macro: m4_set_add_all (SET, VALUE...) 10667 Adds each VALUE to the set SET. This is slightly more efficient 10668 than repeatedly invoking `m4_set_add'. 10669 10670 -- Macro: m4_set_contains (SET, VALUE, [IF-PRESENT], [IF-ABSENT]) 10671 Expands IF-PRESENT if the string VALUE is a member of SET, 10672 otherwise IF-ABSENT. 10673 10674 m4_set_contains([a], [1], [yes], [no]) 10675 =>no 10676 m4_set_add([a], [1], [added], [dup]) 10677 =>added 10678 m4_set_add([a], [1], [added], [dup]) 10679 =>dup 10680 m4_set_contains([a], [1], [yes], [no]) 10681 =>yes 10682 m4_set_remove([a], [1], [removed], [missing]) 10683 =>removed 10684 m4_set_contains([a], [1], [yes], [no]) 10685 =>no 10686 m4_set_remove([a], [1], [removed], [missing]) 10687 =>missing 10688 10689 -- Macro: m4_set_contents (SET, [SEP]) 10690 -- Macro: m4_set_dump (SET, [SEP]) 10691 Expands to a single string consisting of all the members of the set 10692 SET, each separated by SEP, which is not expanded. 10693 `m4_set_contents' leaves the elements in SET but reclaims any 10694 memory occupied by removed elements, while `m4_set_dump' is a 10695 faster one-shot action that also deletes the set. No provision is 10696 made for disambiguating members that contain a non-empty SEP as a 10697 substring; use `m4_set_empty' to distinguish between an empty set 10698 and the set containing only the empty string. The order of the 10699 output is unspecified; in the current implementation, part of the 10700 speed of `m4_set_dump' results from using a different output order 10701 than `m4_set_contents'. These macros scale linearly in the size 10702 of the set before memory pruning, and `m4_set_contents([SET], 10703 [SEP])' is faster than `m4_joinall([SEP]m4_set_listc([SET]))'. 10704 10705 m4_set_add_all([a], [1], [2], [3]) 10706 => 10707 m4_set_contents([a], [-]) 10708 =>1-2-3 10709 m4_joinall([-]m4_set_listc([a])) 10710 =>1-2-3 10711 m4_set_dump([a], [-]) 10712 =>3-2-1 10713 m4_set_contents([a]) 10714 => 10715 m4_set_add([a], []) 10716 => 10717 m4_set_contents([a], [-]) 10718 => 10719 10720 -- Macro: m4_set_delete (SET) 10721 Delete all elements and memory associated with SET. This is 10722 linear in the set size, and faster than removing one element at a 10723 time. 10724 10725 -- Macro: m4_set_difference (SETA, SETB) 10726 -- Macro: m4_set_intersection (SETA, SETB) 10727 -- Macro: m4_set_union (SETA, SETB) 10728 Compute the relation between SETA and SETB, and output the result 10729 as a list of quoted arguments without duplicates and with a 10730 leading comma. Set difference selects the elements in SETA but 10731 not SETB, intersection selects only elements in both sets, and 10732 union selects elements in either set. These actions are linear in 10733 the sum of the set sizes. The leading comma is necessary to 10734 distinguish between no elements and the empty string as the only 10735 element. 10736 10737 m4_set_add_all([a], [1], [2], [3]) 10738 => 10739 m4_set_add_all([b], [3], [], [4]) 10740 => 10741 m4_set_difference([a], [b]) 10742 =>,1,2 10743 m4_set_difference([b], [a]) 10744 =>,,4 10745 m4_set_intersection([a], [b]) 10746 =>,3 10747 m4_set_union([a], [b]) 10748 =>,1,2,3,,4 10749 10750 -- Macro: m4_set_empty (SET, [IF-EMPTY], [IF-ELEMENTS]) 10751 Expand IF-EMPTY if the set SET has no elements, otherwise expand 10752 IF-ELEMENTS. This macro operates in constant time. Using this 10753 macro can help disambiguate output from `m4_set_contents' or 10754 `m4_set_list'. 10755 10756 -- Macro: m4_set_foreach (SET, VARIABLE, ACTION) 10757 For each element in the set SET, expand ACTION with the macro 10758 VARIABLE defined as the set element. Behavior is unspecified if 10759 ACTION recursively lists the contents of SET (although listing 10760 other sets is acceptable), or if it modifies the set in any way 10761 other than removing the element currently contained in VARIABLE. 10762 This macro is faster than the corresponding `m4_foreach([VARIABLE], 10763 m4_indir([m4_dquote]m4_set_listc([SET])), [ACTION])', although 10764 `m4_set_map' might be faster still. 10765 10766 m4_set_add_all([a]m4_for([i], [1], [5], [], [,i])) 10767 => 10768 m4_set_contents([a]) 10769 =>12345 10770 m4_set_foreach([a], [i], 10771 [m4_if(m4_eval(i&1), [0], [m4_set_remove([a], i, [i])])]) 10772 =>24 10773 m4_set_contents([a]) 10774 =>135 10775 10776 -- Macro: m4_set_list (SET) 10777 -- Macro: m4_set_listc (SET) 10778 Produce a list of arguments, where each argument is a quoted 10779 element from the set SET. The variant `m4_set_listc' is 10780 unambiguous, by adding a leading comma if there are any set 10781 elements, whereas the variant `m4_set_list' cannot distinguish 10782 between an empty set and a set containing only the empty string. 10783 These can be directly used in macros that take multiple arguments, 10784 such as `m4_join' or `m4_set_add_all', or wrapped by `m4_dquote' 10785 for macros that take a quoted list, such as `m4_map' or 10786 `m4_foreach'. Any memory occupied by removed elements is 10787 reclaimed during these macros. 10788 10789 m4_set_add_all([a], [1], [2], [3]) 10790 => 10791 m4_set_list([a]) 10792 =>1,2,3 10793 m4_set_list([b]) 10794 => 10795 m4_set_listc([b]) 10796 => 10797 m4_count(m4_set_list([b])) 10798 =>1 10799 m4_set_empty([b], [0], [m4_count(m4_set_list([b]))]) 10800 =>0 10801 m4_set_add([b], []) 10802 => 10803 m4_set_list([b]) 10804 => 10805 m4_set_listc([b]) 10806 =>, 10807 m4_count(m4_set_list([b])) 10808 =>1 10809 m4_set_empty([b], [0], [m4_count(m4_set_list([b]))]) 10810 =>1 10811 10812 -- Macro: m4_set_map (SET, ACTION) 10813 For each element in the set SET, expand ACTION with a single 10814 argument of the set element. Behavior is unspecified if ACTION 10815 recursively lists the contents of SET (although listing other sets 10816 is acceptable), or if it modifies the set in any way other than 10817 removing the element passed as an argument. This macro is faster 10818 than either corresponding counterpart of 10819 `m4_map_args([ACTION]m4_set_listc([SET]))' or 10820 `m4_set_foreach([SET], [var], [ACTION(m4_defn([var]))])'. It is 10821 possible to use `m4_curry' if more than one argument is needed for 10822 ACTION, although it is more efficient to use `m4_set_map_sep' in 10823 that case. 10824 10825 -- Macro: m4_set_map_sep (SET, [PRE], [POST], [SEP]) 10826 For each element in the set SET, expand `PRE[element]POST', 10827 additionally expanding SEP between elements. Behavior is 10828 unspecified if the expansion recursively lists the contents of SET 10829 (although listing other sets is acceptable), or if it modifies the 10830 set in any way other than removing the element visited by the 10831 expansion. This macro provides the most efficient means for 10832 non-destructively visiting the elements of a set; in particular, 10833 `m4_set_map([SET], [ACTION])' is equivalent to 10834 `m4_set_map_sep([SET], [ACTION(], [)])'. 10835 10836 -- Macro: m4_set_remove (SET, VALUE, [IF-PRESENT], [IF-ABSENT]) 10837 If VALUE is an element in the set SET, then remove it and expand 10838 IF-PRESENT. Otherwise expand IF-ABSENT. This macro operates in 10839 constant time so that multiple removals will scale linearly rather 10840 than quadratically; but when used outside of `m4_set_foreach' or 10841 `m4_set_map', it leaves memory occupied until the set is later 10842 compacted by `m4_set_contents' or `m4_set_list'. Several other 10843 set operations are then less efficient between the time of element 10844 removal and subsequent memory compaction, but still maintain their 10845 guaranteed scaling performance. 10846 10847 -- Macro: m4_set_size (SET) 10848 Expand to the size of the set SET. This implementation operates 10849 in constant time, and is thus more efficient than 10850 `m4_eval(m4_count(m4_set_listc([set])) - 1)'. 10851 10852 10853File: autoconf.info, Node: Forbidden Patterns, Prev: Set manipulation Macros, Up: Programming in M4sugar 10854 108558.3.10 Forbidden Patterns 10856------------------------- 10857 10858M4sugar provides a means to define suspicious patterns, patterns 10859describing tokens which should not be found in the output. For 10860instance, if an Autoconf `configure' script includes tokens such as 10861`AC_DEFINE', or `dnl', then most probably something went wrong 10862(typically a macro was not evaluated because of overquotation). 10863 10864 M4sugar forbids all the tokens matching `^_?m4_' and `^dnl$'. 10865Additional layers, such as M4sh and Autoconf, add additional forbidden 10866patterns to the list. 10867 10868 -- Macro: m4_pattern_forbid (PATTERN) 10869 Declare that no token matching PATTERN must be found in the output. 10870 Comments are not checked; this can be a problem if, for instance, 10871 you have some macro left unexpanded after an `#include'. No 10872 consensus is currently found in the Autoconf community, as some 10873 people consider it should be valid to name macros in comments 10874 (which doesn't make sense to the authors of this documentation: 10875 input, such as macros, should be documented by `dnl' comments; 10876 reserving `#'-comments to document the output). 10877 10878 Of course, you might encounter exceptions to these generic rules, for 10879instance you might have to refer to `$m4_flags'. 10880 10881 -- Macro: m4_pattern_allow (PATTERN) 10882 Any token matching PATTERN is allowed, including if it matches an 10883 `m4_pattern_forbid' pattern. 10884 10885 10886File: autoconf.info, Node: Debugging via autom4te, Prev: Programming in M4sugar, Up: Programming in M4 10887 108888.4 Debugging via autom4te 10889========================== 10890 10891At times, it is desirable to see what was happening inside m4, to see 10892why output was not matching expectations. However, post-processing done 10893by `autom4te' means that directly using the m4 builtin `m4_traceon' is 10894likely to interfere with operation. Also, frequent diversion changes 10895and the concept of forbidden tokens make it difficult to use `m4_defn' 10896to generate inline comments in the final output. 10897 10898 There are a couple of tools to help with this. One is the use of the 10899`--trace' option provided by `autom4te' (as well as each of the 10900programs that wrap `autom4te', such as `autoconf'), in order to inspect 10901when a macro is called and with which arguments. For example, when 10902this paragraph was written, the autoconf version could be found by: 10903 10904 $ autoconf --trace=AC_INIT 10905 configure.ac:23:AC_INIT:GNU Autoconf:2.63b.95-3963:bug-autoconf@gnu.org 10906 $ autoconf --trace='AC_INIT:version is $2' 10907 version is 2.63b.95-3963 10908 10909 Another trick is to print out the expansion of various m4 10910expressions to standard error or to an independent file, with no 10911further m4 expansion, and without interfering with diversion changes or 10912the post-processing done to standard output. `m4_errprintn' shows a 10913given expression on standard error. For example, if you want to see 10914the expansion of an autoconf primitive or of one of your autoconf 10915macros, you can do it like this: 10916 10917 $ cat <<\EOF > configure.ac 10918 AC_INIT 10919 m4_errprintn([The definition of AC_DEFINE_UNQUOTED:]) 10920 m4_errprintn(m4_defn([AC_DEFINE_UNQUOTED])) 10921 AC_OUTPUT 10922 EOF 10923 $ autoconf 10924 error-->The definition of AC_DEFINE_UNQUOTED: 10925 error-->_AC_DEFINE_Q([], $@) 10926 10927 10928File: autoconf.info, Node: Programming in M4sh, Next: Writing Autoconf Macros, Prev: Programming in M4, Up: Top 10929 109309 Programming in M4sh 10931********************* 10932 10933M4sh, pronounced "mash", is aiming at producing portable Bourne shell 10934scripts. This name was coined by Lars J. Aas, who notes that, 10935according to the Webster's Revised Unabridged Dictionary (1913): 10936 10937 Mash \Mash\, n. [Akin to G. meisch, maisch, meische, maische, 10938 mash, wash, and prob. to AS. miscian to mix. See "Mix".] 10939 10940 1. A mass of mixed ingredients reduced to a soft pulpy state by 10941 beating or pressure... 10942 10943 2. A mixture of meal or bran and water fed to animals. 10944 10945 3. A mess; trouble. [Obs.] -Beau. & Fl. 10946 10947 M4sh reserves the M4 macro namespace `^_AS_' for internal use, and 10948the namespace `^AS_' for M4sh macros. It also reserves the shell and 10949environment variable namespace `^as_', and the here-document delimiter 10950namespace `^_AS[A-Z]' in the output file. You should not define your 10951own macros or output shell code that conflicts with these namespaces. 10952 10953* Menu: 10954 10955* Common Shell Constructs:: Portability layer for common shell constructs 10956* Polymorphic Variables:: Support for indirect variable names 10957* Initialization Macros:: Macros to establish a sane shell environment 10958* File Descriptor Macros:: File descriptor macros for input and output 10959 10960 10961File: autoconf.info, Node: Common Shell Constructs, Next: Polymorphic Variables, Up: Programming in M4sh 10962 109639.1 Common Shell Constructs 10964=========================== 10965 10966M4sh provides portable alternatives for some common shell constructs 10967that unfortunately are not portable in practice. 10968 10969 -- Macro: AS_BOX (TEXT, [CHAR = `-']) 10970 Expand into shell code that will output TEXT surrounded by a box 10971 with CHAR in the top and bottom border. TEXT should not contain a 10972 newline, but may contain shell expansions valid for unquoted 10973 here-documents. CHAR defaults to `-', but can be any character 10974 except `/', `'', `"', `\', `&', or ``'. This is useful for 10975 outputting a comment box into log files to separate distinct 10976 phases of script operation. 10977 10978 -- Macro: AS_CASE (WORD, [PATTERN1], [IF-MATCHED1], ..., [DEFAULT]) 10979 Expand into a shell `case' statement, where WORD is matched 10980 against one or more patterns. IF-MATCHED is run if the 10981 corresponding pattern matched WORD, else DEFAULT is run. Avoids 10982 several portability issues (*note Limitations of Shell Builtins: 10983 case.). 10984 10985 -- Macro: AS_DIRNAME (FILE-NAME) 10986 Output the directory portion of FILE-NAME. For example, if 10987 `$file' is `/one/two/three', the command 10988 `dir=`AS_DIRNAME(["$file"])`' sets `dir' to `/one/two'. 10989 10990 This interface may be improved in the future to avoid forks and 10991 losing trailing newlines. 10992 10993 -- Macro: AS_ECHO (WORD) 10994 Emits WORD to the standard output, followed by a newline. WORD 10995 must be a single shell word (typically a quoted string). The 10996 bytes of WORD are output as-is, even if it starts with "-" or 10997 contains "\". Redirections can be placed outside the macro 10998 invocation. This is much more portable than using `echo' (*note 10999 Limitations of Shell Builtins: echo.). 11000 11001 -- Macro: AS_ECHO_N (WORD) 11002 Emits WORD to the standard output, without a following newline. 11003 WORD must be a single shell word (typically a quoted string) and, 11004 for portability, should not include more than one newline. The 11005 bytes of WORD are output as-is, even if it starts with "-" or 11006 contains "\". Redirections can be placed outside the macro 11007 invocation. 11008 11009 -- Macro: AS_ESCAPE (STRING, [CHARS = ``\"$']) 11010 Expands to STRING, with any characters in CHARS escaped with a 11011 backslash (`\'). CHARS should be at most four bytes long, and 11012 only contain characters from the set ``\"$'; however, characters 11013 may be safely listed more than once in CHARS for the sake of 11014 syntax highlighting editors. The current implementation expands 11015 STRING after adding escapes; if STRING contains macro calls that 11016 in turn expand to text needing shell quoting, you can use 11017 `AS_ESCAPE(m4_dquote(m4_expand([string])))'. 11018 11019 The default for CHARS (`\"$`') is the set of characters needing 11020 escapes when STRING will be used literally within double quotes. 11021 One common variant is the set of characters to protect when STRING 11022 will be used literally within back-ticks or an unquoted 11023 here-document (`\$`'). Another common variant is `""', which can 11024 be used to form a double-quoted string containing the same 11025 expansions that would have occurred if STRING were expanded in an 11026 unquoted here-document; however, when using this variant, care 11027 must be taken that STRING does not use double quotes within 11028 complex variable expansions (such as `${foo-`echo "hi"`}') that 11029 would be broken with improper escapes. 11030 11031 This macro is often used with `AS_ECHO'. For an example, observe 11032 the output generated by the shell code generated from this snippet: 11033 11034 foo=bar 11035 AS_ECHO(["AS_ESCAPE(["$foo" = ])AS_ESCAPE(["$foo"], [""])"]) 11036 =>"$foo" = "bar" 11037 m4_define([macro], [a, [\b]]) 11038 AS_ECHO(["AS_ESCAPE([[macro]])"]) 11039 =>macro 11040 AS_ECHO(["AS_ESCAPE([macro])"]) 11041 =>a, b 11042 AS_ECHO(["AS_ESCAPE(m4_dquote(m4_expand([macro])))"]) 11043 =>a, \b 11044 11045 To escape a string that will be placed within single quotes, use: 11046 11047 m4_bpatsubst([[STRING]], ['], ['\\'']) 11048 11049 -- Macro: AS_EXECUTABLE_P (FILE) 11050 Emit code to probe whether FILE is a regular file with executable 11051 permissions (and not a directory with search permissions). The 11052 caller is responsible for quoting FILE. 11053 11054 -- Macro: AS_EXIT ([STATUS = `$?']) 11055 Emit code to exit the shell with STATUS, defaulting to `$?'. This 11056 macro works around shells that see the exit status of the command 11057 prior to `exit' inside a `trap 0' handler (*note Limitations of 11058 Shell Builtins: trap.). 11059 11060 -- Macro: AS_IF (TEST1, [RUN-IF-TRUE1], ..., [RUN-IF-FALSE]) 11061 Run shell code TEST1. If TEST1 exits with a zero status then run 11062 shell code RUN-IF-TRUE1, else examine further tests. If no test 11063 exits with a zero status, run shell code RUN-IF-FALSE, with 11064 simplifications if either RUN-IF-TRUE1 or RUN-IF-FALSE is empty. 11065 For example, 11066 11067 AS_IF([test "x$foo" = xyes], [HANDLE_FOO([yes])], 11068 [test "x$foo" != xno], [HANDLE_FOO([maybe])], 11069 [echo foo not specified]) 11070 11071 ensures any required macros of `HANDLE_FOO' are expanded before 11072 the first test. 11073 11074 -- Macro: AS_MKDIR_P (FILE-NAME) 11075 Make the directory FILE-NAME, including intervening directories as 11076 necessary. This is equivalent to `mkdir -p -- FILE-NAME', except 11077 that it is portable to older versions of `mkdir' that lack support 11078 for the `-p' option or for the `--' delimiter (*note Limitations 11079 of Usual Tools: mkdir.). Also, `AS_MKDIR_P' succeeds if FILE-NAME 11080 is a symbolic link to an existing directory, even though Posix is 11081 unclear whether `mkdir -p' should succeed in that case. If 11082 creation of FILE-NAME fails, exit the script. 11083 11084 Also see the `AC_PROG_MKDIR_P' macro (*note Particular Programs::). 11085 11086 -- Macro: AS_SET_STATUS (STATUS) 11087 Emit shell code to set the value of `$?' to STATUS, as efficiently 11088 as possible. However, this is not guaranteed to abort a shell 11089 running with `set -e' (*note Limitations of Shell Builtins: set.). 11090 This should also be used at the end of a complex shell function 11091 instead of `return' (*note Shell Functions::) to avoid a DJGPP 11092 shell bug. 11093 11094 -- Macro: AS_TR_CPP (EXPRESSION) 11095 Transform EXPRESSION into a valid right-hand side for a C 11096 `#define'. For example: 11097 11098 # This outputs "#define HAVE_CHAR_P 1". 11099 # Notice the m4 quoting around #, to prevent an m4 comment 11100 type="char *" 11101 echo "[#]define AS_TR_CPP([HAVE_$type]) 1" 11102 11103 -- Macro: AS_TR_SH (EXPRESSION) 11104 Transform EXPRESSION into shell code that generates a valid shell 11105 variable name. The result is literal when possible at m4 time, 11106 but must be used with `eval' if EXPRESSION causes shell 11107 indirections. For example: 11108 11109 # This outputs "Have it!". 11110 header="sys/some file.h" 11111 eval AS_TR_SH([HAVE_$header])=yes 11112 if test "x$HAVE_sys_some_file_h" = xyes; then echo "Have it!"; fi 11113 11114 -- Macro: AS_SET_CATFILE (VAR, DIR, FILE) 11115 Set the polymorphic shell variable VAR to DIR/FILE, but optimizing 11116 the common cases (DIR or FILE is `.', FILE is absolute, etc.). 11117 11118 -- Macro: AS_UNSET (VAR) 11119 Unsets the shell variable VAR, working around bugs in older shells 11120 (*note Limitations of Shell Builtins: unset.). VAR can be a 11121 literal or indirect variable name. 11122 11123 -- Macro: AS_VERSION_COMPARE (VERSION-1, VERSION-2, [ACTION-IF-LESS], 11124 [ACTION-IF-EQUAL], [ACTION-IF-GREATER]) 11125 Compare two strings VERSION-1 and VERSION-2, possibly containing 11126 shell variables, as version strings, and expand ACTION-IF-LESS, 11127 ACTION-IF-EQUAL, or ACTION-IF-GREATER depending upon the result. 11128 The algorithm to compare is similar to the one used by strverscmp 11129 in glibc (*note String/Array Comparison: (libc)String/Array 11130 Comparison.). 11131 11132 11133File: autoconf.info, Node: Polymorphic Variables, Next: Initialization Macros, Prev: Common Shell Constructs, Up: Programming in M4sh 11134 111359.2 Support for indirect variable names 11136======================================= 11137 11138Often, it is convenient to write a macro that will emit shell code 11139operating on a shell variable. The simplest case is when the variable 11140name is known. But a more powerful idiom is writing shell code that can 11141work through an indirection, where another variable or command 11142substitution produces the name of the variable to actually manipulate. 11143M4sh supports the notion of polymorphic shell variables, making it easy 11144to write a macro that can deal with either literal or indirect variable 11145names and output shell code appropriate for both use cases. Behavior is 11146undefined if expansion of an indirect variable does not result in a 11147literal variable name. 11148 11149 -- Macro: AS_LITERAL_IF (EXPRESSION, [IF-LITERAL], [IF-NOT], 11150 [IF-SIMPLE-REF = `IF-NOT']) 11151 -- Macro: AS_LITERAL_WORD_IF (EXPRESSION, [IF-LITERAL], [IF-NOT], 11152 [IF-SIMPLE-REF = `IF-NOT']) 11153 If the expansion of EXPRESSION is definitely a shell literal, 11154 expand IF-LITERAL. If the expansion of EXPRESSION looks like it 11155 might contain shell indirections (such as `$var' or ``expr`'), 11156 then IF-NOT is expanded. Sometimes, it is possible to output 11157 optimized code if EXPRESSION consists only of shell variable 11158 expansions (such as `${var}'), in which case IF-SIMPLE-REF can be 11159 provided; but defaulting to IF-NOT should always be safe. 11160 `AS_LITERAL_WORD_IF' only expands IF-LITERAL if EXPRESSION looks 11161 like a single shell word, containing no whitespace; while 11162 `AS_LITERAL_IF' allows whitespace in EXPRESSION. 11163 11164 In order to reduce the time spent recognizing whether an 11165 EXPRESSION qualifies as a literal or a simple indirection, the 11166 implementation is somewhat conservative: EXPRESSION must be a 11167 single shell word (possibly after stripping whitespace), 11168 consisting only of bytes that would have the same meaning whether 11169 unquoted or enclosed in double quotes (for example, `a.b' results 11170 in IF-LITERAL, even though it is not a valid shell variable name; 11171 while both `'a'' and `[$]' result in IF-NOT, because they behave 11172 differently than `"'a'"' and `"[$]"'). This macro can be used in 11173 contexts for recognizing portable file names (such as in the 11174 implementation of `AC_LIBSOURCE'), or coupled with some 11175 transliterations for forming valid variable names (such as in the 11176 implementation of `AS_TR_SH', which uses an additional 11177 `m4_translit' to convert `.' to `_'). 11178 11179 This example shows how to read the contents of the shell variable 11180 `bar', exercising all three arguments to `AS_LITERAL_IF'. It 11181 results in a script that will output the line `hello' three times. 11182 11183 AC_DEFUN([MY_ACTION], 11184 [AS_LITERAL_IF([$1], 11185 [echo "$$1"], 11186 [AS_VAR_COPY([var], [$1]) 11187 echo "$var"], 11188 [eval 'echo "$'"$1"\"])]) 11189 foo=bar bar=hello 11190 MY_ACTION([bar]) 11191 MY_ACTION([`echo bar`]) 11192 MY_ACTION([$foo]) 11193 11194 -- Macro: AS_VAR_APPEND (VAR, TEXT) 11195 Emit shell code to append the shell expansion of TEXT to the end 11196 of the current contents of the polymorphic shell variable VAR, 11197 taking advantage of shells that provide the `+=' extension for more 11198 efficient scaling. 11199 11200 For situations where the final contents of VAR are relatively 11201 short (less than 256 bytes), it is more efficient to use the 11202 simpler code sequence of `VAR=${VAR}TEXT' (or its polymorphic 11203 equivalent of `AS_VAR_COPY([t], [VAR])' and `AS_VAR_SET([VAR], 11204 ["$t"TEXT])'). But in the case when the script will be repeatedly 11205 appending text into `var', issues of scaling start to become 11206 apparent. A naive implementation requires execution time linear 11207 to the length of the current contents of VAR as well as the length 11208 of TEXT for a single append, for an overall quadratic scaling with 11209 multiple appends. This macro takes advantage of shells which 11210 provide the extension `VAR+=TEXT', which can provide amortized 11211 constant time for a single append, for an overall linear scaling 11212 with multiple appends. Note that unlike `AS_VAR_SET', this macro 11213 requires that TEXT be quoted properly to avoid field splitting and 11214 file name expansion. 11215 11216 -- Macro: AS_VAR_ARITH (VAR, EXPRESSION) 11217 Emit shell code to compute the arithmetic expansion of EXPRESSION, 11218 assigning the result as the contents of the polymorphic shell 11219 variable VAR. The code takes advantage of shells that provide 11220 `$(())' for fewer forks, but uses `expr' as a fallback. 11221 Therefore, the syntax for a valid EXPRESSION is rather limited: 11222 all operators must occur as separate shell arguments and with 11223 proper quoting, there is no portable equality operator, all 11224 variables containing numeric values must be expanded prior to the 11225 computation, all numeric values must be provided in decimal 11226 without leading zeroes, and the first shell argument should not be 11227 a negative number. In the following example, this snippet will 11228 print `(2+3)*4 == 20'. 11229 11230 bar=3 11231 AS_VAR_ARITH([foo], [\( 2 + $bar \) \* 4]) 11232 echo "(2+$bar)*4 == $foo" 11233 11234 -- Macro: AS_VAR_COPY (DEST, SOURCE) 11235 Emit shell code to assign the contents of the polymorphic shell 11236 variable SOURCE to the polymorphic shell variable DEST. For 11237 example, executing this M4sh snippet will output `bar hi': 11238 11239 foo=bar bar=hi 11240 AS_VAR_COPY([a], [foo]) 11241 AS_VAR_COPY([b], [$foo]) 11242 echo "$a $b" 11243 11244 When it is necessary to access the contents of an indirect variable 11245 inside a shell double-quoted context, the recommended idiom is to 11246 first copy the contents into a temporary literal shell variable. 11247 11248 for header in stdint_h inttypes_h ; do 11249 AS_VAR_COPY([var], [ac_cv_header_$header]) 11250 echo "$header detected: $var" 11251 done 11252 11253 -- Macro: AS_VAR_IF (VAR, [WORD], [IF-EQUAL], [IF-NOT-EQUAL]) 11254 Output a shell conditional statement. If the contents of the 11255 polymorphic shell variable VAR match the string WORD, execute 11256 IF-EQUAL; otherwise execute IF-NOT-EQUAL. WORD must be a single 11257 shell word (typically a quoted string). Avoids shell bugs if an 11258 interrupt signal arrives while a command substitution in VAR is 11259 being expanded. 11260 11261 -- Macro: AS_VAR_PUSHDEF (M4-NAME, VALUE) 11262 -- Macro: AS_VAR_POPDEF (M4-NAME) 11263 A common M4sh idiom involves composing shell variable names from 11264 an m4 argument (for example, writing a macro that uses a cache 11265 variable). VALUE can be an arbitrary string, which will be 11266 transliterated into a valid shell name by `AS_TR_SH'. In order to 11267 access the composed variable name based on VALUE, it is easier to 11268 declare a temporary m4 macro M4-NAME with `AS_VAR_PUSHDEF', then 11269 use that macro as the argument to subsequent `AS_VAR' macros as a 11270 polymorphic variable name, and finally free the temporary macro 11271 with `AS_VAR_POPDEF'. These macros are often followed with `dnl', 11272 to avoid excess newlines in the output. 11273 11274 Here is an involved example, that shows the power of writing 11275 macros that can handle composed shell variable names: 11276 11277 m4_define([MY_CHECK_HEADER], 11278 [AS_VAR_PUSHDEF([my_Header], [ac_cv_header_$1])dnl 11279 AS_VAR_IF([my_Header], [yes], [echo "header $1 detected"])dnl 11280 AS_VAR_POPDEF([my_Header])dnl 11281 ]) 11282 MY_CHECK_HEADER([stdint.h]) 11283 for header in inttypes.h stdlib.h ; do 11284 MY_CHECK_HEADER([$header]) 11285 done 11286 11287 In the above example, `MY_CHECK_HEADER' can operate on polymorphic 11288 variable names. In the first invocation, the m4 argument is 11289 `stdint.h', which transliterates into a literal `stdint_h'. As a 11290 result, the temporary macro `my_Header' expands to the literal 11291 shell name `ac_cv_header_stdint_h'. In the second invocation, the 11292 m4 argument to `MY_CHECK_HEADER' is `$header', and the temporary 11293 macro `my_Header' expands to the indirect shell name 11294 `$as_my_Header'. During the shell execution of the for loop, when 11295 `$header' contains `inttypes.h', then `$as_my_Header' contains 11296 `ac_cv_header_inttypes_h'. If this script is then run on a 11297 platform where all three headers have been previously detected, the 11298 output of the script will include: 11299 11300 header stdint.h detected 11301 header inttypes.h detected 11302 header stdlib.h detected 11303 11304 -- Macro: AS_VAR_SET (VAR, [VALUE]) 11305 Emit shell code to assign the contents of the polymorphic shell 11306 variable VAR to the shell expansion of VALUE. VALUE is not 11307 subject to field splitting or file name expansion, so if command 11308 substitution is used, it may be done with ``""`' rather than using 11309 an intermediate variable (*note Shell Substitutions::). However, 11310 VALUE does undergo rescanning for additional macro names; behavior 11311 is unspecified if late expansion results in any shell 11312 meta-characters. 11313 11314 -- Macro: AS_VAR_SET_IF (VAR, [IF-SET], [IF-UNDEF]) 11315 Emit a shell conditional statement, which executes IF-SET if the 11316 polymorphic shell variable `var' is set to any value, and IF-UNDEF 11317 otherwise. 11318 11319 -- Macro: AS_VAR_TEST_SET (VAR) 11320 Emit a shell statement that results in a successful exit status 11321 only if the polymorphic shell variable `var' is set. 11322 11323 11324File: autoconf.info, Node: Initialization Macros, Next: File Descriptor Macros, Prev: Polymorphic Variables, Up: Programming in M4sh 11325 113269.3 Initialization Macros 11327========================= 11328 11329 -- Macro: AS_BOURNE_COMPATIBLE 11330 Set up the shell to be more compatible with the Bourne shell as 11331 standardized by Posix, if possible. This may involve setting 11332 environment variables, or setting options, or similar 11333 implementation-specific actions. This macro is deprecated, since 11334 `AS_INIT' already invokes it. 11335 11336 -- Macro: AS_INIT 11337 Initialize the M4sh environment. This macro calls `m4_init', then 11338 outputs the `#! /bin/sh' line, a notice about where the output was 11339 generated from, and code to sanitize the environment for the rest 11340 of the script. Among other initializations, this sets `SHELL' to 11341 the shell chosen to run the script (*note CONFIG_SHELL::), and 11342 `LC_ALL' to ensure the C locale. Finally, it changes the current 11343 diversion to `BODY'. `AS_INIT' is called automatically by 11344 `AC_INIT' and `AT_INIT', so shell code in `configure', 11345 `config.status', and `testsuite' all benefit from a sanitized 11346 shell environment. 11347 11348 -- Macro: AS_INIT_GENERATED (FILE, [COMMENT]) 11349 Emit shell code to start the creation of a subsidiary shell script 11350 in FILE, including changing FILE to be executable. This macro 11351 populates the child script with information learned from the parent 11352 (thus, the emitted code is equivalent in effect, but more 11353 efficient, than the code output by `AS_INIT', 11354 `AS_BOURNE_COMPATIBLE', and `AS_SHELL_SANITIZE'). If present, 11355 COMMENT is output near the beginning of the child, prior to the 11356 shell initialization code, and is subject to parameter expansion, 11357 command substitution, and backslash quote removal. The parent 11358 script should check the exit status after this macro, in case FILE 11359 could not be properly created (for example, if the disk was full). 11360 If successfully created, the parent script can then proceed to 11361 append additional M4sh constructs into the child script. 11362 11363 Note that the child script starts life without a log file open, so 11364 if the parent script uses logging (*note AS_MESSAGE_LOG_FD::), you 11365 must temporarily disable any attempts to use the log file until 11366 after emitting code to open a log within the child. On the other 11367 hand, if the parent script has `AS_MESSAGE_FD' redirected 11368 somewhere besides `1', then the child script already has code that 11369 copies stdout to that descriptor. Currently, the suggested idiom 11370 for writing a M4sh shell script from within another script is: 11371 11372 AS_INIT_GENERATED([FILE], [[# My child script. 11373 ]]) || { AS_ECHO(["Failed to create child script"]); AS_EXIT; } 11374 m4_pushdef([AS_MESSAGE_LOG_FD])dnl 11375 cat >> "FILE" <<\__EOF__ 11376 # Code to initialize AS_MESSAGE_LOG_FD 11377 m4_popdef([AS_MESSAGE_LOG_FD])dnl 11378 # Additional code 11379 __EOF__ 11380 11381 This, however, may change in the future as the M4sh interface is 11382 stabilized further. 11383 11384 Also, be aware that use of `LINENO' within the child script may 11385 report line numbers relative to their location in the parent 11386 script, even when using `AS_LINENO_PREPARE', if the parent script 11387 was unable to locate a shell with working `LINENO' support. 11388 11389 -- Macro: AS_LINENO_PREPARE 11390 Find a shell that supports the special variable `LINENO', which 11391 contains the number of the currently executing line. This macro is 11392 automatically invoked by `AC_INIT' in configure scripts. 11393 11394 -- Macro: AS_ME_PREPARE 11395 Set up variable `as_me' to be the basename of the currently 11396 executing script. This macro is automatically invoked by 11397 `AC_INIT' in configure scripts. 11398 11399 -- Macro: AS_TMPDIR (PREFIX, [DIR = `${TMPDIR:=/tmp}']) 11400 Create, as safely as possible, a temporary sub-directory within 11401 DIR with a name starting with PREFIX. PREFIX should be 2-4 11402 characters, to make it slightly easier to identify the owner of 11403 the directory. If DIR is omitted, then the value of `TMPDIR' will 11404 be used (defaulting to `/tmp'). On success, the name of the newly 11405 created directory is stored in the shell variable `tmp'. On 11406 error, the script is aborted. 11407 11408 Typically, this macro is coupled with some exit traps to delete 11409 the created directory and its contents on exit or interrupt. 11410 However, there is a slight window between when the directory is 11411 created and when the name is actually known to the shell, so an 11412 interrupt at the right moment might leave the temporary directory 11413 behind. Hence it is important to use a PREFIX that makes it 11414 easier to determine if a leftover temporary directory from an 11415 interrupted script is safe to delete. 11416 11417 The use of the output variable `$tmp' rather than something in the 11418 `as_' namespace is historical; it has the unfortunate consequence 11419 that reusing this otherwise common name for any other purpose 11420 inside your script has the potential to break any cleanup traps 11421 designed to remove the temporary directory. 11422 11423 -- Macro: AS_SHELL_SANITIZE 11424 Initialize the shell suitably for `configure' scripts. This has 11425 the effect of `AS_BOURNE_COMPATIBLE', and sets some other 11426 environment variables for predictable results from configuration 11427 tests. For example, it sets `LC_ALL' to change to the default C 11428 locale. *Note Special Shell Variables::. This macro is 11429 deprecated, since `AS_INIT' already invokes it. 11430 11431 11432File: autoconf.info, Node: File Descriptor Macros, Prev: Initialization Macros, Up: Programming in M4sh 11433 114349.4 File Descriptor Macros 11435========================== 11436 11437The following macros define file descriptors used to output messages 11438(or input values) from `configure' scripts. For example: 11439 11440 echo "$wombats found" >&AS_MESSAGE_LOG_FD 11441 echo 'Enter desired kangaroo count:' >&AS_MESSAGE_FD 11442 read kangaroos <&AS_ORIGINAL_STDIN_FD` 11443 11444However doing so is seldom needed, because Autoconf provides higher 11445level macros as described below. 11446 11447 -- Macro: AS_MESSAGE_FD 11448 The file descriptor for `checking for...' messages and results. 11449 By default, `AS_INIT' sets this to `1' for standalone M4sh 11450 clients. However, `AC_INIT' shuffles things around to another file 11451 descriptor, in order to allow the `-q' option of `configure' to 11452 choose whether messages should go to the script's standard output 11453 or be discarded. 11454 11455 If you want to display some messages, consider using one of the 11456 printing macros (*note Printing Messages::) instead. Copies of 11457 messages output via these macros are also recorded in `config.log'. 11458 11459 -- Macro: AS_MESSAGE_LOG_FD 11460 This must either be empty, or expand to a file descriptor for log 11461 messages. By default, `AS_INIT' sets this macro to the empty 11462 string for standalone M4sh clients, thus disabling logging. 11463 However, `AC_INIT' shuffles things around so that both `configure' 11464 and `config.status' use `config.log' for log messages. Macros 11465 that run tools, like `AC_COMPILE_IFELSE' (*note Running the 11466 Compiler::), redirect all output to this descriptor. You may want 11467 to do so if you develop such a low-level macro. 11468 11469 -- Macro: AS_ORIGINAL_STDIN_FD 11470 This must expand to a file descriptor for the original standard 11471 input. By default, `AS_INIT' sets this macro to `0' for standalone 11472 M4sh clients. However, `AC_INIT' shuffles things around for 11473 safety. 11474 11475 When `configure' runs, it may accidentally execute an interactive 11476 command that has the same name as the non-interactive meant to be 11477 used or checked. If the standard input was the terminal, such 11478 interactive programs would cause `configure' to stop, pending some 11479 user input. Therefore `configure' redirects its standard input 11480 from `/dev/null' during its initialization. This is not normally 11481 a problem, since `configure' normally does not need user input. 11482 11483 In the extreme case where your `configure' script really needs to 11484 obtain some values from the original standard input, you can read 11485 them explicitly from `AS_ORIGINAL_STDIN_FD'. 11486 11487 11488File: autoconf.info, Node: Writing Autoconf Macros, Next: Portable Shell, Prev: Programming in M4sh, Up: Top 11489 1149010 Writing Autoconf Macros 11491************************** 11492 11493When you write a feature test that could be applicable to more than one 11494software package, the best thing to do is encapsulate it in a new macro. 11495Here are some instructions and guidelines for writing Autoconf macros. 11496 11497* Menu: 11498 11499* Macro Definitions:: Basic format of an Autoconf macro 11500* Macro Names:: What to call your new macros 11501* Reporting Messages:: Notifying `autoconf' users 11502* Dependencies Between Macros:: What to do when macros depend on other macros 11503* Obsoleting Macros:: Warning about old ways of doing things 11504* Coding Style:: Writing Autoconf macros a` la Autoconf 11505 11506 11507File: autoconf.info, Node: Macro Definitions, Next: Macro Names, Up: Writing Autoconf Macros 11508 1150910.1 Macro Definitions 11510====================== 11511 11512 -- Macro: AC_DEFUN (NAME, [BODY]) 11513 Autoconf macros are defined using the `AC_DEFUN' macro, which is 11514 similar to the M4 builtin `m4_define' macro; this creates a macro 11515 named NAME and with BODY as its expansion. In addition to 11516 defining a macro, `AC_DEFUN' adds to it some code that is used to 11517 constrain the order in which macros are called, while avoiding 11518 redundant output (*note Prerequisite Macros::). 11519 11520 An Autoconf macro definition looks like this: 11521 11522 AC_DEFUN(MACRO-NAME, MACRO-BODY) 11523 11524 You can refer to any arguments passed to the macro as `$1', `$2', 11525etc. *Note How to define new macros: (m4.info)Definitions, for more 11526complete information on writing M4 macros. 11527 11528 Most macros fall in one of two general categories. The first 11529category includes macros which take arguments, in order to generate 11530output parameterized by those arguments. Macros in this category are 11531designed to be directly expanded, often multiple times, and should not 11532be used as the argument to `AC_REQUIRE'. The other category includes 11533macros which are shorthand for a fixed block of text, and therefore do 11534not take arguments. For this category of macros, directly expanding 11535the macro multiple times results in redundant output, so it is more 11536common to use the macro as the argument to `AC_REQUIRE', or to declare 11537the macro with `AC_DEFUN_ONCE' (*note One-Shot Macros::). 11538 11539 Be sure to properly quote both the MACRO-BODY _and_ the MACRO-NAME 11540to avoid any problems if the macro happens to have been previously 11541defined. 11542 11543 Each macro should have a header comment that gives its prototype, 11544and a brief description. When arguments have default values, display 11545them in the prototype. For example: 11546 11547 # AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1]) 11548 # -------------------------------------- 11549 m4_define([AC_MSG_ERROR], 11550 [{ AS_MESSAGE([error: $1], [2]) 11551 exit m4_default([$2], [1]); }]) 11552 11553 Comments about the macro should be left in the header comment. Most 11554other comments make their way into `configure', so just keep using `#' 11555to introduce comments. 11556 11557 If you have some special comments about pure M4 code, comments that 11558make no sense in `configure' and in the header comment, then use the 11559builtin `dnl': it causes M4 to discard the text through the next 11560newline. 11561 11562 Keep in mind that `dnl' is rarely needed to introduce comments; 11563`dnl' is more useful to get rid of the newlines following macros that 11564produce no output, such as `AC_REQUIRE'. 11565 11566 Public third-party macros need to use `AC_DEFUN', and not 11567`m4_define', in order to be found by `aclocal' (*note Extending 11568aclocal: (automake)Extending aclocal.). Additionally, if it is ever 11569determined that a macro should be made obsolete, it is easy to convert 11570from `AC_DEFUN' to `AU_DEFUN' in order to have `autoupdate' assist the 11571user in choosing a better alternative, but there is no corresponding 11572way to make `m4_define' issue an upgrade notice (*note AU_DEFUN::). 11573 11574 There is another subtle, but important, difference between using 11575`m4_define' and `AC_DEFUN': only the former is unaffected by 11576`AC_REQUIRE'. When writing a file, it is always safe to replace a 11577block of text with a `m4_define' macro that will expand to the same 11578text. But replacing a block of text with an `AC_DEFUN' macro with the 11579same content does not necessarily give the same results, because it 11580changes the location where any embedded but unsatisfied `AC_REQUIRE' 11581invocations within the block will be expanded. For an example of this, 11582see *note Expanded Before Required::. 11583 11584 11585File: autoconf.info, Node: Macro Names, Next: Reporting Messages, Prev: Macro Definitions, Up: Writing Autoconf Macros 11586 1158710.2 Macro Names 11588================ 11589 11590All of the public Autoconf macros have all-uppercase names in the 11591namespace `^AC_' to prevent them from accidentally conflicting with 11592other text; Autoconf also reserves the namespace `^_AC_' for internal 11593macros. All shell variables that they use for internal purposes have 11594mostly-lowercase names starting with `ac_'. Autoconf also uses 11595here-document delimiters in the namespace `^_AC[A-Z]'. During 11596`configure', files produced by Autoconf make heavy use of the file 11597system namespace `^conf'. 11598 11599 Since Autoconf is built on top of M4sugar (*note Programming in 11600M4sugar::) and M4sh (*note Programming in M4sh::), you must also be 11601aware of those namespaces (`^_?\(m4\|AS\)_'). And since `configure.ac' 11602is also designed to be scanned by Autoheader, Autoscan, Autoupdate, and 11603Automake, you should be aware of the `^_?A[HNUM]_' namespaces. In 11604general, you _should not use_ the namespace of a package that does not 11605own the macro or shell code you are writing. 11606 11607 To ensure that your macros don't conflict with present or future 11608Autoconf macros, you should prefix your own macro names and any shell 11609variables they use with some other sequence. Possibilities include your 11610initials, or an abbreviation for the name of your organization or 11611software package. Historically, people have not always followed the 11612rule of using a namespace appropriate for their package, and this has 11613made it difficult for determining the origin of a macro (and where to 11614report bugs about that macro), as well as difficult for the true 11615namespace owner to add new macros without interference from pre-existing 11616uses of third-party macros. Perhaps the best example of this confusion 11617is the `AM_GNU_GETTEXT' macro, which belongs, not to Automake, but to 11618Gettext. 11619 11620 Most of the Autoconf macros' names follow a structured naming 11621convention that indicates the kind of feature check by the name. The 11622macro names consist of several words, separated by underscores, going 11623from most general to most specific. The names of their cache variables 11624use the same convention (*note Cache Variable Names::, for more 11625information on them). 11626 11627 The first word of the name after the namespace initials (such as 11628`AC_') usually tells the category of the feature being tested. Here 11629are the categories used in Autoconf for specific test macros, the kind 11630of macro that you are more likely to write. They are also used for 11631cache variables, in all-lowercase. Use them where applicable; where 11632they're not, invent your own categories. 11633 11634`C' 11635 C language builtin features. 11636 11637`DECL' 11638 Declarations of C variables in header files. 11639 11640`FUNC' 11641 Functions in libraries. 11642 11643`GROUP' 11644 Posix group owners of files. 11645 11646`HEADER' 11647 Header files. 11648 11649`LIB' 11650 C libraries. 11651 11652`PROG' 11653 The base names of programs. 11654 11655`MEMBER' 11656 Members of aggregates. 11657 11658`SYS' 11659 Operating system features. 11660 11661`TYPE' 11662 C builtin or declared types. 11663 11664`VAR' 11665 C variables in libraries. 11666 11667 After the category comes the name of the particular feature being 11668tested. Any further words in the macro name indicate particular aspects 11669of the feature. For example, `AC_PROG_CC_STDC' checks whether the C 11670compiler supports ISO Standard C. 11671 11672 An internal macro should have a name that starts with an underscore; 11673Autoconf internals should therefore start with `_AC_'. Additionally, a 11674macro that is an internal subroutine of another macro should have a 11675name that starts with an underscore and the name of that other macro, 11676followed by one or more words saying what the internal macro does. For 11677example, `AC_PATH_X' has internal macros `_AC_PATH_X_XMKMF' and 11678`_AC_PATH_X_DIRECT'. 11679 11680 11681File: autoconf.info, Node: Reporting Messages, Next: Dependencies Between Macros, Prev: Macro Names, Up: Writing Autoconf Macros 11682 1168310.3 Reporting Messages 11684======================= 11685 11686When macros statically diagnose abnormal situations, benign or fatal, it 11687is possible to make `autoconf' detect the problem, and refuse to create 11688`configure' in the case of an error. The macros in this section are 11689considered obsolescent, and new code should use M4sugar macros for this 11690purpose, see *note Diagnostic Macros::. 11691 11692 On the other hand, it is possible to want to detect errors when 11693`configure' is run, which are dependent on the environment of the user 11694rather than the maintainer. For dynamic diagnostics, see *note 11695Printing Messages::. 11696 11697 -- Macro: AC_DIAGNOSE (CATEGORY, MESSAGE) 11698 Report MESSAGE as a warning (or as an error if requested by the 11699 user) if warnings of the CATEGORY are turned on. This macro is 11700 obsolescent; you are encouraged to use: 11701 m4_warn([CATEGORY], [MESSAGE]) 11702 instead. *Note m4_warn::, for more details, including valid 11703 CATEGORY names. 11704 11705 -- Macro: AC_WARNING (MESSAGE) 11706 Report MESSAGE as a syntax warning. This macro is obsolescent; 11707 you are encouraged to use: 11708 m4_warn([syntax], [MESSAGE]) 11709 instead. *Note m4_warn::, for more details, as well as better 11710 finer-grained categories of warnings (not all problems have to do 11711 with syntax). 11712 11713 -- Macro: AC_FATAL (MESSAGE) 11714 Report a severe error MESSAGE, and have `autoconf' die. This 11715 macro is obsolescent; you are encouraged to use: 11716 m4_fatal([MESSAGE]) 11717 instead. *Note m4_fatal::, for more details. 11718 11719 When the user runs `autoconf -W error', warnings from `m4_warn' 11720(including those issued through `AC_DIAGNOSE' and `AC_WARNING') are 11721reported as errors, see *note autoconf Invocation::. 11722 11723 11724File: autoconf.info, Node: Dependencies Between Macros, Next: Obsoleting Macros, Prev: Reporting Messages, Up: Writing Autoconf Macros 11725 1172610.4 Dependencies Between Macros 11727================================ 11728 11729Some Autoconf macros depend on other macros having been called first in 11730order to work correctly. Autoconf provides a way to ensure that certain 11731macros are called if needed and a way to warn the user if macros are 11732called in an order that might cause incorrect operation. 11733 11734* Menu: 11735 11736* Prerequisite Macros:: Ensuring required information 11737* Suggested Ordering:: Warning about possible ordering problems 11738* One-Shot Macros:: Ensuring a macro is called only once 11739 11740 11741File: autoconf.info, Node: Prerequisite Macros, Next: Suggested Ordering, Up: Dependencies Between Macros 11742 1174310.4.1 Prerequisite Macros 11744-------------------------- 11745 11746A macro that you write might need to use values that have previously 11747been computed by other macros. For example, `AC_DECL_YYTEXT' examines 11748the output of `flex' or `lex', so it depends on `AC_PROG_LEX' having 11749been called first to set the shell variable `LEX'. 11750 11751 Rather than forcing the user of the macros to keep track of the 11752dependencies between them, you can use the `AC_REQUIRE' macro to do it 11753automatically. `AC_REQUIRE' can ensure that a macro is only called if 11754it is needed, and only called once. 11755 11756 -- Macro: AC_REQUIRE (MACRO-NAME) 11757 If the M4 macro MACRO-NAME has not already been called, call it 11758 (without any arguments). Make sure to quote MACRO-NAME with 11759 square brackets. MACRO-NAME must have been defined using 11760 `AC_DEFUN' or else contain a call to `AC_PROVIDE' to indicate that 11761 it has been called. 11762 11763 `AC_REQUIRE' must be used inside a macro defined by `AC_DEFUN'; it 11764 must not be called from the top level. Also, it does not make 11765 sense to require a macro that takes parameters. 11766 11767 `AC_REQUIRE' is often misunderstood. It really implements 11768dependencies between macros in the sense that if one macro depends upon 11769another, the latter is expanded _before_ the body of the former. To be 11770more precise, the required macro is expanded before the outermost 11771defined macro in the current expansion stack. In particular, 11772`AC_REQUIRE([FOO])' is not replaced with the body of `FOO'. For 11773instance, this definition of macros: 11774 11775 AC_DEFUN([TRAVOLTA], 11776 [test "$body_temperature_in_celsius" -gt "38" && 11777 dance_floor=occupied]) 11778 AC_DEFUN([NEWTON_JOHN], 11779 [test "x$hair_style" = xcurly && 11780 dance_floor=occupied]) 11781 11782 AC_DEFUN([RESERVE_DANCE_FLOOR], 11783 [if date | grep '^Sat.*pm' >/dev/null 2>&1; then 11784 AC_REQUIRE([TRAVOLTA]) 11785 AC_REQUIRE([NEWTON_JOHN]) 11786 fi]) 11787 11788with this `configure.ac' 11789 11790 AC_INIT([Dance Manager], [1.0], [bug-dance@example.org]) 11791 RESERVE_DANCE_FLOOR 11792 if test "x$dance_floor" = xoccupied; then 11793 AC_MSG_ERROR([cannot pick up here, let's move]) 11794 fi 11795 11796does not leave you with a better chance to meet a kindred soul at other 11797times than Saturday night since it expands into: 11798 11799 test "$body_temperature_in_Celsius" -gt "38" && 11800 dance_floor=occupied 11801 test "x$hair_style" = xcurly && 11802 dance_floor=occupied 11803 fi 11804 if date | grep '^Sat.*pm' >/dev/null 2>&1; then 11805 11806 11807 fi 11808 11809 This behavior was chosen on purpose: (i) it prevents messages in 11810required macros from interrupting the messages in the requiring macros; 11811(ii) it avoids bad surprises when shell conditionals are used, as in: 11812 11813 if ...; then 11814 AC_REQUIRE([SOME_CHECK]) 11815 fi 11816 ... 11817 SOME_CHECK 11818 11819 However, this implementation can lead to another class of problems. 11820Consider the case where an outer macro first expands, then indirectly 11821requires, an inner macro: 11822 11823 AC_DEFUN([TESTA], [[echo in A 11824 if test -n "$SEEN_A" ; then echo duplicate ; fi 11825 SEEN_A=:]]) 11826 AC_DEFUN([TESTB], [AC_REQUIRE([TESTA])[echo in B 11827 if test -z "$SEEN_A" ; then echo bug ; fi]]) 11828 AC_DEFUN([TESTC], [AC_REQUIRE([TESTB])[echo in C]]) 11829 AC_DEFUN([OUTER], [[echo in OUTER] 11830 TESTA 11831 TESTC]) 11832 OUTER 11833 11834Prior to Autoconf 2.64, the implementation of `AC_REQUIRE' recognized 11835that `TESTB' needed to be hoisted prior to the expansion of `OUTER', 11836but because `TESTA' had already been directly expanded, it failed to 11837hoist `TESTA'. Therefore, the expansion of `TESTB' occurs prior to its 11838prerequisites, leading to the following output: 11839 11840 in B 11841 bug 11842 in OUTER 11843 in A 11844 in C 11845 11846Newer Autoconf is smart enough to recognize this situation, and hoists 11847`TESTA' even though it has already been expanded, but issues a syntax 11848warning in the process. This is because the hoisted expansion of 11849`TESTA' defeats the purpose of using `AC_REQUIRE' to avoid redundant 11850code, and causes its own set of problems if the hoisted macro is not 11851idempotent: 11852 11853 in A 11854 in B 11855 in OUTER 11856 in A 11857 duplicate 11858 in C 11859 11860 The bug is not in Autoconf, but in the macro definitions. If you 11861ever pass a particular macro name to `AC_REQUIRE', then you are implying 11862that the macro only needs to be expanded once. But to enforce this, 11863either the macro must be declared with `AC_DEFUN_ONCE' (although this 11864only helps in Autoconf 2.64 or newer), or all uses of that macro should 11865be through `AC_REQUIRE'; directly expanding the macro defeats the point 11866of using `AC_REQUIRE' to eliminate redundant expansion. In the 11867example, this rule of thumb was violated because `TESTB' requires 11868`TESTA' while `OUTER' directly expands it. One way of fixing the bug 11869is to factor `TESTA' into two macros, the portion designed for direct 11870and repeated use (here, named `TESTA'), and the portion designed for 11871one-shot output and used only inside `AC_REQUIRE' (here, named 11872`TESTA_PREREQ'). Then, by fixing all clients to use the correct 11873calling convention according to their needs: 11874 11875 AC_DEFUN([TESTA], [AC_REQUIRE([TESTA_PREREQ])[echo in A]]) 11876 AC_DEFUN([TESTA_PREREQ], [[echo in A_PREREQ 11877 if test -n "$SEEN_A" ; then echo duplicate ; fi 11878 SEEN_A=:]]) 11879 AC_DEFUN([TESTB], [AC_REQUIRE([TESTA_PREREQ])[echo in B 11880 if test -z "$SEEN_A" ; then echo bug ; fi]]) 11881 AC_DEFUN([TESTC], [AC_REQUIRE([TESTB])[echo in C]]) 11882 AC_DEFUN([OUTER], [[echo in OUTER] 11883 TESTA 11884 TESTC]) 11885 OUTER 11886 11887the resulting output will then obey all dependency rules and avoid any 11888syntax warnings, whether the script is built with old or new Autoconf 11889versions: 11890 11891 in A_PREREQ 11892 in B 11893 in OUTER 11894 in A 11895 in C 11896 11897 The helper macros `AS_IF' and `AS_CASE' may be used to enforce 11898expansion of required macros outside of shell conditional constructs. 11899You are furthermore encouraged, although not required, to put all 11900`AC_REQUIRE' calls at the beginning of a macro. You can use `dnl' to 11901avoid the empty lines they leave. 11902 11903 11904File: autoconf.info, Node: Suggested Ordering, Next: One-Shot Macros, Prev: Prerequisite Macros, Up: Dependencies Between Macros 11905 1190610.4.2 Suggested Ordering 11907------------------------- 11908 11909Some macros should be run before another macro if both are called, but 11910neither _requires_ that the other be called. For example, a macro that 11911changes the behavior of the C compiler should be called before any 11912macros that run the C compiler. Many of these dependencies are noted in 11913the documentation. 11914 11915 Autoconf provides the `AC_BEFORE' macro to warn users when macros 11916with this kind of dependency appear out of order in a `configure.ac' 11917file. The warning occurs when creating `configure' from 11918`configure.ac', not when running `configure'. 11919 11920 For example, `AC_PROG_CPP' checks whether the C compiler can run the 11921C preprocessor when given the `-E' option. It should therefore be 11922called after any macros that change which C compiler is being used, 11923such as `AC_PROG_CC'. So `AC_PROG_CC' contains: 11924 11925 AC_BEFORE([$0], [AC_PROG_CPP])dnl 11926 11927This warns the user if a call to `AC_PROG_CPP' has already occurred 11928when `AC_PROG_CC' is called. 11929 11930 -- Macro: AC_BEFORE (THIS-MACRO-NAME, CALLED-MACRO-NAME) 11931 Make M4 print a warning message to the standard error output if 11932 CALLED-MACRO-NAME has already been called. THIS-MACRO-NAME should 11933 be the name of the macro that is calling `AC_BEFORE'. The macro 11934 CALLED-MACRO-NAME must have been defined using `AC_DEFUN' or else 11935 contain a call to `AC_PROVIDE' to indicate that it has been called. 11936 11937 11938File: autoconf.info, Node: One-Shot Macros, Prev: Suggested Ordering, Up: Dependencies Between Macros 11939 1194010.4.3 One-Shot Macros 11941---------------------- 11942 11943Some macros should be called only once, either because calling them 11944multiple time is unsafe, or because it is bad style. For instance 11945Autoconf ensures that `AC_CANONICAL_BUILD' and cousins (*note 11946Canonicalizing::) are evaluated only once, because it makes no sense to 11947run these expensive checks more than once. Such one-shot macros can be 11948defined using `AC_DEFUN_ONCE'. 11949 11950 -- Macro: AC_DEFUN_ONCE (MACRO-NAME, MACRO-BODY) 11951 Declare macro MACRO-NAME like `AC_DEFUN' would (*note Macro 11952 Definitions::), but add additional logic that guarantees that only 11953 the first use of the macro (whether by direct expansion or 11954 `AC_REQUIRE') causes an expansion of MACRO-BODY; the expansion 11955 will occur before the start of any enclosing macro defined by 11956 `AC_DEFUN'. Subsequent expansions are silently ignored. 11957 Generally, it does not make sense for MACRO-BODY to use parameters 11958 such as `$1'. 11959 11960 Prior to Autoconf 2.64, a macro defined by `AC_DEFUN_ONCE' would 11961emit a warning if it was directly expanded a second time, so for 11962portability, it is better to use `AC_REQUIRE' than direct invocation of 11963MACRO-NAME inside a macro defined by `AC_DEFUN' (*note Prerequisite 11964Macros::). 11965 11966 11967File: autoconf.info, Node: Obsoleting Macros, Next: Coding Style, Prev: Dependencies Between Macros, Up: Writing Autoconf Macros 11968 1196910.5 Obsoleting Macros 11970====================== 11971 11972Configuration and portability technology has evolved over the years. 11973Often better ways of solving a particular problem are developed, or 11974ad-hoc approaches are systematized. This process has occurred in many 11975parts of Autoconf. One result is that some of the macros are now 11976considered "obsolete"; they still work, but are no longer considered 11977the best thing to do, hence they should be replaced with more modern 11978macros. Ideally, `autoupdate' should replace the old macro calls with 11979their modern implementation. 11980 11981 Autoconf provides a simple means to obsolete a macro. 11982 11983 -- Macro: AU_DEFUN (OLD-MACRO, IMPLEMENTATION, [MESSAGE]) 11984 Define OLD-MACRO as IMPLEMENTATION. The only difference with 11985 `AC_DEFUN' is that the user is warned that OLD-MACRO is now 11986 obsolete. 11987 11988 If she then uses `autoupdate', the call to OLD-MACRO is replaced 11989 by the modern IMPLEMENTATION. MESSAGE should include information 11990 on what to do after running `autoupdate'; `autoupdate' prints it 11991 as a warning, and includes it in the updated `configure.ac' file. 11992 11993 The details of this macro are hairy: if `autoconf' encounters an 11994 `AU_DEFUN'ed macro, all macros inside its second argument are 11995 expanded as usual. However, when `autoupdate' is run, only M4 and 11996 M4sugar macros are expanded here, while all other macros are 11997 disabled and appear literally in the updated `configure.ac'. 11998 11999 -- Macro: AU_ALIAS (OLD-NAME, NEW-NAME) 12000 Used if the OLD-NAME is to be replaced by a call to NEW-MACRO with 12001 the same parameters. This happens for example if the macro was 12002 renamed. 12003 12004 12005File: autoconf.info, Node: Coding Style, Prev: Obsoleting Macros, Up: Writing Autoconf Macros 12006 1200710.6 Coding Style 12008================= 12009 12010The Autoconf macros follow a strict coding style. You are encouraged to 12011follow this style, especially if you intend to distribute your macro, 12012either by contributing it to Autoconf itself or the Autoconf Macro 12013Archive (http://www.gnu.org/software/autoconf-archive/), or by other 12014means. 12015 12016 The first requirement is to pay great attention to the quotation. 12017For more details, see *note Autoconf Language::, and *note M4 12018Quotation::. 12019 12020 Do not try to invent new interfaces. It is likely that there is a 12021macro in Autoconf that resembles the macro you are defining: try to 12022stick to this existing interface (order of arguments, default values, 12023etc.). We _are_ conscious that some of these interfaces are not 12024perfect; nevertheless, when harmless, homogeneity should be preferred 12025over creativity. 12026 12027 Be careful about clashes both between M4 symbols and between shell 12028variables. 12029 12030 If you stick to the suggested M4 naming scheme (*note Macro Names::), 12031you are unlikely to generate conflicts. Nevertheless, when you need to 12032set a special value, _avoid using a regular macro name_; rather, use an 12033"impossible" name. For instance, up to version 2.13, the macro 12034`AC_SUBST' used to remember what SYMBOL macros were already defined by 12035setting `AC_SUBST_SYMBOL', which is a regular macro name. But since 12036there is a macro named `AC_SUBST_FILE', it was just impossible to 12037`AC_SUBST(FILE)'! In this case, `AC_SUBST(SYMBOL)' or 12038`_AC_SUBST(SYMBOL)' should have been used (yes, with the parentheses). 12039 12040 No Autoconf macro should ever enter the user-variable name space; 12041i.e., except for the variables that are the actual result of running the 12042macro, all shell variables should start with `ac_'. In addition, small 12043macros or any macro that is likely to be embedded in other macros 12044should be careful not to use obvious names. 12045 12046 Do not use `dnl' to introduce comments: most of the comments you are 12047likely to write are either header comments which are not output anyway, 12048or comments that should make their way into `configure'. There are 12049exceptional cases where you do want to comment special M4 constructs, 12050in which case `dnl' is right, but keep in mind that it is unlikely. 12051 12052 M4 ignores the leading blanks and newlines before each argument. 12053Use this feature to indent in such a way that arguments are (more or 12054less) aligned with the opening parenthesis of the macro being called. 12055For instance, instead of 12056 12057 AC_CACHE_CHECK(for EMX OS/2 environment, 12058 ac_cv_emxos2, 12059 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])], 12060 [ac_cv_emxos2=yes], [ac_cv_emxos2=no])]) 12061 12062write 12063 12064 AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2], 12065 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])], 12066 [ac_cv_emxos2=yes], 12067 [ac_cv_emxos2=no])]) 12068 12069or even 12070 12071 AC_CACHE_CHECK([for EMX OS/2 environment], 12072 [ac_cv_emxos2], 12073 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], 12074 [return __EMX__;])], 12075 [ac_cv_emxos2=yes], 12076 [ac_cv_emxos2=no])]) 12077 12078 When using `AC_RUN_IFELSE' or any macro that cannot work when 12079cross-compiling, provide a pessimistic value (typically `no'). 12080 12081 Feel free to use various tricks to prevent auxiliary tools, such as 12082syntax-highlighting editors, from behaving improperly. For instance, 12083instead of: 12084 12085 m4_bpatsubst([$1], [$"]) 12086 12087use 12088 12089 m4_bpatsubst([$1], [$""]) 12090 12091so that Emacsen do not open an endless "string" at the first quote. 12092For the same reasons, avoid: 12093 12094 test $[#] != 0 12095 12096and use: 12097 12098 test $[@%:@] != 0 12099 12100Otherwise, the closing bracket would be hidden inside a `#'-comment, 12101breaking the bracket-matching highlighting from Emacsen. Note the 12102preferred style to escape from M4: `$[1]', `$[@]', etc. Do not escape 12103when it is unnecessary. Common examples of useless quotation are 12104`[$]$1' (write `$$1'), `[$]var' (use `$var'), etc. If you add 12105portability issues to the picture, you'll prefer `${1+"$[@]"}' to 12106`"[$]@"', and you'll prefer do something better than hacking Autoconf 12107`:-)'. 12108 12109 When using `sed', don't use `-e' except for indenting purposes. 12110With the `s' and `y' commands, the preferred separator is `/' unless 12111`/' itself might appear in the pattern or replacement, in which case 12112you should use `|', or optionally `,' if you know the pattern and 12113replacement cannot contain a file name. If none of these characters 12114will do, choose a printable character that cannot appear in the pattern 12115or replacement. Characters from the set `"#$&'()*;<=>?`|~' are good 12116choices if the pattern or replacement might contain a file name, since 12117they have special meaning to the shell and are less likely to occur in 12118file names. 12119 12120 *Note Macro Definitions::, for details on how to define a macro. If 12121a macro doesn't use `AC_REQUIRE', is expected to never be the object of 12122an `AC_REQUIRE' directive, and macros required by other macros inside 12123arguments do not need to be expanded before this macro, then use 12124`m4_define'. In case of doubt, use `AC_DEFUN'. Also take into account 12125that public third-party macros need to use `AC_DEFUN' in order to be 12126found by `aclocal' (*note Extending aclocal: (automake)Extending 12127aclocal.). All the `AC_REQUIRE' statements should be at the beginning 12128of the macro, and each statement should be followed by `dnl'. 12129 12130 You should not rely on the number of arguments: instead of checking 12131whether an argument is missing, test that it is not empty. It provides 12132both a simpler and a more predictable interface to the user, and saves 12133room for further arguments. 12134 12135 Unless the macro is short, try to leave the closing `])' at the 12136beginning of a line, followed by a comment that repeats the name of the 12137macro being defined. This introduces an additional newline in 12138`configure'; normally, that is not a problem, but if you want to remove 12139it you can use `[]dnl' on the last line. You can similarly use `[]dnl' 12140after a macro call to remove its newline. `[]dnl' is recommended 12141instead of `dnl' to ensure that M4 does not interpret the `dnl' as 12142being attached to the preceding text or macro output. For example, 12143instead of: 12144 12145 AC_DEFUN([AC_PATH_X], 12146 [AC_MSG_CHECKING([for X]) 12147 AC_REQUIRE_CPP() 12148 # ...omitted... 12149 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes]) 12150 fi]) 12151 12152you would write: 12153 12154 AC_DEFUN([AC_PATH_X], 12155 [AC_REQUIRE_CPP()[]dnl 12156 AC_MSG_CHECKING([for X]) 12157 # ...omitted... 12158 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes]) 12159 fi[]dnl 12160 ])# AC_PATH_X 12161 12162 If the macro is long, try to split it into logical chunks. 12163Typically, macros that check for a bug in a function and prepare its 12164`AC_LIBOBJ' replacement should have an auxiliary macro to perform this 12165setup. Do not hesitate to introduce auxiliary macros to factor your 12166code. 12167 12168 In order to highlight the recommended coding style, here is a macro 12169written the old way: 12170 12171 dnl Check for EMX on OS/2. 12172 dnl _AC_EMXOS2 12173 AC_DEFUN(_AC_EMXOS2, 12174 [AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2, 12175 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)], 12176 ac_cv_emxos2=yes, ac_cv_emxos2=no)]) 12177 test "x$ac_cv_emxos2" = xyes && EMXOS2=yes]) 12178 12179and the new way: 12180 12181 # _AC_EMXOS2 12182 # ---------- 12183 # Check for EMX on OS/2. 12184 m4_define([_AC_EMXOS2], 12185 [AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2], 12186 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])], 12187 [ac_cv_emxos2=yes], 12188 [ac_cv_emxos2=no])]) 12189 test "x$ac_cv_emxos2" = xyes && EMXOS2=yes[]dnl 12190 ])# _AC_EMXOS2 12191 12192 12193File: autoconf.info, Node: Portable Shell, Next: Portable Make, Prev: Writing Autoconf Macros, Up: Top 12194 1219511 Portable Shell Programming 12196***************************** 12197 12198When writing your own checks, there are some shell-script programming 12199techniques you should avoid in order to make your code portable. The 12200Bourne shell and upward-compatible shells like the Korn shell and Bash 12201have evolved over the years, and many features added to the original 12202System7 shell are now supported on all interesting porting targets. 12203However, the following discussion between Russ Allbery and Robert Lipe 12204is worth reading: 12205 12206Russ Allbery: 12207 12208 The GNU assumption that `/bin/sh' is the one and only shell leads 12209 to a permanent deadlock. Vendors don't want to break users' 12210 existing shell scripts, and there are some corner cases in the 12211 Bourne shell that are not completely compatible with a Posix 12212 shell. Thus, vendors who have taken this route will _never_ 12213 (OK..."never say never") replace the Bourne shell (as `/bin/sh') 12214 with a Posix shell. 12215 12216Robert Lipe: 12217 12218 This is exactly the problem. While most (at least most System 12219 V's) do have a Bourne shell that accepts shell functions most 12220 vendor `/bin/sh' programs are not the Posix shell. 12221 12222 So while most modern systems do have a shell _somewhere_ that 12223 meets the Posix standard, the challenge is to find it. 12224 12225 For this reason, part of the job of M4sh (*note Programming in 12226M4sh::) is to find such a shell. But to prevent trouble, if you're not 12227using M4sh you should not take advantage of features that were added 12228after Unix version 7, circa 1977 (*note Systemology::); you should not 12229use aliases, negated character classes, or even `unset'. `#' comments, 12230while not in Unix version 7, were retrofitted in the original Bourne 12231shell and can be assumed to be part of the least common denominator. 12232 12233 On the other hand, if you're using M4sh you can assume that the shell 12234has the features that were added in SVR2 (circa 1984), including shell 12235functions, `return', `unset', and I/O redirection for builtins. For 12236more information, refer to `http://www.in-ulm.de/~mascheck/bourne/'. 12237However, some pitfalls have to be avoided for portable use of these 12238constructs; these will be documented in the rest of this chapter. See 12239in particular *note Shell Functions:: and *note Limitations of Shell 12240Builtins: Limitations of Builtins. 12241 12242 Some ancient systems have quite small limits on the length of the 12243`#!' line; for instance, 32 bytes (not including the newline) on SunOS 122444. However, these ancient systems are no longer of practical concern. 12245 12246 The set of external programs you should run in a `configure' script 12247is fairly small. *Note Utilities in Makefiles: (standards)Utilities in 12248Makefiles, for the list. This restriction allows users to start out 12249with a fairly small set of programs and build the rest, avoiding too 12250many interdependencies between packages. 12251 12252 Some of these external utilities have a portable subset of features; 12253see *note Limitations of Usual Tools::. 12254 12255 There are other sources of documentation about shells. The 12256specification for the Posix Shell Command Language 12257(http://www.opengroup.org/susv3/utilities/xcu_chap02.html), though more 12258generous than the restrictive shell subset described above, is fairly 12259portable nowadays. Also please see the Shell FAQs 12260(http://www.faqs.org/faqs/unix-faq/shell/). 12261 12262* Menu: 12263 12264* Shellology:: A zoology of shells 12265* Invoking the Shell:: Invoking the shell as a command 12266* Here-Documents:: Quirks and tricks 12267* File Descriptors:: FDs and redirections 12268* Signal Handling:: Shells, signals, and headaches 12269* File System Conventions:: File names 12270* Shell Pattern Matching:: Pattern matching 12271* Shell Substitutions:: Variable and command expansions 12272* Assignments:: Varying side effects of assignments 12273* Parentheses:: Parentheses in shell scripts 12274* Slashes:: Slashes in shell scripts 12275* Special Shell Variables:: Variables you should not change 12276* Shell Functions:: What to look out for if you use them 12277* Limitations of Builtins:: Portable use of not so portable /bin/sh 12278* Limitations of Usual Tools:: Portable use of portable tools 12279 12280 12281File: autoconf.info, Node: Shellology, Next: Invoking the Shell, Up: Portable Shell 12282 1228311.1 Shellology 12284=============== 12285 12286There are several families of shells, most prominently the Bourne family 12287and the C shell family which are deeply incompatible. If you want to 12288write portable shell scripts, avoid members of the C shell family. The 12289the Shell difference FAQ 12290(http://www.faqs.org/faqs/unix-faq/shell/shell-differences/) includes a 12291small history of Posix shells, and a comparison between several of them. 12292 12293 Below we describe some of the members of the Bourne shell family. 12294 12295Ash 12296 Ash is often used on GNU/Linux and BSD systems as a light-weight 12297 Bourne-compatible shell. Ash 0.2 has some bugs that are fixed in 12298 the 0.3.x series, but portable shell scripts should work around 12299 them, since version 0.2 is still shipped with many GNU/Linux 12300 distributions. 12301 12302 To be compatible with Ash 0.2: 12303 12304 - don't use `$?' after expanding empty or unset variables, or 12305 at the start of an `eval': 12306 12307 foo= 12308 false 12309 $foo 12310 echo "Do not use it: $?" 12311 false 12312 eval 'echo "Do not use it: $?"' 12313 12314 - don't use command substitution within variable expansion: 12315 12316 cat ${FOO=`bar`} 12317 12318 - beware that single builtin substitutions are not performed by 12319 a subshell, hence their effect applies to the current shell! 12320 *Note Shell Substitutions::, item "Command Substitution". 12321 12322Bash 12323 To detect whether you are running Bash, test whether 12324 `BASH_VERSION' is set. To require Posix compatibility, run `set 12325 -o posix'. *Note Bash Posix Mode: (bash)Bash POSIX Mode, for 12326 details. 12327 12328Bash 2.05 and later 12329 Versions 2.05 and later of Bash use a different format for the 12330 output of the `set' builtin, designed to make evaluating its 12331 output easier. However, this output is not compatible with earlier 12332 versions of Bash (or with many other shells, probably). So if you 12333 use Bash 2.05 or higher to execute `configure', you'll need to use 12334 Bash 2.05 for all other build tasks as well. 12335 12336Ksh 12337 The Korn shell is compatible with the Bourne family and it mostly 12338 conforms to Posix. It has two major variants commonly called 12339 `ksh88' and `ksh93', named after the years of initial release. It 12340 is usually called `ksh', but is called `sh' on some hosts if you 12341 set your path appropriately. 12342 12343 Solaris systems have three variants: `/usr/bin/ksh' is `ksh88'; it 12344 is standard on Solaris 2.0 and later. `/usr/xpg4/bin/sh' is a 12345 Posix-compliant variant of `ksh88'; it is standard on Solaris 9 12346 and later. `/usr/dt/bin/dtksh' is `ksh93'. Variants that are not 12347 standard may be parts of optional packages. There is no extra 12348 charge for these packages, but they are not part of a minimal OS 12349 install and therefore some installations may not have it. 12350 12351 Starting with Tru64 Version 4.0, the Korn shell `/usr/bin/ksh' is 12352 also available as `/usr/bin/posix/sh'. If the environment 12353 variable `BIN_SH' is set to `xpg4', subsidiary invocations of the 12354 standard shell conform to Posix. 12355 12356Pdksh 12357 A public-domain clone of the Korn shell called `pdksh' is widely 12358 available: it has most of the `ksh88' features along with a few of 12359 its own. It usually sets `KSH_VERSION', except if invoked as 12360 `/bin/sh' on OpenBSD, and similarly to Bash you can require Posix 12361 compatibility by running `set -o posix'. Unfortunately, with 12362 `pdksh' 5.2.14 (the latest stable version as of January 2007) 12363 Posix mode is buggy and causes `pdksh' to depart from Posix in at 12364 least one respect, see *note Shell Substitutions::. 12365 12366Zsh 12367 To detect whether you are running `zsh', test whether 12368 `ZSH_VERSION' is set. By default `zsh' is _not_ compatible with 12369 the Bourne shell: you must execute `emulate sh', and for `zsh' 12370 versions before 3.1.6-dev-18 you must also set `NULLCMD' to `:'. 12371 *Note Compatibility: (zsh)Compatibility, for details. 12372 12373 The default Mac OS X `sh' was originally Zsh; it was changed to 12374 Bash in Mac OS X 10.2. 12375 12376 12377File: autoconf.info, Node: Invoking the Shell, Next: Here-Documents, Prev: Shellology, Up: Portable Shell 12378 1237911.2 Invoking the Shell 12380======================= 12381 12382The Korn shell (up to at least version M-12/28/93d) has a bug when 12383invoked on a file whose name does not contain a slash. It first 12384searches for the file's name in `PATH', and if found it executes that 12385rather than the original file. For example, assuming there is a binary 12386executable `/usr/bin/script' in your `PATH', the last command in the 12387following example fails because the Korn shell finds `/usr/bin/script' 12388and refuses to execute it as a shell script: 12389 12390 $ touch xxyzzyz script 12391 $ ksh xxyzzyz 12392 $ ksh ./script 12393 $ ksh script 12394 ksh: script: cannot execute 12395 12396 Bash 2.03 has a bug when invoked with the `-c' option: if the 12397option-argument ends in backslash-newline, Bash incorrectly reports a 12398syntax error. The problem does not occur if a character follows the 12399backslash: 12400 12401 $ $ bash -c 'echo foo \ 12402 > ' 12403 bash: -c: line 2: syntax error: unexpected end of file 12404 $ bash -c 'echo foo \ 12405 > ' 12406 foo 12407 12408*Note Backslash-Newline-Empty::, for how this can cause problems in 12409makefiles. 12410 12411 12412File: autoconf.info, Node: Here-Documents, Next: File Descriptors, Prev: Invoking the Shell, Up: Portable Shell 12413 1241411.3 Here-Documents 12415=================== 12416 12417Don't rely on `\' being preserved just because it has no special 12418meaning together with the next symbol. In the native `sh' on OpenBSD 124192.7 `\"' expands to `"' in here-documents with unquoted delimiter. As 12420a general rule, if `\\' expands to `\' use `\\' to get `\'. 12421 12422 With OpenBSD 2.7's `sh' 12423 12424 $ cat <<EOF 12425 > \" \\ 12426 > EOF 12427 " \ 12428 12429and with Bash: 12430 12431 bash-2.04$ cat <<EOF 12432 > \" \\ 12433 > EOF 12434 \" \ 12435 12436 Using command substitutions in a here-document that is fed to a shell 12437function is not portable. For example, with Solaris 10 `/bin/sh': 12438 12439 $ kitty () { cat; } 12440 $ kitty <<EOF 12441 > `echo ok` 12442 > EOF 12443 /tmp/sh199886: cannot open 12444 $ echo $? 12445 1 12446 12447 Some shells mishandle large here-documents: for example, Solaris 10 12448`dtksh' and the UnixWare 7.1.1 Posix shell, which are derived from Korn 12449shell version M-12/28/93d, mishandle braced variable expansion that 12450crosses a 1024- or 4096-byte buffer boundary within a here-document. 12451Only the part of the variable name after the boundary is used. For 12452example, `${variable}' could be replaced by the expansion of `${ble}'. 12453If the end of the variable name is aligned with the block boundary, the 12454shell reports an error, as if you used `${}'. Instead of 12455`${variable-default}', the shell may expand `${riable-default}', or 12456even `${fault}'. This bug can often be worked around by omitting the 12457braces: `$variable'. The bug was fixed in `ksh93g' (1998-04-30) but as 12458of 2006 many operating systems were still shipping older versions with 12459the bug. 12460 12461 Empty here-documents are not portable either; with the following 12462code, `zsh' up to at least version 4.3.10 creates a file with a single 12463newline, whereas other shells create an empty file: 12464 12465 cat >file <<EOF 12466 EOF 12467 12468 Many shells (including the Bourne shell) implement here-documents 12469inefficiently. In particular, some shells can be extremely inefficient 12470when a single statement contains many here-documents. For instance if 12471your `configure.ac' includes something like: 12472 12473 if <cross_compiling>; then 12474 assume this and that 12475 else 12476 check this 12477 check that 12478 check something else 12479 ... 12480 on and on forever 12481 ... 12482 fi 12483 12484 A shell parses the whole `if'/`fi' construct, creating temporary 12485files for each here-document in it. Some shells create links for such 12486here-documents on every `fork', so that the clean-up code they had 12487installed correctly removes them. It is creating the links that can 12488take the shell forever. 12489 12490 Moving the tests out of the `if'/`fi', or creating multiple 12491`if'/`fi' constructs, would improve the performance significantly. 12492Anyway, this kind of construct is not exactly the typical use of 12493Autoconf. In fact, it's even not recommended, because M4 macros can't 12494look into shell conditionals, so we may fail to expand a macro when it 12495was expanded before in a conditional path, and the condition turned out 12496to be false at runtime, and we end up not executing the macro at all. 12497 12498 Be careful with the use of `<<-' to unindent here-documents. The 12499behavior is only portable for stripping leading <TAB>s, and things can 12500silently break if an overzealous editor converts to using leading 12501spaces (not all shells are nice enough to warn about unterminated 12502here-documents). 12503 12504 $ printf 'cat <<-x\n\t1\n\t 2\n\tx\n' | bash && echo done 12505 1 12506 2 12507 done 12508 $ printf 'cat <<-x\n 1\n 2\n x\n' | bash-3.2 && echo done 12509 1 12510 2 12511 x 12512 done 12513 12514 12515File: autoconf.info, Node: File Descriptors, Next: Signal Handling, Prev: Here-Documents, Up: Portable Shell 12516 1251711.4 File Descriptors 12518===================== 12519 12520Most shells, if not all (including Bash, Zsh, Ash), output traces on 12521stderr, even for subshells. This might result in undesirable content 12522if you meant to capture the standard-error output of the inner command: 12523 12524 $ ash -x -c '(eval "echo foo >&2") 2>stderr' 12525 $ cat stderr 12526 + eval echo foo >&2 12527 + echo foo 12528 foo 12529 $ bash -x -c '(eval "echo foo >&2") 2>stderr' 12530 $ cat stderr 12531 + eval 'echo foo >&2' 12532 ++ echo foo 12533 foo 12534 $ zsh -x -c '(eval "echo foo >&2") 2>stderr' 12535 # Traces on startup files deleted here. 12536 $ cat stderr 12537 +zsh:1> eval echo foo >&2 12538 +zsh:1> echo foo 12539 foo 12540 12541One workaround is to grep out uninteresting lines, hoping not to remove 12542good ones. 12543 12544 If you intend to redirect both standard error and standard output, 12545redirect standard output first. This works better with HP-UX, since 12546its shell mishandles tracing if standard error is redirected first: 12547 12548 $ sh -x -c ': 2>err >out' 12549 + : 12550 + 2> err $ cat err 12551 1> out 12552 12553 Don't try to redirect the standard error of a command substitution. 12554It must be done _inside_ the command substitution. When running `: `cd 12555/zorglub` 2>/dev/null' expect the error message to escape, while `: `cd 12556/zorglub 2>/dev/null`' works properly. 12557 12558 On the other hand, some shells, such as Solaris or FreeBSD 12559`/bin/sh', warn about missing programs before performing redirections. 12560Therefore, to silently check whether a program exists, it is necessary 12561to perform redirections on a subshell or brace group: 12562 $ /bin/sh -c 'nosuch 2>/dev/null' 12563 nosuch: not found 12564 $ /bin/sh -c '(nosuch) 2>/dev/null' 12565 $ /bin/sh -c '{ nosuch; } 2>/dev/null' 12566 $ bash -c 'nosuch 2>/dev/null' 12567 12568 FreeBSD 6.2 sh may mix the trace output lines from the statements in 12569a shell pipeline. 12570 12571 It is worth noting that Zsh (but not Ash nor Bash) makes it possible 12572in assignments though: `foo=`cd /zorglub` 2>/dev/null'. 12573 12574 Some shells, like `ash', don't recognize bi-directional redirection 12575(`<>'). And even on shells that recognize it, it is not portable to 12576use on fifos: Posix does not require read-write support for named 12577pipes, and Cygwin does not support it: 12578 12579 $ mkfifo fifo 12580 $ exec 5<>fifo 12581 $ echo hi >&5 12582 bash: echo: write error: Communication error on send 12583 12584Furthermore, versions of `dash' before 0.5.6 mistakenly truncate 12585regular files when using `<>': 12586 12587 $ echo a > file 12588 $ bash -c ': 1<>file'; cat file 12589 a 12590 $ dash -c ': 1<>file'; cat file 12591 $ rm a 12592 12593 When catering to old systems, don't redirect the same file descriptor 12594several times, as you are doomed to failure under Ultrix. 12595 12596 ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995 12597 UWS V4.4 (Rev. 11) 12598 $ eval 'echo matter >fullness' >void 12599 illegal io 12600 $ eval '(echo matter >fullness)' >void 12601 illegal io 12602 $ (eval '(echo matter >fullness)') >void 12603 Ambiguous output redirect. 12604 12605In each case the expected result is of course `fullness' containing 12606`matter' and `void' being empty. However, this bug is probably not of 12607practical concern to modern platforms. 12608 12609 Solaris 10 `sh' will try to optimize away a `:' command (even if it 12610is redirected) in a loop after the first iteration, or in a shell 12611function after the first call: 12612 12613 $ for i in 1 2 3 ; do : >x$i; done 12614 $ ls x* 12615 x1 12616 $ f () { : >$1; }; f y1; f y2; f y3; 12617 $ ls y* 12618 y1 12619 12620As a workaround, `echo' or `eval' can be used. 12621 12622 Don't rely on file descriptors 0, 1, and 2 remaining closed in a 12623subsidiary program. If any of these descriptors is closed, the 12624operating system may open an unspecified file for the descriptor in the 12625new process image. Posix 2008 says this may be done only if the 12626subsidiary program is set-user-ID or set-group-ID, but HP-UX 11.23 does 12627it even for ordinary programs, and the next version of Posix will allow 12628HP-UX behavior. 12629 12630 If you want a file descriptor above 2 to be inherited into a child 12631process, then you must use redirections specific to that command or a 12632containing subshell or command group, rather than relying on `exec' in 12633the shell. In `ksh' as well as HP-UX `sh', file descriptors above 2 12634which are opened using `exec N>file' are closed by a subsequent `exec' 12635(such as that involved in the fork-and-exec which runs a program or 12636script): 12637 12638 $ echo 'echo hello >&5' >k 12639 $ /bin/sh -c 'exec 5>t; ksh ./k; exec 5>&-; cat t 12640 hello 12641 $ bash -c 'exec 5>t; ksh ./k; exec 5>&-; cat t 12642 hello 12643 $ ksh -c 'exec 5>t; ksh ./k; exec 5>&-; cat t 12644 ./k[1]: 5: cannot open [Bad file number] 12645 $ ksh -c '(ksh ./k) 5>t; cat t' 12646 hello 12647 $ ksh -c '{ ksh ./k; } 5>t; cat t' 12648 hello 12649 $ ksh -c '5>t ksh ./k; cat t 12650 hello 12651 12652 Don't rely on duplicating a closed file descriptor to cause an 12653error. With Solaris `/bin/sh', failed duplication is silently ignored, 12654which can cause unintended leaks to the original file descriptor. In 12655this example, observe the leak to standard output: 12656 12657 $ bash -c 'echo hi >&3' 3>&-; echo $? 12658 bash: 3: Bad file descriptor 12659 1 12660 $ /bin/sh -c 'echo hi >&3' 3>&-; echo $? 12661 hi 12662 0 12663 12664 Fortunately, an attempt to close an already closed file descriptor 12665will portably succeed. Likewise, it is safe to use either style of 12666`N<&-' or `N>&-' for closing a file descriptor, even if it doesn't 12667match the read/write mode that the file descriptor was opened with. 12668 12669 DOS variants cannot rename or remove open files, such as in `mv foo 12670bar >foo' or `rm foo >foo', even though this is perfectly portable 12671among Posix hosts. 12672 12673 A few ancient systems reserved some file descriptors. By convention, 12674file descriptor 3 was opened to `/dev/tty' when you logged into Eighth 12675Edition (1985) through Tenth Edition Unix (1989). File descriptor 4 12676had a special use on the Stardent/Kubota Titan (circa 1990), though we 12677don't now remember what it was. Both these systems are obsolete, so 12678it's now safe to treat file descriptors 3 and 4 like any other file 12679descriptors. 12680 12681 On the other hand, you can't portably use multi-digit file 12682descriptors. Solaris `ksh' doesn't understand any file descriptor 12683larger than `9': 12684 12685 $ bash -c 'exec 10>&-'; echo $? 12686 0 12687 $ ksh -c 'exec 9>&-'; echo $? 12688 0 12689 $ ksh -c 'exec 10>&-'; echo $? 12690 ksh[1]: exec: 10: not found 12691 127 12692 12693 12694File: autoconf.info, Node: Signal Handling, Next: File System Conventions, Prev: File Descriptors, Up: Portable Shell 12695 1269611.5 Signal Handling 12697==================== 12698 12699Portable handling of signals within the shell is another major source of 12700headaches. This is worsened by the fact that various different, 12701mutually incompatible approaches are possible in this area, each with 12702its distinctive merits and demerits. A detailed description of these 12703possible approaches, as well as of their pros and cons, can be found in 12704this article (http://www.cons.org/cracauer/sigint.html). 12705 12706 Solaris 10 `/bin/sh' automatically traps most signals by default; 12707the shell still exits with error upon termination by one of those 12708signals, but in such a case the exit status might be somewhat 12709unexpected (even if allowed by POSIX, strictly speaking): 12710 12711 $ bash -c 'kill -1 $$'; echo $? # Will exit 128 + (signal number). 12712 Hangup 12713 129 12714 $ /bin/ksh -c 'kill -15 $$'; echo $? # Likewise. 12715 Terminated 12716 143 12717 $ for sig in 1 2 3 15; do 12718 > echo $sig: 12719 > /bin/sh -c "kill -$s \$\$"; echo $? 12720 > done 12721 signal 1: 12722 Hangup 12723 129 12724 signal 2: 12725 208 12726 signal 3: 12727 208 12728 signal 15: 12729 208 12730 12731 This gets even worse if one is using the POSIX `wait' interface to 12732get details about the shell process terminations: it will result in the 12733shell having exited normally, rather than by receiving a signal. 12734 12735 $ cat > foo.c <<'END' 12736 #include <stdio.h> /* for printf */ 12737 #include <stdlib.h> /* for system */ 12738 #include <sys/wait.h> /* for WIF* macros */ 12739 int main(void) 12740 { 12741 int status = system ("kill -15 $$"); 12742 printf ("Terminated by signal: %s\n", 12743 WIFSIGNALED (status) ? "yes" : "no"); 12744 printf ("Exited normally: %s\n", 12745 WIFEXITED (status) ? "yes" : "no"); 12746 return 0; 12747 } 12748 END 12749 $ cc -o foo foo.c 12750 $ ./a.out # On GNU/Linux 12751 Terminated by signal: no 12752 Exited normally: yes 12753 $ ./a.out # On Solaris 10 12754 Terminated by signal: yes 12755 Exited normally: no 12756 12757 Various shells seem to handle `SIGQUIT' specially: they ignore it 12758even if it is not blocked, and even if the shell is not running 12759interactively (in fact, even if the shell has no attached tty); among 12760these shells are at least Bash (from version 2 onwards), Zsh 4.3.12, 12761Solaris 10 `/bin/ksh' and `/usr/xpg4/bin/sh', and AT&T `ksh93' (2011). 12762Still, `SIGQUIT' seems to be trappable quite portably within all these 12763shells. OTOH, some other shells doesn't special-case the handling of 12764`SIGQUIT'; among these shells are at least `pdksh' 5.2.14, Solaris 10 12765and NetBSD 5.1 `/bin/sh', and the Almquist Shell 0.5.5.1. 12766 12767 Some shells (especially Korn shells and derivatives) might try to 12768propagate to themselves a signal that has killed a child process; this 12769is not a bug, but a conscious design choice (although its overall value 12770might be debatable). The exact details of how this is attained vary 12771from shell to shell. For example, upon running `perl -e 'kill 2, $$'', 12772after the perl process has been interrupted AT&T `ksh93' (2011) will 12773proceed to send itself a `SIGINT', while Solaris 10 `/bin/ksh' and 12774`/usr/xpg4/bin/sh' will proceed to exit with status 130 (i.e., 128 + 127752). In any case, if there is an active trap associated with `SIGINT', 12776those shells will correctly execute it. 12777 12778 Some Korn shells, when a child process die due receiving a signal 12779with signal number N, can leave in `$?' an exit status of 256+N instead 12780of the more common 128+N. Observe the difference between AT&T `ksh93' 12781(2011) and `bash' 4.1.5 on Debian: 12782 12783 $ /bin/ksh -c 'sh -c "kill -1 \$\$"; echo $?' 12784 /bin/ksh: line 1: 7837: Hangup 12785 257 12786 $ /bin/bash -c 'sh -c "kill -1 \$\$"; echo $?' 12787 /bin/bash: line 1: 7861 Hangup (sh -c "kill -1 \$\$") 12788 129 12789 12790This `ksh' behavior is allowed by POSIX, if implemented with due care; 12791see this Austin Group discussion 12792(http://www.austingroupbugs.net/view.php?id=51) for more background. 12793However, if it is not implemented with proper care, such a behavior 12794might cause problems in some corner cases. To see why, assume we have 12795a "wrapper" script like this: 12796 12797 #!/bin/sh 12798 # Ignore some signals in the shell only, not in its child processes. 12799 trap : 1 2 13 15 12800 wrapped_command "$@" 12801 ret=$? 12802 other_command 12803 exit $ret 12804 12805If `wrapped_command' is interrupted by a `SIGHUP' (which has signal 12806number 1), `ret' will be set to 257. Unless the `exit' shell builtin 12807is smart enough to understand that such a value can only have 12808originated from a signal, and adjust the final wait status of the shell 12809appropriately, the value 257 will just get truncated to 1 by the 12810closing `exit' call, so that a caller of the script will have no way to 12811determine that termination by a signal was involved. Observe the 12812different behavior of AT&T `ksh93' (2011) and `bash' 4.1.5 on Debian: 12813 12814 $ cat foo.sh 12815 #!/bin/sh 12816 sh -c 'kill -1 $$' 12817 ret=$? 12818 echo $ret 12819 exit $ret 12820 $ /bin/ksh foo.sh; echo $? 12821 foo.sh: line 2: 12479: Hangup 12822 257 12823 1 12824 $ /bin/bash foo.sh; echo $? 12825 foo.sh: line 2: 12487 Hangup (sh -c 'kill -1 $$') 12826 129 12827 129 12828 12829 12830File: autoconf.info, Node: File System Conventions, Next: Shell Pattern Matching, Prev: Signal Handling, Up: Portable Shell 12831 1283211.6 File System Conventions 12833============================ 12834 12835Autoconf uses shell-script processing extensively, so the file names 12836that it processes should not contain characters that are special to the 12837shell. Special characters include space, tab, newline, NUL, and the 12838following: 12839 12840 " # $ & ' ( ) * ; < = > ? [ \ ` | 12841 12842 Also, file names should not begin with `~' or `-', and should 12843contain neither `-' immediately after `/' nor `~' immediately after 12844`:'. On Posix-like platforms, directory names should not contain `:', 12845as this runs afoul of `:' used as the path separator. 12846 12847 These restrictions apply not only to the files that you distribute, 12848but also to the absolute file names of your source, build, and 12849destination directories. 12850 12851 On some Posix-like platforms, `!' and `^' are special too, so they 12852should be avoided. 12853 12854 Posix lets implementations treat leading `//' specially, but 12855requires leading `///' and beyond to be equivalent to `/'. Most Unix 12856variants treat `//' like `/'. However, some treat `//' as a 12857"super-root" that can provide access to files that are not otherwise 12858reachable from `/'. The super-root tradition began with Apollo 12859Domain/OS, which died out long ago, but unfortunately Cygwin has 12860revived it. 12861 12862 While `autoconf' and friends are usually run on some Posix variety, 12863they can be used on other systems, most notably DOS variants. This 12864impacts several assumptions regarding file names. 12865 12866For example, the following code: 12867 12868 case $foo_dir in 12869 /*) # Absolute 12870 ;; 12871 *) 12872 foo_dir=$dots$foo_dir ;; 12873 esac 12874 12875fails to properly detect absolute file names on those systems, because 12876they can use a drivespec, and usually use a backslash as directory 12877separator. If you want to be portable to DOS variants (at the price of 12878rejecting valid but oddball Posix file names like `a:\b'), you can 12879check for absolute file names like this: 12880 12881 case $foo_dir in 12882 [\\/]* | ?:[\\/]* ) # Absolute 12883 ;; 12884 *) 12885 foo_dir=$dots$foo_dir ;; 12886 esac 12887 12888Make sure you quote the brackets if appropriate and keep the backslash 12889as first character (*note Limitations of Shell Builtins: case.). 12890 12891 Also, because the colon is used as part of a drivespec, these 12892systems don't use it as path separator. When creating or accessing 12893paths, you can use the `PATH_SEPARATOR' output variable instead. 12894`configure' sets this to the appropriate value for the build system 12895(`:' or `;') when it starts up. 12896 12897 File names need extra care as well. While DOS variants that are 12898Posixy enough to run `autoconf' (such as DJGPP) are usually able to 12899handle long file names properly, there are still limitations that can 12900seriously break packages. Several of these issues can be easily 12901detected by the doschk 12902(ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz) package. 12903 12904 A short overview follows; problems are marked with SFN/LFN to 12905indicate where they apply: SFN means the issues are only relevant to 12906plain DOS, not to DOS under Microsoft Windows variants, while LFN 12907identifies problems that exist even under Microsoft Windows variants. 12908 12909No multiple dots (SFN) 12910 DOS cannot handle multiple dots in file names. This is an 12911 especially important thing to remember when building a portable 12912 configure script, as `autoconf' uses a .in suffix for template 12913 files. 12914 12915 This is perfectly OK on Posix variants: 12916 12917 AC_CONFIG_HEADERS([config.h]) 12918 AC_CONFIG_FILES([source.c foo.bar]) 12919 AC_OUTPUT 12920 12921 but it causes problems on DOS, as it requires `config.h.in', 12922 `source.c.in' and `foo.bar.in'. To make your package more portable 12923 to DOS-based environments, you should use this instead: 12924 12925 AC_CONFIG_HEADERS([config.h:config.hin]) 12926 AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in]) 12927 AC_OUTPUT 12928 12929No leading dot (SFN) 12930 DOS cannot handle file names that start with a dot. This is 12931 usually not important for `autoconf'. 12932 12933Case insensitivity (LFN) 12934 DOS is case insensitive, so you cannot, for example, have both a 12935 file called `INSTALL' and a directory called `install'. This also 12936 affects `make'; if there's a file called `INSTALL' in the 12937 directory, `make install' does nothing (unless the `install' 12938 target is marked as PHONY). 12939 12940The 8+3 limit (SFN) 12941 Because the DOS file system only stores the first 8 characters of 12942 the file name and the first 3 of the extension, those must be 12943 unique. That means that `foobar-part1.c', `foobar-part2.c' and 12944 `foobar-prettybird.c' all resolve to the same file name 12945 (`FOOBAR-P.C'). The same goes for `foo.bar' and `foo.bartender'. 12946 12947 The 8+3 limit is not usually a problem under Microsoft Windows, as 12948 it uses numeric tails in the short version of file names to make 12949 them unique. However, a registry setting can turn this behavior 12950 off. While this makes it possible to share file trees containing 12951 long file names between SFN and LFN environments, it also means 12952 the above problem applies there as well. 12953 12954Invalid characters (LFN) 12955 Some characters are invalid in DOS file names, and should therefore 12956 be avoided. In a LFN environment, these are `/', `\', `?', `*', 12957 `:', `<', `>', `|' and `"'. In a SFN environment, other 12958 characters are also invalid. These include `+', `,', `[' and `]'. 12959 12960Invalid names (LFN) 12961 Some DOS file names are reserved, and cause problems if you try to 12962 use files with those names. These names include `CON', `AUX', 12963 `COM1', `COM2', `COM3', `COM4', `LPT1', `LPT2', `LPT3', `NUL', and 12964 `PRN'. File names are case insensitive, so even names like 12965 `aux/config.guess' are disallowed. 12966 12967 12968 12969File: autoconf.info, Node: Shell Pattern Matching, Next: Shell Substitutions, Prev: File System Conventions, Up: Portable Shell 12970 1297111.7 Shell Pattern Matching 12972=========================== 12973 12974Nowadays portable patterns can use negated character classes like 12975`[!-aeiou]'. The older syntax `[^-aeiou]' is supported by some shells 12976but not others; hence portable scripts should never use `^' as the 12977first character of a bracket pattern. 12978 12979 Outside the C locale, patterns like `[a-z]' are problematic since 12980they may match characters that are not lower-case letters. 12981 12982 12983File: autoconf.info, Node: Shell Substitutions, Next: Assignments, Prev: Shell Pattern Matching, Up: Portable Shell 12984 1298511.8 Shell Substitutions 12986======================== 12987 12988Contrary to a persistent urban legend, the Bourne shell does not 12989systematically split variables and back-quoted expressions, in 12990particular on the right-hand side of assignments and in the argument of 12991`case'. For instance, the following code: 12992 12993 case "$given_srcdir" in 12994 .) top_srcdir="`echo "$dots" | sed 's|/$||'`" ;; 12995 *) top_srcdir="$dots$given_srcdir" ;; 12996 esac 12997 12998is more readable when written as: 12999 13000 case $given_srcdir in 13001 .) top_srcdir=`echo "$dots" | sed 's|/$||'` ;; 13002 *) top_srcdir=$dots$given_srcdir ;; 13003 esac 13004 13005and in fact it is even _more_ portable: in the first case of the first 13006attempt, the computation of `top_srcdir' is not portable, since not all 13007shells properly understand `"`..."..."...`"', for example Solaris 10 13008ksh: 13009 13010 $ foo="`echo " bar" | sed 's, ,,'`" 13011 ksh: : cannot execute 13012 ksh: bar | sed 's, ,,': cannot execute 13013 13014Posix does not specify behavior for this sequence. On the other hand, 13015behavior for `"`...\"...\"...`"' is specified by Posix, but in 13016practice, not all shells understand it the same way: pdksh 5.2.14 13017prints spurious quotes when in Posix mode: 13018 13019 $ echo "`echo \"hello\"`" 13020 hello 13021 $ set -o posix 13022 $ echo "`echo \"hello\"`" 13023 "hello" 13024 13025There is just no portable way to use double-quoted strings inside 13026double-quoted back-quoted expressions (pfew!). 13027 13028 Bash 4.1 has a bug where quoted empty strings adjacent to unquoted 13029parameter expansions are elided during word splitting. Meanwhile, zsh 13030does not perform word splitting except when in Bourne compatibility 13031mode. In the example below, the correct behavior is to have five 13032arguments to the function, and exactly two spaces on either side of the 13033middle `-', since word splitting collapses multiple spaces in `$f' but 13034leaves empty arguments intact. 13035 13036 $ bash -c 'n() { echo "$#$@"; }; f=" - "; n - ""$f"" -' 13037 3- - - 13038 $ ksh -c 'n() { echo "$#$@"; }; f=" - "; n - ""$f"" -' 13039 5- - - 13040 $ zsh -c 'n() { echo "$#$@"; }; f=" - "; n - ""$f"" -' 13041 3- - - 13042 $ zsh -c 'emulate sh; 13043 > n() { echo "$#$@"; }; f=" - "; n - ""$f"" -' 13044 5- - - 13045 13046You can work around this by doing manual word splitting, such as using 13047`"$str" $list' rather than `"$str"$list'. 13048 13049 There are also portability pitfalls with particular expansions: 13050 13051`$@' 13052 One of the most famous shell-portability issues is related to 13053 `"$@"'. When there are no positional arguments, Posix says that 13054 `"$@"' is supposed to be equivalent to nothing, but the original 13055 Unix version 7 Bourne shell treated it as equivalent to `""' 13056 instead, and this behavior survives in later implementations like 13057 Digital Unix 5.0. 13058 13059 The traditional way to work around this portability problem is to 13060 use `${1+"$@"}'. Unfortunately this method does not work with Zsh 13061 (3.x and 4.x), which is used on Mac OS X. When emulating the 13062 Bourne shell, Zsh performs word splitting on `${1+"$@"}': 13063 13064 zsh $ emulate sh 13065 zsh $ for i in "$@"; do echo $i; done 13066 Hello World 13067 ! 13068 zsh $ for i in ${1+"$@"}; do echo $i; done 13069 Hello 13070 World 13071 ! 13072 13073 Zsh handles plain `"$@"' properly, but we can't use plain `"$@"' 13074 because of the portability problems mentioned above. One 13075 workaround relies on Zsh's "global aliases" to convert `${1+"$@"}' 13076 into `"$@"' by itself: 13077 13078 test "${ZSH_VERSION+set}" = set && alias -g '${1+"$@"}'='"$@"' 13079 13080 Zsh only recognizes this alias when a shell word matches it 13081 exactly; `"foo"${1+"$@"}' remains subject to word splitting. 13082 Since this case always yields at least one shell word, use plain 13083 `"$@"'. 13084 13085 A more conservative workaround is to avoid `"$@"' if it is 13086 possible that there may be no positional arguments. For example, 13087 instead of: 13088 13089 cat conftest.c "$@" 13090 13091 you can use this instead: 13092 13093 case $# in 13094 0) cat conftest.c;; 13095 *) cat conftest.c "$@";; 13096 esac 13097 13098 Autoconf macros often use the `set' command to update `$@', so if 13099 you are writing shell code intended for `configure' you should not 13100 assume that the value of `$@' persists for any length of time. 13101 13102`${10}' 13103 The 10th, 11th, ... positional parameters can be accessed only 13104 after a `shift'. The 7th Edition shell reported an error if given 13105 `${10}', and Solaris 10 `/bin/sh' still acts that way: 13106 13107 $ set 1 2 3 4 5 6 7 8 9 10 13108 $ echo ${10} 13109 bad substitution 13110 13111 Conversely, not all shells obey the Posix rule that when braces are 13112 omitted, multiple digits beyond a `$' imply the single-digit 13113 positional parameter expansion concatenated with the remaining 13114 literal digits. To work around the issue, you must use braces. 13115 13116 $ bash -c 'set a b c d e f g h i j; echo $10 ${1}0' 13117 a0 a0 13118 $ dash -c 'set a b c d e f g h i j; echo $10 ${1}0' 13119 j a0 13120 13121`${VAR:-VALUE}' 13122 Old BSD shells, including the Ultrix `sh', don't accept the colon 13123 for any shell substitution, and complain and die. Similarly for 13124 ${VAR:=VALUE}, ${VAR:?VALUE}, etc. However, all shells that 13125 support functions allow the use of colon in shell substitution, 13126 and since m4sh requires functions, you can portably use null 13127 variable substitution patterns in configure scripts. 13128 13129`${VAR+VALUE}' 13130 When using `${VAR-VALUE}' or `${VAR-VALUE}' for providing 13131 alternate substitutions, VALUE must either be a single shell word, 13132 quoted, or in the context of an unquoted here-document. Solaris 13133 `/bin/sh' complains otherwise. 13134 13135 $ /bin/sh -c 'echo ${a-b c}' 13136 /bin/sh: bad substitution 13137 $ /bin/sh -c 'echo ${a-'\''b c'\''}' 13138 b c 13139 $ /bin/sh -c 'echo "${a-b c}"' 13140 b c 13141 $ /bin/sh -c 'cat <<EOF 13142 ${a-b c} 13143 EOF 13144 b c 13145 13146 According to Posix, if an expansion occurs inside double quotes, 13147 then the use of unquoted double quotes within VALUE is 13148 unspecified, and any single quotes become literal characters; in 13149 that case, escaping must be done with backslash. Likewise, the 13150 use of unquoted here-documents is a case where double quotes have 13151 unspecified results: 13152 13153 $ /bin/sh -c 'echo "${a-"b c"}"' 13154 /bin/sh: bad substitution 13155 $ ksh -c 'echo "${a-"b c"}"' 13156 b c 13157 $ bash -c 'echo "${a-"b c"}"' 13158 b c 13159 $ /bin/sh -c 'a=; echo ${a+'\''b c'\''}' 13160 b c 13161 $ /bin/sh -c 'a=; echo "${a+'\''b c'\''}"' 13162 'b c' 13163 $ /bin/sh -c 'a=; echo "${a+\"b c\"}"' 13164 "b c" 13165 $ /bin/sh -c 'a=; echo "${a+b c}"' 13166 b c 13167 $ /bin/sh -c 'cat <<EOF 13168 ${a-"b c"} 13169 EOF' 13170 "b c" 13171 $ /bin/sh -c 'cat <<EOF 13172 ${a-'b c'} 13173 EOF' 13174 'b c' 13175 $ bash -c 'cat <<EOF 13176 ${a-"b c"} 13177 EOF' 13178 b c 13179 $ bash -c 'cat <<EOF 13180 ${a-'b c'} 13181 EOF' 13182 'b c' 13183 13184 Perhaps the easiest way to work around quoting issues in a manner 13185 portable to all shells is to place the results in a temporary 13186 variable, then use `$t' as the VALUE, rather than trying to inline 13187 the expression needing quoting. 13188 13189 $ /bin/sh -c 't="b c\"'\''}\\"; echo "${a-$t}"' 13190 b c"'}\ 13191 $ ksh -c 't="b c\"'\''}\\"; echo "${a-$t}"' 13192 b c"'}\ 13193 $ bash -c 't="b c\"'\''}\\"; echo "${a-$t}"' 13194 b c"'}\ 13195 13196`${VAR=VALUE}' 13197 When using `${VAR=VALUE}' to assign a default value to VAR, 13198 remember that even though the assignment to VAR does not undergo 13199 file name expansion, the result of the variable expansion does 13200 unless the expansion occurred within double quotes. In particular, 13201 when using `:' followed by unquoted variable expansion for the 13202 side effect of setting a default value, if the final value of 13203 `$var' contains any globbing characters (either from VALUE or from 13204 prior contents), the shell has to spend time performing file name 13205 expansion and field splitting even though those results will not be 13206 used. Therefore, it is a good idea to consider double quotes when 13207 performing default initialization; while remembering how this 13208 impacts any quoting characters appearing in VALUE. 13209 13210 $ time bash -c ': "${a=/usr/bin/*}"; echo "$a"' 13211 /usr/bin/* 13212 13213 real 0m0.005s 13214 user 0m0.002s 13215 sys 0m0.003s 13216 $ time bash -c ': ${a=/usr/bin/*}; echo "$a"' 13217 /usr/bin/* 13218 13219 real 0m0.039s 13220 user 0m0.026s 13221 sys 0m0.009s 13222 $ time bash -c 'a=/usr/bin/*; : ${a=noglob}; echo "$a"' 13223 /usr/bin/* 13224 13225 real 0m0.031s 13226 user 0m0.020s 13227 sys 0m0.010s 13228 13229 $ time bash -c 'a=/usr/bin/*; : "${a=noglob}"; echo "$a"' 13230 /usr/bin/* 13231 13232 real 0m0.006s 13233 user 0m0.002s 13234 sys 0m0.003s 13235 13236 As with `+' and `-', you must use quotes when using `=' if the 13237 VALUE contains more than one shell word; either single quotes for 13238 just the VALUE, or double quotes around the entire expansion: 13239 13240 $ : ${var1='Some words'} 13241 $ : "${var2=like this}" 13242 $ echo $var1 $var2 13243 Some words like this 13244 13245 otherwise some shells, such as Solaris `/bin/sh' or on Digital 13246 Unix V 5.0, die because of a "bad substitution". Meanwhile, Posix 13247 requires that with `=', quote removal happens prior to the 13248 assignment, and the expansion be the final contents of VAR without 13249 quoting (and thus subject to field splitting), in contrast to the 13250 behavior with `-' passing the quoting through to the final 13251 expansion. However, `bash' 4.1 does not obey this rule. 13252 13253 $ ksh -c 'echo ${var-a\ \ b}' 13254 a b 13255 $ ksh -c 'echo ${var=a\ \ b}' 13256 a b 13257 $ bash -c 'echo ${var=a\ \ b}' 13258 a b 13259 13260 Finally, Posix states that when mixing `${a=b}' with regular 13261 commands, it is unspecified whether the assignments affect the 13262 parent shell environment. It is best to perform assignments 13263 independently from commands, to avoid the problems demonstrated in 13264 this example: 13265 13266 $ bash -c 'x= y=${x:=b} sh -c "echo +\$x+\$y+";echo -$x-' 13267 +b+b+ 13268 -b- 13269 $ /bin/sh -c 'x= y=${x:=b} sh -c "echo +\$x+\$y+";echo -$x-' 13270 ++b+ 13271 -- 13272 $ ksh -c 'x= y=${x:=b} sh -c "echo +\$x+\$y+";echo -$x-' 13273 +b+b+ 13274 -- 13275 13276`${VAR=VALUE}' 13277 Solaris `/bin/sh' has a frightening bug in its handling of literal 13278 assignments. Imagine you need set a variable to a string 13279 containing `}'. This `}' character confuses Solaris `/bin/sh' 13280 when the affected variable was already set. This bug can be 13281 exercised by running: 13282 13283 $ unset foo 13284 $ foo=${foo='}'} 13285 $ echo $foo 13286 } 13287 $ foo=${foo='}' # no error; this hints to what the bug is 13288 $ echo $foo 13289 } 13290 $ foo=${foo='}'} 13291 $ echo $foo 13292 }} 13293 ^ ugh! 13294 13295 It seems that `}' is interpreted as matching `${', even though it 13296 is enclosed in single quotes. The problem doesn't happen using 13297 double quotes, or when using a temporary variable holding the 13298 problematic string. 13299 13300`${VAR=EXPANDED-VALUE}' 13301 On Ultrix, running 13302 13303 default="yu,yaa" 13304 : ${var="$default"} 13305 13306 sets VAR to `M-yM-uM-,M-yM-aM-a', i.e., the 8th bit of each char 13307 is set. You don't observe the phenomenon using a simple `echo 13308 $var' since apparently the shell resets the 8th bit when it 13309 expands $var. Here are two means to make this shell confess its 13310 sins: 13311 13312 $ cat -v <<EOF 13313 $var 13314 EOF 13315 13316 and 13317 13318 $ set | grep '^var=' | cat -v 13319 13320 One classic incarnation of this bug is: 13321 13322 default="a b c" 13323 : ${list="$default"} 13324 for c in $list; do 13325 echo $c 13326 done 13327 13328 You'll get `a b c' on a single line. Why? Because there are no 13329 spaces in `$list': there are `M- ', i.e., spaces with the 8th bit 13330 set, hence no IFS splitting is performed!!! 13331 13332 One piece of good news is that Ultrix works fine with `: 13333 ${list=$default}'; i.e., if you _don't_ quote. The bad news is 13334 then that QNX 4.25 then sets LIST to the _last_ item of DEFAULT! 13335 13336 The portable way out consists in using a double assignment, to 13337 switch the 8th bit twice on Ultrix: 13338 13339 list=${list="$default"} 13340 13341 ...but beware of the `}' bug from Solaris (see above). For safety, 13342 use: 13343 13344 test "${var+set}" = set || var={VALUE} 13345 13346`${#VAR}' 13347`${VAR%WORD}' 13348`${VAR%%WORD}' 13349`${VAR#WORD}' 13350`${VAR##WORD}' 13351 Posix requires support for these usages, but they do not work with 13352 many traditional shells, e.g., Solaris 10 `/bin/sh'. 13353 13354 Also, `pdksh' 5.2.14 mishandles some WORD forms. For example if 13355 `$1' is `a/b' and `$2' is `a', then `${1#$2}' should yield `/b', 13356 but with `pdksh' it yields the empty string. 13357 13358``COMMANDS`' 13359 Posix requires shells to trim all trailing newlines from command 13360 output before substituting it, so assignments like `dir=`echo 13361 "$file" | tr a A`' do not work as expected if `$file' ends in a 13362 newline. 13363 13364 While in general it makes no sense, do not substitute a single 13365 builtin with side effects, because Ash 0.2, trying to optimize, 13366 does not fork a subshell to perform the command. 13367 13368 For instance, if you wanted to check that `cd' is silent, do not 13369 use `test -z "`cd /`"' because the following can happen: 13370 13371 $ pwd 13372 /tmp 13373 $ test -z "`cd /`" && pwd 13374 / 13375 13376 The result of `foo=`exit 1`' is left as an exercise to the reader. 13377 13378 The MSYS shell leaves a stray byte in the expansion of a 13379 double-quoted command substitution of a native program, if the end 13380 of the substitution is not aligned with the end of the double 13381 quote. This may be worked around by inserting another pair of 13382 quotes: 13383 13384 $ echo "`printf 'foo\r\n'` bar" > broken 13385 $ echo "`printf 'foo\r\n'`"" bar" | cmp - broken 13386 - broken differ: char 4, line 1 13387 13388 Upon interrupt or SIGTERM, some shells may abort a command 13389 substitution, replace it with a null string, and wrongly evaluate 13390 the enclosing command before entering the trap or ending the 13391 script. This can lead to spurious errors: 13392 13393 $ sh -c 'if test `sleep 5; echo hi` = hi; then echo yes; fi' 13394 $ ^C 13395 sh: test: hi: unexpected operator/operand 13396 13397 You can avoid this by assigning the command substitution to a 13398 temporary variable: 13399 13400 $ sh -c 'res=`sleep 5; echo hi` 13401 if test "x$res" = xhi; then echo yes; fi' 13402 $ ^C 13403 13404`$(COMMANDS)' 13405 This construct is meant to replace ``COMMANDS`', and it has most 13406 of the problems listed under ``COMMANDS`'. 13407 13408 This construct can be nested while this is impossible to do 13409 portably with back quotes. Unfortunately it is not yet 13410 universally supported. Most notably, even recent releases of 13411 Solaris don't support it: 13412 13413 $ showrev -c /bin/sh | grep version 13414 Command version: SunOS 5.10 Generic 121005-03 Oct 2006 13415 $ echo $(echo blah) 13416 syntax error: `(' unexpected 13417 13418 nor does IRIX 6.5's Bourne shell: 13419 $ uname -a 13420 IRIX firebird-image 6.5 07151432 IP22 13421 $ echo $(echo blah) 13422 $(echo blah) 13423 13424 If you do use `$(COMMANDS)', make sure that the commands do not 13425 start with a parenthesis, as that would cause confusion with a 13426 different notation `$((EXPRESSION))' that in modern shells is an 13427 arithmetic expression not a command. To avoid the confusion, 13428 insert a space between the two opening parentheses. 13429 13430 Avoid COMMANDS that contain unbalanced parentheses in 13431 here-documents, comments, or case statement patterns, as many 13432 shells mishandle them. For example, Bash 3.1, `ksh88', `pdksh' 13433 5.2.14, and Zsh 4.2.6 all mishandle the following valid command: 13434 13435 echo $(case x in x) echo hello;; esac) 13436 13437`$((EXPRESSION))' 13438 Arithmetic expansion is not portable as some shells (most notably 13439 Solaris 10 `/bin/sh') don't support it. 13440 13441 Among shells that do support `$(( ))', not all of them obey the 13442 Posix rule that octal and hexadecimal constants must be recognized: 13443 13444 $ bash -c 'echo $(( 010 + 0x10 ))' 13445 24 13446 $ zsh -c 'echo $(( 010 + 0x10 ))' 13447 26 13448 $ zsh -c 'emulate sh; echo $(( 010 + 0x10 ))' 13449 24 13450 $ pdksh -c 'echo $(( 010 + 0x10 ))' 13451 pdksh: 010 + 0x10 : bad number `0x10' 13452 $ pdksh -c 'echo $(( 010 ))' 13453 10 13454 13455 When it is available, using arithmetic expansion provides a 13456 noticeable speedup in script execution; but testing for support 13457 requires `eval' to avoid syntax errors. The following construct 13458 is used by `AS_VAR_ARITH' to provide arithmetic computation when 13459 all arguments are provided in decimal and without a leading zero, 13460 and all operators are properly quoted and appear as distinct 13461 arguments: 13462 13463 if ( eval 'test $(( 1 + 1 )) = 2' ) 2>/dev/null; then 13464 eval 'func_arith () 13465 { 13466 func_arith_result=$(( $* )) 13467 }' 13468 else 13469 func_arith () 13470 { 13471 func_arith_result=`expr "$@"` 13472 } 13473 fi 13474 func_arith 1 + 1 13475 foo=$func_arith_result 13476 13477`^' 13478 Always quote `^', otherwise traditional shells such as `/bin/sh' 13479 on Solaris 10 treat this like `|'. 13480 13481 13482 13483File: autoconf.info, Node: Assignments, Next: Parentheses, Prev: Shell Substitutions, Up: Portable Shell 13484 1348511.9 Assignments 13486================ 13487 13488When setting several variables in a row, be aware that the order of the 13489evaluation is undefined. For instance `foo=1 foo=2; echo $foo' gives 13490`1' with Solaris `/bin/sh', but `2' with Bash. You must use `;' to 13491enforce the order: `foo=1; foo=2; echo $foo'. 13492 13493 Don't rely on the following to find `subdir/program': 13494 13495 PATH=subdir$PATH_SEPARATOR$PATH program 13496 13497as this does not work with Zsh 3.0.6. Use something like this instead: 13498 13499 (PATH=subdir$PATH_SEPARATOR$PATH; export PATH; exec program) 13500 13501 Don't rely on the exit status of an assignment: Ash 0.2 does not 13502change the status and propagates that of the last statement: 13503 13504 $ false || foo=bar; echo $? 13505 1 13506 $ false || foo=`:`; echo $? 13507 0 13508 13509and to make things even worse, QNX 4.25 just sets the exit status to 0 13510in any case: 13511 13512 $ foo=`exit 1`; echo $? 13513 0 13514 13515 To assign default values, follow this algorithm: 13516 13517 1. If the default value is a literal and does not contain any closing 13518 brace, use: 13519 13520 : "${var='my literal'}" 13521 13522 2. If the default value contains no closing brace, has to be 13523 expanded, and the variable being initialized is not intended to be 13524 IFS-split (i.e., it's not a list), then use: 13525 13526 : ${var="$default"} 13527 13528 3. If the default value contains no closing brace, has to be 13529 expanded, and the variable being initialized is intended to be 13530 IFS-split (i.e., it's a list), then use: 13531 13532 var=${var="$default"} 13533 13534 4. If the default value contains a closing brace, then use: 13535 13536 test "${var+set}" = set || var="has a '}'" 13537 13538 In most cases `var=${var="$default"}' is fine, but in case of doubt, 13539just use the last form. *Note Shell Substitutions::, items 13540`${VAR:-VALUE}' and `${VAR=VALUE}' for the rationale. 13541 13542 13543File: autoconf.info, Node: Parentheses, Next: Slashes, Prev: Assignments, Up: Portable Shell 13544 1354511.10 Parentheses in Shell Scripts 13546================================== 13547 13548Beware of two opening parentheses in a row, as many shell 13549implementations treat them specially, and Posix says that a portable 13550script cannot use `((' outside the `$((' form used for shell 13551arithmetic. In traditional shells, `((cat))' behaves like `(cat)'; but 13552many shells, including Bash and the Korn shell, treat `((cat))' as an 13553arithmetic expression equivalent to `let "cat"', and may or may not 13554report an error when they detect that `cat' is not a number. As another 13555example, `pdksh' 5.2.14 does not treat the following code as a 13556traditional shell would: 13557 13558 if ((true) || false); then 13559 echo ok 13560 fi 13561 13562To work around this problem, insert a space between the two opening 13563parentheses. There is a similar problem and workaround with `$(('; see 13564*note Shell Substitutions::. 13565 13566 13567File: autoconf.info, Node: Slashes, Next: Special Shell Variables, Prev: Parentheses, Up: Portable Shell 13568 1356911.11 Slashes in Shell Scripts 13570============================== 13571 13572Unpatched Tru64 5.1 `sh' omits the last slash of command-line arguments 13573that contain two trailing slashes: 13574 13575 $ echo / // /// //// .// //. 13576 / / // /// ./ //. 13577 $ x=// 13578 $ eval "echo \$x" 13579 / 13580 $ set -x 13581 $ echo abc | tr -t ab // 13582 + echo abc 13583 + tr -t ab / 13584 /bc 13585 13586 Unpatched Tru64 4.0 `sh' adds a slash after `"$var"' if the variable 13587is empty and the second double-quote is followed by a word that begins 13588and ends with slash: 13589 13590 $ sh -xc 'p=; echo "$p"/ouch/' 13591 p= 13592 + echo //ouch/ 13593 //ouch/ 13594 13595 However, our understanding is that patches are available, so perhaps 13596it's not worth worrying about working around these horrendous bugs. 13597 13598 13599File: autoconf.info, Node: Special Shell Variables, Next: Shell Functions, Prev: Slashes, Up: Portable Shell 13600 1360111.12 Special Shell Variables 13602============================= 13603 13604Some shell variables should not be used, since they can have a deep 13605influence on the behavior of the shell. In order to recover a sane 13606behavior from the shell, some variables should be unset; M4sh takes 13607care of this and provides fallback values, whenever needed, to cater 13608for a very old `/bin/sh' that does not support `unset'. (*note 13609Portable Shell Programming: Portable Shell.). 13610 13611 As a general rule, shell variable names containing a lower-case 13612letter are safe; you can define and use these variables without 13613worrying about their effect on the underlying system, and without 13614worrying about whether the shell changes them unexpectedly. (The 13615exception is the shell variable `status', as described below.) 13616 13617 Here is a list of names that are known to cause trouble. This list 13618is not exhaustive, but you should be safe if you avoid the name 13619`status' and names containing only upper-case letters and underscores. 13620 13621`?' 13622 Not all shells correctly reset `$?' after conditionals (*note 13623 Limitations of Shell Builtins: if.). Not all shells manage `$?' 13624 correctly in shell functions (*note Shell Functions::) or in traps 13625 (*note Limitations of Shell Builtins: trap.). Not all shells reset 13626 `$?' to zero after an empty command. 13627 13628 $ bash -c 'false; $empty; echo $?' 13629 0 13630 $ zsh -c 'false; $empty; echo $?' 13631 1 13632 13633`_' 13634 Many shells reserve `$_' for various purposes, e.g., the name of 13635 the last command executed. 13636 13637`BIN_SH' 13638 In Tru64, if `BIN_SH' is set to `xpg4', subsidiary invocations of 13639 the standard shell conform to Posix. 13640 13641`CDPATH' 13642 When this variable is set it specifies a list of directories to 13643 search when invoking `cd' with a relative file name that did not 13644 start with `./' or `../'. Posix 1003.1-2001 says that if a 13645 nonempty directory name from `CDPATH' is used successfully, `cd' 13646 prints the resulting absolute file name. Unfortunately this 13647 output can break idioms like `abs=`cd src && pwd`' because `abs' 13648 receives the name twice. Also, many shells do not conform to this 13649 part of Posix; for example, `zsh' prints the result only if a 13650 directory name other than `.' was chosen from `CDPATH'. 13651 13652 In practice the shells that have this problem also support 13653 `unset', so you can work around the problem as follows: 13654 13655 (unset CDPATH) >/dev/null 2>&1 && unset CDPATH 13656 13657 You can also avoid output by ensuring that your directory name is 13658 absolute or anchored at `./', as in `abs=`cd ./src && pwd`'. 13659 13660 Configure scripts use M4sh, which automatically unsets `CDPATH' if 13661 possible, so you need not worry about this problem in those 13662 scripts. 13663 13664`CLICOLOR_FORCE' 13665 When this variable is set, some implementations of tools like `ls' 13666 attempt to add color to their output via terminal escape 13667 sequences, even when the output is not directed to a terminal, and 13668 can thus cause spurious failures in scripts. Configure scripts 13669 use M4sh, which automatically unsets this variable. 13670 13671`DUALCASE' 13672 In the MKS shell, case statements and file name generation are 13673 case-insensitive unless `DUALCASE' is nonzero. Autoconf-generated 13674 scripts export this variable when they start up. 13675 13676`ENV' 13677`MAIL' 13678`MAILPATH' 13679`PS1' 13680`PS2' 13681`PS4' 13682 These variables should not matter for shell scripts, since they are 13683 supposed to affect only interactive shells. However, at least one 13684 shell (the pre-3.0 UWIN Korn shell) gets confused about whether it 13685 is interactive, which means that (for example) a `PS1' with a side 13686 effect can unexpectedly modify `$?'. To work around this bug, 13687 M4sh scripts (including `configure' scripts) do something like 13688 this: 13689 13690 (unset ENV) >/dev/null 2>&1 && unset ENV MAIL MAILPATH 13691 PS1='$ ' 13692 PS2='> ' 13693 PS4='+ ' 13694 13695 (actually, there is some complication due to bugs in `unset'; 13696 *note Limitations of Shell Builtins: unset.). 13697 13698`FPATH' 13699 The Korn shell uses `FPATH' to find shell functions, so avoid 13700 `FPATH' in portable scripts. `FPATH' is consulted after `PATH', 13701 but you still need to be wary of tests that use `PATH' to find 13702 whether a command exists, since they might report the wrong result 13703 if `FPATH' is also set. 13704 13705`GREP_OPTIONS' 13706 When this variable is set, some implementations of `grep' honor 13707 these options, even if the options include direction to enable 13708 colored output via terminal escape sequences, and the result can 13709 cause spurious failures when the output is not directed to a 13710 terminal. Configure scripts use M4sh, which automatically unsets 13711 this variable. 13712 13713`IFS' 13714 Long ago, shell scripts inherited `IFS' from the environment, but 13715 this caused many problems so modern shells ignore any environment 13716 settings for `IFS'. 13717 13718 Don't set the first character of `IFS' to backslash. Indeed, 13719 Bourne shells use the first character (backslash) when joining the 13720 components in `"$@"' and some shells then reinterpret (!) the 13721 backslash escapes, so you can end up with backspace and other 13722 strange characters. 13723 13724 The proper value for `IFS' (in regular code, not when performing 13725 splits) is `<SPC><TAB><RET>'. The first character is especially 13726 important, as it is used to join the arguments in `$*'; however, 13727 note that traditional shells, but also bash-2.04, fail to adhere 13728 to this and join with a space anyway. 13729 13730 M4sh guarantees that `IFS' will have the default value at the 13731 beginning of a script, and many macros within autoconf rely on this 13732 setting. It is okay to use blocks of shell code that temporarily 13733 change the value of `IFS' in order to split on another character, 13734 but remember to restore it before expanding further macros. 13735 13736 Unsetting `IFS' instead of resetting it to the default sequence is 13737 not suggested, since code that tries to save and restore the 13738 variable's value will incorrectly reset it to an empty value, thus 13739 disabling field splitting: 13740 13741 unset IFS 13742 # default separators used for field splitting 13743 13744 save_IFS=$IFS 13745 IFS=: 13746 # ... 13747 IFS=$save_IFS 13748 # no field splitting performed 13749 13750`LANG' 13751`LC_ALL' 13752`LC_COLLATE' 13753`LC_CTYPE' 13754`LC_MESSAGES' 13755`LC_MONETARY' 13756`LC_NUMERIC' 13757`LC_TIME' 13758 You should set all these variables to `C' because so much 13759 configuration code assumes the C locale and Posix requires that 13760 locale environment variables be set to `C' if the C locale is 13761 desired; `configure' scripts and M4sh do that for you. Export 13762 these variables after setting them. 13763 13764`LANGUAGE' 13765 `LANGUAGE' is not specified by Posix, but it is a GNU extension 13766 that overrides `LC_ALL' in some cases, so you (or M4sh) should set 13767 it too. 13768 13769`LC_ADDRESS' 13770`LC_IDENTIFICATION' 13771`LC_MEASUREMENT' 13772`LC_NAME' 13773`LC_PAPER' 13774`LC_TELEPHONE' 13775 These locale environment variables are GNU extensions. They are 13776 treated like their Posix brethren (`LC_COLLATE', etc.) as 13777 described above. 13778 13779`LINENO' 13780 Most modern shells provide the current line number in `LINENO'. 13781 Its value is the line number of the beginning of the current 13782 command. M4sh, and hence Autoconf, attempts to execute 13783 `configure' with a shell that supports `LINENO'. If no such shell 13784 is available, it attempts to implement `LINENO' with a Sed prepass 13785 that replaces each instance of the string `$LINENO' (not followed 13786 by an alphanumeric character) with the line's number. In M4sh 13787 scripts you should execute `AS_LINENO_PREPARE' so that these 13788 workarounds are included in your script; configure scripts do this 13789 automatically in `AC_INIT'. 13790 13791 You should not rely on `LINENO' within `eval' or shell functions, 13792 as the behavior differs in practice. The presence of a quoted 13793 newline within simple commands can alter which line number is used 13794 as the starting point for `$LINENO' substitutions within that 13795 command. Also, the possibility of the Sed prepass means that you 13796 should not rely on `$LINENO' when quoted, when in here-documents, 13797 or when line continuations are used. Subshells should be OK, 13798 though. In the following example, lines 1, 9, and 14 are 13799 portable, but the other instances of `$LINENO' do not have 13800 deterministic values: 13801 13802 $ cat lineno 13803 echo 1. $LINENO 13804 echo "2. $LINENO 13805 3. $LINENO" 13806 cat <<EOF 13807 5. $LINENO 13808 6. $LINENO 13809 7. \$LINENO 13810 EOF 13811 ( echo 9. $LINENO ) 13812 eval 'echo 10. $LINENO' 13813 eval 'echo 11. $LINENO 13814 echo 12. $LINENO' 13815 echo 13. '$LINENO' 13816 echo 14. $LINENO ' 13817 15.' $LINENO 13818 f () { echo $1 $LINENO; 13819 echo $1 $LINENO } 13820 f 18. 13821 echo 19. \ 13822 $LINENO 13823 $ bash-3.2 ./lineno 13824 1. 1 13825 2. 3 13826 3. 3 13827 5. 4 13828 6. 4 13829 7. $LINENO 13830 9. 9 13831 10. 10 13832 11. 12 13833 12. 13 13834 13. $LINENO 13835 14. 14 13836 15. 14 13837 18. 16 13838 18. 17 13839 19. 19 13840 $ zsh-4.3.4 ./lineno 13841 1. 1 13842 2. 2 13843 3. 2 13844 5. 4 13845 6. 4 13846 7. $LINENO 13847 9. 9 13848 10. 1 13849 11. 1 13850 12. 2 13851 13. $LINENO 13852 14. 14 13853 15. 14 13854 18. 0 13855 18. 1 13856 19. 19 13857 $ pdksh-5.2.14 ./lineno 13858 1. 1 13859 2. 2 13860 3. 2 13861 5. 4 13862 6. 4 13863 7. $LINENO 13864 9. 9 13865 10. 0 13866 11. 0 13867 12. 0 13868 13. $LINENO 13869 14. 14 13870 15. 14 13871 18. 16 13872 18. 17 13873 19. 19 13874 $ sed '=' <lineno | 13875 > sed ' 13876 > N 13877 > s,$,-, 13878 > t loop 13879 > :loop 13880 > s,^\([0-9]*\)\(.*\)[$]LINENO\([^a-zA-Z0-9_]\),\1\2\1\3, 13881 > t loop 13882 > s,-$,, 13883 > s,^[0-9]*\n,, 13884 > ' | 13885 > sh 13886 1. 1 13887 2. 2 13888 3. 3 13889 5. 5 13890 6. 6 13891 7. \7 13892 9. 9 13893 10. 10 13894 11. 11 13895 12. 12 13896 13. 13 13897 14. 14 13898 15. 15 13899 18. 16 13900 18. 17 13901 19. 20 13902 13903 In particular, note that `config.status' (and any other subsidiary 13904 script created by `AS_INIT_GENERATED') might report line numbers 13905 relative to the parent script as a result of the potential Sed 13906 pass. 13907 13908`NULLCMD' 13909 When executing the command `>foo', `zsh' executes `$NULLCMD >foo' 13910 unless it is operating in Bourne shell compatibility mode and the 13911 `zsh' version is newer than 3.1.6-dev-18. If you are using an 13912 older `zsh' and forget to set `NULLCMD', your script might be 13913 suspended waiting for data on its standard input. 13914 13915`options' 13916 For `zsh' 4.3.10, `options' is treated as an associative array 13917 even after `emulate sh', so it should not be used. 13918 13919`PATH_SEPARATOR' 13920 On DJGPP systems, the `PATH_SEPARATOR' environment variable can be 13921 set to either `:' or `;' to control the path separator Bash uses 13922 to set up certain environment variables (such as `PATH'). You can 13923 set this variable to `;' if you want `configure' to use `;' as a 13924 separator; this might be useful if you plan to use non-Posix 13925 shells to execute files. *Note File System Conventions::, for 13926 more information about `PATH_SEPARATOR'. 13927 13928`POSIXLY_CORRECT' 13929 In the GNU environment, exporting `POSIXLY_CORRECT' with any value 13930 (even empty) causes programs to try harder to conform to Posix. 13931 Autoconf does not directly manipulate this variable, but `bash' 13932 ties the shell variable `POSIXLY_CORRECT' to whether the script is 13933 running in Posix mode. Therefore, take care when exporting or 13934 unsetting this variable, so as not to change whether `bash' is in 13935 Posix mode. 13936 13937 $ bash --posix -c 'set -o | grep posix 13938 > unset POSIXLY_CORRECT 13939 > set -o | grep posix' 13940 posix on 13941 posix off 13942 13943`PWD' 13944 Posix 1003.1-2001 requires that `cd' and `pwd' must update the 13945 `PWD' environment variable to point to the logical name of the 13946 current directory, but traditional shells do not support this. 13947 This can cause confusion if one shell instance maintains `PWD' but 13948 a subsidiary and different shell does not know about `PWD' and 13949 executes `cd'; in this case `PWD' points to the wrong directory. 13950 Use ``pwd`' rather than `$PWD'. 13951 13952`RANDOM' 13953 Many shells provide `RANDOM', a variable that returns a different 13954 integer each time it is used. Most of the time, its value does not 13955 change when it is not used, but on IRIX 6.5 the value changes all 13956 the time. This can be observed by using `set'. It is common 13957 practice to use `$RANDOM' as part of a file name, but code 13958 shouldn't rely on `$RANDOM' expanding to a nonempty string. 13959 13960`status' 13961 This variable is an alias to `$?' for `zsh' (at least 3.1.6), 13962 hence read-only. Do not use it. 13963 13964 13965File: autoconf.info, Node: Shell Functions, Next: Limitations of Builtins, Prev: Special Shell Variables, Up: Portable Shell 13966 1396711.13 Shell Functions 13968===================== 13969 13970Nowadays, it is difficult to find a shell that does not support shell 13971functions at all. However, some differences should be expected. 13972 13973 When declaring a shell function, you must include whitespace between 13974the `)' after the function name and the start of the compound 13975expression, to avoid upsetting `ksh'. While it is possible to use any 13976compound command, most scripts use `{...}'. 13977 13978 $ /bin/sh -c 'a(){ echo hi;}; a' 13979 hi 13980 $ ksh -c 'a(){ echo hi;}; a' 13981 ksh: syntax error at line 1: `}' unexpected 13982 $ ksh -c 'a() { echo hi;}; a' 13983 hi 13984 13985 Inside a shell function, you should not rely on the error status of a 13986subshell if the last command of that subshell was `exit' or `trap', as 13987this triggers bugs in zsh 4.x; while Autoconf tries to find a shell 13988that does not exhibit the bug, zsh might be the only shell present on 13989the user's machine. 13990 13991 Likewise, the state of `$?' is not reliable when entering a shell 13992function. This has the effect that using a function as the first 13993command in a `trap' handler can cause problems. 13994 13995 $ bash -c 'foo() { echo $?; }; trap foo 0; (exit 2); exit 2'; echo $? 13996 2 13997 2 13998 $ ash -c 'foo() { echo $?; }; trap foo 0; (exit 2); exit 2'; echo $? 13999 0 14000 2 14001 14002 DJGPP bash 2.04 has a bug in that `return' from a shell function 14003which also used a command substitution causes a segmentation fault. To 14004work around the issue, you can use `return' from a subshell, or 14005`AS_SET_STATUS' as last command in the execution flow of the function 14006(*note Common Shell Constructs::). 14007 14008 Not all shells treat shell functions as simple commands impacted by 14009`set -e', for example with Solaris 10 `/bin/sh': 14010 14011 $ bash -c 'f() { return 1; }; set -e; f; echo oops' 14012 $ /bin/sh -c 'f() { return 1; }; set -e; f; echo oops' 14013 oops 14014 14015 Shell variables and functions may share the same namespace, for 14016example with Solaris 10 `/bin/sh': 14017 14018 $ f () { :; }; f=; f 14019 f: not found 14020 14021For this reason, Autoconf (actually M4sh, *note Programming in M4sh::) 14022uses the prefix `as_fn_' for its functions. 14023 14024 Handling of positional parameters and shell options varies among 14025shells. For example, Korn shells reset and restore trace output (`set 14026-x') and other options upon function entry and exit. Inside a function, 14027IRIX sh sets `$0' to the function name. 14028 14029 It is not portable to pass temporary environment variables to shell 14030functions. Solaris `/bin/sh' does not see the variable. Meanwhile, 14031not all shells follow the Posix rule that the assignment must affect 14032the current environment in the same manner as special built-ins. 14033 14034 $ /bin/sh -c 'func() { echo $a;}; a=1 func; echo $a' 14035 => 14036 => 14037 $ ash -c 'func() { echo $a;}; a=1 func; echo $a' 14038 =>1 14039 => 14040 $ bash -c 'set -o posix; func() { echo $a;}; a=1 func; echo $a' 14041 =>1 14042 =>1 14043 14044 Some ancient Bourne shell variants with function support did not 14045reset `$I, I >= 0', upon function exit, so effectively the arguments of 14046the script were lost after the first function invocation. It is 14047probably not worth worrying about these shells any more. 14048 14049 With AIX sh, a `trap' on 0 installed in a shell function triggers at 14050function exit rather than at script exit. *Note Limitations of Shell 14051Builtins: trap. 14052 14053 14054File: autoconf.info, Node: Limitations of Builtins, Next: Limitations of Usual Tools, Prev: Shell Functions, Up: Portable Shell 14055 1405611.14 Limitations of Shell Builtins 14057=================================== 14058 14059No, no, we are serious: some shells do have limitations! :) 14060 14061 You should always keep in mind that any builtin or command may 14062support options, and therefore differ in behavior with arguments 14063starting with a dash. For instance, even the innocent `echo "$word"' 14064can give unexpected results when `word' starts with a dash. It is 14065often possible to avoid this problem using `echo "x$word"', taking the 14066`x' into account later in the pipe. Many of these limitations can be 14067worked around using M4sh (*note Programming in M4sh::). 14068 14069`.' 14070 Use `.' only with regular files (use `test -f'). Bash 2.03, for 14071 instance, chokes on `. /dev/null'. Remember that `.' uses `PATH' 14072 if its argument contains no slashes. Also, some shells, including 14073 bash 3.2, implicitly append the current directory to this `PATH' 14074 search, even though Posix forbids it. So if you want to use `.' 14075 on a file `foo' in the current directory, you must use `. ./foo'. 14076 14077 Not all shells gracefully handle syntax errors within a sourced 14078 file. On one extreme, some non-interactive shells abort the 14079 entire script. On the other, `zsh' 4.3.10 has a bug where it 14080 fails to react to the syntax error. 14081 14082 $ echo 'fi' > syntax 14083 $ bash -c '. ./syntax; echo $?' 14084 ./syntax: line 1: syntax error near unexpected token `fi' 14085 ./syntax: line 1: `fi' 14086 1 14087 $ ash -c '. ./syntax; echo $?' 14088 ./syntax: 1: Syntax error: "fi" unexpected 14089 $ zsh -c '. ./syntax; echo $?' 14090 ./syntax:1: parse error near `fi' 14091 0 14092 14093`!' 14094 The Unix version 7 shell did not support negating the exit status 14095 of commands with `!', and this feature is still absent from some 14096 shells (e.g., Solaris `/bin/sh'). Other shells, such as FreeBSD 14097 `/bin/sh' or `ash', have bugs when using `!': 14098 14099 $ sh -c '! : | :'; echo $? 14100 1 14101 $ ash -c '! : | :'; echo $? 14102 0 14103 $ sh -c '! { :; }'; echo $? 14104 1 14105 $ ash -c '! { :; }'; echo $? 14106 {: not found 14107 Syntax error: "}" unexpected 14108 2 14109 14110 Shell code like this: 14111 14112 if ! cmp file1 file2 >/dev/null 2>&1; then 14113 echo files differ or trouble 14114 fi 14115 14116 is therefore not portable in practice. Typically it is easy to 14117 rewrite such code, e.g.: 14118 14119 cmp file1 file2 >/dev/null 2>&1 || 14120 echo files differ or trouble 14121 14122 More generally, one can always rewrite `! COMMAND' as: 14123 14124 if COMMAND; then (exit 1); else :; fi 14125 14126`{...}' 14127 Bash 3.2 (and earlier versions) sometimes does not properly set 14128 `$?' when failing to write redirected output of a compound command. 14129 This problem is most commonly observed with `{...}'; it does not 14130 occur with `(...)'. For example: 14131 14132 $ bash -c '{ echo foo; } >/bad; echo $?' 14133 bash: line 1: /bad: Permission denied 14134 0 14135 $ bash -c 'while :; do echo; done >/bad; echo $?' 14136 bash: line 1: /bad: Permission denied 14137 0 14138 14139 To work around the bug, prepend `:;': 14140 14141 $ bash -c ':;{ echo foo; } >/bad; echo $?' 14142 bash: line 1: /bad: Permission denied 14143 1 14144 14145 Posix requires a syntax error if a brace list has no contents. 14146 However, not all shells obey this rule; and on shells where empty 14147 lists are permitted, the effect on `$?' is inconsistent. To avoid 14148 problems, ensure that a brace list is never empty. 14149 14150 $ bash -c 'false; { }; echo $?' || echo $? 14151 bash: line 1: syntax error near unexpected token `}' 14152 bash: line 1: `false; { }; echo $?' 14153 2 14154 $ zsh -c 'false; { }; echo $?' || echo $? 14155 1 14156 $ pdksh -c 'false; { }; echo $?' || echo $? 14157 0 14158 14159`break' 14160 The use of `break 2' etc. is safe. 14161 14162`case' 14163 You don't need to quote the argument; no splitting is performed. 14164 14165 You don't need the final `;;', but you should use it. 14166 14167 Posix requires support for `case' patterns with opening 14168 parentheses like this: 14169 14170 case $file_name in 14171 (*.c) echo "C source code";; 14172 esac 14173 14174 but the `(' in this example is not portable to many Bourne shell 14175 implementations, which is a pity for those of us using tools that 14176 rely on balanced parentheses. For instance, with Solaris 14177 `/bin/sh': 14178 14179 $ case foo in (foo) echo foo;; esac 14180 error-->syntax error: `(' unexpected 14181 14182 The leading `(' can be omitted safely. Unfortunately, there are 14183 contexts where unbalanced parentheses cause other problems, such 14184 as when using a syntax-highlighting editor that searches for the 14185 balancing counterpart, or more importantly, when using a case 14186 statement as an underquoted argument to an Autoconf macro. *Note 14187 Balancing Parentheses::, for tradeoffs involved in various styles 14188 of dealing with unbalanced `)'. 14189 14190 Zsh handles pattern fragments derived from parameter expansions or 14191 command substitutions as though quoted: 14192 14193 $ pat=\?; case aa in ?$pat) echo match;; esac 14194 $ pat=\?; case a? in ?$pat) echo match;; esac 14195 match 14196 14197 Because of a bug in its `fnmatch', Bash fails to properly handle 14198 backslashes in character classes: 14199 14200 bash-2.02$ case /tmp in [/\\]*) echo OK;; esac 14201 bash-2.02$ 14202 14203 This is extremely unfortunate, since you are likely to use this 14204 code to handle Posix or MS-DOS absolute file names. To work 14205 around this bug, always put the backslash first: 14206 14207 bash-2.02$ case '\TMP' in [\\/]*) echo OK;; esac 14208 OK 14209 bash-2.02$ case /tmp in [\\/]*) echo OK;; esac 14210 OK 14211 14212 Many Bourne shells cannot handle closing brackets in character 14213 classes correctly. 14214 14215 Some shells also have problems with backslash escaping in case you 14216 do not want to match the backslash: both a backslash and the 14217 escaped character match this pattern. To work around this, 14218 specify the character class in a variable, so that quote removal 14219 does not apply afterwards, and the special characters don't have 14220 to be backslash-escaped: 14221 14222 $ case '\' in [\<]) echo OK;; esac 14223 OK 14224 $ scanset='[<]'; case '\' in $scanset) echo OK;; esac 14225 $ 14226 14227 Even with this, Solaris `ksh' matches a backslash if the set 14228 contains any of the characters `|', `&', `(', or `)'. 14229 14230 Conversely, Tru64 `ksh' (circa 2003) erroneously always matches a 14231 closing parenthesis if not specified in a character class: 14232 14233 $ case foo in *\)*) echo fail ;; esac 14234 fail 14235 $ case foo in *')'*) echo fail ;; esac 14236 fail 14237 14238 Some shells, such as Ash 0.3.8, are confused by an empty 14239 `case'/`esac': 14240 14241 ash-0.3.8 $ case foo in esac; 14242 error-->Syntax error: ";" unexpected (expecting ")") 14243 14244 Posix requires `case' to give an exit status of 0 if no cases 14245 match. However, `/bin/sh' in Solaris 10 does not obey this rule. 14246 Meanwhile, it is unclear whether a case that matches, but contains 14247 no statements, must also change the exit status to 0. The M4sh 14248 macro `AS_CASE' works around these inconsistencies. 14249 14250 $ bash -c 'case `false` in ?) ;; esac; echo $?' 14251 0 14252 $ /bin/sh -c 'case `false` in ?) ;; esac; echo $?' 14253 255 14254 14255`cd' 14256 Posix 1003.1-2001 requires that `cd' must support the `-L' 14257 ("logical") and `-P' ("physical") options, with `-L' being the 14258 default. However, traditional shells do not support these 14259 options, and their `cd' command has the `-P' behavior. 14260 14261 Portable scripts should assume neither option is supported, and 14262 should assume neither behavior is the default. This can be a bit 14263 tricky, since the Posix default behavior means that, for example, 14264 `ls ..' and `cd ..' may refer to different directories if the 14265 current logical directory is a symbolic link. It is safe to use 14266 `cd DIR' if DIR contains no `..' components. Also, 14267 Autoconf-generated scripts check for this problem when computing 14268 variables like `ac_top_srcdir' (*note Configuration Actions::), so 14269 it is safe to `cd' to these variables. 14270 14271 Posix states that behavior is undefined if `cd' is given an 14272 explicit empty argument. Some shells do nothing, some change to 14273 the first entry in `CDPATH', some change to `HOME', and some exit 14274 the shell rather than returning an error. Unfortunately, this 14275 means that if `$var' is empty, then `cd "$var"' is less predictable 14276 than `cd $var' (at least the latter is well-behaved in all shells 14277 at changing to `HOME', although this is probably not what you 14278 wanted in a script). You should check that a directory name was 14279 supplied before trying to change locations. 14280 14281 *Note Special Shell Variables::, for portability problems involving 14282 `cd' and the `CDPATH' environment variable. Also please see the 14283 discussion of the `pwd' command. 14284 14285`echo' 14286 The simple `echo' is probably the most surprising source of 14287 portability troubles. It is not possible to use `echo' portably 14288 unless both options and escape sequences are omitted. Don't 14289 expect any option. 14290 14291 Do not use backslashes in the arguments, as there is no consensus 14292 on their handling. For `echo '\n' | wc -l', the `sh' of Solaris 14293 outputs 2, but Bash and Zsh (in `sh' emulation mode) output 1. 14294 The problem is truly `echo': all the shells understand `'\n'' as 14295 the string composed of a backslash and an `n'. Within a command 14296 substitution, `echo 'string\c'' will mess up the internal state of 14297 ksh88 on AIX 6.1 so that it will print the first character `s' 14298 only, followed by a newline, and then entirely drop the output of 14299 the next echo in a command substitution. 14300 14301 Because of these problems, do not pass a string containing 14302 arbitrary characters to `echo'. For example, `echo "$foo"' is safe 14303 only if you know that FOO's value cannot contain backslashes and 14304 cannot start with `-'. 14305 14306 If this may not be true, `printf' is in general safer and easier 14307 to use than `echo' and `echo -n'. Thus, scripts where portability 14308 is not a major concern should use `printf '%s\n'' whenever `echo' 14309 could fail, and similarly use `printf %s' instead of `echo -n'. 14310 For portable shell scripts, instead, it is suggested to use a 14311 here-document like this: 14312 14313 cat <<EOF 14314 $foo 14315 EOF 14316 14317 Alternatively, M4sh provides `AS_ECHO' and `AS_ECHO_N' macros 14318 which choose between various portable implementations: `echo' or 14319 `print' where they work, `printf' if it is available, or else 14320 other creative tricks in order to work around the above problems. 14321 14322`eval' 14323 The `eval' command is useful in limited circumstances, e.g., using 14324 commands like `eval table_$key=\$value' and `eval 14325 value=table_$key' to simulate a hash table when the key is known 14326 to be alphanumeric. 14327 14328 You should also be wary of common bugs in `eval' implementations. 14329 In some shell implementations (e.g., older `ash', OpenBSD 3.8 14330 `sh', `pdksh' v5.2.14 99/07/13.2, and `zsh' 4.2.5), the arguments 14331 of `eval' are evaluated in a context where `$?' is 0, so they 14332 exhibit behavior like this: 14333 14334 $ false; eval 'echo $?' 14335 0 14336 14337 The correct behavior here is to output a nonzero value, but 14338 portable scripts should not rely on this. 14339 14340 You should not rely on `LINENO' within `eval'. *Note Special 14341 Shell Variables::. 14342 14343 Note that, even though these bugs are easily avoided, `eval' is 14344 tricky to use on arbitrary arguments. It is obviously unwise to 14345 use `eval $cmd' if the string value of `cmd' was derived from an 14346 untrustworthy source. But even if the string value is valid, 14347 `eval $cmd' might not work as intended, since it causes field 14348 splitting and file name expansion to occur twice, once for the 14349 `eval' and once for the command itself. It is therefore safer to 14350 use `eval "$cmd"'. For example, if CMD has the value `cat 14351 test?.c', `eval $cmd' might expand to the equivalent of `cat 14352 test;.c' if there happens to be a file named `test;.c' in the 14353 current directory; and this in turn mistakenly attempts to invoke 14354 `cat' on the file `test' and then execute the command `.c'. To 14355 avoid this problem, use `eval "$cmd"' rather than `eval $cmd'. 14356 14357 However, suppose that you want to output the text of the evaluated 14358 command just before executing it. Assuming the previous example, 14359 `echo "Executing: $cmd"' outputs `Executing: cat test?.c', but 14360 this output doesn't show the user that `test;.c' is the actual name 14361 of the copied file. Conversely, `eval "echo Executing: $cmd"' 14362 works on this example, but it fails with `cmd='cat foo >bar'', 14363 since it mistakenly replaces the contents of `bar' by the string 14364 `cat foo'. No simple, general, and portable solution to this 14365 problem is known. 14366 14367`exec' 14368 Posix describes several categories of shell built-ins. Special 14369 built-ins (such as `exit') must impact the environment of the 14370 current shell, and need not be available through `exec'. All 14371 other built-ins are regular, and must not propagate variable 14372 assignments to the environment of the current shell. However, the 14373 group of regular built-ins is further distinguished by commands 14374 that do not require a `PATH' search (such as `cd'), in contrast to 14375 built-ins that are offered as a more efficient version of 14376 something that must still be found in a `PATH' search (such as 14377 `echo'). Posix is not clear on whether `exec' must work with the 14378 list of 17 utilities that are invoked without a `PATH' search, and 14379 many platforms lack an executable for some of those built-ins: 14380 14381 $ sh -c 'exec cd /tmp' 14382 sh: line 0: exec: cd: not found 14383 14384 All other built-ins that provide utilities specified by Posix must 14385 have a counterpart executable that exists on `PATH', although Posix 14386 allows `exec' to use the built-in instead of the executable. For 14387 example, contrast `bash' 3.2 and `pdksh' 5.2.14: 14388 14389 $ bash -c 'pwd --version' | head -n1 14390 bash: line 0: pwd: --: invalid option 14391 pwd: usage: pwd [-LP] 14392 $ bash -c 'exec pwd --version' | head -n1 14393 pwd (GNU coreutils) 6.10 14394 $ pdksh -c 'exec pwd --version' | head -n1 14395 pdksh: pwd: --: unknown option 14396 14397 When it is desired to avoid a regular shell built-in, the 14398 workaround is to use some other forwarding command, such as `env' 14399 or `nice', that will ensure a path search: 14400 14401 $ pdksh -c 'exec true --version' | head -n1 14402 $ pdksh -c 'nice true --version' | head -n1 14403 true (GNU coreutils) 6.10 14404 $ pdksh -c 'env true --version' | head -n1 14405 true (GNU coreutils) 6.10 14406 14407`exit' 14408 The default value of `exit' is supposed to be `$?'; unfortunately, 14409 some shells, such as the DJGPP port of Bash 2.04, just perform 14410 `exit 0'. 14411 14412 bash-2.04$ foo=`exit 1` || echo fail 14413 fail 14414 bash-2.04$ foo=`(exit 1)` || echo fail 14415 fail 14416 bash-2.04$ foo=`(exit 1); exit` || echo fail 14417 bash-2.04$ 14418 14419 Using `exit $?' restores the expected behavior. 14420 14421 Some shell scripts, such as those generated by `autoconf', use a 14422 trap to clean up before exiting. If the last shell command exited 14423 with nonzero status, the trap also exits with nonzero status so 14424 that the invoker can tell that an error occurred. 14425 14426 Unfortunately, in some shells, such as Solaris `/bin/sh', an exit 14427 trap ignores the `exit' command's argument. In these shells, a 14428 trap cannot determine whether it was invoked by plain `exit' or by 14429 `exit 1'. Instead of calling `exit' directly, use the 14430 `AC_MSG_ERROR' macro that has a workaround for this problem. 14431 14432`export' 14433 The builtin `export' dubs a shell variable "environment variable". 14434 Each update of exported variables corresponds to an update of the 14435 environment variables. Conversely, each environment variable 14436 received by the shell when it is launched should be imported as a 14437 shell variable marked as exported. 14438 14439 Alas, many shells, such as Solaris `/bin/sh', IRIX 6.3, IRIX 5.2, 14440 AIX 4.1.5, and Digital Unix 4.0, forget to `export' the 14441 environment variables they receive. As a result, two variables 14442 coexist: the environment variable and the shell variable. The 14443 following code demonstrates this failure: 14444 14445 #!/bin/sh 14446 echo $FOO 14447 FOO=bar 14448 echo $FOO 14449 exec /bin/sh $0 14450 14451 when run with `FOO=foo' in the environment, these shells print 14452 alternately `foo' and `bar', although they should print only `foo' 14453 and then a sequence of `bar's. 14454 14455 Therefore you should `export' again each environment variable that 14456 you update; the export can occur before or after the assignment. 14457 14458 Posix is not clear on whether the `export' of an undefined 14459 variable causes the variable to be defined with the value of an 14460 empty string, or merely marks any future definition of a variable 14461 by that name for export. Various shells behave differently in 14462 this regard: 14463 14464 $ sh -c 'export foo; env | grep foo' 14465 $ ash -c 'export foo; env | grep foo' 14466 foo= 14467 14468 Posix requires `export' to honor assignments made as arguments, 14469 but older shells do not support this, including `/bin/sh' in 14470 Solaris 10. Portable scripts should separate assignments and 14471 exports into different statements. 14472 14473 $ bash -c 'export foo=bar; echo $foo' 14474 bar 14475 $ /bin/sh -c 'export foo=bar; echo $foo' 14476 /bin/sh: foo=bar: is not an identifier 14477 $ /bin/sh -c 'export foo; foo=bar; echo $foo' 14478 bar 14479 14480`false' 14481 Don't expect `false' to exit with status 1: in native Solaris 14482 `/bin/false' exits with status 255. 14483 14484`for' 14485 To loop over positional arguments, use: 14486 14487 for arg 14488 do 14489 echo "$arg" 14490 done 14491 14492 You may _not_ leave the `do' on the same line as `for', since some 14493 shells improperly grok: 14494 14495 for arg; do 14496 echo "$arg" 14497 done 14498 14499 If you want to explicitly refer to the positional arguments, given 14500 the `$@' bug (*note Shell Substitutions::), use: 14501 14502 for arg in ${1+"$@"}; do 14503 echo "$arg" 14504 done 14505 14506 But keep in mind that Zsh, even in Bourne shell emulation mode, 14507 performs word splitting on `${1+"$@"}'; see *note Shell 14508 Substitutions::, item `$@', for more. 14509 14510 In Solaris `/bin/sh', when the list of arguments of a `for' loop 14511 starts with _unquoted_ tokens looking like variable assignments, 14512 the loop is not executed on those tokens: 14513 14514 $ /bin/sh -c 'for v in a=b c=d x e=f; do echo $v; done' 14515 x 14516 e=f 14517 14518 Thankfully, quoting the assignment-like tokens, or starting the 14519 list with other tokens (including unquoted variable expansion that 14520 results in an assignment-like result), avoids the problem, so it 14521 is easy to work around: 14522 14523 $ /bin/sh -c 'for v in "a=b"; do echo $v; done' 14524 a=b 14525 $ /bin/sh -c 'x=a=b; for v in $x c=d; do echo $v; done' 14526 a=b 14527 c=d 14528 14529`if' 14530 Using `!' is not portable. Instead of: 14531 14532 if ! cmp -s file file.new; then 14533 mv file.new file 14534 fi 14535 14536 use: 14537 14538 if cmp -s file file.new; then :; else 14539 mv file.new file 14540 fi 14541 14542 Or, especially if the "else" branch is short, you can use `||'. 14543 In M4sh, the `AS_IF' macro provides an easy way to write these 14544 kinds of conditionals: 14545 14546 AS_IF([cmp -s file file.new], [], [mv file.new file]) 14547 14548 This is especially useful in other M4 macros, where the "then" and 14549 "else" branches might be macro arguments. 14550 14551 Some very old shells did not reset the exit status from an `if' 14552 with no `else': 14553 14554 $ if (exit 42); then true; fi; echo $? 14555 42 14556 14557 whereas a proper shell should have printed `0'. But this is no 14558 longer a portability problem; any shell that supports functions 14559 gets it correct. However, it explains why some makefiles have 14560 lengthy constructs: 14561 14562 if test -f "$file"; then 14563 install "$file" "$dest" 14564 else 14565 : 14566 fi 14567 14568`printf' 14569 A format string starting with a `-' can cause problems. Bash 14570 interprets it as an option and gives an error. And `--' to mark 14571 the end of options is not good in the NetBSD Almquist shell (e.g., 14572 0.4.6) which takes that literally as the format string. Putting 14573 the `-' in a `%c' or `%s' is probably easiest: 14574 14575 printf %s -foo 14576 14577 Bash 2.03 mishandles an escape sequence that happens to evaluate 14578 to `%': 14579 14580 $ printf '\045' 14581 bash: printf: `%': missing format character 14582 14583 Large outputs may cause trouble. On Solaris 2.5.1 through 10, for 14584 example, `/usr/bin/printf' is buggy, so when using `/bin/sh' the 14585 command `printf %010000x 123' normally dumps core. 14586 14587 Since `printf' is not always a shell builtin, there is a potential 14588 speed penalty for using `printf '%s\n'' as a replacement for an 14589 `echo' that does not interpret `\' or leading `-'. With Solaris 14590 `ksh', it is possible to use `print -r --' for this role instead. 14591 14592 *Note Limitations of Shell Builtins: echo for a discussion of 14593 portable alternatives to both `printf' and `echo'. 14594 14595`pwd' 14596 With modern shells, plain `pwd' outputs a "logical" directory 14597 name, some of whose components may be symbolic links. These 14598 directory names are in contrast to "physical" directory names, 14599 whose components are all directories. 14600 14601 Posix 1003.1-2001 requires that `pwd' must support the `-L' 14602 ("logical") and `-P' ("physical") options, with `-L' being the 14603 default. However, traditional shells do not support these 14604 options, and their `pwd' command has the `-P' behavior. 14605 14606 Portable scripts should assume neither option is supported, and 14607 should assume neither behavior is the default. Also, on many hosts 14608 `/bin/pwd' is equivalent to `pwd -P', but Posix does not require 14609 this behavior and portable scripts should not rely on it. 14610 14611 Typically it's best to use plain `pwd'. On modern hosts this 14612 outputs logical directory names, which have the following 14613 advantages: 14614 14615 * Logical names are what the user specified. 14616 14617 * Physical names may not be portable from one installation host 14618 to another due to network file system gymnastics. 14619 14620 * On modern hosts `pwd -P' may fail due to lack of permissions 14621 to some parent directory, but plain `pwd' cannot fail for this 14622 reason. 14623 14624 Also please see the discussion of the `cd' command. 14625 14626`read' 14627 No options are portable, not even support `-r' (Solaris `/bin/sh' 14628 for example). Tru64/OSF 5.1 `sh' treats `read' as a special 14629 built-in, so it may exit if input is redirected from a 14630 non-existent or unreadable file. 14631 14632`set' 14633 With the FreeBSD 6.0 shell, the `set' command (without any 14634 options) does not sort its output. 14635 14636 The `set' builtin faces the usual problem with arguments starting 14637 with a dash. Modern shells such as Bash or Zsh understand `--' to 14638 specify the end of the options (any argument after `--' is a 14639 parameter, even `-x' for instance), but many traditional shells 14640 (e.g., Solaris 10 `/bin/sh') simply stop option processing as soon 14641 as a non-option argument is found. Therefore, use `dummy' or 14642 simply `x' to end the option processing, and use `shift' to pop it 14643 out: 14644 14645 set x $my_list; shift 14646 14647 Avoid `set -', e.g., `set - $my_list'. Posix no longer requires 14648 support for this command, and in traditional shells `set - 14649 $my_list' resets the `-v' and `-x' options, which makes scripts 14650 harder to debug. 14651 14652 Some nonstandard shells do not recognize more than one option 14653 (e.g., `set -e -x' assigns `-x' to the command line). It is 14654 better to combine them: 14655 14656 set -ex 14657 14658 The option `-e' has historically been underspecified, with enough 14659 ambiguities to cause numerous differences across various shell 14660 implementations; see for example this overview 14661 (http://www.in-ulm.de/~mascheck/various/set-e/), or this link 14662 (http://www.austingroupbugs.net/view.php?id=52), documenting a 14663 change to Posix 2008 to match `ksh88' behavior. Note that mixing 14664 `set -e' and shell functions is asking for surprises: 14665 14666 set -e 14667 doit() 14668 { 14669 rm file 14670 echo one 14671 } 14672 doit || echo two 14673 14674 According to the recommendation, `one' should always be output 14675 regardless of whether the `rm' failed, because it occurs within 14676 the body of the shell function `doit' invoked on the left side of 14677 `||', where the effects of `set -e' are not enforced. Likewise, 14678 `two' should never be printed, since the failure of `rm' does not 14679 abort the function, such that the status of `doit' is 0. 14680 14681 The BSD shell has had several problems with the `-e' option. 14682 Older versions of the BSD shell (circa 1990) mishandled `&&', 14683 `||', `if', and `case' when `-e' was in effect, causing the shell 14684 to exit unexpectedly in some cases. This was particularly a 14685 problem with makefiles, and led to circumlocutions like `sh -c 14686 'test -f file || touch file'', where the seemingly-unnecessary `sh 14687 -c '...'' wrapper works around the bug (*note Failure in Make 14688 Rules::). 14689 14690 Even relatively-recent versions of the BSD shell (e.g., OpenBSD 14691 3.4) wrongly exit with `-e' if the last command within a compound 14692 statement fails and is guarded by an `&&' only. For example: 14693 14694 #! /bin/sh 14695 set -e 14696 foo='' 14697 test -n "$foo" && exit 1 14698 echo one 14699 if :; then 14700 test -n "$foo" && exit 1 14701 echo two 14702 test -n "$foo" && exit 1 14703 fi 14704 echo three 14705 14706 does not print `three'. One workaround is to change the last 14707 instance of `test -n "$foo" && exit 1' to be `if test -n "$foo"; 14708 then exit 1; fi' instead. Another possibility is to warn BSD 14709 users not to use `sh -e'. 14710 14711 When `set -e' is in effect, a failed command substitution in 14712 Solaris `/bin/sh' cannot be ignored, even with `||'. 14713 14714 $ /bin/sh -c 'set -e; foo=`false` || echo foo; echo bar' 14715 $ bash -c 'set -e; foo=`false` || echo foo; echo bar' 14716 foo 14717 bar 14718 14719 Moreover, a command substitution, successful or not, causes this 14720 shell to exit from a failing outer command even in presence of an 14721 `&&' list: 14722 14723 $ bash -c 'set -e; false `true` && echo notreached; echo ok' 14724 ok 14725 $ sh -c 'set -e; false `true` && echo notreached; echo ok' 14726 $ 14727 14728 Portable scripts should not use `set -e' if `trap' is used to 14729 install an exit handler. This is because Tru64/OSF 5.1 `sh' 14730 sometimes enters the trap handler with the exit status of the 14731 command prior to the one that triggered the errexit handler: 14732 14733 $ sh -ec 'trap '\''echo $?'\'' 0; false' 14734 0 14735 $ sh -c 'set -e; trap '\''echo $?'\'' 0; false' 14736 1 14737 14738 Thus, when writing a script in M4sh, rather than trying to rely on 14739 `set -e', it is better to append `|| AS_EXIT' to any statement 14740 where it is desirable to abort on failure. 14741 14742 Job control is not provided by all shells, so the use of `set -m' 14743 or `set -b' must be done with care. When using `zsh' in native 14744 mode, asynchronous notification (`set -b') is enabled by default, 14745 and using `emulate sh' to switch to Posix mode does not clear this 14746 setting (although asynchronous notification has no impact unless 14747 job monitoring is also enabled). Also, `zsh' 4.3.10 and earlier 14748 have a bug where job control can be manipulated in interactive 14749 shells, but not in subshells or scripts. Furthermore, some 14750 shells, like `pdksh', fail to treat subshells as interactive, even 14751 though the parent shell was. 14752 14753 $ echo $ZSH_VERSION 14754 4.3.10 14755 $ set -m; echo $? 14756 0 14757 $ zsh -c 'set -m; echo $?' 14758 set: can't change option: -m 14759 $ (set -m); echo $? 14760 set: can't change option: -m 14761 1 14762 $ pdksh -ci 'echo $-; (echo $-)' 14763 cim 14764 c 14765 14766 Use of `set -n' (typically via `sh -n script') to validate a 14767 script is not foolproof. Modern `ksh93' tries to be helpful by 14768 informing you about better syntax, but switching the script to use 14769 the suggested syntax in order to silence the warnings would render 14770 the script no longer portable to older shells: 14771 14772 $ ksh -nc '``' 14773 ksh: warning: line 1: `...` obsolete, use $(...) 14774 0 14775 14776 Furthermore, on ancient hosts, such as SunOS 4, `sh -n' could go 14777 into an infinite loop; even with that bug fixed, Solaris 8 14778 `/bin/sh' takes extremely long to parse large scripts. Autoconf 14779 itself uses `sh -n' within its testsuite to check that correct 14780 scripts were generated, but only after first probing for other 14781 shell features (such as `test -n "${BASH_VERSION+set}"') that 14782 indicate a reasonably fast and working implementation. 14783 14784`shift' 14785 Not only is `shift'ing a bad idea when there is nothing left to 14786 shift, but in addition it is not portable: the shell of MIPS 14787 RISC/OS 4.52 refuses to do it. 14788 14789 Don't use `shift 2' etc.; while it in the SVR1 shell (1983), it is 14790 also absent in many pre-Posix shells. 14791 14792`source' 14793 This command is not portable, as Posix does not require it; use 14794 `.' instead. 14795 14796`test' 14797 The `test' program is the way to perform many file and string 14798 tests. It is often invoked by the alternate name `[', but using 14799 that name in Autoconf code is asking for trouble since it is an M4 14800 quote character. 14801 14802 The `-a', `-o', `(', and `)' operands are not present in all 14803 implementations, and have been marked obsolete by Posix 2008. 14804 This is because there are inherent ambiguities in using them. For 14805 example, `test "$1" -a "$2"' looks like a binary operator to check 14806 whether two strings are both non-empty, but if `$1' is the literal 14807 `!', then some implementations of `test' treat it as a negation of 14808 the unary operator `-a'. 14809 14810 Thus, portable uses of `test' should never have more than four 14811 arguments, and scripts should use shell constructs like `&&' and 14812 `||' instead. If you combine `&&' and `||' in the same statement, 14813 keep in mind that they have equal precedence, so it is often 14814 better to parenthesize even when this is redundant. For example: 14815 14816 # Not portable: 14817 test "X$a" = "X$b" -a \ 14818 '(' "X$c" != "X$d" -o "X$e" = "X$f" ')' 14819 14820 # Portable: 14821 test "X$a" = "X$b" && 14822 { test "X$c" != "X$d" || test "X$e" = "X$f"; } 14823 14824 `test' does not process options like most other commands do; for 14825 example, it does not recognize the `--' argument as marking the 14826 end of options. 14827 14828 It is safe to use `!' as a `test' operator. For example, `if test 14829 ! -d foo; ...' is portable even though `if ! test -d foo; ...' is 14830 not. 14831 14832`test' (files) 14833 To enable `configure' scripts to support cross-compilation, they 14834 shouldn't do anything that tests features of the build system 14835 instead of the host system. But occasionally you may find it 14836 necessary to check whether some arbitrary file exists. To do so, 14837 use `test -f', `test -r', or `test -x'. Do not use `test -e', 14838 because Solaris 10 `/bin/sh' lacks it. To test for symbolic links 14839 on systems that have them, use `test -h' rather than `test -L'; 14840 either form conforms to Posix 1003.1-2001, but older shells like 14841 Solaris 8 `/bin/sh' support only `-h'. 14842 14843 For historical reasons, Posix reluctantly allows implementations of 14844 `test -x' that will succeed for the root user, even if no execute 14845 permissions are present. Furthermore, shells do not all agree on 14846 whether Access Control Lists should affect `test -r', `test -w', 14847 and `test -x'; some shells base test results strictly on the 14848 current user id compared to file owner and mode, as if by 14849 `stat(2)'; while other shells base test results on whether the 14850 current user has the given right, even if that right is only 14851 granted by an ACL, as if by `faccessat(2)'. Furthermore, there is 14852 a classic time of check to time of use race between any use of 14853 `test' followed by operating on the just-checked file. Therefore, 14854 it is a good idea to write scripts that actually attempt an 14855 operation, and are prepared for the resulting failure if 14856 permission is denied, rather than trying to avoid an operation 14857 based solely on whether `test' guessed that it might not be 14858 permitted. 14859 14860`test' (strings) 14861 Posix says that `test "STRING"' succeeds if STRING is not null, 14862 but this usage is not portable to traditional platforms like 14863 Solaris 10 `/bin/sh', which mishandle strings like `!' and `-n'. 14864 14865 Posix also says that `test ! "STRING"', `test -n "STRING"' and 14866 `test -z "STRING"' work with any string, but many shells (such as 14867 Solaris, AIX 3.2, UNICOS 10.0.0.6, Digital Unix 4, etc.) get 14868 confused if STRING looks like an operator: 14869 14870 $ test -n = 14871 test: argument expected 14872 $ test ! -n 14873 test: argument expected 14874 $ test -z ")"; echo $? 14875 0 14876 14877 Similarly, Posix says that both `test "STRING1" = "STRING2"' and 14878 `test "STRING1" != "STRING2"' work for any pairs of strings, but 14879 in practice this is not true for troublesome strings that look 14880 like operators or parentheses, or that begin with `-'. 14881 14882 It is best to protect such strings with a leading `X', e.g., `test 14883 "XSTRING" != X' rather than `test -n "STRING"' or `test ! 14884 "STRING"'. 14885 14886 It is common to find variations of the following idiom: 14887 14888 test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" && 14889 ACTION 14890 14891 to take an action when a token matches a given pattern. Such 14892 constructs should be avoided by using: 14893 14894 case $ac_feature in 14895 *[!-a-zA-Z0-9_]*) ACTION;; 14896 esac 14897 14898 If the pattern is a complicated regular expression that cannot be 14899 expressed as a shell pattern, use something like this instead: 14900 14901 expr "X$ac_feature" : 'X.*[^-a-zA-Z0-9_]' >/dev/null && 14902 ACTION 14903 14904 `expr "XFOO" : "XBAR"' is more robust than `echo "XFOO" | grep 14905 "^XBAR"', because it avoids problems when `FOO' contains 14906 backslashes. 14907 14908`trap' 14909 It is safe to trap at least the signals 1, 2, 13, and 15. You can 14910 also trap 0, i.e., have the `trap' run when the script ends 14911 (either via an explicit `exit', or the end of the script). The 14912 trap for 0 should be installed outside of a shell function, or AIX 14913 5.3 `/bin/sh' will invoke the trap at the end of this function. 14914 14915 Posix says that `trap - 1 2 13 15' resets the traps for the 14916 specified signals to their default values, but many common shells 14917 (e.g., Solaris `/bin/sh') misinterpret this and attempt to execute 14918 a "command" named `-' when the specified conditions arise. Posix 14919 2008 also added a requirement to support `trap 1 2 13 15' to reset 14920 traps, as this is supported by a larger set of shells, but there 14921 are still shells like `dash' that mistakenly try to execute `1' 14922 instead of resetting the traps. Therefore, there is no portable 14923 workaround, except for `trap - 0', for which `trap '' 0' is a 14924 portable substitute. 14925 14926 Although Posix is not absolutely clear on this point, it is widely 14927 admitted that when entering the trap `$?' should be set to the exit 14928 status of the last command run before the trap. The ambiguity can 14929 be summarized as: "when the trap is launched by an `exit', what is 14930 the _last_ command run: that before `exit', or `exit' itself?" 14931 14932 Bash considers `exit' to be the last command, while Zsh and 14933 Solaris `/bin/sh' consider that when the trap is run it is _still_ 14934 in the `exit', hence it is the previous exit status that the trap 14935 receives: 14936 14937 $ cat trap.sh 14938 trap 'echo $?' 0 14939 (exit 42); exit 0 14940 $ zsh trap.sh 14941 42 14942 $ bash trap.sh 14943 0 14944 14945 The portable solution is then simple: when you want to `exit 42', 14946 run `(exit 42); exit 42', the first `exit' being used to set the 14947 exit status to 42 for Zsh, and the second to trigger the trap and 14948 pass 42 as exit status for Bash. In M4sh, this is covered by using 14949 `AS_EXIT'. 14950 14951 The shell in FreeBSD 4.0 has the following bug: `$?' is reset to 0 14952 by empty lines if the code is inside `trap'. 14953 14954 $ trap 'false 14955 14956 echo $?' 0 14957 $ exit 14958 0 14959 14960 Fortunately, this bug only affects `trap'. 14961 14962 Several shells fail to execute an exit trap that is defined inside 14963 a subshell, when the last command of that subshell is not a 14964 builtin. A workaround is to use `exit $?' as the shell builtin. 14965 14966 $ bash -c '(trap "echo hi" 0; /bin/true)' 14967 hi 14968 $ /bin/sh -c '(trap "echo hi" 0; /bin/true)' 14969 $ /bin/sh -c '(trap "echo hi" 0; /bin/true; exit $?)' 14970 hi 14971 14972 Likewise, older implementations of `bash' failed to preserve `$?' 14973 across an exit trap consisting of a single cleanup command. 14974 14975 $ bash -c 'trap "/bin/true" 0; exit 2'; echo $? 14976 2 14977 $ bash-2.05b -c 'trap "/bin/true" 0; exit 2'; echo $? 14978 0 14979 $ bash-2.05b -c 'trap ":; /bin/true" 0; exit 2'; echo $? 14980 2 14981 14982`true' 14983 Don't worry: as far as we know `true' is portable. Nevertheless, 14984 it's not always a builtin (e.g., Bash 1.x), and the portable shell 14985 community tends to prefer using `:'. This has a funny side 14986 effect: when asked whether `false' is more portable than `true' 14987 Alexandre Oliva answered: 14988 14989 In a sense, yes, because if it doesn't exist, the shell will 14990 produce an exit status of failure, which is correct for 14991 `false', but not for `true'. 14992 14993 Remember that even though `:' ignores its arguments, it still takes 14994 time to compute those arguments. It is a good idea to use double 14995 quotes around any arguments to `:' to avoid time spent in field 14996 splitting and file name expansion. 14997 14998`unset' 14999 In some nonconforming shells (e.g., Solaris 10 `/bin/ksh' and 15000 `/usr/xpg4/bin/sh', NetBSD 5.99.43 sh, or Bash 2.05a), `unset FOO' 15001 fails when `FOO' is not set. This can interfere with `set -e' 15002 operation. You can use 15003 15004 FOO=; unset FOO 15005 15006 if you are not sure that `FOO' is set. 15007 15008 A few ancient shells lack `unset' entirely. For some variables 15009 such as `PS1', you can use a neutralizing value instead: 15010 15011 PS1='$ ' 15012 15013 Usually, shells that do not support `unset' need less effort to 15014 make the environment sane, so for example is not a problem if you 15015 cannot unset `CDPATH' on those shells. However, Bash 2.01 15016 mishandles `unset MAIL' and `unset MAILPATH' in some cases and 15017 dumps core. So, you should do something like 15018 15019 ( (unset MAIL) || exit 1) >/dev/null 2>&1 && unset MAIL || : 15020 15021 *Note Special Shell Variables::, for some neutralizing values. 15022 Also, see *note Limitations of Builtins: export, for the case of 15023 environment variables. 15024 15025`wait' 15026 The exit status of `wait' is not always reliable. 15027 15028 15029File: autoconf.info, Node: Limitations of Usual Tools, Prev: Limitations of Builtins, Up: Portable Shell 15030 1503111.15 Limitations of Usual Tools 15032================================ 15033 15034The small set of tools you can expect to find on any machine can still 15035include some limitations you should be aware of. 15036 15037`awk' 15038 Don't leave white space before the opening parenthesis in a user 15039 function call. Posix does not allow this and GNU Awk rejects it: 15040 15041 $ gawk 'function die () { print "Aaaaarg!" } 15042 BEGIN { die () }' 15043 gawk: cmd. line:2: BEGIN { die () } 15044 gawk: cmd. line:2: ^ parse error 15045 $ gawk 'function die () { print "Aaaaarg!" } 15046 BEGIN { die() }' 15047 Aaaaarg! 15048 15049 Posix says that if a program contains only `BEGIN' actions, and 15050 contains no instances of `getline', then the program merely 15051 executes the actions without reading input. However, traditional 15052 Awk implementations (such as Solaris 10 `awk') read and discard 15053 input in this case. Portable scripts can redirect input from 15054 `/dev/null' to work around the problem. For example: 15055 15056 awk 'BEGIN {print "hello world"}' </dev/null 15057 15058 Posix says that in an `END' action, `$NF' (and presumably, `$1') 15059 retain their value from the last record read, if no intervening 15060 `getline' occurred. However, some implementations (such as 15061 Solaris 10 `/usr/bin/awk', `nawk', or Darwin `awk') reset these 15062 variables. A workaround is to use an intermediate variable prior 15063 to the `END' block. For example: 15064 15065 $ cat end.awk 15066 { tmp = $1 } 15067 END { print "a", $1, $NF, "b", tmp } 15068 $ echo 1 | awk -f end.awk 15069 a b 1 15070 $ echo 1 | gawk -f end.awk 15071 a 1 1 b 1 15072 15073 If you want your program to be deterministic, don't depend on `for' 15074 on arrays: 15075 15076 $ cat for.awk 15077 END { 15078 arr["foo"] = 1 15079 arr["bar"] = 1 15080 for (i in arr) 15081 print i 15082 } 15083 $ gawk -f for.awk </dev/null 15084 foo 15085 bar 15086 $ nawk -f for.awk </dev/null 15087 bar 15088 foo 15089 15090 Some Awk implementations, such as HP-UX 11.0's native one, 15091 mishandle anchors: 15092 15093 $ echo xfoo | $AWK '/foo|^bar/ { print }' 15094 $ echo bar | $AWK '/foo|^bar/ { print }' 15095 bar 15096 $ echo xfoo | $AWK '/^bar|foo/ { print }' 15097 xfoo 15098 $ echo bar | $AWK '/^bar|foo/ { print }' 15099 bar 15100 15101 Either do not depend on such patterns (i.e., use `/^(.*foo|bar)/', 15102 or use a simple test to reject such implementations. 15103 15104 On `ia64-hp-hpux11.23', Awk mishandles `printf' conversions after 15105 `%u': 15106 15107 $ awk 'BEGIN { printf "%u %d\n", 0, -1 }' 15108 0 0 15109 15110 AIX version 5.2 has an arbitrary limit of 399 on the length of 15111 regular expressions and literal strings in an Awk program. 15112 15113 Traditional Awk implementations derived from Unix version 7, such 15114 as Solaris `/bin/awk', have many limitations and do not conform to 15115 Posix. Nowadays `AC_PROG_AWK' (*note Particular Programs::) finds 15116 you an Awk that doesn't have these problems, but if for some 15117 reason you prefer not to use `AC_PROG_AWK' you may need to address 15118 them. For more detailed descriptions, see *note `awk' language 15119 history: (gawk)Language History. 15120 15121 Traditional Awk does not support multidimensional arrays or 15122 user-defined functions. 15123 15124 Traditional Awk does not support the `-v' option. You can use 15125 assignments after the program instead, e.g., `$AWK '{print v $1}' 15126 v=x'; however, don't forget that such assignments are not 15127 evaluated until they are encountered (e.g., after any `BEGIN' 15128 action). 15129 15130 Traditional Awk does not support the keywords `delete' or `do'. 15131 15132 Traditional Awk does not support the expressions `A?B:C', `!A', 15133 `A^B', or `A^=B'. 15134 15135 Traditional Awk does not support the predefined `CONVFMT' or 15136 `ENVIRON' variables. 15137 15138 Traditional Awk supports only the predefined functions `exp', 15139 `index', `int', `length', `log', `split', `sprintf', `sqrt', and 15140 `substr'. 15141 15142 Traditional Awk `getline' is not at all compatible with Posix; 15143 avoid it. 15144 15145 Traditional Awk has `for (i in a) ...' but no other uses of the 15146 `in' keyword. For example, it lacks `if (i in a) ...'. 15147 15148 In code portable to both traditional and modern Awk, `FS' must be a 15149 string containing just one ordinary character, and similarly for 15150 the field-separator argument to `split'. 15151 15152 Traditional Awk has a limit of 99 fields in a record. Since some 15153 Awk implementations, like Tru64's, split the input even if you 15154 don't refer to any field in the script, to circumvent this 15155 problem, set `FS' to an unusual character and use `split'. 15156 15157 Traditional Awk has a limit of at most 99 bytes in a number 15158 formatted by `OFMT'; for example, `OFMT="%.300e"; print 0.1;' 15159 typically dumps core. 15160 15161 The original version of Awk had a limit of at most 99 bytes per 15162 `split' field, 99 bytes per `substr' substring, and 99 bytes per 15163 run of non-special characters in a `printf' format, but these bugs 15164 have been fixed on all practical hosts that we know of. 15165 15166 HP-UX 11.00 and IRIX 6.5 Awk require that input files have a line 15167 length of at most 3070 bytes. 15168 15169`basename' 15170 Not all hosts have a working `basename'. You can use `expr' 15171 instead. 15172 15173`cat' 15174 Don't rely on any option. 15175 15176`cc' 15177 The command `cc -c foo.c' traditionally produces an object file 15178 named `foo.o'. Most compilers allow `-c' to be combined with `-o' 15179 to specify a different object file name, but Posix does not 15180 require this combination and a few compilers lack support for it. 15181 *Note C Compiler::, for how GNU Make tests for this feature with 15182 `AC_PROG_CC_C_O'. 15183 15184 When a compilation such as `cc -o foo foo.c' fails, some compilers 15185 (such as CDS on Reliant Unix) leave a `foo.o'. 15186 15187 HP-UX `cc' doesn't accept `.S' files to preprocess and assemble. 15188 `cc -c foo.S' appears to succeed, but in fact does nothing. 15189 15190 The default executable, produced by `cc foo.c', can be 15191 15192 * `a.out' -- usual Posix convention. 15193 15194 * `b.out' -- i960 compilers (including `gcc'). 15195 15196 * `a.exe' -- DJGPP port of `gcc'. 15197 15198 * `a_out.exe' -- GNV `cc' wrapper for DEC C on OpenVMS. 15199 15200 * `foo.exe' -- various MS-DOS compilers. 15201 15202 The C compiler's traditional name is `cc', but other names like 15203 `gcc' are common. Posix 1003.1-2001 specifies the name `c99', but 15204 older Posix editions specified `c89' and anyway these standard 15205 names are rarely used in practice. Typically the C compiler is 15206 invoked from makefiles that use `$(CC)', so the value of the `CC' 15207 make variable selects the compiler name. 15208 15209`chgrp' 15210`chown' 15211 It is not portable to change a file's group to a group that the 15212 owner does not belong to. 15213 15214`chmod' 15215 Avoid usages like `chmod -w file'; use `chmod a-w file' instead, 15216 for two reasons. First, plain `-w' does not necessarily make the 15217 file unwritable, since it does not affect mode bits that 15218 correspond to bits in the file mode creation mask. Second, Posix 15219 says that the `-w' might be interpreted as an 15220 implementation-specific option, not as a mode; Posix suggests 15221 using `chmod -- -w file' to avoid this confusion, but unfortunately 15222 `--' does not work on some older hosts. 15223 15224`cmp' 15225 `cmp' performs a raw data comparison of two files, while `diff' 15226 compares two text files. Therefore, if you might compare DOS 15227 files, even if only checking whether two files are different, use 15228 `diff' to avoid spurious differences due to differences of newline 15229 encoding. 15230 15231`cp' 15232 Avoid the `-r' option, since Posix 1003.1-2004 marks it as 15233 obsolescent and its behavior on special files is 15234 implementation-defined. Use `-R' instead. On GNU hosts the two 15235 options are equivalent, but on Solaris hosts (for example) `cp -r' 15236 reads from pipes instead of replicating them. AIX 5.3 `cp -R' may 15237 corrupt its own memory with some directory hierarchies and error 15238 out or dump core: 15239 15240 mkdir -p 12345678/12345678/12345678/12345678 15241 touch 12345678/12345678/x 15242 cp -R 12345678 t 15243 cp: 0653-440 12345678/12345678/: name too long. 15244 15245 Some `cp' implementations (e.g., BSD/OS 4.2) do not allow trailing 15246 slashes at the end of nonexistent destination directories. To 15247 avoid this problem, omit the trailing slashes. For example, use 15248 `cp -R source /tmp/newdir' rather than `cp -R source /tmp/newdir/' 15249 if `/tmp/newdir' does not exist. 15250 15251 The ancient SunOS 4 `cp' does not support `-f', although its `mv' 15252 does. 15253 15254 Traditionally, file timestamps had 1-second resolution, and `cp 15255 -p' copied the timestamps exactly. However, many modern file 15256 systems have timestamps with 1-nanosecond resolution. 15257 Unfortunately, some older `cp -p' implementations truncate 15258 timestamps when copying files, which can cause the destination 15259 file to appear to be older than the source. The exact amount of 15260 truncation depends on the resolution of the system calls that `cp' 15261 uses. Traditionally this was `utime', which has 1-second 15262 resolution. Less-ancient `cp' implementations such as GNU Core 15263 Utilities 5.0.91 (2003) use `utimes', which has 1-microsecond 15264 resolution. Modern implementations such as GNU Core Utilities 15265 6.12 (2008) can set timestamps to the full nanosecond resolution, 15266 using the modern system calls `futimens' and `utimensat' when they 15267 are available. As of 2011, though, many platforms do not yet 15268 fully support these new system calls. 15269 15270 Bob Proulx notes that `cp -p' always _tries_ to copy ownerships. 15271 But whether it actually does copy ownerships or not is a system 15272 dependent policy decision implemented by the kernel. If the 15273 kernel allows it then it happens. If the kernel does not allow it 15274 then it does not happen. It is not something `cp' itself has 15275 control over. 15276 15277 In Unix System V any user can chown files to any other user, and 15278 System V also has a non-sticky `/tmp'. That probably derives from 15279 the heritage of System V in a business environment without hostile 15280 users. BSD changed this to be a more secure model where only root 15281 can `chown' files and a sticky `/tmp' is used. That undoubtedly 15282 derives from the heritage of BSD in a campus environment. 15283 15284 GNU/Linux and Solaris by default follow BSD, but can be configured 15285 to allow a System V style `chown'. On the other hand, HP-UX 15286 follows System V, but can be configured to use the modern security 15287 model and disallow `chown'. Since it is an 15288 administrator-configurable parameter you can't use the name of the 15289 kernel as an indicator of the behavior. 15290 15291`date' 15292 Some versions of `date' do not recognize special `%' directives, 15293 and unfortunately, instead of complaining, they just pass them 15294 through, and exit with success: 15295 15296 $ uname -a 15297 OSF1 medusa.sis.pasteur.fr V5.1 732 alpha 15298 $ date "+%s" 15299 %s 15300 15301`diff' 15302 Option `-u' is nonportable. 15303 15304 Some implementations, such as Tru64's, fail when comparing to 15305 `/dev/null'. Use an empty file instead. 15306 15307`dirname' 15308 Not all hosts have a working `dirname', and you should instead use 15309 `AS_DIRNAME' (*note Programming in M4sh::). For example: 15310 15311 dir=`dirname "$file"` # This is not portable. 15312 dir=`AS_DIRNAME(["$file"])` # This is more portable. 15313 15314`egrep' 15315 Posix 1003.1-2001 no longer requires `egrep', but many hosts do 15316 not yet support the Posix replacement `grep -E'. Also, some 15317 traditional implementations do not work on long input lines. To 15318 work around these problems, invoke `AC_PROG_EGREP' and then use 15319 `$EGREP'. 15320 15321 Portable extended regular expressions should use `\' only to escape 15322 characters in the string `$()*+.?[\^{|'. For example, `\}' is not 15323 portable, even though it typically matches `}'. 15324 15325 The empty alternative is not portable. Use `?' instead. For 15326 instance with Digital Unix v5.0: 15327 15328 > printf "foo\n|foo\n" | $EGREP '^(|foo|bar)$' 15329 |foo 15330 > printf "bar\nbar|\n" | $EGREP '^(foo|bar|)$' 15331 bar| 15332 > printf "foo\nfoo|\n|bar\nbar\n" | $EGREP '^(foo||bar)$' 15333 foo 15334 |bar 15335 15336 `$EGREP' also suffers the limitations of `grep' (*note Limitations 15337 of Usual Tools: grep.). 15338 15339`expr' 15340 Not all implementations obey the Posix rule that `--' separates 15341 options from arguments; likewise, not all implementations provide 15342 the extension to Posix that the first argument can be treated as 15343 part of a valid expression rather than an invalid option if it 15344 begins with `-'. When performing arithmetic, use `expr 0 + $var' 15345 if `$var' might be a negative number, to keep `expr' from 15346 interpreting it as an option. 15347 15348 No `expr' keyword starts with `X', so use `expr X"WORD" : 15349 'XREGEX'' to keep `expr' from misinterpreting WORD. 15350 15351 Don't use `length', `substr', `match' and `index'. 15352 15353`expr' (`|') 15354 You can use `|'. Although Posix does require that `expr ''' 15355 return the empty string, it does not specify the result when you 15356 `|' together the empty string (or zero) with the empty string. For 15357 example: 15358 15359 expr '' \| '' 15360 15361 Posix 1003.2-1992 returns the empty string for this case, but 15362 traditional Unix returns `0' (Solaris is one such example). In 15363 Posix 1003.1-2001, the specification was changed to match 15364 traditional Unix's behavior (which is bizarre, but it's too late 15365 to fix this). Please note that the same problem does arise when 15366 the empty string results from a computation, as in: 15367 15368 expr bar : foo \| foo : bar 15369 15370 Avoid this portability problem by avoiding the empty string. 15371 15372`expr' (`:') 15373 Portable `expr' regular expressions should use `\' to escape only 15374 characters in the string `$()*.0123456789[\^n{}'. For example, 15375 alternation, `\|', is common but Posix does not require its 15376 support, so it should be avoided in portable scripts. Similarly, 15377 `\+' and `\?' should be avoided. 15378 15379 Portable `expr' regular expressions should not begin with `^'. 15380 Patterns are automatically anchored so leading `^' is not needed 15381 anyway. 15382 15383 On the other hand, the behavior of the `$' anchor is not portable 15384 on multi-line strings. Posix is ambiguous whether the anchor 15385 applies to each line, as was done in older versions of the GNU 15386 Core Utilities, or whether it applies only to the end of the 15387 overall string, as in Coreutils 6.0 and most other implementations. 15388 15389 $ baz='foo 15390 > bar' 15391 $ expr "X$baz" : 'X\(foo\)$' 15392 15393 $ expr-5.97 "X$baz" : 'X\(foo\)$' 15394 foo 15395 15396 The Posix standard is ambiguous as to whether `expr 'a' : '\(b\)'' 15397 outputs `0' or the empty string. In practice, it outputs the 15398 empty string on most platforms, but portable scripts should not 15399 assume this. For instance, the QNX 4.25 native `expr' returns `0'. 15400 15401 One might think that a way to get a uniform behavior would be to 15402 use the empty string as a default value: 15403 15404 expr a : '\(b\)' \| '' 15405 15406 Unfortunately this behaves exactly as the original expression; see 15407 the `expr' (`|') entry for more information. 15408 15409 Some ancient `expr' implementations (e.g., SunOS 4 `expr' and 15410 Solaris 8 `/usr/ucb/expr') have a silly length limit that causes 15411 `expr' to fail if the matched substring is longer than 120 bytes. 15412 In this case, you might want to fall back on `echo|sed' if `expr' 15413 fails. Nowadays this is of practical importance only for the rare 15414 installer who mistakenly puts `/usr/ucb' before `/usr/bin' in 15415 `PATH'. 15416 15417 On Mac OS X 10.4, `expr' mishandles the pattern `[^-]' in some 15418 cases. For example, the command 15419 expr Xpowerpc-apple-darwin8.1.0 : 'X[^-]*-[^-]*-\(.*\)' 15420 15421 outputs `apple-darwin8.1.0' rather than the correct `darwin8.1.0'. 15422 This particular case can be worked around by substituting `[^--]' 15423 for `[^-]'. 15424 15425 Don't leave, there is some more! 15426 15427 The QNX 4.25 `expr', in addition of preferring `0' to the empty 15428 string, has a funny behavior in its exit status: it's always 1 15429 when parentheses are used! 15430 15431 $ val=`expr 'a' : 'a'`; echo "$?: $val" 15432 0: 1 15433 $ val=`expr 'a' : 'b'`; echo "$?: $val" 15434 1: 0 15435 15436 $ val=`expr 'a' : '\(a\)'`; echo "?: $val" 15437 1: a 15438 $ val=`expr 'a' : '\(b\)'`; echo "?: $val" 15439 1: 0 15440 15441 In practice this can be a big problem if you are ready to catch 15442 failures of `expr' programs with some other method (such as using 15443 `sed'), since you may get twice the result. For instance 15444 15445 $ expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/' 15446 15447 outputs `a' on most hosts, but `aa' on QNX 4.25. A simple 15448 workaround consists of testing `expr' and using a variable set to 15449 `expr' or to `false' according to the result. 15450 15451 Tru64 `expr' incorrectly treats the result as a number, if it can 15452 be interpreted that way: 15453 15454 $ expr 00001 : '.*\(...\)' 15455 1 15456 15457 On HP-UX 11, `expr' only supports a single sub-expression. 15458 15459 $ expr 'Xfoo' : 'X\(f\(oo\)*\)$' 15460 expr: More than one '\(' was used. 15461 15462`fgrep' 15463 Posix 1003.1-2001 no longer requires `fgrep', but many hosts do 15464 not yet support the Posix replacement `grep -F'. Also, some 15465 traditional implementations do not work on long input lines. To 15466 work around these problems, invoke `AC_PROG_FGREP' and then use 15467 `$FGREP'. 15468 15469 Tru64/OSF 5.1 `fgrep' does not match an empty pattern. 15470 15471`find' 15472 The option `-maxdepth' seems to be GNU specific. Tru64 v5.1, 15473 NetBSD 1.5 and Solaris `find' commands do not understand it. 15474 15475 The replacement of `{}' is guaranteed only if the argument is 15476 exactly _{}_, not if it's only a part of an argument. For 15477 instance on DU, and HP-UX 10.20 and HP-UX 11: 15478 15479 $ touch foo 15480 $ find . -name foo -exec echo "{}-{}" \; 15481 {}-{} 15482 15483 while GNU `find' reports `./foo-./foo'. 15484 15485`grep' 15486 Portable scripts can rely on the `grep' options `-c', `-l', `-n', 15487 and `-v', but should avoid other options. For example, don't use 15488 `-w', as Posix does not require it and Irix 6.5.16m's `grep' does 15489 not support it. Also, portable scripts should not combine `-c' 15490 with `-l', as Posix does not allow this. 15491 15492 Some of the options required by Posix are not portable in practice. 15493 Don't use `grep -q' to suppress output, because many `grep' 15494 implementations (e.g., Solaris) do not support `-q'. Don't use 15495 `grep -s' to suppress output either, because Posix says `-s' does 15496 not suppress output, only some error messages; also, the `-s' 15497 option of traditional `grep' behaved like `-q' does in most modern 15498 implementations. Instead, redirect the standard output and 15499 standard error (in case the file doesn't exist) of `grep' to 15500 `/dev/null'. Check the exit status of `grep' to determine whether 15501 it found a match. 15502 15503 The QNX4 implementation fails to count lines with `grep -c '$'', 15504 but works with `grep -c '^''. Other alternatives for counting 15505 lines are to use `sed -n '$='' or `wc -l'. 15506 15507 Some traditional `grep' implementations do not work on long input 15508 lines. On AIX the default `grep' silently truncates long lines on 15509 the input before matching. 15510 15511 Also, many implementations do not support multiple regexps with 15512 `-e': they either reject `-e' entirely (e.g., Solaris) or honor 15513 only the last pattern (e.g., IRIX 6.5 and NeXT). To work around 15514 these problems, invoke `AC_PROG_GREP' and then use `$GREP'. 15515 15516 Another possible workaround for the multiple `-e' problem is to 15517 separate the patterns by newlines, for example: 15518 15519 grep 'foo 15520 bar' in.txt 15521 15522 except that this fails with traditional `grep' implementations and 15523 with OpenBSD 3.8 `grep'. 15524 15525 Traditional `grep' implementations (e.g., Solaris) do not support 15526 the `-E' or `-F' options. To work around these problems, invoke 15527 `AC_PROG_EGREP' and then use `$EGREP', and similarly for 15528 `AC_PROG_FGREP' and `$FGREP'. Even if you are willing to require 15529 support for Posix `grep', your script should not use both `-E' and 15530 `-F', since Posix does not allow this combination. 15531 15532 Portable `grep' regular expressions should use `\' only to escape 15533 characters in the string `$()*.0123456789[\^{}'. For example, 15534 alternation, `\|', is common but Posix does not require its 15535 support in basic regular expressions, so it should be avoided in 15536 portable scripts. Solaris and HP-UX `grep' do not support it. 15537 Similarly, the following escape sequences should also be avoided: 15538 `\<', `\>', `\+', `\?', `\`', `\'', `\B', `\b', `\S', `\s', `\W', 15539 and `\w'. 15540 15541 Posix does not specify the behavior of `grep' on binary files. An 15542 example where this matters is using BSD `grep' to search text that 15543 includes embedded ANSI escape sequences for colored output to 15544 terminals (`\033[m' is the sequence to restore normal output); the 15545 behavior depends on whether input is seekable: 15546 15547 $ printf 'esc\033[mape\n' > sample 15548 $ grep . sample 15549 Binary file sample matches 15550 $ cat sample | grep . 15551 escape 15552 15553`join' 15554 Solaris 8 `join' has bugs when the second operand is standard 15555 input, and when standard input is a pipe. For example, the 15556 following shell script causes Solaris 8 `join' to loop forever: 15557 15558 cat >file <<'EOF' 15559 1 x 15560 2 y 15561 EOF 15562 cat file | join file - 15563 15564 Use `join - file' instead. 15565 15566 On NetBSD, `join -a 1 file1 file2' mistakenly behaves like `join 15567 -a 1 -a 2 1 file1 file2', resulting in a usage warning; the 15568 workaround is to use `join -a1 file1 file2' instead. 15569 15570`ln' 15571 Don't rely on `ln' having a `-f' option. Symbolic links are not 15572 available on old systems; use `$(LN_S)' as a portable substitute. 15573 15574 For versions of the DJGPP before 2.04, `ln' emulates symbolic links 15575 to executables by generating a stub that in turn calls the real 15576 program. This feature also works with nonexistent files like in 15577 the Posix spec. So `ln -s file link' generates `link.exe', which 15578 attempts to call `file.exe' if run. But this feature only works 15579 for executables, so `cp -p' is used instead for these systems. 15580 DJGPP versions 2.04 and later have full support for symbolic links. 15581 15582`ls' 15583 The portable options are `-acdilrtu'. Current practice is for 15584 `-l' to output both owner and group, even though ancient versions 15585 of `ls' omitted the group. 15586 15587 On ancient hosts, `ls foo' sent the diagnostic `foo not found' to 15588 standard output if `foo' did not exist. Hence a shell command 15589 like `sources=`ls *.c 2>/dev/null`' did not always work, since it 15590 was equivalent to `sources='*.c not found'' in the absence of `.c' 15591 files. This is no longer a practical problem, since current `ls' 15592 implementations send diagnostics to standard error. 15593 15594 The behavior of `ls' on a directory that is being concurrently 15595 modified is not always predictable, because of a data race where 15596 cached information returned by `readdir' does not match the current 15597 directory state. In fact, MacOS 10.5 has an intermittent bug where 15598 `readdir', and thus `ls', sometimes lists a file more than once if 15599 other files were added or removed from the directory immediately 15600 prior to the `ls' call. Since `ls' already sorts its output, the 15601 duplicate entries can be avoided by piping the results through 15602 `uniq'. 15603 15604`mkdir' 15605 No `mkdir' option is portable to older systems. Instead of `mkdir 15606 -p FILE-NAME', you should use `AS_MKDIR_P(FILE-NAME)' (*note 15607 Programming in M4sh::) or `AC_PROG_MKDIR_P' (*note Particular 15608 Programs::). 15609 15610 Combining the `-m' and `-p' options, as in `mkdir -m go-w -p DIR', 15611 often leads to trouble. FreeBSD `mkdir' incorrectly attempts to 15612 change the permissions of DIR even if it already exists. HP-UX 15613 11.23 and IRIX 6.5 `mkdir' often assign the wrong permissions to 15614 any newly-created parents of DIR. 15615 15616 Posix does not clearly specify whether `mkdir -p foo' should 15617 succeed when `foo' is a symbolic link to an already-existing 15618 directory. The GNU Core Utilities 5.1.0 `mkdir' succeeds, but 15619 Solaris `mkdir' fails. 15620 15621 Traditional `mkdir -p' implementations suffer from race conditions. 15622 For example, if you invoke `mkdir -p a/b' and `mkdir -p a/c' at 15623 the same time, both processes might detect that `a' is missing, 15624 one might create `a', then the other might try to create `a' and 15625 fail with a `File exists' diagnostic. The GNU Core Utilities 15626 (`fileutils' version 4.1), FreeBSD 5.0, NetBSD 2.0.2, and OpenBSD 15627 2.4 are known to be race-free when two processes invoke `mkdir -p' 15628 simultaneously, but earlier versions are vulnerable. Solaris 15629 `mkdir' is still vulnerable as of Solaris 10, and other 15630 traditional Unix systems are probably vulnerable too. This 15631 possible race is harmful in parallel builds when several Make 15632 rules call `mkdir -p' to construct directories. You may use 15633 `install-sh -d' as a safe replacement, provided this script is 15634 recent enough; the copy shipped with Autoconf 2.60 and Automake 15635 1.10 is OK, but copies from older versions are vulnerable. 15636 15637`mkfifo' 15638`mknod' 15639 The GNU Coding Standards state that `mknod' is safe to use on 15640 platforms where it has been tested to exist; but it is generally 15641 portable only for creating named FIFOs, since device numbers are 15642 platform-specific. Autotest uses `mkfifo' to implement parallel 15643 testsuites. Posix states that behavior is unspecified when 15644 opening a named FIFO for both reading and writing; on at least 15645 Cygwin, this results in failure on any attempt to read or write to 15646 that file descriptor. 15647 15648`mktemp' 15649 Shell scripts can use temporary files safely with `mktemp', but it 15650 does not exist on all systems. A portable way to create a safe 15651 temporary file name is to create a temporary directory with mode 15652 700 and use a file inside this directory. Both methods prevent 15653 attackers from gaining control, though `mktemp' is far less likely 15654 to fail gratuitously under attack. 15655 15656 Here is sample code to create a new temporary directory `$dir' 15657 safely: 15658 15659 # Create a temporary directory $dir in $TMPDIR (default /tmp). 15660 # Use mktemp if possible; otherwise fall back on mkdir, 15661 # with $RANDOM to make collisions less likely. 15662 : "${TMPDIR:=/tmp}" 15663 { 15664 dir=` 15665 (umask 077 && mktemp -d "$TMPDIR/fooXXXXXX") 2>/dev/null 15666 ` && 15667 test -d "$dir" 15668 } || { 15669 dir=$TMPDIR/foo$$-$RANDOM 15670 (umask 077 && mkdir "$dir") 15671 } || exit $? 15672 15673`mv' 15674 The only portable options are `-f' and `-i'. 15675 15676 Moving individual files between file systems is portable (it was 15677 in Unix version 6), but it is not always atomic: when doing `mv 15678 new existing', there's a critical section where neither the old 15679 nor the new version of `existing' actually exists. 15680 15681 On some systems moving files from `/tmp' can sometimes cause 15682 undesirable (but perfectly valid) warnings, even if you created 15683 these files. This is because `/tmp' belongs to a group that 15684 ordinary users are not members of, and files created in `/tmp' 15685 inherit the group of `/tmp'. When the file is copied, `mv' issues 15686 a diagnostic without failing: 15687 15688 $ touch /tmp/foo 15689 $ mv /tmp/foo . 15690 error-->mv: ./foo: set owner/group (was: 100/0): Operation not permitted 15691 $ echo $? 15692 0 15693 $ ls foo 15694 foo 15695 15696 This annoying behavior conforms to Posix, unfortunately. 15697 15698 Moving directories across mount points is not portable, use `cp' 15699 and `rm'. 15700 15701 DOS variants cannot rename or remove open files, and do not 15702 support commands like `mv foo bar >foo', even though this is 15703 perfectly portable among Posix hosts. 15704 15705`od' 15706 In Mac OS X 10.3, `od' does not support the standard Posix options 15707 `-A', `-j', `-N', or `-t', or the XSI option `-s'. The only 15708 supported Posix option is `-v', and the only supported XSI options 15709 are those in `-bcdox'. The BSD `hexdump' program can be used 15710 instead. 15711 15712 This problem no longer exists in Mac OS X 10.4.3. 15713 15714`rm' 15715 The `-f' and `-r' options are portable. 15716 15717 It is not portable to invoke `rm' without options or operands. On 15718 the other hand, Posix now requires `rm -f' to silently succeed 15719 when there are no operands (useful for constructs like `rm -rf 15720 $filelist' without first checking if `$filelist' was empty). But 15721 this was not always portable; at least NetBSD `rm' built before 15722 2008 would fail with a diagnostic. 15723 15724 A file might not be removed even if its parent directory is 15725 writable and searchable. Many Posix hosts cannot remove a mount 15726 point, a named stream, a working directory, or a last link to a 15727 file that is being executed. 15728 15729 DOS variants cannot rename or remove open files, and do not 15730 support commands like `rm foo >foo', even though this is perfectly 15731 portable among Posix hosts. 15732 15733`rmdir' 15734 Just as with `rm', some platforms refuse to remove a working 15735 directory. 15736 15737`sed' 15738 Patterns should not include the separator (unless escaped), even 15739 as part of a character class. In conformance with Posix, the Cray 15740 `sed' rejects `s/[^/]*$//': use `s%[^/]*$%%'. Even when escaped, 15741 patterns should not include separators that are also used as `sed' 15742 metacharacters. For example, GNU sed 4.0.9 rejects 15743 `s,x\{1\,\},,', while sed 4.1 strips the backslash before the comma 15744 before evaluating the basic regular expression. 15745 15746 Avoid empty patterns within parentheses (i.e., `\(\)'). Posix does 15747 not require support for empty patterns, and Unicos 9 `sed' rejects 15748 them. 15749 15750 Unicos 9 `sed' loops endlessly on patterns like `.*\n.*'. 15751 15752 Sed scripts should not use branch labels longer than 7 characters 15753 and should not contain comments; AIX 5.3 `sed' rejects indented 15754 comments. HP-UX sed has a limit of 99 commands (not counting `:' 15755 commands) and 48 labels, which cannot be circumvented by using 15756 more than one script file. It can execute up to 19 reads with the 15757 `r' command per cycle. Solaris `/usr/ucb/sed' rejects usages that 15758 exceed a limit of about 6000 bytes for the internal representation 15759 of commands. 15760 15761 Avoid redundant `;', as some `sed' implementations, such as NetBSD 15762 1.4.2's, incorrectly try to interpret the second `;' as a command: 15763 15764 $ echo a | sed 's/x/x/;;s/x/x/' 15765 sed: 1: "s/x/x/;;s/x/x/": invalid command code ; 15766 15767 Some `sed' implementations have a buffer limited to 4000 bytes, 15768 and this limits the size of input lines, output lines, and internal 15769 buffers that can be processed portably. Likewise, not all `sed' 15770 implementations can handle embedded `NUL' or a missing trailing 15771 newline. 15772 15773 Remember that ranges within a bracket expression of a regular 15774 expression are only well-defined in the `C' (or `POSIX') locale. 15775 Meanwhile, support for character classes like `[[:upper:]]' is not 15776 yet universal, so if you cannot guarantee the setting of `LC_ALL', 15777 it is better to spell out a range `[ABCDEFGHIJKLMNOPQRSTUVWXYZ]' 15778 than to rely on `[A-Z]'. 15779 15780 Additionally, Posix states that regular expressions are only 15781 well-defined on characters. Unfortunately, there exist platforms 15782 such as MacOS X 10.5 where not all 8-bit byte values are valid 15783 characters, even though that platform has a single-byte `C' 15784 locale. And Posix allows the existence of a multi-byte `C' 15785 locale, although that does not yet appear to be a common 15786 implementation. At any rate, it means that not all bytes will be 15787 matched by the regular expression `.': 15788 15789 $ printf '\200\n' | LC_ALL=C sed -n /./p | wc -l 15790 0 15791 $ printf '\200\n' | LC_ALL=en_US.ISO8859-1 sed -n /./p | wc -l 15792 1 15793 15794 Portable `sed' regular expressions should use `\' only to escape 15795 characters in the string `$()*.0123456789[\^n{}'. For example, 15796 alternation, `\|', is common but Posix does not require its 15797 support, so it should be avoided in portable scripts. Solaris 15798 `sed' does not support alternation; e.g., `sed '/a\|b/d'' deletes 15799 only lines that contain the literal string `a|b'. Similarly, `\+' 15800 and `\?' should be avoided. 15801 15802 Anchors (`^' and `$') inside groups are not portable. 15803 15804 Nested parentheses in patterns (e.g., `\(\(a*\)b*)\)') are quite 15805 portable to current hosts, but was not supported by some ancient 15806 `sed' implementations like SVR3. 15807 15808 Some `sed' implementations, e.g., Solaris, restrict the special 15809 role of the asterisk `*' to one-character regular expressions and 15810 back-references, and the special role of interval expressions 15811 `\{M\}', `\{M,\}', or `\{M,N\}' to one-character regular 15812 expressions. This may lead to unexpected behavior: 15813 15814 $ echo '1*23*4' | /usr/bin/sed 's/\(.\)*/x/g' 15815 x2x4 15816 $ echo '1*23*4' | /usr/xpg4/bin/sed 's/\(.\)*/x/g' 15817 x 15818 15819 The `-e' option is mostly portable. However, its argument cannot 15820 start with `a', `c', or `i', as this runs afoul of a Tru64 5.1 bug. 15821 Also, its argument cannot be empty, as this fails on AIX 5.3. 15822 Some people prefer to use `-e': 15823 15824 sed -e 'COMMAND-1' \ 15825 -e 'COMMAND-2' 15826 15827 as opposed to the equivalent: 15828 15829 sed ' 15830 COMMAND-1 15831 COMMAND-2 15832 ' 15833 15834 The following usage is sometimes equivalent: 15835 15836 sed 'COMMAND-1;COMMAND-2' 15837 15838 but Posix says that this use of a semicolon has undefined effect if 15839 COMMAND-1's verb is `{', `a', `b', `c', `i', `r', `t', `w', `:', 15840 or `#', so you should use semicolon only with simple scripts that 15841 do not use these verbs. 15842 15843 Posix up to the 2008 revision requires the argument of the `-e' 15844 option to be a syntactically complete script. GNU `sed' allows to 15845 pass multiple script fragments, each as argument of a separate 15846 `-e' option, that are then combined, with newlines between the 15847 fragments, and a future Posix revision may allow this as well. 15848 This approach is not portable with script fragments ending in 15849 backslash; for example, the `sed' programs on Solaris 10, HP-UX 15850 11, and AIX don't allow splitting in this case: 15851 15852 $ echo a | sed -n -e 'i\ 15853 0' 15854 0 15855 $ echo a | sed -n -e 'i\' -e 0 15856 Unrecognized command: 0 15857 15858 In practice, however, this technique of joining fragments through 15859 `-e' works for multiple `sed' functions within `{' and `}', even 15860 if that is not specified by Posix: 15861 15862 $ echo a | sed -n -e '/a/{' -e s/a/b/ -e p -e '}' 15863 b 15864 15865 Commands inside { } brackets are further restricted. Posix 2008 15866 says that they cannot be preceded by addresses, `!', or `;', and 15867 that each command must be followed immediately by a newline, 15868 without any intervening blanks or semicolons. The closing bracket 15869 must be alone on a line, other than white space preceding or 15870 following it. However, a future version of Posix may standardize 15871 the use of addresses within brackets. 15872 15873 Contrary to yet another urban legend, you may portably use `&' in 15874 the replacement part of the `s' command to mean "what was 15875 matched". All descendants of Unix version 7 `sed' (at least; we 15876 don't have first hand experience with older `sed' implementations) 15877 have supported it. 15878 15879 Posix requires that you must not have any white space between `!' 15880 and the following command. It is OK to have blanks between the 15881 address and the `!'. For instance, on Solaris: 15882 15883 $ echo "foo" | sed -n '/bar/ ! p' 15884 error-->Unrecognized command: /bar/ ! p 15885 $ echo "foo" | sed -n '/bar/! p' 15886 error-->Unrecognized command: /bar/! p 15887 $ echo "foo" | sed -n '/bar/ !p' 15888 foo 15889 15890 Posix also says that you should not combine `!' and `;'. If you 15891 use `!', it is best to put it on a command that is delimited by 15892 newlines rather than `;'. 15893 15894 Also note that Posix requires that the `b', `t', `r', and `w' 15895 commands be followed by exactly one space before their argument. 15896 On the other hand, no white space is allowed between `:' and the 15897 subsequent label name. 15898 15899 If a sed script is specified on the command line and ends in an 15900 `a', `c', or `i' command, the last line of inserted text should be 15901 followed by a newline. Otherwise some `sed' implementations 15902 (e.g., OpenBSD 3.9) do not append a newline to the inserted text. 15903 15904 Many `sed' implementations (e.g., MacOS X 10.4, OpenBSD 3.9, 15905 Solaris 10 `/usr/ucb/sed') strip leading white space from the text 15906 of `a', `c', and `i' commands. Prepend a backslash to work around 15907 this incompatibility with Posix: 15908 15909 $ echo flushleft | sed 'a\ 15910 > indented 15911 > ' 15912 flushleft 15913 indented 15914 $ echo foo | sed 'a\ 15915 > \ indented 15916 > ' 15917 flushleft 15918 indented 15919 15920 Posix requires that with an empty regular expression, the last 15921 non-empty regular expression from either an address specification 15922 or substitution command is applied. However, busybox 1.6.1 15923 complains when using a substitution command with a replacement 15924 containing a back-reference to an empty regular expression; the 15925 workaround is repeating the regular expression. 15926 15927 $ echo abc | busybox sed '/a\(b\)c/ s//\1/' 15928 sed: No previous regexp. 15929 $ echo abc | busybox sed '/a\(b\)c/ s/a\(b\)c/\1/' 15930 b 15931 15932`sed' (`t') 15933 Some old systems have `sed' that "forget" to reset their `t' flag 15934 when starting a new cycle. For instance on MIPS RISC/OS, and on 15935 IRIX 5.3, if you run the following `sed' script (the line numbers 15936 are not actual part of the texts): 15937 15938 s/keep me/kept/g # a 15939 t end # b 15940 s/.*/deleted/g # c 15941 :end # d 15942 15943 on 15944 15945 delete me # 1 15946 delete me # 2 15947 keep me # 3 15948 delete me # 4 15949 15950 you get 15951 15952 deleted 15953 delete me 15954 kept 15955 deleted 15956 15957 instead of 15958 15959 deleted 15960 deleted 15961 kept 15962 deleted 15963 15964 Why? When processing line 1, (c) matches, therefore sets the `t' 15965 flag, and the output is produced. When processing line 2, the `t' 15966 flag is still set (this is the bug). Command (a) fails to match, 15967 but `sed' is not supposed to clear the `t' flag when a 15968 substitution fails. Command (b) sees that the flag is set, 15969 therefore it clears it, and jumps to (d), hence you get `delete me' 15970 instead of `deleted'. When processing line (3), `t' is clear, (a) 15971 matches, so the flag is set, hence (b) clears the flags and jumps. 15972 Finally, since the flag is clear, line 4 is processed properly. 15973 15974 There are two things one should remember about `t' in `sed'. 15975 Firstly, always remember that `t' jumps if _some_ substitution 15976 succeeded, not only the immediately preceding substitution. 15977 Therefore, always use a fake `t clear' followed by a `:clear' on 15978 the next line, to reset the `t' flag where needed. 15979 15980 Secondly, you cannot rely on `sed' to clear the flag at each new 15981 cycle. 15982 15983 One portable implementation of the script above is: 15984 15985 t clear 15986 :clear 15987 s/keep me/kept/g 15988 t end 15989 s/.*/deleted/g 15990 :end 15991 15992`sleep' 15993 Using `sleep' is generally portable. However, remember that 15994 adding a `sleep' to work around timestamp issues, with a minimum 15995 granularity of one second, doesn't scale well for parallel builds 15996 on modern machines with sub-second process completion. 15997 15998`sort' 15999 Remember that sort order is influenced by the current locale. 16000 Inside `configure', the C locale is in effect, but in Makefile 16001 snippets, you may need to specify `LC_ALL=C sort'. 16002 16003`tar' 16004 There are multiple file formats for `tar'; if you use Automake, 16005 the macro `AM_INIT_AUTOMAKE' has some options controlling which 16006 level of portability to use. 16007 16008`touch' 16009 If you specify the desired timestamp (e.g., with the `-r' option), 16010 older `touch' implementations use the `utime' or `utimes' system 16011 call, which can result in the same kind of timestamp truncation 16012 problems that `cp -p' has. 16013 16014 On ancient BSD systems, `touch' or any command that results in an 16015 empty file does not update the timestamps, so use a command like 16016 `echo' as a workaround. Also, GNU `touch' 3.16r (and presumably 16017 all before that) fails to work on SunOS 4.1.3 when the empty file 16018 is on an NFS-mounted 4.2 volume. However, these problems are no 16019 longer of practical concern. 16020 16021`tr' 16022 Not all versions of `tr' handle all backslash character escapes. 16023 For example, Solaris 10 `/usr/ucb/tr' falls over, even though 16024 Solaris contains more modern `tr' in other locations. Using octal 16025 escapes is more portable for carriage returns, since `\015' is the 16026 same for both ASCII and EBCDIC, and since use of literal carriage 16027 returns in scripts causes a number of other problems. But for 16028 other characters, like newline, using octal escapes ties the 16029 operation to ASCII, so it is better to use literal characters. 16030 16031 $ { echo moon; echo light; } | /usr/ucb/tr -d '\n' ; echo 16032 moo 16033 light 16034 $ { echo moon; echo light; } | /usr/bin/tr -d '\n' ; echo 16035 moonlight 16036 $ { echo moon; echo light; } | /usr/ucb/tr -d '\012' ; echo 16037 moonlight 16038 $ nl=' 16039 '; { echo moon; echo light; } | /usr/ucb/tr -d "$nl" ; echo 16040 moonlight 16041 16042 Not all versions of `tr' recognize direct ranges of characters: at 16043 least Solaris `/usr/bin/tr' still fails to do so. But you can use 16044 `/usr/xpg4/bin/tr' instead, or add brackets (which in Posix 16045 transliterate to themselves). 16046 16047 $ echo "Hazy Fantazy" | LC_ALL=C /usr/bin/tr a-z A-Z 16048 HAZy FAntAZy 16049 $ echo "Hazy Fantazy" | LC_ALL=C /usr/bin/tr '[a-z]' '[A-Z]' 16050 HAZY FANTAZY 16051 $ echo "Hazy Fantazy" | LC_ALL=C /usr/xpg4/bin/tr a-z A-Z 16052 HAZY FANTAZY 16053 16054 When providing two arguments, be sure the second string is at 16055 least as long as the first. 16056 16057 $ echo abc | /usr/xpg4/bin/tr bc d 16058 adc 16059 $ echo abc | coreutils/tr bc d 16060 add 16061 16062 Posix requires `tr' to operate on binary files. But at least 16063 Solaris `/usr/ucb/tr' and `/usr/bin/tr' silently discard `NUL' in 16064 the input prior to doing any translation. When using `tr' to 16065 process a binary file that may contain `NUL' bytes, it is 16066 necessary to use `/usr/xpg4/bin/tr' instead, or `/usr/xpg6/bin/tr' 16067 if that is available. 16068 16069 $ printf 'a\0b' | /usr/ucb/tr x x | od -An -tx1 16070 61 62 16071 $ printf 'a\0b' | /usr/bin/tr x x | od -An -tx1 16072 61 62 16073 $ printf 'a\0b' | /usr/xpg4/bin/tr x x | od -An -tx1 16074 61 00 62 16075 16076 Solaris `/usr/ucb/tr' additionally fails to handle `\0' as the 16077 octal escape for `NUL'. 16078 16079 $ printf 'abc' | /usr/ucb/tr 'bc' '\0d' | od -An -tx1 16080 61 62 63 16081 $ printf 'abc' | /usr/bin/tr 'bc' '\0d' | od -An -tx1 16082 61 00 64 16083 $ printf 'abc' | /usr/xpg4/bin/tr 'bc' '\0d' | od -An -tx1 16084 61 00 64 16085 16086 16087 16088File: autoconf.info, Node: Portable Make, Next: Portable C and C++, Prev: Portable Shell, Up: Top 16089 1609012 Portable Make Programming 16091**************************** 16092 16093Writing portable makefiles is an art. Since a makefile's commands are 16094executed by the shell, you must consider the shell portability issues 16095already mentioned. However, other issues are specific to `make' itself. 16096 16097* Menu: 16098 16099* $< in Ordinary Make Rules:: $< in ordinary rules 16100* Failure in Make Rules:: Failing portably in rules 16101* Special Chars in Names:: Special Characters in Macro Names 16102* Backslash-Newline-Empty:: Empty lines after backslash-newline 16103* Backslash-Newline Comments:: Spanning comments across line boundaries 16104* Long Lines in Makefiles:: Line length limitations 16105* Macros and Submakes:: `make macro=value' and submakes 16106* The Make Macro MAKEFLAGS:: `$(MAKEFLAGS)' portability issues 16107* The Make Macro SHELL:: `$(SHELL)' portability issues 16108* Parallel Make:: Parallel `make' quirks 16109* Comments in Make Rules:: Other problems with Make comments 16110* Newlines in Make Rules:: Using literal newlines in rules 16111* Comments in Make Macros:: Other problems with Make comments in macros 16112* Trailing whitespace in Make Macros:: Macro substitution problems 16113* Command-line Macros and whitespace:: Whitespace trimming of values 16114* obj/ and Make:: Don't name a subdirectory `obj' 16115* make -k Status:: Exit status of `make -k' 16116* VPATH and Make:: `VPATH' woes 16117* Single Suffix Rules:: Single suffix rules and separated dependencies 16118* Timestamps and Make:: Subsecond timestamp resolution 16119 16120 16121File: autoconf.info, Node: $< in Ordinary Make Rules, Next: Failure in Make Rules, Up: Portable Make 16122 1612312.1 `$<' in Ordinary Make Rules 16124================================ 16125 16126Posix says that the `$<' construct in makefiles can be used only in 16127inference rules and in the `.DEFAULT' rule; its meaning in ordinary 16128rules is unspecified. Solaris `make' for instance replaces it with the 16129empty string. OpenBSD (3.0 and later) `make' diagnoses these uses and 16130errors out. 16131 16132 16133File: autoconf.info, Node: Failure in Make Rules, Next: Special Chars in Names, Prev: $< in Ordinary Make Rules, Up: Portable Make 16134 1613512.2 Failure in Make Rules 16136========================== 16137 16138Posix 2008 requires that `make' must invoke each command with the 16139equivalent of a `sh -e -c' subshell, which causes the subshell to exit 16140immediately if a subsidiary simple-command fails, although not all 16141`make' implementations have historically followed this rule. For 16142example, the command `touch T; rm -f U' may attempt to remove `U' even 16143if the `touch' fails, although this is not permitted with Posix make. 16144One way to work around failures in simple commands is to reword them so 16145that they always succeed, e.g., `touch T || :; rm -f U'. However, even 16146this approach can run into common bugs in BSD implementations of the 16147`-e' option of `sh' and `set' (*note Limitations of Shell Builtins: 16148set.), so if you are worried about porting to buggy BSD shells it may 16149be simpler to migrate complicated `make' actions into separate scripts. 16150 16151 16152File: autoconf.info, Node: Special Chars in Names, Next: Backslash-Newline-Empty, Prev: Failure in Make Rules, Up: Portable Make 16153 1615412.3 Special Characters in Make Macro Names 16155=========================================== 16156 16157Posix limits macro names to nonempty strings containing only ASCII 16158letters and digits, `.', and `_'. Many `make' implementations allow a 16159wider variety of characters, but portable makefiles should avoid them. 16160It is portable to start a name with a special character, e.g., 16161`$(.FOO)'. 16162 16163 Some ancient `make' implementations don't support leading 16164underscores in macro names. An example is NEWS-OS 4.2R. 16165 16166 $ cat Makefile 16167 _am_include = # 16168 _am_quote = 16169 all:; @echo this is test 16170 $ make 16171 Make: Must be a separator on rules line 2. Stop. 16172 $ cat Makefile2 16173 am_include = # 16174 am_quote = 16175 all:; @echo this is test 16176 $ make -f Makefile2 16177 this is test 16178 16179However, this problem is no longer of practical concern. 16180 16181 16182File: autoconf.info, Node: Backslash-Newline-Empty, Next: Backslash-Newline Comments, Prev: Special Chars in Names, Up: Portable Make 16183 1618412.4 Backslash-Newline Before Empty Lines 16185========================================= 16186 16187A bug in Bash 2.03 can cause problems if a Make rule contains a 16188backslash-newline followed by line that expands to nothing. For 16189example, on Solaris 8: 16190 16191 SHELL = /bin/bash 16192 EMPTY = 16193 foo: 16194 touch foo \ 16195 $(EMPTY) 16196 16197executes 16198 16199 /bin/bash -c 'touch foo \ 16200 ' 16201 16202which fails with a syntax error, due to the Bash bug. To avoid this 16203problem, avoid nullable macros in the last line of a multiline command. 16204 16205 On some versions of HP-UX, `make' reads multiple newlines following 16206a backslash, continuing to the next non-empty line. For example, 16207 16208 FOO = one \ 16209 16210 BAR = two 16211 16212 test: 16213 : FOO is "$(FOO)" 16214 : BAR is "$(BAR)" 16215 16216shows `FOO' equal to `one BAR = two'. Other implementations sensibly 16217let a backslash continue only to the immediately following line. 16218 16219 16220File: autoconf.info, Node: Backslash-Newline Comments, Next: Long Lines in Makefiles, Prev: Backslash-Newline-Empty, Up: Portable Make 16221 1622212.5 Backslash-Newline in Make Comments 16223======================================= 16224 16225According to Posix, Make comments start with `#' and continue until an 16226unescaped newline is reached. 16227 16228 $ cat Makefile 16229 # A = foo \ 16230 bar \ 16231 baz 16232 16233 all: 16234 @echo ok 16235 $ make # GNU make 16236 ok 16237 16238However this is not always the case. Some implementations discard 16239everything from `#' through the end of the line, ignoring any trailing 16240backslash. 16241 16242 $ pmake # BSD make 16243 "Makefile", line 3: Need an operator 16244 Fatal errors encountered -- cannot continue 16245 16246Therefore, if you want to comment out a multi-line definition, prefix 16247each line with `#', not only the first. 16248 16249 # A = foo \ 16250 # bar \ 16251 # baz 16252 16253 16254File: autoconf.info, Node: Long Lines in Makefiles, Next: Macros and Submakes, Prev: Backslash-Newline Comments, Up: Portable Make 16255 1625612.6 Long Lines in Makefiles 16257============================ 16258 16259Tru64 5.1's `make' has been reported to crash when given a makefile 16260with lines longer than around 20 kB. Earlier versions are reported to 16261exit with `Line too long' diagnostics. 16262 16263 16264File: autoconf.info, Node: Macros and Submakes, Next: The Make Macro MAKEFLAGS, Prev: Long Lines in Makefiles, Up: Portable Make 16265 1626612.7 `make macro=value' and Submakes 16267==================================== 16268 16269A command-line variable definition such as `foo=bar' overrides any 16270definition of `foo' in a makefile. Some `make' implementations (such 16271as GNU `make') propagate this override to subsidiary invocations of 16272`make'. Some other implementations do not pass the substitution along 16273to submakes. 16274 16275 $ cat Makefile 16276 foo = foo 16277 one: 16278 @echo $(foo) 16279 $(MAKE) two 16280 two: 16281 @echo $(foo) 16282 $ make foo=bar # GNU make 3.79.1 16283 bar 16284 make two 16285 make[1]: Entering directory `/home/adl' 16286 bar 16287 make[1]: Leaving directory `/home/adl' 16288 $ pmake foo=bar # BSD make 16289 bar 16290 pmake two 16291 foo 16292 16293 You have a few possibilities if you do want the `foo=bar' override 16294to propagate to submakes. One is to use the `-e' option, which causes 16295all environment variables to have precedence over the makefile macro 16296definitions, and declare foo as an environment variable: 16297 16298 $ env foo=bar make -e 16299 16300 The `-e' option is propagated to submakes automatically, and since 16301the environment is inherited between `make' invocations, the `foo' 16302macro is overridden in submakes as expected. 16303 16304 This syntax (`foo=bar make -e') is portable only when used outside 16305of a makefile, for instance from a script or from the command line. 16306When run inside a `make' rule, GNU `make' 3.80 and prior versions 16307forget to propagate the `-e' option to submakes. 16308 16309 Moreover, using `-e' could have unexpected side effects if your 16310environment contains some other macros usually defined by the makefile. 16311(See also the note about `make -e' and `SHELL' below.) 16312 16313 If you can foresee all macros that a user might want to override, 16314then you can propagate them to submakes manually, from your makefile: 16315 16316 foo = foo 16317 one: 16318 @echo $(foo) 16319 $(MAKE) foo=$(foo) two 16320 two: 16321 @echo $(foo) 16322 16323 Another way to propagate a variable to submakes in a portable way is 16324to expand an extra variable in every invocation of `$(MAKE)' within 16325your makefile: 16326 16327 foo = foo 16328 one: 16329 @echo $(foo) 16330 $(MAKE) $(SUBMAKEFLAGS) two 16331 two: 16332 @echo $(foo) 16333 16334 Users must be aware that this technique is in use to take advantage 16335of it, e.g. with `make foo=bar SUBMAKEFLAGS='foo=bar'', but it allows 16336any macro to be overridden. Makefiles generated by `automake' use this 16337technique, expanding `$(AM_MAKEFLAGS)' on the command lines of submakes 16338(*note Automake: (automake)Subdirectories.). 16339 16340 16341File: autoconf.info, Node: The Make Macro MAKEFLAGS, Next: The Make Macro SHELL, Prev: Macros and Submakes, Up: Portable Make 16342 1634312.8 The Make Macro MAKEFLAGS 16344============================= 16345 16346Posix requires `make' to use `MAKEFLAGS' to affect the current and 16347recursive invocations of make, but allows implementations several 16348formats for the variable. It is tricky to parse `$MAKEFLAGS' to 16349determine whether `-s' for silent execution or `-k' for continued 16350execution are in effect. For example, you cannot assume that the first 16351space-separated word in `$MAKEFLAGS' contains single-letter options, 16352since in the Cygwin version of GNU `make' it is either `--unix' or 16353`--win32' with the second word containing single-letter options. 16354 16355 $ cat Makefile 16356 all: 16357 @echo MAKEFLAGS = $(MAKEFLAGS) 16358 $ make 16359 MAKEFLAGS = --unix 16360 $ make -k 16361 MAKEFLAGS = --unix -k 16362 16363 16364File: autoconf.info, Node: The Make Macro SHELL, Next: Parallel Make, Prev: The Make Macro MAKEFLAGS, Up: Portable Make 16365 1636612.9 The Make Macro `SHELL' 16367=========================== 16368 16369Posix-compliant `make' internally uses the `$(SHELL)' macro to spawn 16370shell processes and execute Make rules. This is a builtin macro 16371supplied by `make', but it can be modified by a makefile or by a 16372command-line argument. 16373 16374 Not all `make' implementations define this `SHELL' macro. Tru64 16375`make' is an example; this implementation always uses `/bin/sh'. So 16376it's a good idea to always define `SHELL' in your makefiles. If you 16377use Autoconf, do 16378 16379 SHELL = @SHELL@ 16380 16381If you use Automake, this is done for you. 16382 16383 Do not force `SHELL = /bin/sh' because that is not correct 16384everywhere. Remember, `/bin/sh' is not Posix compliant on many 16385systems, such as FreeBSD 4, NetBSD 3, AIX 3, Solaris 10, or Tru64. 16386Additionally, DJGPP lacks `/bin/sh', and when its GNU `make' port sees 16387such a setting it enters a special emulation mode where features like 16388pipes and redirections are emulated on top of DOS's `command.com'. 16389Unfortunately this emulation is incomplete; for instance it does not 16390handle command substitutions. Using `@SHELL@' means that your makefile 16391will benefit from the same improved shell, such as `bash' or `ksh', 16392that was discovered during `configure', so that you aren't fighting two 16393different sets of shell bugs between the two contexts. 16394 16395 Posix-compliant `make' should never acquire the value of $(SHELL) 16396from the environment, even when `make -e' is used (otherwise, think 16397about what would happen to your rules if `SHELL=/bin/tcsh'). 16398 16399 However not all `make' implementations have this exception. For 16400instance it's not surprising that Tru64 `make' doesn't protect `SHELL', 16401since it doesn't use it. 16402 16403 $ cat Makefile 16404 SHELL = /bin/sh 16405 FOO = foo 16406 all: 16407 @echo $(SHELL) 16408 @echo $(FOO) 16409 $ env SHELL=/bin/tcsh FOO=bar make -e # Tru64 Make 16410 /bin/tcsh 16411 bar 16412 $ env SHELL=/bin/tcsh FOO=bar gmake -e # GNU make 16413 /bin/sh 16414 bar 16415 16416 Conversely, `make' is not supposed to export any changes to the 16417macro `SHELL' to child processes. Again, many implementations break 16418this rule: 16419 16420 $ cat Makefile 16421 all: 16422 @echo $(SHELL) 16423 @printenv SHELL 16424 $ env SHELL=sh make -e SHELL=/bin/ksh # BSD Make, GNU make 3.80 16425 /bin/ksh 16426 /bin/ksh 16427 $ env SHELL=sh gmake -e SHELL=/bin/ksh # GNU make 3.81 16428 /bin/ksh 16429 sh 16430 16431 16432File: autoconf.info, Node: Parallel Make, Next: Comments in Make Rules, Prev: The Make Macro SHELL, Up: Portable Make 16433 1643412.10 Parallel Make 16435=================== 16436 16437Support for parallel execution in `make' implementation varies. 16438Generally, using GNU make is your best bet. 16439 16440 When NetBSD or FreeBSD `make' are run in parallel mode, they will 16441reuse the same shell for multiple commands within one recipe. This can 16442have various unexpected consequences. For example, changes of 16443directories or variables persist between recipes, so that: 16444 16445 all: 16446 @var=value; cd /; pwd; echo $$var; echo $$$$ 16447 @pwd; echo $$var; echo $$$$ 16448 16449may output the following with `make -j1', at least on NetBSD up to 5.1 16450and FreeBSD up to 8.2: 16451 16452 / 16453 value 16454 32235 16455 / 16456 value 16457 32235 16458 16459while without `-j1', or with `-B', the output looks less surprising: 16460 16461 / 16462 value 16463 32238 16464 /tmp 16465 16466 32239 16467 16468Another consequence is that, if one command in a recipe uses `exit 0' 16469to indicate a successful exit, the shell will be gone and the remaining 16470commands of this recipe will not be executed. 16471 16472 The BSD `make' implementations, when run in parallel mode, will also 16473pass the `Makefile' recipes to the shell through its standard input, 16474thus making it unusable from the recipes: 16475 16476 $ cat Makefile 16477 read: 16478 @read line; echo LINE: $$line 16479 $ echo foo | make read 16480 LINE: foo 16481 $ echo foo | make -j1 read # NetBSD 5.1 and FreeBSD 8.2 16482 LINE: 16483 16484Moreover, when FreeBSD `make' (up at least to 8.2) is run in parallel 16485mode, it implements the `@' and `-' "recipe modifiers" by dynamically 16486modifying the active shell flags. This behavior has the effects of 16487potentially clobbering the exit status of recipes silenced with the `@' 16488modifier if they also unset the `errexit' shell flag, and of mangling 16489the output in unexpected ways: 16490 16491 $ cat Makefile 16492 a: 16493 @echo $$-; set +e; false 16494 b: 16495 -echo $$-; false; echo set - 16496 $ make a; echo status: $? 16497 ehBc 16498 *** Error code 1 16499 status: 1 16500 $ make -j1 a; echo status: $? 16501 ehB 16502 status: 0 16503 $ make b 16504 echo $-; echo set - 16505 hBc 16506 set - 16507 $ make -j1 b 16508 echo $-; echo hvB 16509 16510You can avoid all these issues by using the `-B' option to enable 16511compatibility semantics. However, that will effectively also disable 16512all parallelism as that will cause prerequisites to be updated in the 16513order they are listed in a rule. 16514 16515 Some make implementations (among them, FreeBSD `make', NetBSD 16516`make', and Solaris `dmake'), when invoked with a `-jN' option, connect 16517the standard output and standard error of all their child processes to 16518pipes or temporary regular files. This can lead to subtly different 16519semantics in the behavior of the spawned processes. For example, even 16520if the `make' standard output is connected to a tty, the recipe command 16521will not be: 16522 16523 $ cat Makefile 16524 all: 16525 @test -t 1 && echo "Is a tty" || echo "Is not a tty" 16526 $ make -j 2 # FreeBSD 8.2 make 16527 Is not a tty 16528 $ make -j 2 # NetBSD 5.1 make 16529 --- all --- 16530 Is not a tty 16531 $ dmake -j 2 # Solaris 10 dmake 16532 HOSTNAME --> 1 job 16533 HOSTNAME --> Job output 16534 Is not a tty 16535 16536On the other hand: 16537 16538 $ make -j 2 # GNU make, Heirloom make 16539 Is a tty 16540 16541The above examples also show additional status output produced in 16542parallel mode for targets being updated by Solaris `dmake' and NetBSD 16543`make' (but _not_ by FreeBSD `make'). 16544 16545 Furthermore, parallel runs of those `make' implementations will 16546route standard error from commands that they spawn into their own 16547standard output, and may remove leading whitespace from output lines. 16548 16549 16550File: autoconf.info, Node: Comments in Make Rules, Next: Newlines in Make Rules, Prev: Parallel Make, Up: Portable Make 16551 1655212.11 Comments in Make Rules 16553============================ 16554 16555Never put comments in a rule. 16556 16557 Some `make' treat anything starting with a tab as a command for the 16558current rule, even if the tab is immediately followed by a `#'. The 16559`make' from Tru64 Unix V5.1 is one of them. The following makefile 16560runs `# foo' through the shell. 16561 16562 all: 16563 # foo 16564 16565 As a workaround, you can use the `:' no-op command with a string 16566argument that gets ignored: 16567 16568 all: 16569 : "foo" 16570 16571 Conversely, if you want to use the `#' character in some command, 16572you can only do so by expanding it inside a rule (*note Comments in 16573Make Macros::). So for example, if `COMMENT_CHAR' is substituted by 16574`config.status' as `#', then the following substitutes `@COMMENT_CHAR@' 16575in a generated header: 16576 16577 foo.h: foo.h.in 16578 sed -e 's|@''COMMENT_CHAR''@|@COMMENT_CHAR@|g' \ 16579 $(srcdir)/foo.h.in > $@ 16580 16581 The funny shell quoting avoids a substitution at `config.status' run 16582time of the left-hand side of the `sed' `s' command. 16583 16584 16585File: autoconf.info, Node: Newlines in Make Rules, Next: Comments in Make Macros, Prev: Comments in Make Rules, Up: Portable Make 16586 1658712.12 Newlines in Make Rules 16588============================ 16589 16590In shell scripts, newlines can be used inside string literals. But in 16591the shell statements of `Makefile' rules, this is not possible: A 16592newline not preceded by a backslash is a separator between shell 16593statements. Whereas a newline that is preceded by a backslash becomes 16594part of the shell statement according to POSIX, but gets replaced, 16595together with the backslash that precedes it, by a space in GNU `make' 165963.80 and older. So, how can a newline be used in a string literal? 16597 16598 The trick is to set up a shell variable that contains a newline: 16599 16600 nlinit=`echo 'nl="'; echo '"'`; eval "$$nlinit" 16601 16602 For example, in order to create a multiline `sed' expression that 16603inserts a blank line after every line of a file, this code can be used: 16604 16605 nlinit=`echo 'nl="'; echo '"'`; eval "$$nlinit"; \ 16606 sed -e "s/\$$/\\$${nl}/" < input > output 16607 16608 16609File: autoconf.info, Node: Comments in Make Macros, Next: Trailing whitespace in Make Macros, Prev: Newlines in Make Rules, Up: Portable Make 16610 1661112.13 Comments in Make Macros 16612============================= 16613 16614Avoid putting comments in macro values as far as possible. Posix 16615specifies that the text starting from the `#' sign until the end of the 16616line is to be ignored, which has the unfortunate effect of disallowing 16617them even within quotes. Thus, the following might lead to a syntax 16618error at compile time: 16619 16620 CPPFLAGS = "-DCOMMENT_CHAR='#'" 16621 16622as `CPPFLAGS' may be expanded to `"-DCOMMENT_CHAR=''. 16623 16624 Most `make' implementations disregard this and treat single and 16625double quotes specially here. Also, GNU `make' lets you put `#' into a 16626macro value by escaping it with a backslash, i.e., `\#'. However, 16627neither of these usages are portable. *Note Comments in Make Rules::, 16628for a portable alternative. 16629 16630 Even without quoting involved, comments can have surprising effects, 16631because the whitespace before them is part of the variable value: 16632 16633 foo = bar # trailing comment 16634 print: ; @echo "$(foo)." 16635 16636prints `bar .', which is usually not intended, and can expose `make' 16637bugs as described below. 16638 16639 16640File: autoconf.info, Node: Trailing whitespace in Make Macros, Next: Command-line Macros and whitespace, Prev: Comments in Make Macros, Up: Portable Make 16641 1664212.14 Trailing whitespace in Make Macros 16643======================================== 16644 16645GNU `make' 3.80 mistreats trailing whitespace in macro substitutions 16646and appends another spurious suffix: 16647 16648 empty = 16649 foo = bar $(empty) 16650 print: ; @echo $(foo:=.test) 16651 16652prints `bar.test .test'. 16653 16654 BSD and Solaris `make' implementations do not honor trailing 16655whitespace in macro definitions as Posix requires: 16656 16657 foo = bar # Note the space after "bar". 16658 print: ; @echo $(foo)t 16659 16660prints `bart' instead of `bar t'. To work around this, you can use a 16661helper macro as in the previous example. 16662 16663 16664File: autoconf.info, Node: Command-line Macros and whitespace, Next: obj/ and Make, Prev: Trailing whitespace in Make Macros, Up: Portable Make 16665 1666612.15 Command-line Macros and whitespace 16667======================================== 16668 16669Some `make' implementations may strip trailing whitespace off of macros 16670set on the command line in addition to leading whitespace. Further, 16671some may strip leading whitespace off of macros set from environment 16672variables: 16673 16674 $ echo 'print: ; @echo "x$(foo)x$(bar)x"' | 16675 foo=' f f ' make -f - bar=' b b ' 16676 x f f xb b x # AIX, BSD, GNU make 16677 xf f xb b x # HP-UX, IRIX, Tru64/OSF make 16678 x f f xb bx # Solaris make 16679 16680 16681File: autoconf.info, Node: obj/ and Make, Next: make -k Status, Prev: Command-line Macros and whitespace, Up: Portable Make 16682 1668312.16 The `obj/' Subdirectory and Make 16684====================================== 16685 16686Never name one of your subdirectories `obj/' if you don't like 16687surprises. 16688 16689 If an `obj/' directory exists, BSD `make' enters it before reading 16690the makefile. Hence the makefile in the current directory is not read. 16691 16692 $ cat Makefile 16693 all: 16694 echo Hello 16695 $ cat obj/Makefile 16696 all: 16697 echo World 16698 $ make # GNU make 16699 echo Hello 16700 Hello 16701 $ pmake # BSD make 16702 echo World 16703 World 16704 16705 16706File: autoconf.info, Node: make -k Status, Next: VPATH and Make, Prev: obj/ and Make, Up: Portable Make 16707 1670812.17 Exit Status of `make -k' 16709============================== 16710 16711Do not rely on the exit status of `make -k'. Some implementations 16712reflect whether they encountered an error in their exit status; other 16713implementations always succeed. 16714 16715 $ cat Makefile 16716 all: 16717 false 16718 $ make -k; echo exit status: $? # GNU make 16719 false 16720 make: *** [all] Error 1 16721 exit status: 2 16722 $ pmake -k; echo exit status: $? # BSD make 16723 false 16724 *** Error code 1 (continuing) 16725 exit status: 0 16726 16727 16728File: autoconf.info, Node: VPATH and Make, Next: Single Suffix Rules, Prev: make -k Status, Up: Portable Make 16729 1673012.18 `VPATH' and Make 16731====================== 16732 16733Posix does not specify the semantics of `VPATH'. Typically, `make' 16734supports `VPATH', but its implementation is not consistent. 16735 16736 Autoconf and Automake support makefiles whose usages of `VPATH' are 16737portable to recent-enough popular implementations of `make', but to 16738keep the resulting makefiles portable, a package's makefile prototypes 16739must take the following issues into account. These issues are 16740complicated and are often poorly understood, and installers who use 16741`VPATH' should expect to find many bugs in this area. If you use 16742`VPATH', the simplest way to avoid these portability bugs is to stick 16743with GNU `make', since it is the most commonly-used `make' among 16744Autoconf users. 16745 16746 Here are some known issues with some `VPATH' implementations. 16747 16748* Menu: 16749 16750* Variables listed in VPATH:: `VPATH' must be literal on ancient hosts 16751* VPATH and Double-colon:: Problems with `::' on ancient hosts 16752* $< in Explicit Rules:: `$<' does not work in ordinary rules 16753* Automatic Rule Rewriting:: `VPATH' goes wild on Solaris 16754* Tru64 Directory Magic:: `mkdir' goes wild on Tru64 16755* Make Target Lookup:: More details about `VPATH' lookup 16756 16757 16758File: autoconf.info, Node: Variables listed in VPATH, Next: VPATH and Double-colon, Up: VPATH and Make 16759 1676012.18.1 Variables listed in `VPATH' 16761----------------------------------- 16762 16763Do not set `VPATH' to the value of another variable, for example `VPATH 16764= $(srcdir)', because some ancient versions of `make' do not do 16765variable substitutions on the value of `VPATH'. For example, use this 16766 16767 srcdir = @srcdir@ 16768 VPATH = @srcdir@ 16769 16770rather than `VPATH = $(srcdir)'. Note that with GNU Automake, there is 16771no need to set this yourself. 16772 16773 16774File: autoconf.info, Node: VPATH and Double-colon, Next: $< in Explicit Rules, Prev: Variables listed in VPATH, Up: VPATH and Make 16775 1677612.18.2 `VPATH' and Double-colon Rules 16777-------------------------------------- 16778 16779With ancient versions of Sun `make', any assignment to `VPATH' causes 16780`make' to execute only the first set of double-colon rules. However, 16781this problem is no longer of practical concern. 16782 16783 16784File: autoconf.info, Node: $< in Explicit Rules, Next: Automatic Rule Rewriting, Prev: VPATH and Double-colon, Up: VPATH and Make 16785 1678612.18.3 `$<' Not Supported in Explicit Rules 16787-------------------------------------------- 16788 16789Using `$<' in explicit rules is not portable. The prerequisite file 16790must be named explicitly in the rule. If you want to find the 16791prerequisite via a `VPATH' search, you have to code the whole thing 16792manually. *Note Build Directories::. 16793 16794 16795File: autoconf.info, Node: Automatic Rule Rewriting, Next: Tru64 Directory Magic, Prev: $< in Explicit Rules, Up: VPATH and Make 16796 1679712.18.4 Automatic Rule Rewriting 16798-------------------------------- 16799 16800Some `make' implementations, such as Solaris and Tru64, search for 16801prerequisites in `VPATH' and then rewrite each occurrence as a plain 16802word in the rule. For instance: 16803 16804 # This isn't portable to GNU make. 16805 VPATH = ../pkg/src 16806 f.c: if.c 16807 cp if.c f.c 16808 16809executes `cp ../pkg/src/if.c f.c' if `if.c' is found in `../pkg/src'. 16810 16811 However, this rule leads to real problems in practice. For example, 16812if the source directory contains an ordinary file named `test' that is 16813used in a dependency, Solaris `make' rewrites commands like `if test -r 16814foo; ...' to `if ../pkg/src/test -r foo; ...', which is typically 16815undesirable. In fact, `make' is completely unaware of shell syntax 16816used in the rules, so the VPATH rewrite can potentially apply to _any_ 16817whitespace-separated word in a rule, including shell variables, 16818functions, and keywords. 16819 16820 $ mkdir build 16821 $ cd build 16822 $ cat > Makefile <<'END' 16823 VPATH = .. 16824 all: arg func for echo 16825 func () { for arg in "$$@"; do echo $$arg; done; }; \ 16826 func "hello world" 16827 END 16828 $ touch ../arg ../func ../for ../echo 16829 $ make 16830 ../func () { ../for ../arg in "$@"; do ../echo $arg; done; }; \ 16831 ../func "hello world" 16832 sh: syntax error at line 1: `do' unexpected 16833 *** Error code 2 16834 16835To avoid this problem, portable makefiles should never mention a source 16836file or dependency whose name is that of a shell keyword like `for' or 16837`until', a shell command like `cat' or `gcc' or `test', or a shell 16838function or variable used in the corresponding `Makefile' recipe. 16839 16840 Because of these problems GNU `make' and many other `make' 16841implementations do not rewrite commands, so portable makefiles should 16842search `VPATH' manually. It is tempting to write this: 16843 16844 # This isn't portable to Solaris make. 16845 VPATH = ../pkg/src 16846 f.c: if.c 16847 cp `test -f if.c || echo $(VPATH)/`if.c f.c 16848 16849However, the "prerequisite rewriting" still applies here. So if `if.c' 16850is in `../pkg/src', Solaris and Tru64 `make' execute 16851 16852 cp `test -f ../pkg/src/if.c || echo ../pkg/src/`if.c f.c 16853 16854which reduces to 16855 16856 cp if.c f.c 16857 16858and thus fails. Oops. 16859 16860 A simple workaround, and good practice anyway, is to use `$?' and 16861`$@' when possible: 16862 16863 VPATH = ../pkg/src 16864 f.c: if.c 16865 cp $? $@ 16866 16867but this does not generalize well to commands with multiple 16868prerequisites. A more general workaround is to rewrite the rule so that 16869the prerequisite `if.c' never appears as a plain word. For example, 16870these three rules would be safe, assuming `if.c' is in `../pkg/src' and 16871the other files are in the working directory: 16872 16873 VPATH = ../pkg/src 16874 f.c: if.c f1.c 16875 cat `test -f ./if.c || echo $(VPATH)/`if.c f1.c >$@ 16876 g.c: if.c g1.c 16877 cat `test -f 'if.c' || echo $(VPATH)/`if.c g1.c >$@ 16878 h.c: if.c h1.c 16879 cat `test -f "if.c" || echo $(VPATH)/`if.c h1.c >$@ 16880 16881 Things get worse when your prerequisites are in a macro. 16882 16883 VPATH = ../pkg/src 16884 HEADERS = f.h g.h h.h 16885 install-HEADERS: $(HEADERS) 16886 for i in $(HEADERS); do \ 16887 $(INSTALL) -m 644 \ 16888 `test -f $$i || echo $(VPATH)/`$$i \ 16889 $(DESTDIR)$(includedir)/$$i; \ 16890 done 16891 16892 The above `install-HEADERS' rule is not Solaris-proof because `for i 16893in $(HEADERS);' is expanded to `for i in f.h g.h h.h;' where `f.h' and 16894`g.h' are plain words and are hence subject to `VPATH' adjustments. 16895 16896 If the three files are in `../pkg/src', the rule is run as: 16897 16898 for i in ../pkg/src/f.h ../pkg/src/g.h h.h; do \ 16899 install -m 644 \ 16900 `test -f $i || echo ../pkg/src/`$i \ 16901 /usr/local/include/$i; \ 16902 done 16903 16904 where the two first `install' calls fail. For instance, consider 16905the `f.h' installation: 16906 16907 install -m 644 \ 16908 `test -f ../pkg/src/f.h || \ 16909 echo ../pkg/src/ \ 16910 `../pkg/src/f.h \ 16911 /usr/local/include/../pkg/src/f.h; 16912 16913It reduces to: 16914 16915 install -m 644 \ 16916 ../pkg/src/f.h \ 16917 /usr/local/include/../pkg/src/f.h; 16918 16919 Note that the manual `VPATH' search did not cause any problems here; 16920however this command installs `f.h' in an incorrect directory. 16921 16922 Trying to quote `$(HEADERS)' in some way, as we did for `foo.c' a 16923few makefiles ago, does not help: 16924 16925 install-HEADERS: $(HEADERS) 16926 headers='$(HEADERS)'; \ 16927 for i in $$headers; do \ 16928 $(INSTALL) -m 644 \ 16929 `test -f $$i || echo $(VPATH)/`$$i \ 16930 $(DESTDIR)$(includedir)/$$i; \ 16931 done 16932 16933 Now, `headers='$(HEADERS)'' macro-expands to: 16934 16935 headers='f.h g.h h.h' 16936 16937but `g.h' is still a plain word. (As an aside, the idiom 16938`headers='$(HEADERS)'; for i in $$headers;' is a good idea if 16939`$(HEADERS)' can be empty, because some shells diagnose a syntax error 16940on `for i in;'.) 16941 16942 One workaround is to strip this unwanted `../pkg/src/' prefix 16943manually: 16944 16945 VPATH = ../pkg/src 16946 HEADERS = f.h g.h h.h 16947 install-HEADERS: $(HEADERS) 16948 headers='$(HEADERS)'; \ 16949 for i in $$headers; do \ 16950 i=`expr "$$i" : '$(VPATH)/\(.*\)'`; 16951 $(INSTALL) -m 644 \ 16952 `test -f $$i || echo $(VPATH)/`$$i \ 16953 $(DESTDIR)$(includedir)/$$i; \ 16954 done 16955 16956 Automake does something similar. However the above hack works only 16957if the files listed in `HEADERS' are in the current directory or a 16958subdirectory; they should not be in an enclosing directory. If we had 16959`HEADERS = ../f.h', the above fragment would fail in a VPATH build with 16960Tru64 `make'. The reason is that not only does Tru64 `make' rewrite 16961dependencies, but it also simplifies them. Hence `../f.h' becomes 16962`../pkg/f.h' instead of `../pkg/src/../f.h'. This obviously defeats 16963any attempt to strip a leading `../pkg/src/' component. 16964 16965 The following example makes the behavior of Tru64 `make' more 16966apparent. 16967 16968 $ cat Makefile 16969 VPATH = sub 16970 all: ../foo 16971 echo ../foo 16972 $ ls 16973 Makefile foo 16974 $ make 16975 echo foo 16976 foo 16977 16978Dependency `../foo' was found in `sub/../foo', but Tru64 `make' 16979simplified it as `foo'. (Note that the `sub/' directory does not even 16980exist, this just means that the simplification occurred before the file 16981was checked for.) 16982 16983 For the record here is how SunOS 4 `make' behaves on this example. 16984 16985 $ make 16986 make: Fatal error: Don't know how to make target `../foo' 16987 $ mkdir sub 16988 $ make 16989 echo sub/../foo 16990 sub/../foo 16991 16992 16993File: autoconf.info, Node: Tru64 Directory Magic, Next: Make Target Lookup, Prev: Automatic Rule Rewriting, Up: VPATH and Make 16994 1699512.18.5 Tru64 `make' Creates Prerequisite Directories Magically 16996--------------------------------------------------------------- 16997 16998When a prerequisite is a subdirectory of `VPATH', Tru64 `make' creates 16999it in the current directory. 17000 17001 $ mkdir -p foo/bar build 17002 $ cd build 17003 $ cat >Makefile <<END 17004 VPATH = .. 17005 all: foo/bar 17006 END 17007 $ make 17008 mkdir foo 17009 mkdir foo/bar 17010 17011 This can yield unexpected results if a rule uses a manual `VPATH' 17012search as presented before. 17013 17014 VPATH = .. 17015 all : foo/bar 17016 command `test -d foo/bar || echo ../`foo/bar 17017 17018 The above `command' is run on the empty `foo/bar' directory that was 17019created in the current directory. 17020 17021 17022File: autoconf.info, Node: Make Target Lookup, Prev: Tru64 Directory Magic, Up: VPATH and Make 17023 1702412.18.6 Make Target Lookup 17025-------------------------- 17026 17027GNU `make' uses a complex algorithm to decide when it should use files 17028found via a `VPATH' search. *Note How Directory Searches are 17029Performed: (make)Search Algorithm. 17030 17031 If a target needs to be rebuilt, GNU `make' discards the file name 17032found during the `VPATH' search for this target, and builds the file 17033locally using the file name given in the makefile. If a target does 17034not need to be rebuilt, GNU `make' uses the file name found during the 17035`VPATH' search. 17036 17037 Other `make' implementations, like NetBSD `make', are easier to 17038describe: the file name found during the `VPATH' search is used whether 17039the target needs to be rebuilt or not. Therefore new files are created 17040locally, but existing files are updated at their `VPATH' location. 17041 17042 OpenBSD and FreeBSD `make', however, never perform a `VPATH' search 17043for a dependency that has an explicit rule. This is extremely annoying. 17044 17045 When attempting a `VPATH' build for an autoconfiscated package 17046(e.g., `mkdir build && cd build && ../configure'), this means GNU 17047`make' builds everything locally in the `build' directory, while BSD 17048`make' builds new files locally and updates existing files in the 17049source directory. 17050 17051 $ cat Makefile 17052 VPATH = .. 17053 all: foo.x bar.x 17054 foo.x bar.x: newer.x 17055 @echo Building $@ 17056 $ touch ../bar.x 17057 $ touch ../newer.x 17058 $ make # GNU make 17059 Building foo.x 17060 Building bar.x 17061 $ pmake # NetBSD make 17062 Building foo.x 17063 Building ../bar.x 17064 $ fmake # FreeBSD make, OpenBSD make 17065 Building foo.x 17066 Building bar.x 17067 $ tmake # Tru64 make 17068 Building foo.x 17069 Building bar.x 17070 $ touch ../bar.x 17071 $ make # GNU make 17072 Building foo.x 17073 $ pmake # NetBSD make 17074 Building foo.x 17075 $ fmake # FreeBSD make, OpenBSD make 17076 Building foo.x 17077 Building bar.x 17078 $ tmake # Tru64 make 17079 Building foo.x 17080 Building bar.x 17081 17082 Note how NetBSD `make' updates `../bar.x' in its VPATH location, and 17083how FreeBSD, OpenBSD, and Tru64 `make' always update `bar.x', even when 17084`../bar.x' is up to date. 17085 17086 Another point worth mentioning is that once GNU `make' has decided 17087to ignore a `VPATH' file name (e.g., it ignored `../bar.x' in the above 17088example) it continues to ignore it when the target occurs as a 17089prerequisite of another rule. 17090 17091 The following example shows that GNU `make' does not look up `bar.x' 17092in `VPATH' before performing the `.x.y' rule, because it ignored the 17093`VPATH' result of `bar.x' while running the `bar.x: newer.x' rule. 17094 17095 $ cat Makefile 17096 VPATH = .. 17097 all: bar.y 17098 bar.x: newer.x 17099 @echo Building $@ 17100 .SUFFIXES: .x .y 17101 .x.y: 17102 cp $< $@ 17103 $ touch ../bar.x 17104 $ touch ../newer.x 17105 $ make # GNU make 17106 Building bar.x 17107 cp bar.x bar.y 17108 cp: cannot stat `bar.x': No such file or directory 17109 make: *** [bar.y] Error 1 17110 $ pmake # NetBSD make 17111 Building ../bar.x 17112 cp ../bar.x bar.y 17113 $ rm bar.y 17114 $ fmake # FreeBSD make, OpenBSD make 17115 echo Building bar.x 17116 cp bar.x bar.y 17117 cp: cannot stat `bar.x': No such file or directory 17118 *** Error code 1 17119 $ tmake # Tru64 make 17120 Building bar.x 17121 cp: bar.x: No such file or directory 17122 *** Exit 1 17123 17124 Note that if you drop away the command from the `bar.x: newer.x' 17125rule, GNU `make' magically starts to work: it knows that `bar.x' hasn't 17126been updated, therefore it doesn't discard the result from `VPATH' 17127(`../bar.x') in succeeding uses. Tru64 also works, but FreeBSD and 17128OpenBSD still don't. 17129 17130 $ cat Makefile 17131 VPATH = .. 17132 all: bar.y 17133 bar.x: newer.x 17134 .SUFFIXES: .x .y 17135 .x.y: 17136 cp $< $@ 17137 $ touch ../bar.x 17138 $ touch ../newer.x 17139 $ make # GNU make 17140 cp ../bar.x bar.y 17141 $ rm bar.y 17142 $ pmake # NetBSD make 17143 cp ../bar.x bar.y 17144 $ rm bar.y 17145 $ fmake # FreeBSD make, OpenBSD make 17146 cp bar.x bar.y 17147 cp: cannot stat `bar.x': No such file or directory 17148 *** Error code 1 17149 $ tmake # Tru64 make 17150 cp ../bar.x bar.y 17151 17152 It seems the sole solution that would please every `make' 17153implementation is to never rely on `VPATH' searches for targets. In 17154other words, `VPATH' should be reserved to unbuilt sources. 17155 17156 17157File: autoconf.info, Node: Single Suffix Rules, Next: Timestamps and Make, Prev: VPATH and Make, Up: Portable Make 17158 1715912.19 Single Suffix Rules and Separated Dependencies 17160==================================================== 17161 17162A "Single Suffix Rule" is basically a usual suffix (inference) rule 17163(`.from.to:'), but which _destination_ suffix is empty (`.from:'). 17164 17165 "Separated dependencies" simply refers to listing the prerequisite 17166of a target, without defining a rule. Usually one can list on the one 17167hand side, the rules, and on the other hand side, the dependencies. 17168 17169 Solaris `make' does not support separated dependencies for targets 17170defined by single suffix rules: 17171 17172 $ cat Makefile 17173 .SUFFIXES: .in 17174 foo: foo.in 17175 .in: 17176 cp $< $@ 17177 $ touch foo.in 17178 $ make 17179 $ ls 17180 Makefile foo.in 17181 17182while GNU Make does: 17183 17184 $ gmake 17185 cp foo.in foo 17186 $ ls 17187 Makefile foo foo.in 17188 17189 Note it works without the `foo: foo.in' dependency. 17190 17191 $ cat Makefile 17192 .SUFFIXES: .in 17193 .in: 17194 cp $< $@ 17195 $ make foo 17196 cp foo.in foo 17197 17198and it works with double suffix inference rules: 17199 17200 $ cat Makefile 17201 foo.out: foo.in 17202 .SUFFIXES: .in .out 17203 .in.out: 17204 cp $< $@ 17205 $ make 17206 cp foo.in foo.out 17207 17208 As a result, in such a case, you have to write target rules. 17209 17210 17211File: autoconf.info, Node: Timestamps and Make, Prev: Single Suffix Rules, Up: Portable Make 17212 1721312.20 Timestamp Resolution and Make 17214=================================== 17215 17216Traditionally, file timestamps had 1-second resolution, and `make' used 17217those timestamps to determine whether one file was newer than the 17218other. However, many modern file systems have timestamps with 172191-nanosecond resolution. Some `make' implementations look at the 17220entire timestamp; others ignore the fractional part, which can lead to 17221incorrect results. Normally this is not a problem, but in some extreme 17222cases you may need to use tricks like `sleep 1' to work around 17223timestamp truncation bugs. 17224 17225 Commands like `cp -p' and `touch -r' typically do not copy file 17226timestamps to their full resolutions (*note Limitations of Usual Tools: 17227touch.). Hence you should be wary of rules like this: 17228 17229 dest: src 17230 cp -p src dest 17231 17232 as `dest' often appears to be older than `src' after the timestamp 17233is truncated, and this can cause `make' to do needless rework the next 17234time it is invoked. To work around this problem, you can use a 17235timestamp file, e.g.: 17236 17237 dest-stamp: src 17238 cp -p src dest 17239 date >dest-stamp 17240 17241 Apart from timestamp resolution, there are also differences in 17242handling equal timestamps. HP-UX `make' updates targets if it has the 17243same time stamp as one of its prerequisites, in violation of Posix 17244rules. 17245 17246 This can cause spurious rebuilds for repeated runs of `make'. This 17247in turn can cause `make' to fail if it tries to rebuild generated files 17248in a possibly read-only source tree with tools not present on the 17249end-user machine. Use GNU `make' instead. 17250 17251 17252File: autoconf.info, Node: Portable C and C++, Next: Manual Configuration, Prev: Portable Make, Up: Top 17253 1725413 Portable C and C++ Programming 17255********************************* 17256 17257C and C++ programs often use low-level features of the underlying 17258system, and therefore are often more difficult to make portable to other 17259platforms. 17260 17261 Several standards have been developed to help make your programs more 17262portable. If you write programs with these standards in mind, you can 17263have greater confidence that your programs work on a wide variety of 17264systems. *Note Language Standards Supported by GCC: (gcc)Standards, 17265for a list of C-related standards. Many programs also assume the Posix 17266standard (http://www.opengroup.org/susv3). 17267 17268 Some old code is written to be portable to K&R C, which predates any 17269C standard. K&R C compilers are no longer of practical interest, 17270though, and the rest of section assumes at least C89, the first C 17271standard. 17272 17273 Program portability is a huge topic, and this section can only 17274briefly introduce common pitfalls. *Note Portability between System 17275Types: (standards)System Portability, for more information. 17276 17277* Menu: 17278 17279* Varieties of Unportability:: How to make your programs unportable 17280* Integer Overflow:: When integers get too large 17281* Preprocessor Arithmetic:: `#if' expression problems 17282* Null Pointers:: Properties of null pointers 17283* Buffer Overruns:: Subscript errors and the like 17284* Volatile Objects:: `volatile' and signals 17285* Floating Point Portability:: Portable floating-point arithmetic 17286* Exiting Portably:: Exiting and the exit status 17287 17288 17289File: autoconf.info, Node: Varieties of Unportability, Next: Integer Overflow, Up: Portable C and C++ 17290 1729113.1 Varieties of Unportability 17292=============================== 17293 17294Autoconf tests and ordinary programs often need to test what is allowed 17295on a system, and therefore they may need to deliberately exceed the 17296boundaries of what the standards allow, if only to see whether an 17297optional feature is present. When you write such a program, you should 17298keep in mind the difference between constraints, unspecified behavior, 17299and undefined behavior. 17300 17301 In C, a "constraint" is a rule that the compiler must enforce. An 17302example constraint is that C programs must not declare a bit-field with 17303negative width. Tests can therefore reliably assume that programs with 17304negative-width bit-fields are rejected by a compiler that conforms to 17305the standard. 17306 17307 "Unspecified behavior" is valid behavior, where the standard allows 17308multiple possibilities. For example, the order of evaluation of 17309function arguments is unspecified. Some unspecified behavior is 17310"implementation-defined", i.e., documented by the implementation, but 17311since Autoconf tests cannot read the documentation they cannot 17312distinguish between implementation-defined and other unspecified 17313behavior. It is common for Autoconf tests to probe implementations to 17314determine otherwise-unspecified behavior. 17315 17316 "Undefined behavior" is invalid behavior, where the standard allows 17317the implementation to do anything it pleases. For example, 17318dereferencing a null pointer leads to undefined behavior. If possible, 17319test programs should avoid undefined behavior, since a program with 17320undefined behavior might succeed on a test that should fail. 17321 17322 The above rules apply to programs that are intended to conform to the 17323standard. However, strictly-conforming programs are quite rare, since 17324the standards are so limiting. A major goal of Autoconf is to support 17325programs that use implementation features not described by the standard, 17326and it is fairly common for test programs to violate the above rules, if 17327the programs work well enough in practice. 17328 17329 17330File: autoconf.info, Node: Integer Overflow, Next: Preprocessor Arithmetic, Prev: Varieties of Unportability, Up: Portable C and C++ 17331 1733213.2 Integer Overflow 17333===================== 17334 17335In practice many portable C programs assume that signed integer 17336overflow wraps around reliably using two's complement arithmetic. Yet 17337the C standard says that program behavior is undefined on overflow, and 17338in a few cases C programs do not work on some modern implementations 17339because their overflows do not wrap around as their authors expected. 17340Conversely, in signed integer remainder, the C standard requires 17341overflow behavior that is commonly not implemented. 17342 17343* Menu: 17344 17345* Integer Overflow Basics:: Why integer overflow is a problem 17346* Signed Overflow Examples:: Examples of code assuming wraparound 17347* Optimization and Wraparound:: Optimizations that break uses of wraparound 17348* Signed Overflow Advice:: Practical advice for signed overflow issues 17349* Signed Integer Division:: `INT_MIN / -1' and `INT_MIN % -1' 17350 17351 17352File: autoconf.info, Node: Integer Overflow Basics, Next: Signed Overflow Examples, Up: Integer Overflow 17353 1735413.2.1 Basics of Integer Overflow 17355--------------------------------- 17356 17357In languages like C, unsigned integer overflow reliably wraps around; 17358e.g., `UINT_MAX + 1' yields zero. This is guaranteed by the C standard 17359and is portable in practice, unless you specify aggressive, nonstandard 17360optimization options suitable only for special applications. 17361 17362 In contrast, the C standard says that signed integer overflow leads 17363to undefined behavior where a program can do anything, including dumping 17364core or overrunning a buffer. The misbehavior can even precede the 17365overflow. Such an overflow can occur during addition, subtraction, 17366multiplication, division, and left shift. 17367 17368 Despite this requirement of the standard, many C programs and 17369Autoconf tests assume that signed integer overflow silently wraps 17370around modulo a power of two, using two's complement arithmetic, so 17371long as you cast the resulting value to a signed integer type or store 17372it into a signed integer variable. If you use conservative 17373optimization flags, such programs are generally portable to the vast 17374majority of modern platforms, with a few exceptions discussed later. 17375 17376 For historical reasons the C standard also allows implementations 17377with ones' complement or signed magnitude arithmetic, but it is safe to 17378assume two's complement nowadays. 17379 17380 Also, overflow can occur when converting an out-of-range value to a 17381signed integer type. Here a standard implementation must define what 17382happens, but this might include raising an exception. In practice all 17383known implementations support silent wraparound in this case, so you 17384need not worry about other possibilities. 17385 17386 17387File: autoconf.info, Node: Signed Overflow Examples, Next: Optimization and Wraparound, Prev: Integer Overflow Basics, Up: Integer Overflow 17388 1738913.2.2 Examples of Code Assuming Wraparound Overflow 17390---------------------------------------------------- 17391 17392There has long been a tension between what the C standard requires for 17393signed integer overflow, and what C programs commonly assume. The 17394standard allows aggressive optimizations based on assumptions that 17395overflow never occurs, but many practical C programs rely on overflow 17396wrapping around. These programs do not conform to the standard, but 17397they commonly work in practice because compiler writers are 17398understandably reluctant to implement optimizations that would break 17399many programs, unless perhaps a user specifies aggressive optimization. 17400 17401 The C Standard says that if a program has signed integer overflow its 17402behavior is undefined, and the undefined behavior can even precede the 17403overflow. To take an extreme example: 17404 17405 if (password == expected_password) 17406 allow_superuser_privileges (); 17407 else if (counter++ == INT_MAX) 17408 abort (); 17409 else 17410 printf ("%d password mismatches\n", counter); 17411 17412If the `int' variable `counter' equals `INT_MAX', `counter++' must 17413overflow and the behavior is undefined, so the C standard allows the 17414compiler to optimize away the test against `INT_MAX' and the `abort' 17415call. Worse, if an earlier bug in the program lets the compiler deduce 17416that `counter == INT_MAX' or that `counter' previously overflowed, the 17417C standard allows the compiler to optimize away the password test and 17418generate code that allows superuser privileges unconditionally. 17419 17420 Despite this requirement by the standard, it has long been common 17421for C code to assume wraparound arithmetic after signed overflow, and 17422all known practical C implementations support some C idioms that assume 17423wraparound signed arithmetic, even if the idioms do not conform 17424strictly to the standard. If your code looks like the following 17425examples it will almost surely work with real-world compilers. 17426 17427 Here is an example derived from the 7th Edition Unix implementation 17428of `atoi' (1979-01-10): 17429 17430 char *p; 17431 int f, n; 17432 ... 17433 while (*p >= '0' && *p <= '9') 17434 n = n * 10 + *p++ - '0'; 17435 return (f ? -n : n); 17436 17437Even if the input string is in range, on most modern machines this has 17438signed overflow when computing the most negative integer (the `-n' 17439overflows) or a value near an extreme integer (the first `+' overflows). 17440 17441 Here is another example, derived from the 7th Edition implementation 17442of `rand' (1979-01-10). Here the programmer expects both 17443multiplication and addition to wrap on overflow: 17444 17445 static long int randx = 1; 17446 ... 17447 randx = randx * 1103515245 + 12345; 17448 return (randx >> 16) & 077777; 17449 17450 In the following example, derived from the GNU C Library 2.5 17451implementation of `mktime' (2006-09-09), the code assumes wraparound 17452arithmetic in `+' to detect signed overflow: 17453 17454 time_t t, t1, t2; 17455 int sec_requested, sec_adjustment; 17456 ... 17457 t1 = t + sec_requested; 17458 t2 = t1 + sec_adjustment; 17459 if (((t1 < t) != (sec_requested < 0)) 17460 | ((t2 < t1) != (sec_adjustment < 0))) 17461 return -1; 17462 17463 If your code looks like these examples, it is probably safe even 17464though it does not strictly conform to the C standard. This might lead 17465one to believe that one can generally assume wraparound on overflow, 17466but that is not always true, as can be seen in the next section. 17467 17468 17469File: autoconf.info, Node: Optimization and Wraparound, Next: Signed Overflow Advice, Prev: Signed Overflow Examples, Up: Integer Overflow 17470 1747113.2.3 Optimizations That Break Wraparound Arithmetic 17472----------------------------------------------------- 17473 17474Compilers sometimes generate code that is incompatible with wraparound 17475integer arithmetic. A simple example is an algebraic simplification: a 17476compiler might translate `(i * 2000) / 1000' to `i * 2' because it 17477assumes that `i * 2000' does not overflow. The translation is not 17478equivalent to the original when overflow occurs: e.g., in the typical 17479case of 32-bit signed two's complement wraparound `int', if `i' has 17480type `int' and value `1073742', the original expression returns 17481-2147483 but the optimized version returns the mathematically correct 17482value 2147484. 17483 17484 More subtly, loop induction optimizations often exploit the undefined 17485behavior of signed overflow. Consider the following contrived function 17486`sumc': 17487 17488 int 17489 sumc (int lo, int hi) 17490 { 17491 int sum = 0; 17492 int i; 17493 for (i = lo; i <= hi; i++) 17494 sum ^= i * 53; 17495 return sum; 17496 } 17497 17498To avoid multiplying by 53 each time through the loop, an optimizing 17499compiler might internally transform `sumc' to the equivalent of the 17500following: 17501 17502 int 17503 transformed_sumc (int lo, int hi) 17504 { 17505 int sum = 0; 17506 int hic = hi * 53; 17507 int ic; 17508 for (ic = lo * 53; ic <= hic; ic += 53) 17509 sum ^= ic; 17510 return sum; 17511 } 17512 17513This transformation is allowed by the C standard, but it is invalid for 17514wraparound arithmetic when `INT_MAX / 53 < hi', because then the 17515overflow in computing expressions like `hi * 53' can cause the 17516expression `i <= hi' to yield a different value from the transformed 17517expression `ic <= hic'. 17518 17519 For this reason, compilers that use loop induction and similar 17520techniques often do not support reliable wraparound arithmetic when a 17521loop induction variable like `ic' is involved. Since loop induction 17522variables are generated by the compiler, and are not visible in the 17523source code, it is not always trivial to say whether the problem 17524affects your code. 17525 17526 Hardly any code actually depends on wraparound arithmetic in cases 17527like these, so in practice these loop induction optimizations are almost 17528always useful. However, edge cases in this area can cause problems. 17529For example: 17530 17531 int j; 17532 for (j = 1; 0 < j; j *= 2) 17533 test (j); 17534 17535Here, the loop attempts to iterate through all powers of 2 that `int' 17536can represent, but the C standard allows a compiler to optimize away 17537the comparison and generate an infinite loop, under the argument that 17538behavior is undefined on overflow. As of this writing this 17539optimization is not done by any production version of GCC with `-O2', 17540but it might be performed by other compilers, or by more aggressive GCC 17541optimization options, and the GCC developers have not decided whether 17542it will continue to work with GCC and `-O2'. 17543 17544 17545File: autoconf.info, Node: Signed Overflow Advice, Next: Signed Integer Division, Prev: Optimization and Wraparound, Up: Integer Overflow 17546 1754713.2.4 Practical Advice for Signed Overflow Issues 17548-------------------------------------------------- 17549 17550Ideally the safest approach is to avoid signed integer overflow 17551entirely. For example, instead of multiplying two signed integers, you 17552can convert them to unsigned integers, multiply the unsigned values, 17553then test whether the result is in signed range. 17554 17555 Rewriting code in this way will be inconvenient, though, 17556particularly if the signed values might be negative. Also, it may hurt 17557performance. Using unsigned arithmetic to check for overflow is 17558particularly painful to do portably and efficiently when dealing with an 17559integer type like `uid_t' whose width and signedness vary from platform 17560to platform. 17561 17562 Furthermore, many C applications pervasively assume wraparound 17563behavior and typically it is not easy to find and remove all these 17564assumptions. Hence it is often useful to maintain nonstandard code 17565that assumes wraparound on overflow, instead of rewriting the code. 17566The rest of this section attempts to give practical advice for this 17567situation. 17568 17569 If your code wants to detect signed integer overflow in `sum = a + 17570b', it is generally safe to use an expression like `(sum < a) != (b < 175710)'. 17572 17573 If your code uses a signed loop index, make sure that the index 17574cannot overflow, along with all signed expressions derived from the 17575index. Here is a contrived example of problematic code with two 17576instances of overflow. 17577 17578 for (i = INT_MAX - 10; i <= INT_MAX; i++) 17579 if (i + 1 < 0) 17580 { 17581 report_overflow (); 17582 break; 17583 } 17584 17585Because of the two overflows, a compiler might optimize away or 17586transform the two comparisons in a way that is incompatible with the 17587wraparound assumption. 17588 17589 If your code uses an expression like `(i * 2000) / 1000' and you 17590actually want the multiplication to wrap around on overflow, use 17591unsigned arithmetic to do it, e.g., `((int) (i * 2000u)) / 1000'. 17592 17593 If your code assumes wraparound behavior and you want to insulate it 17594against any GCC optimizations that would fail to support that behavior, 17595you should use GCC's `-fwrapv' option, which causes signed overflow to 17596wrap around reliably (except for division and remainder, as discussed 17597in the next section). 17598 17599 If you need to port to platforms where signed integer overflow does 17600not reliably wrap around (e.g., due to hardware overflow checking, or to 17601highly aggressive optimizations), you should consider debugging with 17602GCC's `-ftrapv' option, which causes signed overflow to raise an 17603exception. 17604 17605 17606File: autoconf.info, Node: Signed Integer Division, Prev: Signed Overflow Advice, Up: Integer Overflow 17607 1760813.2.5 Signed Integer Division and Integer Overflow 17609--------------------------------------------------- 17610 17611Overflow in signed integer division is not always harmless: for 17612example, on CPUs of the i386 family, dividing `INT_MIN' by `-1' yields 17613a SIGFPE signal which by default terminates the program. Worse, taking 17614the remainder of these two values typically yields the same signal on 17615these CPUs, even though the C standard requires `INT_MIN % -1' to yield 17616zero because the expression does not overflow. 17617 17618 17619File: autoconf.info, Node: Preprocessor Arithmetic, Next: Null Pointers, Prev: Integer Overflow, Up: Portable C and C++ 17620 1762113.3 Preprocessor Arithmetic 17622============================ 17623 17624In C99, preprocessor arithmetic, used for `#if' expressions, must be 17625evaluated as if all signed values are of type `intmax_t' and all 17626unsigned values of type `uintmax_t'. Many compilers are buggy in this 17627area, though. For example, as of 2007, Sun C mishandles `#if LLONG_MIN 17628< 0' on a platform with 32-bit `long int' and 64-bit `long long int'. 17629Also, some older preprocessors mishandle constants ending in `LL'. To 17630work around these problems, you can compute the value of expressions 17631like `LONG_MAX < LLONG_MAX' at `configure'-time rather than at 17632`#if'-time. 17633 17634 17635File: autoconf.info, Node: Null Pointers, Next: Buffer Overruns, Prev: Preprocessor Arithmetic, Up: Portable C and C++ 17636 1763713.4 Properties of Null Pointers 17638================================ 17639 17640Most modern hosts reliably fail when you attempt to dereference a null 17641pointer. 17642 17643 On almost all modern hosts, null pointers use an all-bits-zero 17644internal representation, so you can reliably use `memset' with 0 to set 17645all the pointers in an array to null values. 17646 17647 If `p' is a null pointer to an object type, the C expression `p + 0' 17648always evaluates to `p' on modern hosts, even though the standard says 17649that it has undefined behavior. 17650 17651 17652File: autoconf.info, Node: Buffer Overruns, Next: Volatile Objects, Prev: Null Pointers, Up: Portable C and C++ 17653 1765413.5 Buffer Overruns and Subscript Errors 17655========================================= 17656 17657Buffer overruns and subscript errors are the most common dangerous 17658errors in C programs. They result in undefined behavior because storing 17659outside an array typically modifies storage that is used by some other 17660object, and most modern systems lack runtime checks to catch these 17661errors. Programs should not rely on buffer overruns being caught. 17662 17663 There is one exception to the usual rule that a portable program 17664cannot address outside an array. In C, it is valid to compute the 17665address just past an object, e.g., `&a[N]' where `a' has `N' elements, 17666so long as you do not dereference the resulting pointer. But it is not 17667valid to compute the address just before an object, e.g., `&a[-1]'; nor 17668is it valid to compute two past the end, e.g., `&a[N+1]'. On most 17669platforms `&a[-1] < &a[0] && &a[N] < &a[N+1]', but this is not reliable 17670in general, and it is usually easy enough to avoid the potential 17671portability problem, e.g., by allocating an extra unused array element 17672at the start or end. 17673 17674 Valgrind (http://valgrind.org/) can catch many overruns. GCC users 17675might also consider using the `-fmudflap' option to catch overruns. 17676 17677 Buffer overruns are usually caused by off-by-one errors, but there 17678are more subtle ways to get them. 17679 17680 Using `int' values to index into an array or compute array sizes 17681causes problems on typical 64-bit hosts where an array index might be 176822^31 or larger. Index values of type `size_t' avoid this problem, but 17683cannot be negative. Index values of type `ptrdiff_t' are signed, and 17684are wide enough in practice. 17685 17686 If you add or multiply two numbers to calculate an array size, e.g., 17687`malloc (x * sizeof y + z)', havoc ensues if the addition or 17688multiplication overflows. 17689 17690 Many implementations of the `alloca' function silently misbehave and 17691can generate buffer overflows if given sizes that are too large. The 17692size limits are implementation dependent, but are at least 4000 bytes 17693on all platforms that we know about. 17694 17695 The standard functions `asctime', `asctime_r', `ctime', `ctime_r', 17696and `gets' are prone to buffer overflows, and portable code should not 17697use them unless the inputs are known to be within certain limits. The 17698time-related functions can overflow their buffers if given timestamps 17699out of range (e.g., a year less than -999 or greater than 9999). 17700Time-related buffer overflows cannot happen with recent-enough versions 17701of the GNU C library, but are possible with other implementations. The 17702`gets' function is the worst, since it almost invariably overflows its 17703buffer when presented with an input line larger than the buffer. 17704 17705 17706File: autoconf.info, Node: Volatile Objects, Next: Floating Point Portability, Prev: Buffer Overruns, Up: Portable C and C++ 17707 1770813.6 Volatile Objects 17709===================== 17710 17711The keyword `volatile' is often misunderstood in portable code. Its 17712use inhibits some memory-access optimizations, but programmers often 17713wish that it had a different meaning than it actually does. 17714 17715 `volatile' was designed for code that accesses special objects like 17716memory-mapped device registers whose contents spontaneously change. 17717Such code is inherently low-level, and it is difficult to specify 17718portably what `volatile' means in these cases. The C standard says, 17719"What constitutes an access to an object that has volatile-qualified 17720type is implementation-defined," so in theory each implementation is 17721supposed to fill in the gap by documenting what `volatile' means for 17722that implementation. In practice, though, this documentation is 17723usually absent or incomplete. 17724 17725 One area of confusion is the distinction between objects defined with 17726volatile types, and volatile lvalues. From the C standard's point of 17727view, an object defined with a volatile type has externally visible 17728behavior. You can think of such objects as having little oscilloscope 17729probes attached to them, so that the user can observe some properties of 17730accesses to them, just as the user can observe data written to output 17731files. However, the standard does not make it clear whether users can 17732observe accesses by volatile lvalues to ordinary objects. For example: 17733 17734 /* Declare and access a volatile object. 17735 Accesses to X are "visible" to users. */ 17736 static int volatile x; 17737 x = 1; 17738 17739 /* Access two ordinary objects via a volatile lvalue. 17740 It's not clear whether accesses to *P are "visible". */ 17741 int y; 17742 int *z = malloc (sizeof (int)); 17743 int volatile *p; 17744 p = &y; 17745 *p = 1; 17746 p = z; 17747 *p = 1; 17748 17749 Programmers often wish that `volatile' meant "Perform the memory 17750access here and now, without merging several memory accesses, without 17751changing the memory word size, and without reordering." But the C 17752standard does not require this. For objects defined with a volatile 17753type, accesses must be done before the next sequence point; but 17754otherwise merging, reordering, and word-size change is allowed. Worse, 17755it is not clear from the standard whether volatile lvalues provide more 17756guarantees in general than nonvolatile lvalues, if the underlying 17757objects are ordinary. 17758 17759 Even when accessing objects defined with a volatile type, the C 17760standard allows only extremely limited signal handlers: the behavior is 17761undefined if a signal handler reads any nonlocal object, or writes to 17762any nonlocal object whose type is not `sig_atomic_t volatile', or calls 17763any standard library function other than `abort', `signal', and (if C99) 17764`_Exit'. Hence C compilers need not worry about a signal handler 17765disturbing ordinary computation, unless the computation accesses a 17766`sig_atomic_t volatile' lvalue that is not a local variable. (There is 17767an obscure exception for accesses via a pointer to a volatile 17768character, since it may point into part of a `sig_atomic_t volatile' 17769object.) Posix adds to the list of library functions callable from a 17770portable signal handler, but otherwise is like the C standard in this 17771area. 17772 17773 Some C implementations allow memory-access optimizations within each 17774translation unit, such that actual behavior agrees with the behavior 17775required by the standard only when calling a function in some other 17776translation unit, and a signal handler acts like it was called from a 17777different translation unit. The C standard hints that in these 17778implementations, objects referred to by signal handlers "would require 17779explicit specification of `volatile' storage, as well as other 17780implementation-defined restrictions." But unfortunately even for this 17781special case these other restrictions are often not documented well. 17782*Note When is a Volatile Object Accessed?: (gcc)Volatiles, for some 17783restrictions imposed by GCC. *Note Defining Signal Handlers: 17784(libc)Defining Handlers, for some restrictions imposed by the GNU C 17785library. Restrictions differ on other platforms. 17786 17787 If possible, it is best to use a signal handler that fits within the 17788limits imposed by the C and Posix standards. 17789 17790 If this is not practical, you can try the following rules of thumb. 17791A signal handler should access only volatile lvalues, preferably lvalues 17792that refer to objects defined with a volatile type, and should not 17793assume that the accessed objects have an internally consistent state if 17794they are larger than a machine word. Furthermore, installers should 17795employ compilers and compiler options that are commonly used for 17796building operating system kernels, because kernels often need more from 17797`volatile' than the C Standard requires, and installers who compile an 17798application in a similar environment can sometimes benefit from the 17799extra constraints imposed by kernels on compilers. Admittedly we are 17800handwaving somewhat here, as there are few guarantees in this area; the 17801rules of thumb may help to fix some bugs but there is a good chance 17802that they will not fix them all. 17803 17804 For `volatile', C++ has the same problems that C does. 17805Multithreaded applications have even more problems with `volatile', but 17806they are beyond the scope of this section. 17807 17808 The bottom line is that using `volatile' typically hurts performance 17809but should not hurt correctness. In some cases its use does help 17810correctness, but these cases are often so poorly understood that all 17811too often adding `volatile' to a data structure merely alleviates some 17812symptoms of a bug while not fixing the bug in general. 17813 17814 17815File: autoconf.info, Node: Floating Point Portability, Next: Exiting Portably, Prev: Volatile Objects, Up: Portable C and C++ 17816 1781713.7 Floating Point Portability 17818=============================== 17819 17820Almost all modern systems use IEEE-754 floating point, and it is safe to 17821assume IEEE-754 in most portable code these days. For more information, 17822please see David Goldberg's classic paper What Every Computer Scientist 17823Should Know About Floating-Point Arithmetic 17824(http://www.validlab.com/goldberg/paper.pdf). 17825 17826 17827File: autoconf.info, Node: Exiting Portably, Prev: Floating Point Portability, Up: Portable C and C++ 17828 1782913.8 Exiting Portably 17830===================== 17831 17832A C or C++ program can exit with status N by returning N from the 17833`main' function. Portable programs are supposed to exit either with 17834status 0 or `EXIT_SUCCESS' to succeed, or with status `EXIT_FAILURE' to 17835fail, but in practice it is portable to fail by exiting with status 1, 17836and test programs that assume Posix can fail by exiting with status 17837values from 1 through 255. Programs on SunOS 2.0 (1985) through 3.5.2 17838(1988) incorrectly exited with zero status when `main' returned 17839nonzero, but ancient systems like these are no longer of practical 17840concern. 17841 17842 A program can also exit with status N by passing N to the `exit' 17843function, and a program can fail by calling the `abort' function. If a 17844program is specialized to just some platforms, it can fail by calling 17845functions specific to those platforms, e.g., `_exit' (Posix) and 17846`_Exit' (C99). However, like other functions, an exit function should 17847be declared, typically by including a header. For example, if a C 17848program calls `exit', it should include `stdlib.h' either directly or 17849via the default includes (*note Default Includes::). 17850 17851 A program can fail due to undefined behavior such as dereferencing a 17852null pointer, but this is not recommended as undefined behavior allows 17853an implementation to do whatever it pleases and this includes exiting 17854successfully. 17855 17856 17857File: autoconf.info, Node: Manual Configuration, Next: Site Configuration, Prev: Portable C and C++, Up: Top 17858 1785914 Manual Configuration 17860*********************** 17861 17862A few kinds of features can't be guessed automatically by running test 17863programs. For example, the details of the object-file format, or 17864special options that need to be passed to the compiler or linker. You 17865can check for such features using ad-hoc means, such as having 17866`configure' check the output of the `uname' program, or looking for 17867libraries that are unique to particular systems. However, Autoconf 17868provides a uniform method for handling unguessable features. 17869 17870* Menu: 17871 17872* Specifying Target Triplets:: Specifying target triplets 17873* Canonicalizing:: Getting the canonical system type 17874* Using System Type:: What to do with the system type 17875 17876 17877File: autoconf.info, Node: Specifying Target Triplets, Next: Canonicalizing, Up: Manual Configuration 17878 1787914.1 Specifying target triplets 17880=============================== 17881 17882Autoconf-generated `configure' scripts can make decisions based on a 17883canonical name for the system type, or "target triplet", which has the 17884form: `CPU-VENDOR-OS', where OS can be `SYSTEM' or `KERNEL-SYSTEM' 17885 17886 `configure' can usually guess the canonical name for the type of 17887system it's running on. To do so it runs a script called 17888`config.guess', which infers the name using the `uname' command or 17889symbols predefined by the C preprocessor. 17890 17891 Alternately, the user can specify the system type with command line 17892arguments to `configure' (*note System Type::. Doing so is necessary 17893when cross-compiling. In the most complex case of cross-compiling, 17894three system types are involved. The options to specify them are: 17895 17896`--build=BUILD-TYPE' 17897 the type of system on which the package is being configured and 17898 compiled. It defaults to the result of running `config.guess'. 17899 Specifying a BUILD-TYPE that differs from HOST-TYPE enables 17900 cross-compilation mode. 17901 17902`--host=HOST-TYPE' 17903 the type of system on which the package runs. By default it is the 17904 same as the build machine. Specifying a HOST-TYPE that differs 17905 from BUILD-TYPE, when BUILD-TYPE was also explicitly specified, 17906 enables cross-compilation mode. 17907 17908`--target=TARGET-TYPE' 17909 the type of system for which any compiler tools in the package 17910 produce code (rarely needed). By default, it is the same as host. 17911 17912 If you mean to override the result of `config.guess', use `--build', 17913not `--host', since the latter enables cross-compilation. For 17914historical reasons, whenever you specify `--host', be sure to specify 17915`--build' too; this will be fixed in the future. So, to enter 17916cross-compilation mode, use a command like this 17917 17918 ./configure --build=i686-pc-linux-gnu --host=m68k-coff 17919 17920Note that if you do not specify `--host', `configure' fails if it can't 17921run the code generated by the specified compiler. For example, 17922configuring as follows fails: 17923 17924 ./configure CC=m68k-coff-gcc 17925 17926 When cross-compiling, `configure' will warn about any tools 17927(compilers, linkers, assemblers) whose name is not prefixed with the 17928host type. This is an aid to users performing cross-compilation. 17929Continuing the example above, if a cross-compiler named `cc' is used 17930with a native `pkg-config', then libraries found by `pkg-config' will 17931likely cause subtle build failures; but using the names `m68k-coff-cc' 17932and `m68k-coff-pkg-config' avoids any confusion. Avoiding the warning 17933is as simple as creating the correct symlinks naming the cross tools. 17934 17935 `configure' recognizes short aliases for many system types; for 17936example, `decstation' can be used instead of `mips-dec-ultrix4.2'. 17937`configure' runs a script called `config.sub' to canonicalize system 17938type aliases. 17939 17940 This section deliberately omits the description of the obsolete 17941interface; see *note Hosts and Cross-Compilation::. 17942 17943 17944File: autoconf.info, Node: Canonicalizing, Next: Using System Type, Prev: Specifying Target Triplets, Up: Manual Configuration 17945 1794614.2 Getting the Canonical System Type 17947====================================== 17948 17949The following macros make the system type available to `configure' 17950scripts. 17951 17952 The variables `build_alias', `host_alias', and `target_alias' are 17953always exactly the arguments of `--build', `--host', and `--target'; in 17954particular, they are left empty if the user did not use them, even if 17955the corresponding `AC_CANONICAL' macro was run. Any configure script 17956may use these variables anywhere. These are the variables that should 17957be used when in interaction with the user. 17958 17959 If you need to recognize some special environments based on their 17960system type, run the following macros to get canonical system names. 17961These variables are not set before the macro call. 17962 17963 If you use these macros, you must distribute `config.guess' and 17964`config.sub' along with your source code. *Note Output::, for 17965information about the `AC_CONFIG_AUX_DIR' macro which you can use to 17966control in which directory `configure' looks for those scripts. 17967 17968 -- Macro: AC_CANONICAL_BUILD 17969 Compute the canonical build-system type variable, `build', and its 17970 three individual parts `build_cpu', `build_vendor', and `build_os'. 17971 17972 If `--build' was specified, then `build' is the canonicalization 17973 of `build_alias' by `config.sub', otherwise it is determined by 17974 the shell script `config.guess'. 17975 17976 -- Macro: AC_CANONICAL_HOST 17977 Compute the canonical host-system type variable, `host', and its 17978 three individual parts `host_cpu', `host_vendor', and `host_os'. 17979 17980 If `--host' was specified, then `host' is the canonicalization of 17981 `host_alias' by `config.sub', otherwise it defaults to `build'. 17982 17983 -- Macro: AC_CANONICAL_TARGET 17984 Compute the canonical target-system type variable, `target', and 17985 its three individual parts `target_cpu', `target_vendor', and 17986 `target_os'. 17987 17988 If `--target' was specified, then `target' is the canonicalization 17989 of `target_alias' by `config.sub', otherwise it defaults to `host'. 17990 17991 Note that there can be artifacts due to the backward compatibility 17992code. *Note Hosts and Cross-Compilation::, for more. 17993 17994 17995File: autoconf.info, Node: Using System Type, Prev: Canonicalizing, Up: Manual Configuration 17996 1799714.3 Using the System Type 17998========================== 17999 18000In `configure.ac' the system type is generally used by one or more 18001`case' statements to select system-specifics. Shell wildcards can be 18002used to match a group of system types. 18003 18004 For example, an extra assembler code object file could be chosen, 18005giving access to a CPU cycle counter register. `$(CYCLE_OBJ)' in the 18006following would be used in a makefile to add the object to a program or 18007library. 18008 18009 AS_CASE([$host], 18010 [alpha*-*-*], [CYCLE_OBJ=rpcc.o], 18011 [i?86-*-*], [CYCLE_OBJ=rdtsc.o], 18012 [CYCLE_OBJ=""] 18013 ) 18014 AC_SUBST([CYCLE_OBJ]) 18015 18016 `AC_CONFIG_LINKS' (*note Configuration Links::) is another good way 18017to select variant source files, for example optimized code for some 18018CPUs. The configured CPU type doesn't always indicate exact CPU types, 18019so some runtime capability checks may be necessary too. 18020 18021 case $host in 18022 alpha*-*-*) AC_CONFIG_LINKS([dither.c:alpha/dither.c]) ;; 18023 powerpc*-*-*) AC_CONFIG_LINKS([dither.c:powerpc/dither.c]) ;; 18024 *-*-*) AC_CONFIG_LINKS([dither.c:generic/dither.c]) ;; 18025 esac 18026 18027 The host system type can also be used to find cross-compilation tools 18028with `AC_CHECK_TOOL' (*note Generic Programs::). 18029 18030 The above examples all show `$host', since this is where the code is 18031going to run. Only rarely is it necessary to test `$build' (which is 18032where the build is being done). 18033 18034 Whenever you're tempted to use `$host' it's worth considering 18035whether some sort of probe would be better. New system types come along 18036periodically or previously missing features are added. Well-written 18037probes can adapt themselves to such things, but hard-coded lists of 18038names can't. Here are some guidelines, 18039 18040 * Availability of libraries and library functions should always be 18041 checked by probing. 18042 18043 * Variant behavior of system calls is best identified with runtime 18044 tests if possible, but bug workarounds or obscure difficulties 18045 might have to be driven from `$host'. 18046 18047 * Assembler code is inevitably highly CPU-specific and is best 18048 selected according to `$host_cpu'. 18049 18050 * Assembler variations like underscore prefix on globals or ELF 18051 versus COFF type directives are however best determined by 18052 probing, perhaps even examining the compiler output. 18053 18054 `$target' is for use by a package creating a compiler or similar. 18055For ordinary packages it's meaningless and should not be used. It 18056indicates what the created compiler should generate code for, if it can 18057cross-compile. `$target' generally selects various hard-coded CPU and 18058system conventions, since usually the compiler or tools under 18059construction themselves determine how the target works. 18060 18061 18062File: autoconf.info, Node: Site Configuration, Next: Running configure Scripts, Prev: Manual Configuration, Up: Top 18063 1806415 Site Configuration 18065********************* 18066 18067`configure' scripts support several kinds of local configuration 18068decisions. There are ways for users to specify where external software 18069packages are, include or exclude optional features, install programs 18070under modified names, and set default values for `configure' options. 18071 18072* Menu: 18073 18074* Help Formatting:: Customizing `configure --help' 18075* External Software:: Working with other optional software 18076* Package Options:: Selecting optional features 18077* Pretty Help Strings:: Formatting help string 18078* Option Checking:: Controlling checking of `configure' options 18079* Site Details:: Configuring site details 18080* Transforming Names:: Changing program names when installing 18081* Site Defaults:: Giving `configure' local defaults 18082 18083 18084File: autoconf.info, Node: Help Formatting, Next: External Software, Up: Site Configuration 18085 1808615.1 Controlling Help Output 18087============================ 18088 18089Users consult `configure --help' to learn of configuration decisions 18090specific to your package. By default, `configure' breaks this output 18091into sections for each type of option; within each section, help 18092strings appear in the order `configure.ac' defines them: 18093 18094 Optional Features: 18095 ... 18096 --enable-bar include bar 18097 18098 Optional Packages: 18099 ... 18100 --with-foo use foo 18101 18102 -- Macro: AC_PRESERVE_HELP_ORDER 18103 Request an alternate `--help' format, in which options of all 18104 types appear together, in the order defined. Call this macro 18105 before any `AC_ARG_ENABLE' or `AC_ARG_WITH'. 18106 18107 Optional Features and Packages: 18108 ... 18109 --enable-bar include bar 18110 --with-foo use foo 18111 18112 18113 18114File: autoconf.info, Node: External Software, Next: Package Options, Prev: Help Formatting, Up: Site Configuration 18115 1811615.2 Working With External Software 18117=================================== 18118 18119Some packages require, or can optionally use, other software packages 18120that are already installed. The user can give `configure' command line 18121options to specify which such external software to use. The options 18122have one of these forms: 18123 18124 --with-PACKAGE[=ARG] 18125 --without-PACKAGE 18126 18127 For example, `--with-gnu-ld' means work with the GNU linker instead 18128of some other linker. `--with-x' means work with The X Window System. 18129 18130 The user can give an argument by following the package name with `=' 18131and the argument. Giving an argument of `no' is for packages that are 18132used by default; it says to _not_ use the package. An argument that is 18133neither `yes' nor `no' could include a name or number of a version of 18134the other package, to specify more precisely which other package this 18135program is supposed to work with. If no argument is given, it defaults 18136to `yes'. `--without-PACKAGE' is equivalent to `--with-PACKAGE=no'. 18137 18138 Normally `configure' scripts complain about `--with-PACKAGE' options 18139that they do not support. *Note Option Checking::, for details, and 18140for how to override the defaults. 18141 18142 For each external software package that may be used, `configure.ac' 18143should call `AC_ARG_WITH' to detect whether the `configure' user asked 18144to use it. Whether each package is used or not by default, and which 18145arguments are valid, is up to you. 18146 18147 -- Macro: AC_ARG_WITH (PACKAGE, HELP-STRING, [ACTION-IF-GIVEN], 18148 [ACTION-IF-NOT-GIVEN]) 18149 If the user gave `configure' the option `--with-PACKAGE' or 18150 `--without-PACKAGE', run shell commands ACTION-IF-GIVEN. If 18151 neither option was given, run shell commands ACTION-IF-NOT-GIVEN. 18152 The name PACKAGE indicates another software package that this 18153 program should work with. It should consist only of alphanumeric 18154 characters, dashes, plus signs, and dots. 18155 18156 The option's argument is available to the shell commands 18157 ACTION-IF-GIVEN in the shell variable `withval', which is actually 18158 just the value of the shell variable named `with_PACKAGE', with 18159 any non-alphanumeric characters in PACKAGE changed into `_'. You 18160 may use that variable instead, if you wish. 18161 18162 The argument HELP-STRING is a description of the option that looks 18163 like this: 18164 --with-readline support fancy command line editing 18165 18166 HELP-STRING may be more than one line long, if more detail is 18167 needed. Just make sure the columns line up in `configure --help'. 18168 Avoid tabs in the help string. The easiest way to provide the 18169 proper leading whitespace is to format your HELP-STRING with the 18170 macro `AS_HELP_STRING' (*note Pretty Help Strings::). 18171 18172 The following example shows how to use the `AC_ARG_WITH' macro in 18173 a common situation. You want to let the user decide whether to 18174 enable support for an external library (e.g., the readline 18175 library); if the user specified neither `--with-readline' nor 18176 `--without-readline', you want to enable support for readline only 18177 if the library is available on the system. 18178 18179 AC_ARG_WITH([readline], 18180 [AS_HELP_STRING([--with-readline], 18181 [support fancy command line editing @<:@default=check@:>@])], 18182 [], 18183 [with_readline=check]) 18184 18185 LIBREADLINE= 18186 AS_IF([test "x$with_readline" != xno], 18187 [AC_CHECK_LIB([readline], [main], 18188 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"]) 18189 AC_DEFINE([HAVE_LIBREADLINE], [1], 18190 [Define if you have libreadline]) 18191 ], 18192 [if test "x$with_readline" != xcheck; then 18193 AC_MSG_FAILURE( 18194 [--with-readline was given, but test for readline failed]) 18195 fi 18196 ], -lncurses)]) 18197 18198 The next example shows how to use `AC_ARG_WITH' to give the user 18199 the possibility to enable support for the readline library, in 18200 case it is still experimental and not well tested, and is 18201 therefore disabled by default. 18202 18203 AC_ARG_WITH([readline], 18204 [AS_HELP_STRING([--with-readline], 18205 [enable experimental support for readline])], 18206 [], 18207 [with_readline=no]) 18208 18209 LIBREADLINE= 18210 AS_IF([test "x$with_readline" != xno], 18211 [AC_CHECK_LIB([readline], [main], 18212 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"]) 18213 AC_DEFINE([HAVE_LIBREADLINE], [1], 18214 [Define if you have libreadline]) 18215 ], 18216 [AC_MSG_FAILURE( 18217 [--with-readline was given, but test for readline failed])], 18218 [-lncurses])]) 18219 18220 The last example shows how to use `AC_ARG_WITH' to give the user 18221 the possibility to disable support for the readline library, given 18222 that it is an important feature and that it should be enabled by 18223 default. 18224 18225 AC_ARG_WITH([readline], 18226 [AS_HELP_STRING([--without-readline], 18227 [disable support for readline])], 18228 [], 18229 [with_readline=yes]) 18230 18231 LIBREADLINE= 18232 AS_IF([test "x$with_readline" != xno], 18233 [AC_CHECK_LIB([readline], [main], 18234 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"]) 18235 AC_DEFINE([HAVE_LIBREADLINE], [1], 18236 [Define if you have libreadline]) 18237 ], 18238 [AC_MSG_FAILURE( 18239 [readline test failed (--without-readline to disable)])], 18240 [-lncurses])]) 18241 18242 These three examples can be easily adapted to the case where 18243 `AC_ARG_ENABLE' should be preferred to `AC_ARG_WITH' (see *note 18244 Package Options::). 18245 18246 18247File: autoconf.info, Node: Package Options, Next: Pretty Help Strings, Prev: External Software, Up: Site Configuration 18248 1824915.3 Choosing Package Options 18250============================= 18251 18252If a software package has optional compile-time features, the user can 18253give `configure' command line options to specify whether to compile 18254them. The options have one of these forms: 18255 18256 --enable-FEATURE[=ARG] 18257 --disable-FEATURE 18258 18259 These options allow users to choose which optional features to build 18260and install. `--enable-FEATURE' options should never make a feature 18261behave differently or cause one feature to replace another. They 18262should only cause parts of the program to be built rather than left out. 18263 18264 The user can give an argument by following the feature name with `=' 18265and the argument. Giving an argument of `no' requests that the feature 18266_not_ be made available. A feature with an argument looks like 18267`--enable-debug=stabs'. If no argument is given, it defaults to `yes'. 18268`--disable-FEATURE' is equivalent to `--enable-FEATURE=no'. 18269 18270 Normally `configure' scripts complain about `--enable-PACKAGE' 18271options that they do not support. *Note Option Checking::, for 18272details, and for how to override the defaults. 18273 18274 For each optional feature, `configure.ac' should call 18275`AC_ARG_ENABLE' to detect whether the `configure' user asked to include 18276it. Whether each feature is included or not by default, and which 18277arguments are valid, is up to you. 18278 18279 -- Macro: AC_ARG_ENABLE (FEATURE, HELP-STRING, [ACTION-IF-GIVEN], 18280 [ACTION-IF-NOT-GIVEN]) 18281 If the user gave `configure' the option `--enable-FEATURE' or 18282 `--disable-FEATURE', run shell commands ACTION-IF-GIVEN. If 18283 neither option was given, run shell commands ACTION-IF-NOT-GIVEN. 18284 The name FEATURE indicates an optional user-level facility. It 18285 should consist only of alphanumeric characters, dashes, plus 18286 signs, and dots. 18287 18288 The option's argument is available to the shell commands 18289 ACTION-IF-GIVEN in the shell variable `enableval', which is 18290 actually just the value of the shell variable named 18291 `enable_FEATURE', with any non-alphanumeric characters in FEATURE 18292 changed into `_'. You may use that variable instead, if you wish. 18293 The HELP-STRING argument is like that of `AC_ARG_WITH' (*note 18294 External Software::). 18295 18296 You should format your HELP-STRING with the macro `AS_HELP_STRING' 18297 (*note Pretty Help Strings::). 18298 18299 See the examples suggested with the definition of `AC_ARG_WITH' 18300 (*note External Software::) to get an idea of possible 18301 applications of `AC_ARG_ENABLE'. 18302 18303 18304File: autoconf.info, Node: Pretty Help Strings, Next: Option Checking, Prev: Package Options, Up: Site Configuration 18305 1830615.4 Making Your Help Strings Look Pretty 18307========================================= 18308 18309Properly formatting the `help strings' which are used in `AC_ARG_WITH' 18310(*note External Software::) and `AC_ARG_ENABLE' (*note Package 18311Options::) can be challenging. Specifically, you want your own `help 18312strings' to line up in the appropriate columns of `configure --help' 18313just like the standard Autoconf `help strings' do. This is the purpose 18314of the `AS_HELP_STRING' macro. 18315 18316 -- Macro: AS_HELP_STRING (LEFT-HAND-SIDE, RIGHT-HAND-SIDE 18317 [INDENT-COLUMN = `26'], [WRAP-COLUMN = `79']) 18318 Expands into a help string that looks pretty when the user executes 18319 `configure --help'. It is typically used in `AC_ARG_WITH' (*note 18320 External Software::) or `AC_ARG_ENABLE' (*note Package Options::). 18321 The following example makes this clearer. 18322 18323 AC_ARG_WITH([foo], 18324 [AS_HELP_STRING([--with-foo], 18325 [use foo (default is no)])], 18326 [use_foo=$withval], 18327 [use_foo=no]) 18328 18329 Then the last few lines of `configure --help' appear like this: 18330 18331 --enable and --with options recognized: 18332 --with-foo use foo (default is no) 18333 18334 Macro expansion is performed on the first argument. However, the 18335 second argument of `AS_HELP_STRING' is treated as a whitespace 18336 separated list of text to be reformatted, and is not subject to 18337 macro expansion. Since it is not expanded, it should not be 18338 double quoted. *Note Autoconf Language::, for a more detailed 18339 explanation. 18340 18341 The `AS_HELP_STRING' macro is particularly helpful when the 18342 LEFT-HAND-SIDE and/or RIGHT-HAND-SIDE are composed of macro 18343 arguments, as shown in the following example. Be aware that 18344 LEFT-HAND-SIDE may not expand to unbalanced quotes, although 18345 quadrigraphs can be used. 18346 18347 AC_DEFUN([MY_ARG_WITH], 18348 [AC_ARG_WITH(m4_translit([[$1]], [_], [-]), 18349 [AS_HELP_STRING([--with-m4_translit([$1], [_], [-])], 18350 [use $1 (default is $2)])], 18351 [use_[]$1=$withval], 18352 [use_[]$1=$2])]) 18353 MY_ARG_WITH([a_b], [no]) 18354 Here, the last few lines of `configure --help' will include: 18355 18356 --enable and --with options recognized: 18357 --with-a-b use a_b (default is no) 18358 18359 The parameters INDENT-COLUMN and WRAP-COLUMN were introduced in 18360 Autoconf 2.62. Generally, they should not be specified; they exist 18361 for fine-tuning of the wrapping. 18362 AS_HELP_STRING([--option], [description of option]) 18363 => --option description of option 18364 AS_HELP_STRING([--option], [description of option], [15], [30]) 18365 => --option description of 18366 => option 18367 18368 18369File: autoconf.info, Node: Option Checking, Next: Site Details, Prev: Pretty Help Strings, Up: Site Configuration 18370 1837115.5 Controlling Checking of `configure' Options 18372================================================ 18373 18374The `configure' script checks its command-line options against a list 18375of known options, like `--help' or `--config-cache'. An unknown option 18376ordinarily indicates a mistake by the user and `configure' halts with 18377an error. However, by default unknown `--with-PACKAGE' and 18378`--enable-FEATURE' options elicit only a warning, to support 18379configuring entire source trees. 18380 18381 Source trees often contain multiple packages with a top-level 18382`configure' script that uses the `AC_CONFIG_SUBDIRS' macro (*note 18383Subdirectories::). Because the packages generally support different 18384`--with-PACKAGE' and `--enable-FEATURE' options, the GNU Coding 18385Standards say they must accept unrecognized options without halting. 18386Even a warning message is undesirable here, so `AC_CONFIG_SUBDIRS' 18387automatically disables the warnings. 18388 18389 This default behavior may be modified in two ways. First, the 18390installer can invoke `configure --disable-option-checking' to disable 18391these warnings, or invoke `configure --enable-option-checking=fatal' 18392options to turn them into fatal errors, respectively. Second, the 18393maintainer can use `AC_DISABLE_OPTION_CHECKING'. 18394 18395 -- Macro: AC_DISABLE_OPTION_CHECKING 18396 By default, disable warnings related to any unrecognized 18397 `--with-PACKAGE' or `--enable-FEATURE' options. This is implied 18398 by `AC_CONFIG_SUBDIRS'. 18399 18400 The installer can override this behavior by passing 18401 `--enable-option-checking' (enable warnings) or 18402 `--enable-option-checking=fatal' (enable errors) to `configure'. 18403 18404 18405File: autoconf.info, Node: Site Details, Next: Transforming Names, Prev: Option Checking, Up: Site Configuration 18406 1840715.6 Configuring Site Details 18408============================= 18409 18410Some software packages require complex site-specific information. Some 18411examples are host names to use for certain services, company names, and 18412email addresses to contact. Since some configuration scripts generated 18413by Metaconfig ask for such information interactively, people sometimes 18414wonder how to get that information in Autoconf-generated configuration 18415scripts, which aren't interactive. 18416 18417 Such site configuration information should be put in a file that is 18418edited _only by users_, not by programs. The location of the file can 18419either be based on the `prefix' variable, or be a standard location 18420such as the user's home directory. It could even be specified by an 18421environment variable. The programs should examine that file at 18422runtime, rather than at compile time. Runtime configuration is more 18423convenient for users and makes the configuration process simpler than 18424getting the information while configuring. *Note Variables for 18425Installation Directories: (standards)Directory Variables, for more 18426information on where to put data files. 18427 18428 18429File: autoconf.info, Node: Transforming Names, Next: Site Defaults, Prev: Site Details, Up: Site Configuration 18430 1843115.7 Transforming Program Names When Installing 18432=============================================== 18433 18434Autoconf supports changing the names of programs when installing them. 18435In order to use these transformations, `configure.ac' must call the 18436macro `AC_ARG_PROGRAM'. 18437 18438 -- Macro: AC_ARG_PROGRAM 18439 Place in output variable `program_transform_name' a sequence of 18440 `sed' commands for changing the names of installed programs. 18441 18442 If any of the options described below are given to `configure', 18443 program names are transformed accordingly. Otherwise, if 18444 `AC_CANONICAL_TARGET' has been called and a `--target' value is 18445 given, the target type followed by a dash is used as a prefix. 18446 Otherwise, no program name transformation is done. 18447 18448* Menu: 18449 18450* Transformation Options:: `configure' options to transform names 18451* Transformation Examples:: Sample uses of transforming names 18452* Transformation Rules:: Makefile uses of transforming names 18453 18454 18455File: autoconf.info, Node: Transformation Options, Next: Transformation Examples, Up: Transforming Names 18456 1845715.7.1 Transformation Options 18458----------------------------- 18459 18460You can specify name transformations by giving `configure' these 18461command line options: 18462 18463`--program-prefix=PREFIX' 18464 prepend PREFIX to the names; 18465 18466`--program-suffix=SUFFIX' 18467 append SUFFIX to the names; 18468 18469`--program-transform-name=EXPRESSION' 18470 perform `sed' substitution EXPRESSION on the names. 18471 18472 18473File: autoconf.info, Node: Transformation Examples, Next: Transformation Rules, Prev: Transformation Options, Up: Transforming Names 18474 1847515.7.2 Transformation Examples 18476------------------------------ 18477 18478These transformations are useful with programs that can be part of a 18479cross-compilation development environment. For example, a 18480cross-assembler running on a Sun 4 configured with 18481`--target=i960-vxworks' is normally installed as `i960-vxworks-as', 18482rather than `as', which could be confused with a native Sun 4 assembler. 18483 18484 You can force a program name to begin with `g', if you don't want 18485GNU programs installed on your system to shadow other programs with the 18486same name. For example, if you configure GNU `diff' with 18487`--program-prefix=g', then when you run `make install' it is installed 18488as `/usr/local/bin/gdiff'. 18489 18490 As a more sophisticated example, you could use 18491 18492 --program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/' 18493 to prepend `g' to most of the program names in a source tree, 18494excepting those like `gdb' that already have one and those like `less' 18495and `lesskey' that aren't GNU programs. (That is assuming that you 18496have a source tree containing those programs that is set up to use this 18497feature.) 18498 18499 One way to install multiple versions of some programs simultaneously 18500is to append a version number to the name of one or both. For example, 18501if you want to keep Autoconf version 1 around for awhile, you can 18502configure Autoconf version 2 using `--program-suffix=2' to install the 18503programs as `/usr/local/bin/autoconf2', `/usr/local/bin/autoheader2', 18504etc. Nevertheless, pay attention that only the binaries are renamed, 18505therefore you'd have problems with the library files which might 18506overlap. 18507 18508 18509File: autoconf.info, Node: Transformation Rules, Prev: Transformation Examples, Up: Transforming Names 18510 1851115.7.3 Transformation Rules 18512--------------------------- 18513 18514Here is how to use the variable `program_transform_name' in a 18515`Makefile.in': 18516 18517 PROGRAMS = cp ls rm 18518 transform = @program_transform_name@ 18519 install: 18520 for p in $(PROGRAMS); do \ 18521 $(INSTALL_PROGRAM) $$p $(DESTDIR)$(bindir)/`echo $$p | \ 18522 sed '$(transform)'`; \ 18523 done 18524 18525 uninstall: 18526 for p in $(PROGRAMS); do \ 18527 rm -f $(DESTDIR)$(bindir)/`echo $$p | sed '$(transform)'`; \ 18528 done 18529 18530 It is guaranteed that `program_transform_name' is never empty, and 18531that there are no useless separators. Therefore you may safely embed 18532`program_transform_name' within a sed program using `;': 18533 18534 transform = @program_transform_name@ 18535 transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/ 18536 18537 Whether to do the transformations on documentation files (Texinfo or 18538`man') is a tricky question; there seems to be no perfect answer, due 18539to the several reasons for name transforming. Documentation is not 18540usually particular to a specific architecture, and Texinfo files do not 18541conflict with system documentation. But they might conflict with 18542earlier versions of the same files, and `man' pages sometimes do 18543conflict with system documentation. As a compromise, it is probably 18544best to do name transformations on `man' pages but not on Texinfo 18545manuals. 18546 18547 18548File: autoconf.info, Node: Site Defaults, Prev: Transforming Names, Up: Site Configuration 18549 1855015.8 Setting Site Defaults 18551========================== 18552 18553Autoconf-generated `configure' scripts allow your site to provide 18554default values for some configuration values. You do this by creating 18555site- and system-wide initialization files. 18556 18557 If the environment variable `CONFIG_SITE' is set, `configure' uses 18558its value as the name of a shell script to read; it is recommended that 18559this be an absolute file name. Otherwise, it reads the shell script 18560`PREFIX/share/config.site' if it exists, then `PREFIX/etc/config.site' 18561if it exists. Thus, settings in machine-specific files override those 18562in machine-independent ones in case of conflict. 18563 18564 Site files can be arbitrary shell scripts, but only certain kinds of 18565code are really appropriate to be in them. Because `configure' reads 18566any cache file after it has read any site files, a site file can define 18567a default cache file to be shared between all Autoconf-generated 18568`configure' scripts run on that system (*note Cache Files::). If you 18569set a default cache file in a site file, it is a good idea to also set 18570the output variable `CC' in that site file, because the cache file is 18571only valid for a particular compiler, but many systems have several 18572available. 18573 18574 You can examine or override the value set by a command line option to 18575`configure' in a site file; options set shell variables that have the 18576same names as the options, with any dashes turned into underscores. 18577The exceptions are that `--without-' and `--disable-' options are like 18578giving the corresponding `--with-' or `--enable-' option and the value 18579`no'. Thus, `--cache-file=localcache' sets the variable `cache_file' 18580to the value `localcache'; `--enable-warnings=no' or 18581`--disable-warnings' sets the variable `enable_warnings' to the value 18582`no'; `--prefix=/usr' sets the variable `prefix' to the value `/usr'; 18583etc. 18584 18585 Site files are also good places to set default values for other 18586output variables, such as `CFLAGS', if you need to give them non-default 18587values: anything you would normally do, repetitively, on the command 18588line. If you use non-default values for PREFIX or EXEC_PREFIX 18589(wherever you locate the site file), you can set them in the site file 18590if you specify it with the `CONFIG_SITE' environment variable. 18591 18592 You can set some cache values in the site file itself. Doing this is 18593useful if you are cross-compiling, where it is impossible to check 18594features that require running a test program. You could "prime the 18595cache" by setting those values correctly for that system in 18596`PREFIX/etc/config.site'. To find out the names of the cache variables 18597you need to set, see the documentation of the respective Autoconf 18598macro. If the variables or their semantics are undocumented, you may 18599need to look for shell variables with `_cv_' in their names in the 18600affected `configure' scripts, or in the Autoconf M4 source code for 18601those macros; but in that case, their name or semantics may change in a 18602future Autoconf version. 18603 18604 The cache file is careful to not override any variables set in the 18605site files. Similarly, you should not override command-line options in 18606the site files. Your code should check that variables such as `prefix' 18607and `cache_file' have their default values (as set near the top of 18608`configure') before changing them. 18609 18610 Here is a sample file `/usr/share/local/gnu/share/config.site'. The 18611command `configure --prefix=/usr/share/local/gnu' would read this file 18612(if `CONFIG_SITE' is not set to a different file). 18613 18614 # /usr/share/local/gnu/share/config.site for configure 18615 # 18616 # Change some defaults. 18617 test "$prefix" = NONE && prefix=/usr/share/local/gnu 18618 test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu 18619 test "$sharedstatedir" = '${prefix}/com' && sharedstatedir=/var 18620 test "$localstatedir" = '${prefix}/var' && localstatedir=/var 18621 18622 # Give Autoconf 2.x generated configure scripts a shared default 18623 # cache file for feature test results, architecture-specific. 18624 if test "$cache_file" = /dev/null; then 18625 cache_file="$prefix/var/config.cache" 18626 # A cache file is only valid for one C compiler. 18627 CC=gcc 18628 fi 18629 18630 Another use of `config.site' is for priming the directory variables 18631in a manner consistent with the Filesystem Hierarchy Standard (FHS). 18632Once the following file is installed at `/usr/share/config.site', a 18633user can execute simply `./configure --prefix=/usr' to get all the 18634directories chosen in the locations recommended by FHS. 18635 18636 # /usr/share/config.site for FHS defaults when installing below /usr, 18637 # and the respective settings were not changed on the command line. 18638 if test "$prefix" = /usr; then 18639 test "$sysconfdir" = '${prefix}/etc' && sysconfdir=/etc 18640 test "$sharedstatedir" = '${prefix}/com' && sharedstatedir=/var 18641 test "$localstatedir" = '${prefix}/var' && localstatedir=/var 18642 fi 18643 18644 Likewise, on platforms where 64-bit libraries are built by default, 18645then installed in `/usr/local/lib64' instead of `/usr/local/lib', it is 18646appropriate to install `/usr/local/share/config.site': 18647 18648 # /usr/local/share/config.site for platforms that prefer 18649 # the directory /usr/local/lib64 over /usr/local/lib. 18650 test "$libdir" = '${exec_prefix}/lib' && libdir='${exec_prefix}/lib64' 18651 18652 18653File: autoconf.info, Node: Running configure Scripts, Next: config.status Invocation, Prev: Site Configuration, Up: Top 18654 1865516 Running `configure' Scripts 18656****************************** 18657 18658Below are instructions on how to configure a package that uses a 18659`configure' script, suitable for inclusion as an `INSTALL' file in the 18660package. A plain-text version of `INSTALL' which you may use comes 18661with Autoconf. 18662 18663* Menu: 18664 18665* Basic Installation:: Instructions for typical cases 18666* Compilers and Options:: Selecting compilers and optimization 18667* Multiple Architectures:: Compiling for multiple architectures at once 18668* Installation Names:: Installing in different directories 18669* Optional Features:: Selecting optional features 18670* Particular Systems:: Particular systems 18671* System Type:: Specifying the system type 18672* Sharing Defaults:: Setting site-wide defaults for `configure' 18673* Defining Variables:: Specifying the compiler etc. 18674* configure Invocation:: Changing how `configure' runs 18675 18676 18677File: autoconf.info, Node: Basic Installation, Next: Compilers and Options, Up: Running configure Scripts 18678 1867916.1 Basic Installation 18680======================= 18681 18682Briefly, the shell commands `./configure; make; make install' should 18683configure, build, and install this package. The following 18684more-detailed instructions are generic; see the `README' file for 18685instructions specific to this package. More recommendations for GNU 18686packages can be found in *note Makefile Conventions: 18687(standards)Makefile Conventions. 18688 18689 The `configure' shell script attempts to guess correct values for 18690various system-dependent variables used during compilation. It uses 18691those values to create a `Makefile' in each directory of the package. 18692It may also create one or more `.h' files containing system-dependent 18693definitions. Finally, it creates a shell script `config.status' that 18694you can run in the future to recreate the current configuration, and a 18695file `config.log' containing compiler output (useful mainly for 18696debugging `configure'). 18697 18698 It can also use an optional file (typically called `config.cache' 18699and enabled with `--cache-file=config.cache' or simply `-C') that saves 18700the results of its tests to speed up reconfiguring. Caching is 18701disabled by default to prevent problems with accidental use of stale 18702cache files. 18703 18704 If you need to do unusual things to compile the package, please try 18705to figure out how `configure' could check whether to do them, and mail 18706diffs or instructions to the address given in the `README' so they can 18707be considered for the next release. If you are using the cache, and at 18708some point `config.cache' contains results you don't want to keep, you 18709may remove or edit it. 18710 18711 The file `configure.ac' (or `configure.in') is used to create 18712`configure' by a program called `autoconf'. You need `configure.ac' if 18713you want to change it or regenerate `configure' using a newer version 18714of `autoconf'. 18715 18716 The simplest way to compile this package is: 18717 18718 1. `cd' to the directory containing the package's source code and type 18719 `./configure' to configure the package for your system. 18720 18721 Running `configure' might take a while. While running, it prints 18722 some messages telling which features it is checking for. 18723 18724 2. Type `make' to compile the package. 18725 18726 3. Optionally, type `make check' to run any self-tests that come with 18727 the package, generally using the just-built uninstalled binaries. 18728 18729 4. Type `make install' to install the programs and any data files and 18730 documentation. When installing into a prefix owned by root, it is 18731 recommended that the package be configured and built as a regular 18732 user, and only the `make install' phase executed with root 18733 privileges. 18734 18735 5. Optionally, type `make installcheck' to repeat any self-tests, but 18736 this time using the binaries in their final installed location. 18737 This target does not install anything. Running this target as a 18738 regular user, particularly if the prior `make install' required 18739 root privileges, verifies that the installation completed 18740 correctly. 18741 18742 6. You can remove the program binaries and object files from the 18743 source code directory by typing `make clean'. To also remove the 18744 files that `configure' created (so you can compile the package for 18745 a different kind of computer), type `make distclean'. There is 18746 also a `make maintainer-clean' target, but that is intended mainly 18747 for the package's developers. If you use it, you may have to get 18748 all sorts of other programs in order to regenerate files that came 18749 with the distribution. 18750 18751 7. Often, you can also type `make uninstall' to remove the installed 18752 files again. In practice, not all packages have tested that 18753 uninstallation works correctly, even though it is required by the 18754 GNU Coding Standards. 18755 18756 8. Some packages, particularly those that use Automake, provide `make 18757 distcheck', which can by used by developers to test that all other 18758 targets like `make install' and `make uninstall' work correctly. 18759 This target is generally not run by end users. 18760 18761 18762File: autoconf.info, Node: Compilers and Options, Next: Multiple Architectures, Prev: Basic Installation, Up: Running configure Scripts 18763 1876416.2 Compilers and Options 18765========================== 18766 18767Some systems require unusual options for compilation or linking that the 18768`configure' script does not know about. Run `./configure --help' for 18769details on some of the pertinent environment variables. 18770 18771 You can give `configure' initial values for configuration parameters 18772by setting variables in the command line or in the environment. Here 18773is an example: 18774 18775 ./configure CC=c99 CFLAGS=-g LIBS=-lposix 18776 18777 *Note Defining Variables::, for more details. 18778 18779 18780File: autoconf.info, Node: Multiple Architectures, Next: Installation Names, Prev: Compilers and Options, Up: Running configure Scripts 18781 1878216.3 Compiling For Multiple Architectures 18783========================================= 18784 18785You can compile the package for more than one kind of computer at the 18786same time, by placing the object files for each architecture in their 18787own directory. To do this, you can use GNU `make'. `cd' to the 18788directory where you want the object files and executables to go and run 18789the `configure' script. `configure' automatically checks for the 18790source code in the directory that `configure' is in and in `..'. This 18791is known as a "VPATH" build. 18792 18793 With a non-GNU `make', it is safer to compile the package for one 18794architecture at a time in the source code directory. After you have 18795installed the package for one architecture, use `make distclean' before 18796reconfiguring for another architecture. 18797 18798 On MacOS X 10.5 and later systems, you can create libraries and 18799executables that work on multiple system types--known as "fat" or 18800"universal" binaries--by specifying multiple `-arch' options to the 18801compiler but only a single `-arch' option to the preprocessor. Like 18802this: 18803 18804 ./configure CC="gcc -arch i386 -arch x86_64 -arch ppc -arch ppc64" \ 18805 CXX="g++ -arch i386 -arch x86_64 -arch ppc -arch ppc64" \ 18806 CPP="gcc -E" CXXCPP="g++ -E" 18807 18808 This is not guaranteed to produce working output in all cases, you 18809may have to build one architecture at a time and combine the results 18810using the `lipo' tool if you have problems. 18811 18812 18813File: autoconf.info, Node: Installation Names, Next: Optional Features, Prev: Multiple Architectures, Up: Running configure Scripts 18814 1881516.4 Installation Names 18816======================= 18817 18818By default, `make install' installs the package's commands under 18819`/usr/local/bin', include files under `/usr/local/include', etc. You 18820can specify an installation prefix other than `/usr/local' by giving 18821`configure' the option `--prefix=PREFIX', where PREFIX must be an 18822absolute file name. 18823 18824 You can specify separate installation prefixes for 18825architecture-specific files and architecture-independent files. If you 18826pass the option `--exec-prefix=PREFIX' to `configure', the package uses 18827PREFIX as the prefix for installing programs and libraries. 18828Documentation and other data files still use the regular prefix. 18829 18830 In addition, if you use an unusual directory layout you can give 18831options like `--bindir=DIR' to specify different values for particular 18832kinds of files. Run `configure --help' for a list of the directories 18833you can set and what kinds of files go in them. In general, the 18834default for these options is expressed in terms of `${prefix}', so that 18835specifying just `--prefix' will affect all of the other directory 18836specifications that were not explicitly provided. 18837 18838 The most portable way to affect installation locations is to pass the 18839correct locations to `configure'; however, many packages provide one or 18840both of the following shortcuts of passing variable assignments to the 18841`make install' command line to change installation locations without 18842having to reconfigure or recompile. 18843 18844 The first method involves providing an override variable for each 18845affected directory. For example, `make install 18846prefix=/alternate/directory' will choose an alternate location for all 18847directory configuration variables that were expressed in terms of 18848`${prefix}'. Any directories that were specified during `configure', 18849but not in terms of `${prefix}', must each be overridden at install 18850time for the entire installation to be relocated. The approach of 18851makefile variable overrides for each directory variable is required by 18852the GNU Coding Standards, and ideally causes no recompilation. 18853However, some platforms have known limitations with the semantics of 18854shared libraries that end up requiring recompilation when using this 18855method, particularly noticeable in packages that use GNU Libtool. 18856 18857 The second method involves providing the `DESTDIR' variable. For 18858example, `make install DESTDIR=/alternate/directory' will prepend 18859`/alternate/directory' before all installation names. The approach of 18860`DESTDIR' overrides is not required by the GNU Coding Standards, and 18861does not work on platforms that have drive letters. On the other hand, 18862it does better at avoiding recompilation issues, and works well even 18863when some directory options were not specified in terms of `${prefix}' 18864at `configure' time. 18865 18866 18867File: autoconf.info, Node: Optional Features, Next: Particular Systems, Prev: Installation Names, Up: Running configure Scripts 18868 1886916.5 Optional Features 18870====================== 18871 18872If the package supports it, you can cause programs to be installed with 18873an extra prefix or suffix on their names by giving `configure' the 18874option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'. 18875 18876 Some packages pay attention to `--enable-FEATURE' options to 18877`configure', where FEATURE indicates an optional part of the package. 18878They may also pay attention to `--with-PACKAGE' options, where PACKAGE 18879is something like `gnu-as' or `x' (for the X Window System). The 18880`README' should mention any `--enable-' and `--with-' options that the 18881package recognizes. 18882 18883 For packages that use the X Window System, `configure' can usually 18884find the X include and library files automatically, but if it doesn't, 18885you can use the `configure' options `--x-includes=DIR' and 18886`--x-libraries=DIR' to specify their locations. 18887 18888 Some packages offer the ability to configure how verbose the 18889execution of `make' will be. For these packages, running `./configure 18890--enable-silent-rules' sets the default to minimal output, which can be 18891overridden with `make V=1'; while running `./configure 18892--disable-silent-rules' sets the default to verbose, which can be 18893overridden with `make V=0'. 18894 18895 18896File: autoconf.info, Node: Particular Systems, Next: System Type, Prev: Optional Features, Up: Running configure Scripts 18897 1889816.6 Particular systems 18899======================= 18900 18901On HP-UX, the default C compiler is not ANSI C compatible. If GNU CC is 18902not installed, it is recommended to use the following options in order 18903to use an ANSI C compiler: 18904 18905 ./configure CC="cc -Ae -D_XOPEN_SOURCE=500" 18906 18907and if that doesn't work, install pre-built binaries of GCC for HP-UX. 18908 18909 HP-UX `make' updates targets which have the same time stamps as 18910their prerequisites, which makes it generally unusable when shipped 18911generated files such as `configure' are involved. Use GNU `make' 18912instead. 18913 18914 On OSF/1 a.k.a. Tru64, some versions of the default C compiler cannot 18915parse its `<wchar.h>' header file. The option `-nodtk' can be used as 18916a workaround. If GNU CC is not installed, it is therefore recommended 18917to try 18918 18919 ./configure CC="cc" 18920 18921and if that doesn't work, try 18922 18923 ./configure CC="cc -nodtk" 18924 18925 On Solaris, don't put `/usr/ucb' early in your `PATH'. This 18926directory contains several dysfunctional programs; working variants of 18927these programs are available in `/usr/bin'. So, if you need `/usr/ucb' 18928in your `PATH', put it _after_ `/usr/bin'. 18929 18930 On Haiku, software installed for all users goes in `/boot/common', 18931not `/usr/local'. It is recommended to use the following options: 18932 18933 ./configure --prefix=/boot/common 18934 18935 18936File: autoconf.info, Node: System Type, Next: Sharing Defaults, Prev: Particular Systems, Up: Running configure Scripts 18937 1893816.7 Specifying the System Type 18939=============================== 18940 18941There may be some features `configure' cannot figure out automatically, 18942but needs to determine by the type of machine the package will run on. 18943Usually, assuming the package is built to be run on the _same_ 18944architectures, `configure' can figure that out, but if it prints a 18945message saying it cannot guess the machine type, give it the 18946`--build=TYPE' option. TYPE can either be a short name for the system 18947type, such as `sun4', or a canonical name which has the form: 18948 18949 CPU-COMPANY-SYSTEM 18950 18951where SYSTEM can have one of these forms: 18952 18953 OS 18954 KERNEL-OS 18955 18956 See the file `config.sub' for the possible values of each field. If 18957`config.sub' isn't included in this package, then this package doesn't 18958need to know the machine type. 18959 18960 If you are _building_ compiler tools for cross-compiling, you should 18961use the option `--target=TYPE' to select the type of system they will 18962produce code for. 18963 18964 If you want to _use_ a cross compiler, that generates code for a 18965platform different from the build platform, you should specify the 18966"host" platform (i.e., that on which the generated programs will 18967eventually be run) with `--host=TYPE'. 18968 18969 18970File: autoconf.info, Node: Sharing Defaults, Next: Defining Variables, Prev: System Type, Up: Running configure Scripts 18971 1897216.8 Sharing Defaults 18973===================== 18974 18975If you want to set default values for `configure' scripts to share, you 18976can create a site shell script called `config.site' that gives default 18977values for variables like `CC', `cache_file', and `prefix'. 18978`configure' looks for `PREFIX/share/config.site' if it exists, then 18979`PREFIX/etc/config.site' if it exists. Or, you can set the 18980`CONFIG_SITE' environment variable to the location of the site script. 18981A warning: not all `configure' scripts look for a site script. 18982 18983 18984File: autoconf.info, Node: Defining Variables, Next: configure Invocation, Prev: Sharing Defaults, Up: Running configure Scripts 18985 1898616.9 Defining Variables 18987======================= 18988 18989Variables not defined in a site shell script can be set in the 18990environment passed to `configure'. However, some packages may run 18991configure again during the build, and the customized values of these 18992variables may be lost. In order to avoid this problem, you should set 18993them in the `configure' command line, using `VAR=value'. For example: 18994 18995 ./configure CC=/usr/local2/bin/gcc 18996 18997causes the specified `gcc' to be used as the C compiler (unless it is 18998overridden in the site shell script). 18999 19000Unfortunately, this technique does not work for `CONFIG_SHELL' due to 19001an Autoconf limitation. Until the limitation is lifted, you can use 19002this workaround: 19003 19004 CONFIG_SHELL=/bin/bash ./configure CONFIG_SHELL=/bin/bash 19005 19006 19007File: autoconf.info, Node: configure Invocation, Prev: Defining Variables, Up: Running configure Scripts 19008 1900916.10 `configure' Invocation 19010============================ 19011 19012`configure' recognizes the following options to control how it operates. 19013 19014`--help' 19015`-h' 19016 Print a summary of all of the options to `configure', and exit. 19017 19018`--help=short' 19019`--help=recursive' 19020 Print a summary of the options unique to this package's 19021 `configure', and exit. The `short' variant lists options used 19022 only in the top level, while the `recursive' variant lists options 19023 also present in any nested packages. 19024 19025`--version' 19026`-V' 19027 Print the version of Autoconf used to generate the `configure' 19028 script, and exit. 19029 19030`--cache-file=FILE' 19031 Enable the cache: use and save the results of the tests in FILE, 19032 traditionally `config.cache'. FILE defaults to `/dev/null' to 19033 disable caching. 19034 19035`--config-cache' 19036`-C' 19037 Alias for `--cache-file=config.cache'. 19038 19039`--quiet' 19040`--silent' 19041`-q' 19042 Do not print messages saying which checks are being made. To 19043 suppress all normal output, redirect it to `/dev/null' (any error 19044 messages will still be shown). 19045 19046`--srcdir=DIR' 19047 Look for the package's source code in directory DIR. Usually 19048 `configure' can determine that directory automatically. 19049 19050`--prefix=DIR' 19051 Use DIR as the installation prefix. *note Installation Names:: 19052 for more details, including other options available for fine-tuning 19053 the installation locations. 19054 19055`--no-create' 19056`-n' 19057 Run the configure checks, but stop before creating any output 19058 files. 19059 19060`configure' also accepts some other, not widely useful, options. Run 19061`configure --help' for more details. 19062 19063 19064File: autoconf.info, Node: config.status Invocation, Next: Obsolete Constructs, Prev: Running configure Scripts, Up: Top 19065 1906617 config.status Invocation 19067*************************** 19068 19069The `configure' script creates a file named `config.status', which 19070actually configures, "instantiates", the template files. It also 19071records the configuration options that were specified when the package 19072was last configured in case reconfiguring is needed. 19073 19074 Synopsis: 19075 ./config.status [OPTION]... [TAG]... 19076 19077 It configures each TAG; if none are specified, all the templates are 19078instantiated. A TAG refers to a file or other tag associated with a 19079configuration action, as specified by an `AC_CONFIG_ITEMS' macro (*note 19080Configuration Actions::). The files must be specified without their 19081dependencies, as in 19082 19083 ./config.status foobar 19084 19085not 19086 19087 ./config.status foobar:foo.in:bar.in 19088 19089 The supported options are: 19090 19091`--help' 19092`-h' 19093 Print a summary of the command line options, the list of the 19094 template files, and exit. 19095 19096`--version' 19097`-V' 19098 Print the version number of Autoconf and the configuration 19099 settings, and exit. 19100 19101`--config' 19102 Print the configuration settings in reusable way, quoted for the 19103 shell, and exit. For example, for a debugging build that 19104 otherwise reuses the configuration from a different build 19105 directory BUILD-DIR of a package in SRC-DIR, you could use the 19106 following: 19107 19108 args=`BUILD-DIR/config.status --config` 19109 eval SRC-DIR/configure "$args" CFLAGS=-g --srcdir=SRC-DIR 19110 19111 Note that it may be necessary to override a `--srcdir' setting 19112 that was saved in the configuration, if the arguments are used in a 19113 different build directory. 19114 19115`--silent' 19116`--quiet' 19117`-q' 19118 Do not print progress messages. 19119 19120`--debug' 19121`-d' 19122 Don't remove the temporary files. 19123 19124`--file=FILE[:TEMPLATE]' 19125 Require that FILE be instantiated as if 19126 `AC_CONFIG_FILES(FILE:TEMPLATE)' was used. Both FILE and TEMPLATE 19127 may be `-' in which case the standard output and/or standard 19128 input, respectively, is used. If a TEMPLATE file name is 19129 relative, it is first looked for in the build tree, and then in 19130 the source tree. *Note Configuration Actions::, for more details. 19131 19132 This option and the following ones provide one way for separately 19133 distributed packages to share the values computed by `configure'. 19134 Doing so can be useful if some of the packages need a superset of 19135 the features that one of them, perhaps a common library, does. 19136 These options allow a `config.status' file to create files other 19137 than the ones that its `configure.ac' specifies, so it can be used 19138 for a different package, or for extracting a subset of values. 19139 For example, 19140 19141 echo '@CC@' | ./config.status --file=- 19142 19143 provides the value of `@CC@' on standard output. 19144 19145`--header=FILE[:TEMPLATE]' 19146 Same as `--file' above, but with `AC_CONFIG_HEADERS'. 19147 19148`--recheck' 19149 Ask `config.status' to update itself and exit (no instantiation). 19150 This option is useful if you change `configure', so that the 19151 results of some tests might be different from the previous run. 19152 The `--recheck' option reruns `configure' with the same arguments 19153 you used before, plus the `--no-create' option, which prevents 19154 `configure' from running `config.status' and creating `Makefile' 19155 and other files, and the `--no-recursion' option, which prevents 19156 `configure' from running other `configure' scripts in 19157 subdirectories. (This is so other Make rules can run 19158 `config.status' when it changes; *note Automatic Remaking::, for 19159 an example). 19160 19161 `config.status' checks several optional environment variables that 19162can alter its behavior: 19163 19164 -- Variable: CONFIG_SHELL 19165 The shell with which to run `configure'. It must be 19166 Bourne-compatible, and the absolute name of the shell should be 19167 passed. The default is a shell that supports `LINENO' if 19168 available, and `/bin/sh' otherwise. 19169 19170 -- Variable: CONFIG_STATUS 19171 The file name to use for the shell script that records the 19172 configuration. The default is `./config.status'. This variable is 19173 useful when one package uses parts of another and the `configure' 19174 scripts shouldn't be merged because they are maintained separately. 19175 19176 You can use `./config.status' in your makefiles. For example, in 19177the dependencies given above (*note Automatic Remaking::), 19178`config.status' is run twice when `configure.ac' has changed. If that 19179bothers you, you can make each run only regenerate the files for that 19180rule: 19181 config.h: stamp-h 19182 stamp-h: config.h.in config.status 19183 ./config.status config.h 19184 echo > stamp-h 19185 19186 Makefile: Makefile.in config.status 19187 ./config.status Makefile 19188 19189 The calling convention of `config.status' has changed; see *note 19190Obsolete config.status Use::, for details. 19191 19192 19193File: autoconf.info, Node: Obsolete Constructs, Next: Using Autotest, Prev: config.status Invocation, Up: Top 19194 1919518 Obsolete Constructs 19196********************** 19197 19198Autoconf changes, and throughout the years some constructs have been 19199obsoleted. Most of the changes involve the macros, but in some cases 19200the tools themselves, or even some concepts, are now considered 19201obsolete. 19202 19203 You may completely skip this chapter if you are new to Autoconf. Its 19204intention is mainly to help maintainers updating their packages by 19205understanding how to move to more modern constructs. 19206 19207* Menu: 19208 19209* Obsolete config.status Use:: Obsolete convention for `config.status' 19210* acconfig Header:: Additional entries in `config.h.in' 19211* autoupdate Invocation:: Automatic update of `configure.ac' 19212* Obsolete Macros:: Backward compatibility macros 19213* Autoconf 1:: Tips for upgrading your files 19214* Autoconf 2.13:: Some fresher tips 19215 19216 19217File: autoconf.info, Node: Obsolete config.status Use, Next: acconfig Header, Up: Obsolete Constructs 19218 1921918.1 Obsolete `config.status' Invocation 19220======================================== 19221 19222`config.status' now supports arguments to specify the files to 19223instantiate; see *note config.status Invocation::, for more details. 19224Before, environment variables had to be used. 19225 19226 -- Variable: CONFIG_COMMANDS 19227 The tags of the commands to execute. The default is the arguments 19228 given to `AC_OUTPUT' and `AC_CONFIG_COMMANDS' in `configure.ac'. 19229 19230 -- Variable: CONFIG_FILES 19231 The files in which to perform `@VARIABLE@' substitutions. The 19232 default is the arguments given to `AC_OUTPUT' and 19233 `AC_CONFIG_FILES' in `configure.ac'. 19234 19235 -- Variable: CONFIG_HEADERS 19236 The files in which to substitute C `#define' statements. The 19237 default is the arguments given to `AC_CONFIG_HEADERS'; if that 19238 macro was not called, `config.status' ignores this variable. 19239 19240 -- Variable: CONFIG_LINKS 19241 The symbolic links to establish. The default is the arguments 19242 given to `AC_CONFIG_LINKS'; if that macro was not called, 19243 `config.status' ignores this variable. 19244 19245 In *note config.status Invocation::, using this old interface, the 19246example would be: 19247 19248 config.h: stamp-h 19249 stamp-h: config.h.in config.status 19250 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \ 19251 CONFIG_HEADERS=config.h ./config.status 19252 echo > stamp-h 19253 19254 Makefile: Makefile.in config.status 19255 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \ 19256 CONFIG_FILES=Makefile ./config.status 19257 19258(If `configure.ac' does not call `AC_CONFIG_HEADERS', there is no need 19259to set `CONFIG_HEADERS' in the `make' rules. Equally for 19260`CONFIG_COMMANDS', etc.) 19261 19262 19263File: autoconf.info, Node: acconfig Header, Next: autoupdate Invocation, Prev: Obsolete config.status Use, Up: Obsolete Constructs 19264 1926518.2 `acconfig.h' 19266================= 19267 19268In order to produce `config.h.in', `autoheader' needs to build or to 19269find templates for each symbol. Modern releases of Autoconf use 19270`AH_VERBATIM' and `AH_TEMPLATE' (*note Autoheader Macros::), but in 19271older releases a file, `acconfig.h', contained the list of needed 19272templates. `autoheader' copied comments and `#define' and `#undef' 19273statements from `acconfig.h' in the current directory, if present. 19274This file used to be mandatory if you `AC_DEFINE' any additional 19275symbols. 19276 19277 Modern releases of Autoconf also provide `AH_TOP' and `AH_BOTTOM' if 19278you need to prepend/append some information to `config.h.in'. Ancient 19279versions of Autoconf had a similar feature: if `./acconfig.h' contains 19280the string `@TOP@', `autoheader' copies the lines before the line 19281containing `@TOP@' into the top of the file that it generates. 19282Similarly, if `./acconfig.h' contains the string `@BOTTOM@', 19283`autoheader' copies the lines after that line to the end of the file it 19284generates. Either or both of those strings may be omitted. An even 19285older alternate way to produce the same effect in ancient versions of 19286Autoconf is to create the files `FILE.top' (typically `config.h.top') 19287and/or `FILE.bot' in the current directory. If they exist, 19288`autoheader' copies them to the beginning and end, respectively, of its 19289output. 19290 19291 In former versions of Autoconf, the files used in preparing a 19292software package for distribution were: 19293 configure.ac --. .------> autoconf* -----> configure 19294 +---+ 19295 [aclocal.m4] --+ `---. 19296 [acsite.m4] ---' | 19297 +--> [autoheader*] -> [config.h.in] 19298 [acconfig.h] ----. | 19299 +-----' 19300 [config.h.top] --+ 19301 [config.h.bot] --' 19302 19303 Using only the `AH_' macros, `configure.ac' should be 19304self-contained, and should not depend upon `acconfig.h' etc. 19305 19306 19307File: autoconf.info, Node: autoupdate Invocation, Next: Obsolete Macros, Prev: acconfig Header, Up: Obsolete Constructs 19308 1930918.3 Using `autoupdate' to Modernize `configure.ac' 19310=================================================== 19311 19312The `autoupdate' program updates a `configure.ac' file that calls 19313Autoconf macros by their old names to use the current macro names. In 19314version 2 of Autoconf, most of the macros were renamed to use a more 19315uniform and descriptive naming scheme. *Note Macro Names::, for a 19316description of the new scheme. Although the old names still work 19317(*note Obsolete Macros::, for a list of the old macros and the 19318corresponding new names), you can make your `configure.ac' files more 19319readable and make it easier to use the current Autoconf documentation 19320if you update them to use the new macro names. 19321 19322 If given no arguments, `autoupdate' updates `configure.ac', backing 19323up the original version with the suffix `~' (or the value of the 19324environment variable `SIMPLE_BACKUP_SUFFIX', if that is set). If you 19325give `autoupdate' an argument, it reads that file instead of 19326`configure.ac' and writes the updated file to the standard output. 19327 19328`autoupdate' accepts the following options: 19329 19330`--help' 19331`-h' 19332 Print a summary of the command line options and exit. 19333 19334`--version' 19335`-V' 19336 Print the version number of Autoconf and exit. 19337 19338`--verbose' 19339`-v' 19340 Report processing steps. 19341 19342`--debug' 19343`-d' 19344 Don't remove the temporary files. 19345 19346`--force' 19347`-f' 19348 Force the update even if the file has not changed. Disregard the 19349 cache. 19350 19351`--include=DIR' 19352`-I DIR' 19353 Also look for input files in DIR. Multiple invocations accumulate. 19354 Directories are browsed from last to first. 19355 19356`--prepend-include=DIR' 19357`-B DIR' 19358 Prepend directory DIR to the search path. This is used to include 19359 the language-specific files before any third-party macros. 19360 19361 19362File: autoconf.info, Node: Obsolete Macros, Next: Autoconf 1, Prev: autoupdate Invocation, Up: Obsolete Constructs 19363 1936418.4 Obsolete Macros 19365==================== 19366 19367Several macros are obsoleted in Autoconf, for various reasons (typically 19368they failed to quote properly, couldn't be extended for more recent 19369issues, etc.). They are still supported, but deprecated: their use 19370should be avoided. 19371 19372 During the jump from Autoconf version 1 to version 2, most of the 19373macros were renamed to use a more uniform and descriptive naming scheme, 19374but their signature did not change. *Note Macro Names::, for a 19375description of the new naming scheme. Below, if there is just the 19376mapping from old names to new names for these macros, the reader is 19377invited to refer to the definition of the new macro for the signature 19378and the description. 19379 19380 -- Macro: AC_AIX 19381 This macro is a platform-specific subset of 19382 `AC_USE_SYSTEM_EXTENSIONS' (*note AC_USE_SYSTEM_EXTENSIONS::). 19383 19384 -- Macro: AC_ALLOCA 19385 Replaced by `AC_FUNC_ALLOCA' (*note AC_FUNC_ALLOCA::). 19386 19387 -- Macro: AC_ARG_ARRAY 19388 Removed because of limited usefulness. 19389 19390 -- Macro: AC_C_CROSS 19391 This macro is obsolete; it does nothing. 19392 19393 -- Macro: AC_C_LONG_DOUBLE 19394 If the C compiler supports a working `long double' type with more 19395 range or precision than the `double' type, define 19396 `HAVE_LONG_DOUBLE'. 19397 19398 You should use `AC_TYPE_LONG_DOUBLE' or 19399 `AC_TYPE_LONG_DOUBLE_WIDER' instead. *Note Particular Types::. 19400 19401 -- Macro: AC_CANONICAL_SYSTEM 19402 Determine the system type and set output variables to the names of 19403 the canonical system types. *Note Canonicalizing::, for details 19404 about the variables this macro sets. 19405 19406 The user is encouraged to use either `AC_CANONICAL_BUILD', or 19407 `AC_CANONICAL_HOST', or `AC_CANONICAL_TARGET', depending on the 19408 needs. Using `AC_CANONICAL_TARGET' is enough to run the two other 19409 macros (*note Canonicalizing::). 19410 19411 -- Macro: AC_CHAR_UNSIGNED 19412 Replaced by `AC_C_CHAR_UNSIGNED' (*note AC_C_CHAR_UNSIGNED::). 19413 19414 -- Macro: AC_CHECK_TYPE (TYPE, DEFAULT) 19415 Autoconf, up to 2.13, used to provide this version of 19416 `AC_CHECK_TYPE', deprecated because of its flaws. First, although 19417 it is a member of the `CHECK' clan, it does more than just 19418 checking. Secondly, missing types are defined using `#define', 19419 not `typedef', and this can lead to problems in the case of 19420 pointer types. 19421 19422 This use of `AC_CHECK_TYPE' is obsolete and discouraged; see *note 19423 Generic Types::, for the description of the current macro. 19424 19425 If the type TYPE is not defined, define it to be the C (or C++) 19426 builtin type DEFAULT, e.g., `short int' or `unsigned int'. 19427 19428 This macro is equivalent to: 19429 19430 AC_CHECK_TYPE([TYPE], [], 19431 [AC_DEFINE_UNQUOTED([TYPE], [DEFAULT], 19432 [Define to `DEFAULT' 19433 if <sys/types.h> does not define.])]) 19434 19435 In order to keep backward compatibility, the two versions of 19436 `AC_CHECK_TYPE' are implemented, selected using these heuristics: 19437 19438 1. If there are three or four arguments, the modern version is 19439 used. 19440 19441 2. If the second argument appears to be a C or C++ type, then the 19442 obsolete version is used. This happens if the argument is a 19443 C or C++ _builtin_ type or a C identifier ending in `_t', 19444 optionally followed by one of `[(* ' and then by a string of 19445 zero or more characters taken from the set `[]()* _a-zA-Z0-9'. 19446 19447 3. If the second argument is spelled with the alphabet of valid 19448 C and C++ types, the user is warned and the modern version is 19449 used. 19450 19451 4. Otherwise, the modern version is used. 19452 19453 You are encouraged either to use a valid builtin type, or to use 19454 the equivalent modern code (see above), or better yet, to use 19455 `AC_CHECK_TYPES' together with 19456 19457 #ifndef HAVE_LOFF_T 19458 typedef loff_t off_t; 19459 #endif 19460 19461 -- Macro: AC_CHECKING (FEATURE-DESCRIPTION) 19462 Same as 19463 19464 AC_MSG_NOTICE([checking FEATURE-DESCRIPTION...] 19465 19466 *Note AC_MSG_NOTICE::. 19467 19468 -- Macro: AC_COMPILE_CHECK (ECHO-TEXT, INCLUDES, FUNCTION-BODY, 19469 ACTION-IF-TRUE, [ACTION-IF-FALSE]) 19470 This is an obsolete version of `AC_TRY_COMPILE' itself replaced by 19471 `AC_COMPILE_IFELSE' (*note Running the Compiler::), with the 19472 addition that it prints `checking for ECHO-TEXT' to the standard 19473 output first, if ECHO-TEXT is non-empty. Use `AC_MSG_CHECKING' 19474 and `AC_MSG_RESULT' instead to print messages (*note Printing 19475 Messages::). 19476 19477 -- Macro: AC_CONST 19478 Replaced by `AC_C_CONST' (*note AC_C_CONST::). 19479 19480 -- Macro: AC_CROSS_CHECK 19481 Same as `AC_C_CROSS', which is obsolete too, and does nothing 19482 `:-)'. 19483 19484 -- Macro: AC_CYGWIN 19485 Check for the Cygwin environment in which case the shell variable 19486 `CYGWIN' is set to `yes'. Don't use this macro, the dignified 19487 means to check the nature of the host is using `AC_CANONICAL_HOST' 19488 (*note Canonicalizing::). As a matter of fact this macro is 19489 defined as: 19490 19491 AC_REQUIRE([AC_CANONICAL_HOST])[]dnl 19492 case $host_os in 19493 *cygwin* ) CYGWIN=yes;; 19494 * ) CYGWIN=no;; 19495 esac 19496 19497 Beware that the variable `CYGWIN' has a special meaning when 19498 running Cygwin, and should not be changed. That's yet another 19499 reason not to use this macro. 19500 19501 -- Macro: AC_DECL_SYS_SIGLIST 19502 Same as: 19503 19504 AC_CHECK_DECLS([sys_siglist], [], [], 19505 [#include <signal.h> 19506 /* NetBSD declares sys_siglist in unistd.h. */ 19507 #ifdef HAVE_UNISTD_H 19508 # include <unistd.h> 19509 #endif 19510 ]) 19511 19512 *Note AC_CHECK_DECLS::. 19513 19514 -- Macro: AC_DECL_YYTEXT 19515 Does nothing, now integrated in `AC_PROG_LEX' (*note 19516 AC_PROG_LEX::). 19517 19518 -- Macro: AC_DIR_HEADER 19519 Like calling `AC_FUNC_CLOSEDIR_VOID' (*note 19520 AC_FUNC_CLOSEDIR_VOID::) and `AC_HEADER_DIRENT' (*note 19521 AC_HEADER_DIRENT::), but defines a different set of C preprocessor 19522 macros to indicate which header file is found: 19523 19524 Header Old Symbol New Symbol 19525 `dirent.h' `DIRENT' `HAVE_DIRENT_H' 19526 `sys/ndir.h' `SYSNDIR' `HAVE_SYS_NDIR_H' 19527 `sys/dir.h' `SYSDIR' `HAVE_SYS_DIR_H' 19528 `ndir.h' `NDIR' `HAVE_NDIR_H' 19529 19530 -- Macro: AC_DYNIX_SEQ 19531 If on DYNIX/ptx, add `-lseq' to output variable `LIBS'. This 19532 macro used to be defined as 19533 19534 AC_CHECK_LIB([seq], [getmntent], [LIBS="-lseq $LIBS"]) 19535 19536 now it is just `AC_FUNC_GETMNTENT' (*note AC_FUNC_GETMNTENT::). 19537 19538 -- Macro: AC_EXEEXT 19539 Defined the output variable `EXEEXT' based on the output of the 19540 compiler, which is now done automatically. Typically set to empty 19541 string if Posix and `.exe' if a DOS variant. 19542 19543 -- Macro: AC_EMXOS2 19544 Similar to `AC_CYGWIN' but checks for the EMX environment on OS/2 19545 and sets `EMXOS2'. Don't use this macro, the dignified means to 19546 check the nature of the host is using `AC_CANONICAL_HOST' (*note 19547 Canonicalizing::). 19548 19549 -- Macro: AC_ENABLE (FEATURE, ACTION-IF-GIVEN, [ACTION-IF-NOT-GIVEN]) 19550 This is an obsolete version of `AC_ARG_ENABLE' that does not 19551 support providing a help string (*note AC_ARG_ENABLE::). 19552 19553 -- Macro: AC_ERROR 19554 Replaced by `AC_MSG_ERROR' (*note AC_MSG_ERROR::). 19555 19556 -- Macro: AC_FIND_X 19557 Replaced by `AC_PATH_X' (*note AC_PATH_X::). 19558 19559 -- Macro: AC_FIND_XTRA 19560 Replaced by `AC_PATH_XTRA' (*note AC_PATH_XTRA::). 19561 19562 -- Macro: AC_FOREACH 19563 Replaced by `m4_foreach_w' (*note m4_foreach_w::). 19564 19565 -- Macro: AC_FUNC_CHECK 19566 Replaced by `AC_CHECK_FUNC' (*note AC_CHECK_FUNC::). 19567 19568 -- Macro: AC_FUNC_SETVBUF_REVERSED 19569 Do nothing. Formerly, this macro checked whether `setvbuf' takes 19570 the buffering type as its second argument and the buffer pointer 19571 as the third, instead of the other way around, and defined 19572 `SETVBUF_REVERSED'. However, the last systems to have the problem 19573 were those based on SVR2, which became obsolete in 1987, and the 19574 macro is no longer needed. 19575 19576 -- Macro: AC_FUNC_WAIT3 19577 If `wait3' is found and fills in the contents of its third argument 19578 (a `struct rusage *'), which HP-UX does not do, define 19579 `HAVE_WAIT3'. 19580 19581 These days portable programs should use `waitpid', not `wait3', as 19582 `wait3' has been removed from Posix. 19583 19584 -- Macro: AC_GCC_TRADITIONAL 19585 Replaced by `AC_PROG_GCC_TRADITIONAL' (*note 19586 AC_PROG_GCC_TRADITIONAL::). 19587 19588 -- Macro: AC_GETGROUPS_T 19589 Replaced by `AC_TYPE_GETGROUPS' (*note AC_TYPE_GETGROUPS::). 19590 19591 -- Macro: AC_GETLOADAVG 19592 Replaced by `AC_FUNC_GETLOADAVG' (*note AC_FUNC_GETLOADAVG::). 19593 19594 -- Macro: AC_GNU_SOURCE 19595 This macro is a platform-specific subset of 19596 `AC_USE_SYSTEM_EXTENSIONS' (*note AC_USE_SYSTEM_EXTENSIONS::). 19597 19598 -- Macro: AC_HAVE_FUNCS 19599 Replaced by `AC_CHECK_FUNCS' (*note AC_CHECK_FUNCS::). 19600 19601 -- Macro: AC_HAVE_HEADERS 19602 Replaced by `AC_CHECK_HEADERS' (*note AC_CHECK_HEADERS::). 19603 19604 -- Macro: AC_HAVE_LIBRARY (LIBRARY, [ACTION-IF-FOUND], 19605 [ACTION-IF-NOT-FOUND], [OTHER-LIBRARIES]) 19606 This macro is equivalent to calling `AC_CHECK_LIB' with a FUNCTION 19607 argument of `main'. In addition, LIBRARY can be written as any of 19608 `foo', `-lfoo', or `libfoo.a'. In all of those cases, the 19609 compiler is passed `-lfoo'. However, LIBRARY cannot be a shell 19610 variable; it must be a literal name. *Note AC_CHECK_LIB::. 19611 19612 -- Macro: AC_HAVE_POUNDBANG 19613 Replaced by `AC_SYS_INTERPRETER' (*note AC_SYS_INTERPRETER::). 19614 19615 -- Macro: AC_HEADER_CHECK 19616 Replaced by `AC_CHECK_HEADER' (*note AC_CHECK_HEADER::). 19617 19618 -- Macro: AC_HEADER_EGREP 19619 Replaced by `AC_EGREP_HEADER' (*note AC_EGREP_HEADER::). 19620 19621 -- Macro: AC_HELP_STRING 19622 Replaced by `AS_HELP_STRING' (*note AS_HELP_STRING::). 19623 19624 -- Macro: AC_INIT (UNIQUE-FILE-IN-SOURCE-DIR) 19625 Formerly `AC_INIT' used to have a single argument, and was 19626 equivalent to: 19627 19628 AC_INIT 19629 AC_CONFIG_SRCDIR(UNIQUE-FILE-IN-SOURCE-DIR) 19630 See *note AC_INIT:: and *note AC_CONFIG_SRCDIR::. 19631 19632 -- Macro: AC_INLINE 19633 Replaced by `AC_C_INLINE' (*note AC_C_INLINE::). 19634 19635 -- Macro: AC_INT_16_BITS 19636 If the C type `int' is 16 bits wide, define `INT_16_BITS'. Use 19637 `AC_CHECK_SIZEOF(int)' instead (*note AC_CHECK_SIZEOF::). 19638 19639 -- Macro: AC_IRIX_SUN 19640 If on IRIX (Silicon Graphics Unix), add `-lsun' to output `LIBS'. 19641 If you were using it to get `getmntent', use `AC_FUNC_GETMNTENT' 19642 instead. If you used it for the NIS versions of the password and 19643 group functions, use `AC_CHECK_LIB(sun, getpwnam)'. Up to 19644 Autoconf 2.13, it used to be 19645 19646 AC_CHECK_LIB([sun], [getmntent], [LIBS="-lsun $LIBS"]) 19647 19648 now it is defined as 19649 19650 AC_FUNC_GETMNTENT 19651 AC_CHECK_LIB([sun], [getpwnam]) 19652 19653 See *note AC_FUNC_GETMNTENT:: and *note AC_CHECK_LIB::. 19654 19655 -- Macro: AC_ISC_POSIX 19656 This macro adds `-lcposix' to output variable `LIBS' if necessary 19657 for Posix facilities. Sun dropped support for the obsolete 19658 INTERACTIVE Systems Corporation Unix on 2006-07-23. New programs 19659 need not use this macro. It is implemented as 19660 `AC_SEARCH_LIBS([strerror], [cposix])' (*note AC_SEARCH_LIBS::). 19661 19662 -- Macro: AC_LANG_C 19663 Same as `AC_LANG([C])' (*note AC_LANG::). 19664 19665 -- Macro: AC_LANG_CPLUSPLUS 19666 Same as `AC_LANG([C++])' (*note AC_LANG::). 19667 19668 -- Macro: AC_LANG_FORTRAN77 19669 Same as `AC_LANG([Fortran 77])' (*note AC_LANG::). 19670 19671 -- Macro: AC_LANG_RESTORE 19672 Select the LANGUAGE that is saved on the top of the stack, as set 19673 by `AC_LANG_SAVE', remove it from the stack, and call 19674 `AC_LANG(LANGUAGE)'. *Note Language Choice::, for the preferred 19675 way to change languages. 19676 19677 -- Macro: AC_LANG_SAVE 19678 Remember the current language (as set by `AC_LANG') on a stack. 19679 The current language does not change. `AC_LANG_PUSH' is preferred 19680 (*note AC_LANG_PUSH::). 19681 19682 -- Macro: AC_LINK_FILES (SOURCE..., DEST...) 19683 This is an obsolete version of `AC_CONFIG_LINKS' (*note 19684 AC_CONFIG_LINKS::. An updated version of: 19685 19686 AC_LINK_FILES(config/$machine.h config/$obj_format.h, 19687 host.h object.h) 19688 19689 is: 19690 19691 AC_CONFIG_LINKS([host.h:config/$machine.h 19692 object.h:config/$obj_format.h]) 19693 19694 -- Macro: AC_LN_S 19695 Replaced by `AC_PROG_LN_S' (*note AC_PROG_LN_S::). 19696 19697 -- Macro: AC_LONG_64_BITS 19698 Define `LONG_64_BITS' if the C type `long int' is 64 bits wide. 19699 Use the generic macro `AC_CHECK_SIZEOF([long int])' instead (*note 19700 AC_CHECK_SIZEOF::). 19701 19702 -- Macro: AC_LONG_DOUBLE 19703 If the C compiler supports a working `long double' type with more 19704 range or precision than the `double' type, define 19705 `HAVE_LONG_DOUBLE'. 19706 19707 You should use `AC_TYPE_LONG_DOUBLE' or 19708 `AC_TYPE_LONG_DOUBLE_WIDER' instead. *Note Particular Types::. 19709 19710 -- Macro: AC_LONG_FILE_NAMES 19711 Replaced by 19712 AC_SYS_LONG_FILE_NAMES 19713 *Note AC_SYS_LONG_FILE_NAMES::. 19714 19715 -- Macro: AC_MAJOR_HEADER 19716 Replaced by `AC_HEADER_MAJOR' (*note AC_HEADER_MAJOR::). 19717 19718 -- Macro: AC_MEMORY_H 19719 Used to define `NEED_MEMORY_H' if the `mem' functions were defined 19720 in `memory.h'. Today it is equivalent to 19721 `AC_CHECK_HEADERS([memory.h])' (*note AC_CHECK_HEADERS::). Adjust 19722 your code to depend upon `HAVE_MEMORY_H', not `NEED_MEMORY_H'; see 19723 *note Standard Symbols::. 19724 19725 -- Macro: AC_MINGW32 19726 Similar to `AC_CYGWIN' but checks for the MinGW compiler 19727 environment and sets `MINGW32'. Don't use this macro, the 19728 dignified means to check the nature of the host is using 19729 `AC_CANONICAL_HOST' (*note Canonicalizing::). 19730 19731 -- Macro: AC_MINIX 19732 This macro is a platform-specific subset of 19733 `AC_USE_SYSTEM_EXTENSIONS' (*note AC_USE_SYSTEM_EXTENSIONS::). 19734 19735 -- Macro: AC_MINUS_C_MINUS_O 19736 Replaced by `AC_PROG_CC_C_O' (*note AC_PROG_CC_C_O::). 19737 19738 -- Macro: AC_MMAP 19739 Replaced by `AC_FUNC_MMAP' (*note AC_FUNC_MMAP::). 19740 19741 -- Macro: AC_MODE_T 19742 Replaced by `AC_TYPE_MODE_T' (*note AC_TYPE_MODE_T::). 19743 19744 -- Macro: AC_OBJEXT 19745 Defined the output variable `OBJEXT' based on the output of the 19746 compiler, after .c files have been excluded. Typically set to `o' 19747 if Posix, `obj' if a DOS variant. Now the compiler checking 19748 macros handle this automatically. 19749 19750 -- Macro: AC_OBSOLETE (THIS-MACRO-NAME, [SUGGESTION]) 19751 Make M4 print a message to the standard error output warning that 19752 THIS-MACRO-NAME is obsolete, and giving the file and line number 19753 where it was called. THIS-MACRO-NAME should be the name of the 19754 macro that is calling `AC_OBSOLETE'. If SUGGESTION is given, it 19755 is printed at the end of the warning message; for example, it can 19756 be a suggestion for what to use instead of THIS-MACRO-NAME. 19757 19758 For instance 19759 19760 AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl 19761 19762 You are encouraged to use `AU_DEFUN' instead, since it gives better 19763 services to the user (*note AU_DEFUN::). 19764 19765 -- Macro: AC_OFF_T 19766 Replaced by `AC_TYPE_OFF_T' (*note AC_TYPE_OFF_T::). 19767 19768 -- Macro: AC_OUTPUT ([FILE]..., [EXTRA-CMDS], [INIT-CMDS]) 19769 The use of `AC_OUTPUT' with arguments is deprecated. This 19770 obsoleted interface is equivalent to: 19771 19772 AC_CONFIG_FILES(FILE...) 19773 AC_CONFIG_COMMANDS([default], 19774 EXTRA-CMDS, INIT-CMDS) 19775 AC_OUTPUT 19776 19777 See *note AC_CONFIG_FILES::, *note AC_CONFIG_COMMANDS::, and *note 19778 AC_OUTPUT::. 19779 19780 -- Macro: AC_OUTPUT_COMMANDS (EXTRA-CMDS, [INIT-CMDS]) 19781 Specify additional shell commands to run at the end of 19782 `config.status', and shell commands to initialize any variables 19783 from `configure'. This macro may be called multiple times. It is 19784 obsolete, replaced by `AC_CONFIG_COMMANDS' (*note 19785 AC_CONFIG_COMMANDS::). 19786 19787 Here is an unrealistic example: 19788 19789 fubar=27 19790 AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.], 19791 [fubar=$fubar]) 19792 AC_OUTPUT_COMMANDS([echo this is another, extra, bit], 19793 [echo init bit]) 19794 19795 Aside from the fact that `AC_CONFIG_COMMANDS' requires an 19796 additional key, an important difference is that 19797 `AC_OUTPUT_COMMANDS' is quoting its arguments twice, unlike 19798 `AC_CONFIG_COMMANDS'. This means that `AC_CONFIG_COMMANDS' can 19799 safely be given macro calls as arguments: 19800 19801 AC_CONFIG_COMMANDS(foo, [my_FOO()]) 19802 19803 Conversely, where one level of quoting was enough for literal 19804 strings with `AC_OUTPUT_COMMANDS', you need two with 19805 `AC_CONFIG_COMMANDS'. The following lines are equivalent: 19806 19807 AC_OUTPUT_COMMANDS([echo "Square brackets: []"]) 19808 AC_CONFIG_COMMANDS([default], [[echo "Square brackets: []"]]) 19809 19810 -- Macro: AC_PID_T 19811 Replaced by `AC_TYPE_PID_T' (*note AC_TYPE_PID_T::). 19812 19813 -- Macro: AC_PREFIX 19814 Replaced by `AC_PREFIX_PROGRAM' (*note AC_PREFIX_PROGRAM::). 19815 19816 -- Macro: AC_PROGRAMS_CHECK 19817 Replaced by `AC_CHECK_PROGS' (*note AC_CHECK_PROGS::). 19818 19819 -- Macro: AC_PROGRAMS_PATH 19820 Replaced by `AC_PATH_PROGS' (*note AC_PATH_PROGS::). 19821 19822 -- Macro: AC_PROGRAM_CHECK 19823 Replaced by `AC_CHECK_PROG' (*note AC_CHECK_PROG::). 19824 19825 -- Macro: AC_PROGRAM_EGREP 19826 Replaced by `AC_EGREP_CPP' (*note AC_EGREP_CPP::). 19827 19828 -- Macro: AC_PROGRAM_PATH 19829 Replaced by `AC_PATH_PROG' (*note AC_PATH_PROG::). 19830 19831 -- Macro: AC_REMOTE_TAPE 19832 Removed because of limited usefulness. 19833 19834 -- Macro: AC_RESTARTABLE_SYSCALLS 19835 This macro was renamed `AC_SYS_RESTARTABLE_SYSCALLS'. However, 19836 these days portable programs should use `sigaction' with 19837 `SA_RESTART' if they want restartable system calls. They should 19838 not rely on `HAVE_RESTARTABLE_SYSCALLS', since nowadays whether a 19839 system call is restartable is a dynamic issue, not a 19840 configuration-time issue. 19841 19842 -- Macro: AC_RETSIGTYPE 19843 Replaced by `AC_TYPE_SIGNAL' (*note AC_TYPE_SIGNAL::), which itself 19844 is obsolete when assuming C89 or better. 19845 19846 -- Macro: AC_RSH 19847 Removed because of limited usefulness. 19848 19849 -- Macro: AC_SCO_INTL 19850 If on SCO Unix, add `-lintl' to output variable `LIBS'. This 19851 macro used to do this: 19852 19853 AC_CHECK_LIB([intl], [strftime], [LIBS="-lintl $LIBS"]) 19854 19855 Now it just calls `AC_FUNC_STRFTIME' instead (*note 19856 AC_FUNC_STRFTIME::). 19857 19858 -- Macro: AC_SETVBUF_REVERSED 19859 Replaced by 19860 AC_FUNC_SETVBUF_REVERSED 19861 *Note AC_FUNC_SETVBUF_REVERSED::. 19862 19863 -- Macro: AC_SET_MAKE 19864 Replaced by `AC_PROG_MAKE_SET' (*note AC_PROG_MAKE_SET::). 19865 19866 -- Macro: AC_SIZEOF_TYPE 19867 Replaced by `AC_CHECK_SIZEOF' (*note AC_CHECK_SIZEOF::). 19868 19869 -- Macro: AC_SIZE_T 19870 Replaced by `AC_TYPE_SIZE_T' (*note AC_TYPE_SIZE_T::). 19871 19872 -- Macro: AC_STAT_MACROS_BROKEN 19873 Replaced by `AC_HEADER_STAT' (*note AC_HEADER_STAT::). 19874 19875 -- Macro: AC_STDC_HEADERS 19876 Replaced by `AC_HEADER_STDC' (*note AC_HEADER_STDC::). 19877 19878 -- Macro: AC_STRCOLL 19879 Replaced by `AC_FUNC_STRCOLL' (*note AC_FUNC_STRCOLL::). 19880 19881 -- Macro: AC_STRUCT_ST_BLKSIZE 19882 If `struct stat' contains an `st_blksize' member, define 19883 `HAVE_STRUCT_STAT_ST_BLKSIZE'. The former name, `HAVE_ST_BLKSIZE' 19884 is to be avoided, as its support will cease in the future. This 19885 macro is obsoleted, and should be replaced by 19886 19887 AC_CHECK_MEMBERS([struct stat.st_blksize]) 19888 *Note AC_CHECK_MEMBERS::. 19889 19890 -- Macro: AC_STRUCT_ST_RDEV 19891 If `struct stat' contains an `st_rdev' member, define 19892 `HAVE_STRUCT_STAT_ST_RDEV'. The former name for this macro, 19893 `HAVE_ST_RDEV', is to be avoided as it will cease to be supported 19894 in the future. Actually, even the new macro is obsolete and 19895 should be replaced by: 19896 AC_CHECK_MEMBERS([struct stat.st_rdev]) 19897 *Note AC_CHECK_MEMBERS::. 19898 19899 -- Macro: AC_ST_BLKSIZE 19900 Replaced by `AC_CHECK_MEMBERS' (*note AC_CHECK_MEMBERS::). 19901 19902 -- Macro: AC_ST_BLOCKS 19903 Replaced by `AC_STRUCT_ST_BLOCKS' (*note AC_STRUCT_ST_BLOCKS::). 19904 19905 -- Macro: AC_ST_RDEV 19906 Replaced by `AC_CHECK_MEMBERS' (*note AC_CHECK_MEMBERS::). 19907 19908 -- Macro: AC_SYS_RESTARTABLE_SYSCALLS 19909 If the system automatically restarts a system call that is 19910 interrupted by a signal, define `HAVE_RESTARTABLE_SYSCALLS'. This 19911 macro does not check whether system calls are restarted in 19912 general--it checks whether a signal handler installed with 19913 `signal' (but not `sigaction') causes system calls to be 19914 restarted. It does not check whether system calls can be 19915 restarted when interrupted by signals that have no handler. 19916 19917 These days portable programs should use `sigaction' with 19918 `SA_RESTART' if they want restartable system calls. They should 19919 not rely on `HAVE_RESTARTABLE_SYSCALLS', since nowadays whether a 19920 system call is restartable is a dynamic issue, not a 19921 configuration-time issue. 19922 19923 -- Macro: AC_SYS_SIGLIST_DECLARED 19924 This macro was renamed `AC_DECL_SYS_SIGLIST'. However, even that 19925 name is obsolete, as the same functionality is now achieved via 19926 `AC_CHECK_DECLS' (*note AC_CHECK_DECLS::). 19927 19928 -- Macro: AC_TEST_CPP 19929 This macro was renamed `AC_TRY_CPP', which in turn was replaced by 19930 `AC_PREPROC_IFELSE' (*note AC_PREPROC_IFELSE::). 19931 19932 -- Macro: AC_TEST_PROGRAM 19933 This macro was renamed `AC_TRY_RUN', which in turn was replaced by 19934 `AC_RUN_IFELSE' (*note AC_RUN_IFELSE::). 19935 19936 -- Macro: AC_TIMEZONE 19937 Replaced by `AC_STRUCT_TIMEZONE' (*note AC_STRUCT_TIMEZONE::). 19938 19939 -- Macro: AC_TIME_WITH_SYS_TIME 19940 Replaced by `AC_HEADER_TIME' (*note AC_HEADER_TIME::). 19941 19942 -- Macro: AC_TRY_COMPILE (INCLUDES, FUNCTION-BODY, [ACTION-IF-TRUE], 19943 [ACTION-IF-FALSE]) 19944 Same as: 19945 19946 AC_COMPILE_IFELSE( 19947 [AC_LANG_PROGRAM([[INCLUDES]], 19948 [[FUNCTION-BODY]])], 19949 [ACTION-IF-TRUE], 19950 [ACTION-IF-FALSE]) 19951 19952 *Note Running the Compiler::. 19953 19954 This macro double quotes both INCLUDES and FUNCTION-BODY. 19955 19956 For C and C++, INCLUDES is any `#include' statements needed by the 19957 code in FUNCTION-BODY (INCLUDES is ignored if the currently 19958 selected language is Fortran or Fortran 77). The compiler and 19959 compilation flags are determined by the current language (*note 19960 Language Choice::). 19961 19962 -- Macro: AC_TRY_CPP (INPUT, [ACTION-IF-TRUE], [ACTION-IF-FALSE]) 19963 Same as: 19964 19965 AC_PREPROC_IFELSE( 19966 [AC_LANG_SOURCE([[INPUT]])], 19967 [ACTION-IF-TRUE], 19968 [ACTION-IF-FALSE]) 19969 19970 *Note Running the Preprocessor::. 19971 19972 This macro double quotes the INPUT. 19973 19974 -- Macro: AC_TRY_LINK (INCLUDES, FUNCTION-BODY, [ACTION-IF-TRUE], 19975 [ACTION-IF-FALSE]) 19976 Same as: 19977 19978 AC_LINK_IFELSE( 19979 [AC_LANG_PROGRAM([[INCLUDES]], 19980 [[FUNCTION-BODY]])], 19981 [ACTION-IF-TRUE], 19982 [ACTION-IF-FALSE]) 19983 19984 *Note Running the Compiler::. 19985 19986 This macro double quotes both INCLUDES and FUNCTION-BODY. 19987 19988 Depending on the current language (*note Language Choice::), 19989 create a test program to see whether a function whose body 19990 consists of FUNCTION-BODY can be compiled and linked. If the file 19991 compiles and links successfully, run shell commands 19992 ACTION-IF-FOUND, otherwise run ACTION-IF-NOT-FOUND. 19993 19994 This macro double quotes both INCLUDES and FUNCTION-BODY. 19995 19996 For C and C++, INCLUDES is any `#include' statements needed by the 19997 code in FUNCTION-BODY (INCLUDES is ignored if the currently 19998 selected language is Fortran or Fortran 77). The compiler and 19999 compilation flags are determined by the current language (*note 20000 Language Choice::), and in addition `LDFLAGS' and `LIBS' are used 20001 for linking. 20002 20003 -- Macro: AC_TRY_LINK_FUNC (FUNCTION, [ACTION-IF-FOUND], 20004 [ACTION-IF-NOT-FOUND]) 20005 This macro is equivalent to 20006 AC_LINK_IFELSE([AC_LANG_CALL([], [FUNCTION])], 20007 [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND]) 20008 *Note AC_LINK_IFELSE::. 20009 20010 -- Macro: AC_TRY_RUN (PROGRAM, [ACTION-IF-TRUE], [ACTION-IF-FALSE], 20011 [ACTION-IF-CROSS-COMPILING = `AC_MSG_FAILURE']) 20012 Same as: 20013 20014 AC_RUN_IFELSE( 20015 [AC_LANG_SOURCE([[PROGRAM]])], 20016 [ACTION-IF-TRUE], 20017 [ACTION-IF-FALSE], 20018 [ACTION-IF-CROSS-COMPILING]) 20019 20020 *Note Runtime::. 20021 20022 -- Macro: AC_TYPE_SIGNAL 20023 If `signal.h' declares `signal' as returning a pointer to a 20024 function returning `void', define `RETSIGTYPE' to be `void'; 20025 otherwise, define it to be `int'. These days, it is portable to 20026 assume C89, and that signal handlers return `void', without 20027 needing to use this macro or `RETSIGTYPE'. 20028 20029 When targeting older K&R C, it is possible to define signal 20030 handlers as returning type `RETSIGTYPE', and omit a return 20031 statement: 20032 20033 RETSIGTYPE 20034 hup_handler () 20035 { 20036 ... 20037 } 20038 20039 -- Macro: AC_UID_T 20040 Replaced by `AC_TYPE_UID_T' (*note AC_TYPE_UID_T::). 20041 20042 -- Macro: AC_UNISTD_H 20043 Same as `AC_CHECK_HEADERS([unistd.h])' (*note AC_CHECK_HEADERS::). 20044 20045 -- Macro: AC_USG 20046 Define `USG' if the BSD string functions are defined in 20047 `strings.h'. You should no longer depend upon `USG', but on 20048 `HAVE_STRING_H'; see *note Standard Symbols::. 20049 20050 -- Macro: AC_UTIME_NULL 20051 Replaced by `AC_FUNC_UTIME_NULL' (*note AC_FUNC_UTIME_NULL::). 20052 20053 -- Macro: AC_VALIDATE_CACHED_SYSTEM_TUPLE ([CMD]) 20054 If the cache file is inconsistent with the current host, target and 20055 build system types, it used to execute CMD or print a default 20056 error message. This is now handled by default. 20057 20058 -- Macro: AC_VERBOSE (RESULT-DESCRIPTION) 20059 Replaced by `AC_MSG_RESULT' (*note AC_MSG_RESULT::). 20060 20061 -- Macro: AC_VFORK 20062 Replaced by `AC_FUNC_FORK' (*note AC_FUNC_FORK::). 20063 20064 -- Macro: AC_VPRINTF 20065 Replaced by `AC_FUNC_VPRINTF' (*note AC_FUNC_VPRINTF::). 20066 20067 -- Macro: AC_WAIT3 20068 This macro was renamed `AC_FUNC_WAIT3'. However, these days 20069 portable programs should use `waitpid', not `wait3', as `wait3' 20070 has been removed from Posix. 20071 20072 -- Macro: AC_WARN 20073 Replaced by `AC_MSG_WARN' (*note AC_MSG_WARN::). 20074 20075 -- Macro: AC_WITH (PACKAGE, ACTION-IF-GIVEN, [ACTION-IF-NOT-GIVEN]) 20076 This is an obsolete version of `AC_ARG_WITH' that does not support 20077 providing a help string (*note AC_ARG_WITH::). 20078 20079 -- Macro: AC_WORDS_BIGENDIAN 20080 Replaced by `AC_C_BIGENDIAN' (*note AC_C_BIGENDIAN::). 20081 20082 -- Macro: AC_XENIX_DIR 20083 This macro used to add `-lx' to output variable `LIBS' if on 20084 Xenix. Also, if `dirent.h' is being checked for, added `-ldir' to 20085 `LIBS'. Now it is merely an alias of `AC_HEADER_DIRENT' instead, 20086 plus some code to detect whether running XENIX on which you should 20087 not depend: 20088 20089 AC_MSG_CHECKING([for Xenix]) 20090 AC_EGREP_CPP([yes], 20091 [#if defined M_XENIX && !defined M_UNIX 20092 yes 20093 #endif], 20094 [AC_MSG_RESULT([yes]); XENIX=yes], 20095 [AC_MSG_RESULT([no]); XENIX=]) 20096 Don't use this macro, the dignified means to check the nature of 20097 the host is using `AC_CANONICAL_HOST' (*note Canonicalizing::). 20098 20099 -- Macro: AC_YYTEXT_POINTER 20100 This macro was renamed `AC_DECL_YYTEXT', which in turn was 20101 integrated into `AC_PROG_LEX' (*note AC_PROG_LEX::). 20102 20103 20104File: autoconf.info, Node: Autoconf 1, Next: Autoconf 2.13, Prev: Obsolete Macros, Up: Obsolete Constructs 20105 2010618.5 Upgrading From Version 1 20107============================= 20108 20109Autoconf version 2 is mostly backward compatible with version 1. 20110However, it introduces better ways to do some things, and doesn't 20111support some of the ugly things in version 1. So, depending on how 20112sophisticated your `configure.ac' files are, you might have to do some 20113manual work in order to upgrade to version 2. This chapter points out 20114some problems to watch for when upgrading. Also, perhaps your 20115`configure' scripts could benefit from some of the new features in 20116version 2; the changes are summarized in the file `NEWS' in the 20117Autoconf distribution. 20118 20119* Menu: 20120 20121* Changed File Names:: Files you might rename 20122* Changed Makefiles:: New things to put in `Makefile.in' 20123* Changed Macros:: Macro calls you might replace 20124* Changed Results:: Changes in how to check test results 20125* Changed Macro Writing:: Better ways to write your own macros 20126 20127 20128File: autoconf.info, Node: Changed File Names, Next: Changed Makefiles, Up: Autoconf 1 20129 2013018.5.1 Changed File Names 20131------------------------- 20132 20133If you have an `aclocal.m4' installed with Autoconf (as opposed to in a 20134particular package's source directory), you must rename it to 20135`acsite.m4'. *Note autoconf Invocation::. 20136 20137 If you distribute `install.sh' with your package, rename it to 20138`install-sh' so `make' builtin rules don't inadvertently create a file 20139called `install' from it. `AC_PROG_INSTALL' looks for the script under 20140both names, but it is best to use the new name. 20141 20142 If you were using `config.h.top', `config.h.bot', or `acconfig.h', 20143you still can, but you have less clutter if you use the `AH_' macros. 20144*Note Autoheader Macros::. 20145 20146 20147File: autoconf.info, Node: Changed Makefiles, Next: Changed Macros, Prev: Changed File Names, Up: Autoconf 1 20148 2014918.5.2 Changed Makefiles 20150------------------------ 20151 20152Add `@CFLAGS@', `@CPPFLAGS@', and `@LDFLAGS@' in your `Makefile.in' 20153files, so they can take advantage of the values of those variables in 20154the environment when `configure' is run. Doing this isn't necessary, 20155but it's a convenience for users. 20156 20157 Also add `@configure_input@' in a comment to each input file for 20158`AC_OUTPUT', so that the output files contain a comment saying they 20159were produced by `configure'. Automatically selecting the right 20160comment syntax for all the kinds of files that people call `AC_OUTPUT' 20161on became too much work. 20162 20163 Add `config.log' and `config.cache' to the list of files you remove 20164in `distclean' targets. 20165 20166 If you have the following in `Makefile.in': 20167 20168 prefix = /usr/local 20169 exec_prefix = $(prefix) 20170 20171you must change it to: 20172 20173 prefix = @prefix@ 20174 exec_prefix = @exec_prefix@ 20175 20176The old behavior of replacing those variables without `@' characters 20177around them has been removed. 20178 20179 20180File: autoconf.info, Node: Changed Macros, Next: Changed Results, Prev: Changed Makefiles, Up: Autoconf 1 20181 2018218.5.3 Changed Macros 20183--------------------- 20184 20185Many of the macros were renamed in Autoconf version 2. You can still 20186use the old names, but the new ones are clearer, and it's easier to find 20187the documentation for them. *Note Obsolete Macros::, for a table 20188showing the new names for the old macros. Use the `autoupdate' program 20189to convert your `configure.ac' to using the new macro names. *Note 20190autoupdate Invocation::. 20191 20192 Some macros have been superseded by similar ones that do the job 20193better, but are not call-compatible. If you get warnings about calling 20194obsolete macros while running `autoconf', you may safely ignore them, 20195but your `configure' script generally works better if you follow the 20196advice that is printed about what to replace the obsolete macros with. 20197In particular, the mechanism for reporting the results of tests has 20198changed. If you were using `echo' or `AC_VERBOSE' (perhaps via 20199`AC_COMPILE_CHECK'), your `configure' script's output looks better if 20200you switch to `AC_MSG_CHECKING' and `AC_MSG_RESULT'. *Note Printing 20201Messages::. Those macros work best in conjunction with cache 20202variables. *Note Caching Results::. 20203 20204 20205File: autoconf.info, Node: Changed Results, Next: Changed Macro Writing, Prev: Changed Macros, Up: Autoconf 1 20206 2020718.5.4 Changed Results 20208---------------------- 20209 20210If you were checking the results of previous tests by examining the 20211shell variable `DEFS', you need to switch to checking the values of the 20212cache variables for those tests. `DEFS' no longer exists while 20213`configure' is running; it is only created when generating output 20214files. This difference from version 1 is because properly quoting the 20215contents of that variable turned out to be too cumbersome and 20216inefficient to do every time `AC_DEFINE' is called. *Note Cache 20217Variable Names::. 20218 20219 For example, here is a `configure.ac' fragment written for Autoconf 20220version 1: 20221 20222 AC_HAVE_FUNCS(syslog) 20223 case "$DEFS" in 20224 *-DHAVE_SYSLOG*) ;; 20225 *) # syslog is not in the default libraries. See if it's in some other. 20226 saved_LIBS="$LIBS" 20227 for lib in bsd socket inet; do 20228 AC_CHECKING(for syslog in -l$lib) 20229 LIBS="-l$lib $saved_LIBS" 20230 AC_HAVE_FUNCS(syslog) 20231 case "$DEFS" in 20232 *-DHAVE_SYSLOG*) break ;; 20233 *) ;; 20234 esac 20235 LIBS="$saved_LIBS" 20236 done ;; 20237 esac 20238 20239 Here is a way to write it for version 2: 20240 20241 AC_CHECK_FUNCS([syslog]) 20242 if test "x$ac_cv_func_syslog" = xno; then 20243 # syslog is not in the default libraries. See if it's in some other. 20244 for lib in bsd socket inet; do 20245 AC_CHECK_LIB([$lib], [syslog], [AC_DEFINE([HAVE_SYSLOG]) 20246 LIBS="-l$lib $LIBS"; break]) 20247 done 20248 fi 20249 20250 If you were working around bugs in `AC_DEFINE_UNQUOTED' by adding 20251backslashes before quotes, you need to remove them. It now works 20252predictably, and does not treat quotes (except back quotes) specially. 20253*Note Setting Output Variables::. 20254 20255 All of the Boolean shell variables set by Autoconf macros now use 20256`yes' for the true value. Most of them use `no' for false, though for 20257backward compatibility some use the empty string instead. If you were 20258relying on a shell variable being set to something like 1 or `t' for 20259true, you need to change your tests. 20260 20261 20262File: autoconf.info, Node: Changed Macro Writing, Prev: Changed Results, Up: Autoconf 1 20263 2026418.5.5 Changed Macro Writing 20265---------------------------- 20266 20267When defining your own macros, you should now use `AC_DEFUN' instead of 20268`define'. `AC_DEFUN' automatically calls `AC_PROVIDE' and ensures that 20269macros called via `AC_REQUIRE' do not interrupt other macros, to 20270prevent nested `checking...' messages on the screen. There's no actual 20271harm in continuing to use the older way, but it's less convenient and 20272attractive. *Note Macro Definitions::. 20273 20274 You probably looked at the macros that came with Autoconf as a guide 20275for how to do things. It would be a good idea to take a look at the new 20276versions of them, as the style is somewhat improved and they take 20277advantage of some new features. 20278 20279 If you were doing tricky things with undocumented Autoconf internals 20280(macros, variables, diversions), check whether you need to change 20281anything to account for changes that have been made. Perhaps you can 20282even use an officially supported technique in version 2 instead of 20283kludging. Or perhaps not. 20284 20285 To speed up your locally written feature tests, add caching to them. 20286See whether any of your tests are of general enough usefulness to 20287encapsulate them into macros that you can share. 20288 20289 20290File: autoconf.info, Node: Autoconf 2.13, Prev: Autoconf 1, Up: Obsolete Constructs 20291 2029218.6 Upgrading From Version 2.13 20293================================ 20294 20295The introduction of the previous section (*note Autoconf 1::) perfectly 20296suits this section... 20297 20298 Autoconf version 2.50 is mostly backward compatible with version 20299 2.13. However, it introduces better ways to do some things, and 20300 doesn't support some of the ugly things in version 2.13. So, 20301 depending on how sophisticated your `configure.ac' files are, you 20302 might have to do some manual work in order to upgrade to version 20303 2.50. This chapter points out some problems to watch for when 20304 upgrading. Also, perhaps your `configure' scripts could benefit 20305 from some of the new features in version 2.50; the changes are 20306 summarized in the file `NEWS' in the Autoconf distribution. 20307 20308* Menu: 20309 20310* Changed Quotation:: Broken code which used to work 20311* New Macros:: Interaction with foreign macros 20312* Hosts and Cross-Compilation:: Bugward compatibility kludges 20313* AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token 20314* AC_ACT_IFELSE vs AC_TRY_ACT:: A more generic scheme for testing sources 20315 20316 20317File: autoconf.info, Node: Changed Quotation, Next: New Macros, Up: Autoconf 2.13 20318 2031918.6.1 Changed Quotation 20320------------------------ 20321 20322The most important changes are invisible to you: the implementation of 20323most macros have completely changed. This allowed more factorization of 20324the code, better error messages, a higher uniformity of the user's 20325interface etc. Unfortunately, as a side effect, some construct which 20326used to (miraculously) work might break starting with Autoconf 2.50. 20327The most common culprit is bad quotation. 20328 20329 For instance, in the following example, the message is not properly 20330quoted: 20331 20332 AC_INIT 20333 AC_CHECK_HEADERS(foo.h, , 20334 AC_MSG_ERROR(cannot find foo.h, bailing out)) 20335 AC_OUTPUT 20336 20337Autoconf 2.13 simply ignores it: 20338 20339 $ autoconf-2.13; ./configure --silent 20340 creating cache ./config.cache 20341 configure: error: cannot find foo.h 20342 $ 20343 20344while Autoconf 2.50 produces a broken `configure': 20345 20346 $ autoconf-2.50; ./configure --silent 20347 configure: error: cannot find foo.h 20348 ./configure: exit: bad non-numeric arg `bailing' 20349 ./configure: exit: bad non-numeric arg `bailing' 20350 $ 20351 20352 The message needs to be quoted, and the `AC_MSG_ERROR' invocation 20353too! 20354 20355 AC_INIT([Example], [1.0], [bug-example@example.org]) 20356 AC_CHECK_HEADERS([foo.h], [], 20357 [AC_MSG_ERROR([cannot find foo.h, bailing out])]) 20358 AC_OUTPUT 20359 20360 Many many (and many more) Autoconf macros were lacking proper 20361quotation, including no less than... `AC_DEFUN' itself! 20362 20363 $ cat configure.in 20364 AC_DEFUN([AC_PROG_INSTALL], 20365 [# My own much better version 20366 ]) 20367 AC_INIT 20368 AC_PROG_INSTALL 20369 AC_OUTPUT 20370 $ autoconf-2.13 20371 autoconf: Undefined macros: 20372 ***BUG in Autoconf--please report*** AC_FD_MSG 20373 ***BUG in Autoconf--please report*** AC_EPI 20374 configure.in:1:AC_DEFUN([AC_PROG_INSTALL], 20375 configure.in:5:AC_PROG_INSTALL 20376 $ autoconf-2.50 20377 $ 20378 20379 20380File: autoconf.info, Node: New Macros, Next: Hosts and Cross-Compilation, Prev: Changed Quotation, Up: Autoconf 2.13 20381 2038218.6.2 New Macros 20383----------------- 20384 20385While Autoconf was relatively dormant in the late 1990s, Automake 20386provided Autoconf-like macros for a while. Starting with Autoconf 2.50 20387in 2001, Autoconf provided versions of these macros, integrated in the 20388`AC_' namespace, instead of `AM_'. But in order to ease the upgrading 20389via `autoupdate', bindings to such `AM_' macros are provided. 20390 20391 Unfortunately older versions of Automake (e.g., Automake 1.4) did 20392not quote the names of these macros. Therefore, when `m4' finds 20393something like `AC_DEFUN(AM_TYPE_PTRDIFF_T, ...)' in `aclocal.m4', 20394`AM_TYPE_PTRDIFF_T' is expanded, replaced with its Autoconf definition. 20395 20396 Fortunately Autoconf catches pre-`AC_INIT' expansions, and 20397complains, in its own words: 20398 20399 $ cat configure.ac 20400 AC_INIT([Example], [1.0], [bug-example@example.org]) 20401 AM_TYPE_PTRDIFF_T 20402 $ aclocal-1.4 20403 $ autoconf 20404 aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion 20405 aclocal.m4:17: the top level 20406 autom4te: m4 failed with exit status: 1 20407 $ 20408 20409 Modern versions of Automake no longer define most of these macros, 20410and properly quote the names of the remaining macros. If you must use 20411an old Automake, do not depend upon macros from Automake as it is 20412simply not its job to provide macros (but the one it requires itself): 20413 20414 $ cat configure.ac 20415 AC_INIT([Example], [1.0], [bug-example@example.org]) 20416 AM_TYPE_PTRDIFF_T 20417 $ rm aclocal.m4 20418 $ autoupdate 20419 autoupdate: `configure.ac' is updated 20420 $ cat configure.ac 20421 AC_INIT([Example], [1.0], [bug-example@example.org]) 20422 AC_CHECK_TYPES([ptrdiff_t]) 20423 $ aclocal-1.4 20424 $ autoconf 20425 $ 20426 20427 20428File: autoconf.info, Node: Hosts and Cross-Compilation, Next: AC_LIBOBJ vs LIBOBJS, Prev: New Macros, Up: Autoconf 2.13 20429 2043018.6.3 Hosts and Cross-Compilation 20431---------------------------------- 20432 20433Based on the experience of compiler writers, and after long public 20434debates, many aspects of the cross-compilation chain have changed: 20435 20436 - the relationship between the build, host, and target architecture 20437 types, 20438 20439 - the command line interface for specifying them to `configure', 20440 20441 - the variables defined in `configure', 20442 20443 - the enabling of cross-compilation mode. 20444 20445 20446 The relationship between build, host, and target have been cleaned 20447up: the chain of default is now simply: target defaults to host, host to 20448build, and build to the result of `config.guess'. Nevertheless, in 20449order to ease the transition from 2.13 to 2.50, the following 20450transition scheme is implemented. _Do not rely on it_, as it will be 20451completely disabled in a couple of releases (we cannot keep it, as it 20452proves to cause more problems than it cures). 20453 20454 They all default to the result of running `config.guess', unless you 20455specify either `--build' or `--host'. In this case, the default 20456becomes the system type you specified. If you specify both, and 20457they're different, `configure' enters cross compilation mode, so it 20458doesn't run any tests that require execution. 20459 20460 Hint: if you mean to override the result of `config.guess', prefer 20461`--build' over `--host'. 20462 20463 20464 For backward compatibility, `configure' accepts a system type as an 20465option by itself. Such an option overrides the defaults for build, 20466host, and target system types. The following configure statement 20467configures a cross toolchain that runs on NetBSD/alpha but generates 20468code for GNU Hurd/sparc, which is also the build platform. 20469 20470 ./configure --host=alpha-netbsd sparc-gnu 20471 20472 20473 In Autoconf 2.13 and before, the variables `build', `host', and 20474`target' had a different semantics before and after the invocation of 20475`AC_CANONICAL_BUILD' etc. Now, the argument of `--build' is strictly 20476copied into `build_alias', and is left empty otherwise. After the 20477`AC_CANONICAL_BUILD', `build' is set to the canonicalized build type. 20478To ease the transition, before, its contents is the same as that of 20479`build_alias'. Do _not_ rely on this broken feature. 20480 20481 For consistency with the backward compatibility scheme exposed above, 20482when `--host' is specified but `--build' isn't, the build system is 20483assumed to be the same as `--host', and `build_alias' is set to that 20484value. Eventually, this historically incorrect behavior will go away. 20485 20486 20487 The former scheme to enable cross-compilation proved to cause more 20488harm than good, in particular, it used to be triggered too easily, 20489leaving regular end users puzzled in front of cryptic error messages. 20490`configure' could even enter cross-compilation mode only because the 20491compiler was not functional. This is mainly because `configure' used 20492to try to detect cross-compilation, instead of waiting for an explicit 20493flag from the user. 20494 20495 Now, `configure' enters cross-compilation mode if and only if 20496`--host' is passed. 20497 20498 That's the short documentation. To ease the transition between 2.13 20499and its successors, a more complicated scheme is implemented. _Do not 20500rely on the following_, as it will be removed in the near future. 20501 20502 If you specify `--host', but not `--build', when `configure' 20503performs the first compiler test it tries to run an executable produced 20504by the compiler. If the execution fails, it enters cross-compilation 20505mode. This is fragile. Moreover, by the time the compiler test is 20506performed, it may be too late to modify the build-system type: other 20507tests may have already been performed. Therefore, whenever you specify 20508`--host', be sure to specify `--build' too. 20509 20510 ./configure --build=i686-pc-linux-gnu --host=m68k-coff 20511 20512enters cross-compilation mode. The former interface, which consisted 20513in setting the compiler to a cross-compiler without informing 20514`configure' is obsolete. For instance, `configure' fails if it can't 20515run the code generated by the specified compiler if you configure as 20516follows: 20517 20518 ./configure CC=m68k-coff-gcc 20519 20520 20521File: autoconf.info, Node: AC_LIBOBJ vs LIBOBJS, Next: AC_ACT_IFELSE vs AC_TRY_ACT, Prev: Hosts and Cross-Compilation, Up: Autoconf 2.13 20522 2052318.6.4 `AC_LIBOBJ' vs. `LIBOBJS' 20524-------------------------------- 20525 20526Up to Autoconf 2.13, the replacement of functions was triggered via the 20527variable `LIBOBJS'. Since Autoconf 2.50, the macro `AC_LIBOBJ' should 20528be used instead (*note Generic Functions::). Starting at Autoconf 205292.53, the use of `LIBOBJS' is an error. 20530 20531 This change is mandated by the unification of the GNU Build System 20532components. In particular, the various fragile techniques used to parse 20533a `configure.ac' are all replaced with the use of traces. As a 20534consequence, any action must be traceable, which obsoletes critical 20535variable assignments. Fortunately, `LIBOBJS' was the only problem, and 20536it can even be handled gracefully (read, "without your having to change 20537something"). 20538 20539 There were two typical uses of `LIBOBJS': asking for a replacement 20540function, and adjusting `LIBOBJS' for Automake and/or Libtool. 20541 20542 20543 As for function replacement, the fix is immediate: use `AC_LIBOBJ'. 20544For instance: 20545 20546 LIBOBJS="$LIBOBJS fnmatch.o" 20547 LIBOBJS="$LIBOBJS malloc.$ac_objext" 20548 20549should be replaced with: 20550 20551 AC_LIBOBJ([fnmatch]) 20552 AC_LIBOBJ([malloc]) 20553 20554 20555 When used with Automake 1.10 or newer, a suitable value for 20556`LIBOBJDIR' is set so that the `LIBOBJS' and `LTLIBOBJS' can be 20557referenced from any `Makefile.am'. Even without Automake, arranging 20558for `LIBOBJDIR' to be set correctly enables referencing `LIBOBJS' and 20559`LTLIBOBJS' in another directory. The `LIBOBJDIR' feature is 20560experimental. 20561 20562 20563File: autoconf.info, Node: AC_ACT_IFELSE vs AC_TRY_ACT, Prev: AC_LIBOBJ vs LIBOBJS, Up: Autoconf 2.13 20564 2056518.6.5 `AC_ACT_IFELSE' vs. `AC_TRY_ACT' 20566--------------------------------------- 20567 20568Since Autoconf 2.50, internal codes uses `AC_PREPROC_IFELSE', 20569`AC_COMPILE_IFELSE', `AC_LINK_IFELSE', and `AC_RUN_IFELSE' on one hand 20570and `AC_LANG_SOURCE', and `AC_LANG_PROGRAM' on the other hand instead 20571of the deprecated `AC_TRY_CPP', `AC_TRY_COMPILE', `AC_TRY_LINK', and 20572`AC_TRY_RUN'. The motivations where: 20573 - a more consistent interface: `AC_TRY_COMPILE' etc. were double 20574 quoting their arguments; 20575 20576 - the combinatoric explosion is solved by decomposing on the one 20577 hand the generation of sources, and on the other hand executing 20578 the program; 20579 20580 - this scheme helps supporting more languages than plain C and C++. 20581 20582 In addition to the change of syntax, the philosophy has changed too: 20583while emphasis was put on speed at the expense of accuracy, today's 20584Autoconf promotes accuracy of the testing framework at, ahem..., the 20585expense of speed. 20586 20587 As a perfect example of what is _not_ to be done, here is how to 20588find out whether a header file contains a particular declaration, such 20589as a typedef, a structure, a structure member, or a function. Use 20590`AC_EGREP_HEADER' instead of running `grep' directly on the header 20591file; on some systems the symbol might be defined in another header 20592file that the file you are checking includes. 20593 20594 As a (bad) example, here is how you should not check for C 20595preprocessor symbols, either defined by header files or predefined by 20596the C preprocessor: using `AC_EGREP_CPP': 20597 20598 AC_EGREP_CPP(yes, 20599 [#ifdef _AIX 20600 yes 20601 #endif 20602 ], is_aix=yes, is_aix=no) 20603 20604 The above example, properly written would (i) use `AC_LANG_PROGRAM', 20605and (ii) run the compiler: 20606 20607 AC_COMPILE_IFELSE([AC_LANG_PROGRAM( 20608 [[#ifndef _AIX 20609 error: This isn't AIX! 20610 #endif 20611 ]])], 20612 [is_aix=yes], 20613 [is_aix=no]) 20614 20615 20616File: autoconf.info, Node: Using Autotest, Next: FAQ, Prev: Obsolete Constructs, Up: Top 20617 2061819 Generating Test Suites with Autotest 20619*************************************** 20620 20621 *N.B.: This section describes a feature which is still 20622 stabilizing. Although we believe that Autotest is useful as-is, this 20623 documentation describes an interface which might change in the future: 20624 do not depend upon Autotest without subscribing to the Autoconf mailing 20625 lists.* 20626 20627 It is paradoxical that portable projects depend on nonportable tools 20628to run their test suite. Autoconf by itself is the paragon of this 20629problem: although it aims at perfectly portability, up to 2.13 its test 20630suite was using DejaGNU, a rich and complex testing framework, but 20631which is far from being standard on Posix systems. Worse yet, it was 20632likely to be missing on the most fragile platforms, the very platforms 20633that are most likely to torture Autoconf and exhibit deficiencies. 20634 20635 To circumvent this problem, many package maintainers have developed 20636their own testing framework, based on simple shell scripts whose sole 20637outputs are exit status values describing whether the test succeeded. 20638Most of these tests share common patterns, and this can result in lots 20639of duplicated code and tedious maintenance. 20640 20641 Following exactly the same reasoning that yielded to the inception of 20642Autoconf, Autotest provides a test suite generation framework, based on 20643M4 macros building a portable shell script. The suite itself is 20644equipped with automatic logging and tracing facilities which greatly 20645diminish the interaction with bug reporters, and simple timing reports. 20646 20647 Autoconf itself has been using Autotest for years, and we do attest 20648that it has considerably improved the strength of the test suite and the 20649quality of bug reports. Other projects are known to use some generation 20650of Autotest, such as Bison, Free Recode, Free Wdiff, GNU Tar, each of 20651them with different needs, and this usage has validated Autotest as a 20652general testing framework. 20653 20654 Nonetheless, compared to DejaGNU, Autotest is inadequate for 20655interactive tool testing, which is probably its main limitation. 20656 20657* Menu: 20658 20659* Using an Autotest Test Suite:: Autotest and the user 20660* Writing Testsuites:: Autotest macros 20661* testsuite Invocation:: Running `testsuite' scripts 20662* Making testsuite Scripts:: Using autom4te to create `testsuite' 20663 20664 20665File: autoconf.info, Node: Using an Autotest Test Suite, Next: Writing Testsuites, Up: Using Autotest 20666 2066719.1 Using an Autotest Test Suite 20668================================= 20669 20670* Menu: 20671 20672* testsuite Scripts:: The concepts of Autotest 20673* Autotest Logs:: Their contents 20674 20675 20676File: autoconf.info, Node: testsuite Scripts, Next: Autotest Logs, Up: Using an Autotest Test Suite 20677 2067819.1.1 `testsuite' Scripts 20679-------------------------- 20680 20681Generating testing or validation suites using Autotest is rather easy. 20682The whole validation suite is held in a file to be processed through 20683`autom4te', itself using GNU M4 under the hood, to produce a 20684stand-alone Bourne shell script which then gets distributed. Neither 20685`autom4te' nor GNU M4 are needed at the installer's end. 20686 20687 Each test of the validation suite should be part of some test group. 20688A "test group" is a sequence of interwoven tests that ought to be 20689executed together, usually because one test in the group creates data 20690files that a later test in the same group needs to read. Complex test 20691groups make later debugging more tedious. It is much better to keep 20692only a few tests per test group. Ideally there is only one test per 20693test group. 20694 20695 For all but the simplest packages, some file such as `testsuite.at' 20696does not fully hold all test sources, as these are often easier to 20697maintain in separate files. Each of these separate files holds a single 20698test group, or a sequence of test groups all addressing some common 20699functionality in the package. In such cases, `testsuite.at' merely 20700initializes the validation suite, and sometimes does elementary health 20701checking, before listing include statements for all other test files. 20702The special file `package.m4', containing the identification of the 20703package, is automatically included if found. 20704 20705 A convenient alternative consists in moving all the global issues 20706(local Autotest macros, elementary health checking, and `AT_INIT' 20707invocation) into the file `local.at', and making `testsuite.at' be a 20708simple list of `m4_include's of sub test suites. In such case, 20709generating the whole test suite or pieces of it is only a matter of 20710choosing the `autom4te' command line arguments. 20711 20712 The validation scripts that Autotest produces are by convention 20713called `testsuite'. When run, `testsuite' executes each test group in 20714turn, producing only one summary line per test to say if that 20715particular test succeeded or failed. At end of all tests, summarizing 20716counters get printed. One debugging directory is left for each test 20717group which failed, if any: such directories are named 20718`testsuite.dir/NN', where NN is the sequence number of the test group, 20719and they include: 20720 20721 * a debugging script named `run' which reruns the test in "debug 20722 mode" (*note testsuite Invocation::). The automatic generation of 20723 debugging scripts has the purpose of easing the chase for bugs. 20724 20725 * all the files created with `AT_DATA' 20726 20727 * all the Erlang source code files created with `AT_CHECK_EUNIT' 20728 20729 * a log of the run, named `testsuite.log' 20730 20731 In the ideal situation, none of the tests fail, and consequently no 20732debugging directory is left behind for validation. 20733 20734 It often happens in practice that individual tests in the validation 20735suite need to get information coming out of the configuration process. 20736Some of this information, common for all validation suites, is provided 20737through the file `atconfig', automatically created by 20738`AC_CONFIG_TESTDIR'. For configuration information which your testing 20739environment specifically needs, you might prepare an optional file 20740named `atlocal.in', instantiated by `AC_CONFIG_FILES'. The 20741configuration process produces `atconfig' and `atlocal' out of these 20742two input files, and these two produced files are automatically read by 20743the `testsuite' script. 20744 20745 Here is a diagram showing the relationship between files. 20746 20747Files used in preparing a software package for distribution: 20748 20749 [package.m4] -->. 20750 \ 20751 subfile-1.at ->. [local.at] ---->+ 20752 ... \ \ 20753 subfile-i.at ---->-- testsuite.at -->-- autom4te* -->testsuite 20754 ... / 20755 subfile-n.at ->' 20756 20757Files used in configuring a software package: 20758 20759 .--> atconfig 20760 / 20761 [atlocal.in] --> config.status* --< 20762 \ 20763 `--> [atlocal] 20764 20765Files created during test suite execution: 20766 20767 atconfig -->. .--> testsuite.log 20768 \ / 20769 >-- testsuite* --< 20770 / \ 20771 [atlocal] ->' `--> [testsuite.dir] 20772 20773 20774File: autoconf.info, Node: Autotest Logs, Prev: testsuite Scripts, Up: Using an Autotest Test Suite 20775 2077619.1.2 Autotest Logs 20777-------------------- 20778 20779When run, the test suite creates a log file named after itself, e.g., a 20780test suite named `testsuite' creates `testsuite.log'. It contains a 20781lot of information, usually more than maintainers actually need, but 20782therefore most of the time it contains all that is needed: 20783 20784command line arguments 20785 A bad but unfortunately widespread habit consists of setting 20786 environment variables before the command, such as in 20787 `CC=my-home-grown-cc ./testsuite'. The test suite does not know 20788 this change, hence (i) it cannot report it to you, and (ii) it 20789 cannot preserve the value of `CC' for subsequent runs. Autoconf 20790 faced exactly the same problem, and solved it by asking users to 20791 pass the variable definitions as command line arguments. Autotest 20792 requires this rule, too, but has no means to enforce it; the log 20793 then contains a trace of the variables that were changed by the 20794 user. 20795 20796`ChangeLog' excerpts 20797 The topmost lines of all the `ChangeLog' files found in the source 20798 hierarchy. This is especially useful when bugs are reported 20799 against development versions of the package, since the version 20800 string does not provide sufficient information to know the exact 20801 state of the sources the user compiled. Of course, this relies on 20802 the use of a `ChangeLog'. 20803 20804build machine 20805 Running a test suite in a cross-compile environment is not an easy 20806 task, since it would mean having the test suite run on a machine 20807 BUILD, while running programs on a machine HOST. It is much 20808 simpler to run both the test suite and the programs on HOST, but 20809 then, from the point of view of the test suite, there remains a 20810 single environment, HOST = BUILD. The log contains relevant 20811 information on the state of the BUILD machine, including some 20812 important environment variables. 20813 20814tested programs 20815 The absolute file name and answers to `--version' of the tested 20816 programs (see *note Writing Testsuites::, `AT_TESTED'). 20817 20818configuration log 20819 The contents of `config.log', as created by `configure', are 20820 appended. It contains the configuration flags and a detailed 20821 report on the configuration itself. 20822 20823 20824File: autoconf.info, Node: Writing Testsuites, Next: testsuite Invocation, Prev: Using an Autotest Test Suite, Up: Using Autotest 20825 2082619.2 Writing `testsuite.at' 20827=========================== 20828 20829The `testsuite.at' is a Bourne shell script making use of special 20830Autotest M4 macros. It often contains a call to `AT_INIT' near its 20831beginning followed by one call to `m4_include' per source file for 20832tests. Each such included file, or the remainder of `testsuite.at' if 20833include files are not used, contain a sequence of test groups. Each 20834test group begins with a call to `AT_SETUP', then an arbitrary number 20835of shell commands or calls to `AT_CHECK', and then completes with a 20836call to `AT_CLEANUP'. Multiple test groups can be categorized by a 20837call to `AT_BANNER'. 20838 20839 All of the public Autotest macros have all-uppercase names in the 20840namespace `^AT_' to prevent them from accidentally conflicting with 20841other text; Autoconf also reserves the namespace `^_AT_' for internal 20842macros. All shell variables used in the testsuite for internal 20843purposes have mostly-lowercase names starting with `at_'. Autotest 20844also uses here-document delimiters in the namespace `^_AT[A-Z]', and 20845makes use of the file system namespace `^at-'. 20846 20847 Since Autoconf is built on top of M4sugar (*note Programming in 20848M4sugar::) and M4sh (*note Programming in M4sh::), you must also be 20849aware of those namespaces (`^_?\(m4\|AS\)_'). In general, you _should 20850not use_ the namespace of a package that does not own the macro or 20851shell code you are writing. 20852 20853 -- Macro: AT_INIT ([NAME]) 20854 Initialize Autotest. Giving a NAME to the test suite is 20855 encouraged if your package includes several test suites. Before 20856 this macro is called, `AT_PACKAGE_STRING' and 20857 `AT_PACKAGE_BUGREPORT' must be defined, which are used to display 20858 information about the testsuite to the user. Typically, these 20859 macros are provided by a file `package.m4' built by `make' (*note 20860 Making testsuite Scripts::), in order to inherit the package name, 20861 version, and bug reporting address from `configure.ac'. 20862 20863 -- Macro: AT_COPYRIGHT (COPYRIGHT-NOTICE) 20864 State that, in addition to the Free Software Foundation's 20865 copyright on the Autotest macros, parts of your test suite are 20866 covered by COPYRIGHT-NOTICE. 20867 20868 The COPYRIGHT-NOTICE shows up in both the head of `testsuite' and 20869 in `testsuite --version'. 20870 20871 -- Macro: AT_ARG_OPTION (OPTIONS, HELP-TEXT, [ACTION-IF-GIVEN], 20872 [ACTION-IF-NOT-GIVEN]) 20873 Accept options from the space-separated list OPTIONS, a list that 20874 has leading dashes removed from the options. Long options will be 20875 prefixed with `--', single-character options with `-'. The first 20876 word in this list is the primary OPTION, any others are assumed to 20877 be short-hand aliases. The variable associated with it is 20878 `at_arg_OPTION', with any dashes in OPTION replaced with 20879 underscores. 20880 20881 If the user passes `--OPTION' to the `testsuite', the variable 20882 will be set to `:'. If the user does not pass the option, or 20883 passes `--no-OPTION', then the variable will be set to `false'. 20884 20885 ACTION-IF-GIVEN is run each time the option is encountered; here, 20886 the variable `at_optarg' will be set to `:' or `false' as 20887 appropriate. `at_optarg' is actually just a copy of 20888 `at_arg_OPTION'. 20889 20890 ACTION-IF-NOT-GIVEN will be run once after option parsing is 20891 complete and if no option from OPTIONS was used. 20892 20893 HELP-TEXT is added to the end of the list of options shown in 20894 `testsuite --help' (*note AS_HELP_STRING::). 20895 20896 It is recommended that you use a package-specific prefix to OPTIONS 20897 names in order to avoid clashes with future Autotest built-in 20898 options. 20899 20900 -- Macro: AT_ARG_OPTION_ARG (OPTIONS, HELP-TEXT, [ACTION-IF-GIVEN], 20901 [ACTION-IF-NOT-GIVEN]) 20902 Accept options with arguments from the space-separated list 20903 OPTIONS, a list that has leading dashes removed from the options. 20904 Long options will be prefixed with `--', single-character options 20905 with `-'. The first word in this list is the primary OPTION, any 20906 others are assumed to be short-hand aliases. The variable 20907 associated with it is `at_arg_OPTION', with any dashes in OPTION 20908 replaced with underscores. 20909 20910 If the user passes `--OPTION=ARG' or `--OPTION ARG' to the 20911 `testsuite', the variable will be set to `ARG'. 20912 20913 ACTION-IF-GIVEN is run each time the option is encountered; here, 20914 the variable `at_optarg' will be set to `ARG'. `at_optarg' is 20915 actually just a copy of `at_arg_OPTION'. 20916 20917 ACTION-IF-NOT-GIVEN will be run once after option parsing is 20918 complete and if no option from OPTIONS was used. 20919 20920 HELP-TEXT is added to the end of the list of options shown in 20921 `testsuite --help' (*note AS_HELP_STRING::). 20922 20923 It is recommended that you use a package-specific prefix to OPTIONS 20924 names in order to avoid clashes with future Autotest built-in 20925 options. 20926 20927 -- Macro: AT_COLOR_TESTS 20928 Enable colored test results by default when the output is 20929 connected to a terminal. 20930 20931 -- Macro: AT_TESTED (EXECUTABLES) 20932 Log the file name and answer to `--version' of each program in 20933 space-separated list EXECUTABLES. Several invocations register 20934 new executables, in other words, don't fear registering one program 20935 several times. 20936 20937 Autotest test suites rely on `PATH' to find the tested program. 20938 This avoids the need to generate absolute names of the various 20939 tools, and makes it possible to test installed programs. 20940 Therefore, knowing which programs are being exercised is crucial 20941 to understanding problems in the test suite itself, or its 20942 occasional misuses. It is a good idea to also subscribe foreign 20943 programs you depend upon, to avoid incompatible diagnostics. 20944 20945 20946 -- Macro: AT_BANNER (TEST-CATEGORY-NAME) 20947 This macro identifies the start of a category of related test 20948 groups. When the resulting `testsuite' is invoked with more than 20949 one test group to run, its output will include a banner containing 20950 TEST-CATEGORY-NAME prior to any tests run from that category. The 20951 banner should be no more than about 40 or 50 characters. A blank 20952 banner indicates uncategorized tests; an empty line will be 20953 inserted after tests from an earlier category, effectively ending 20954 that category. 20955 20956 -- Macro: AT_SETUP (TEST-GROUP-NAME) 20957 This macro starts a group of related tests, all to be executed in 20958 the same subshell. It accepts a single argument, which holds a 20959 few words (no more than about 30 or 40 characters) quickly 20960 describing the purpose of the test group being started. 20961 TEST-GROUP-NAME must not expand to unbalanced quotes, although 20962 quadrigraphs can be used. 20963 20964 -- Macro: AT_KEYWORDS (KEYWORDS) 20965 Associate the space-separated list of KEYWORDS to the enclosing 20966 test group. This makes it possible to run "slices" of the test 20967 suite. For instance, if some of your test groups exercise some 20968 `foo' feature, then using `AT_KEYWORDS(foo)' lets you run 20969 `./testsuite -k foo' to run exclusively these test groups. The 20970 TEST-GROUP-NAME of the test group is automatically recorded to 20971 `AT_KEYWORDS'. 20972 20973 Several invocations within a test group accumulate new keywords. 20974 In other words, don't fear registering the same keyword several 20975 times in a test group. 20976 20977 -- Macro: AT_CAPTURE_FILE (FILE) 20978 If the current test group fails, log the contents of FILE. 20979 Several identical calls within one test group have no additional 20980 effect. 20981 20982 -- Macro: AT_FAIL_IF (SHELL-CONDITION) 20983 Make the test group fail and skip the rest of its execution, if 20984 SHELL-CONDITION is true. SHELL-CONDITION is a shell expression 20985 such as a `test' command. Tests before `AT_FAIL_IF' will be 20986 executed and may still cause the test group to be skipped. You 20987 can instantiate this macro many times from within the same test 20988 group. 20989 20990 You should use this macro only for very simple failure conditions. 20991 If the SHELL-CONDITION could emit any kind of output you should 20992 instead use `AT_CHECK' like 20993 AT_CHECK([if SHELL-CONDITION; then exit 99; fi]) 20994 so that such output is properly recorded in the `testsuite.log' 20995 file. 20996 20997 -- Macro: AT_SKIP_IF (SHELL-CONDITION) 20998 Determine whether the test should be skipped because it requires 20999 features that are unsupported on the machine under test. 21000 SHELL-CONDITION is a shell expression such as a `test' command. 21001 Tests before `AT_SKIP_IF' will be executed and may still cause the 21002 test group to fail. You can instantiate this macro many times 21003 from within the same test group. 21004 21005 You should use this macro only for very simple skip conditions. 21006 If the SHELL-CONDITION could emit any kind of output you should 21007 instead use `AT_CHECK' like 21008 AT_CHECK([if SHELL-CONDITION; then exit 77; fi]) 21009 so that such output is properly recorded in the `testsuite.log' 21010 file. 21011 21012 -- Macro: AT_XFAIL_IF (SHELL-CONDITION) 21013 Determine whether the test is expected to fail because it is a 21014 known bug (for unsupported features, you should skip the test). 21015 SHELL-CONDITION is a shell expression such as a `test' command; 21016 you can instantiate this macro many times from within the same 21017 test group, and one of the conditions is enough to turn the test 21018 into an expected failure. 21019 21020 -- Macro: AT_CLEANUP 21021 End the current test group. 21022 21023 21024 -- Macro: AT_DATA (FILE, CONTENTS) 21025 Initialize an input data FILE with given CONTENTS. Of course, the 21026 CONTENTS have to be properly quoted between square brackets to 21027 protect against included commas or spurious M4 expansion. 21028 CONTENTS must be empty or end with a newline. FILE must be a 21029 single shell word that expands into a single file name. 21030 21031 -- Macro: AT_CHECK (COMMANDS, [STATUS = `0'], [STDOUT], [STDERR], 21032 [RUN-IF-FAIL], [RUN-IF-PASS]) 21033 -- Macro: AT_CHECK_UNQUOTED (COMMANDS, [STATUS = `0'], [STDOUT], 21034 [STDERR], [RUN-IF-FAIL], [RUN-IF-PASS]) 21035 Execute a test by performing given shell COMMANDS in a subshell. 21036 COMMANDS is output as-is, so shell expansions are honored. These 21037 commands should normally exit with STATUS, while producing expected 21038 STDOUT and STDERR contents. If COMMANDS exit with unexpected 21039 status 77, then the rest of the test group is skipped. If 21040 COMMANDS exit with unexpected status 99, then the test group is 21041 immediately failed. Otherwise, if this test fails, run shell 21042 commands RUN-IF-FAIL or, if this test passes, run shell commands 21043 RUN-IF-PASS, both inside the current shell execution environment. 21044 At the beginning of RUN-IF-FAIL and RUN-IF-PASS, the status of 21045 COMMANDS is available in the `at_status' shell variable. 21046 21047 This macro must be invoked in between `AT_SETUP' and `AT_CLEANUP'. 21048 21049 If STATUS is the literal `ignore', then the corresponding exit 21050 status is not checked, except for the special cases of 77 (skip) 21051 and 99 (hard failure). The existence of hard failures allows one 21052 to mark a test as an expected failure with `AT_XFAIL_IF' because a 21053 feature has not yet been implemented, but to still distinguish 21054 between gracefully handling the missing feature and dumping core. 21055 A hard failure also inhibits post-test actions in RUN-IF-FAIL. 21056 21057 If the value of the STDOUT or STDERR parameter is one of the 21058 literals in the following table, then the test treats the output 21059 according to the rules of that literal. Otherwise, the value of 21060 the parameter is treated as text that must exactly match the 21061 output given by COMMANDS on standard output and standard error 21062 (including an empty parameter for no output); any differences are 21063 captured in the testsuite log and the test is failed (unless an 21064 unexpected exit status of 77 skipped the test instead). The 21065 difference between `AT_CHECK' and `AT_CHECK_UNQUOTED' is that only 21066 the latter performs shell variable expansion (`$'), command 21067 substitution (``'), and backslash escaping (`\') on comparison 21068 text given in the STDOUT and STDERR arguments; if the text 21069 includes a trailing newline, this would be the same as if it were 21070 specified via an unquoted here-document. (However, there is no 21071 difference in the interpretation of COMMANDS). 21072 21073 `ignore' 21074 The content of the output is ignored, but still captured in 21075 the test group log (if the testsuite is run with option `-v', 21076 the test group log is displayed as the test is run; if the 21077 test group later fails, the test group log is also copied 21078 into the overall testsuite log). This action is valid for 21079 both STDOUT and STDERR. 21080 21081 `ignore-nolog' 21082 The content of the output is ignored, and nothing is captured 21083 in the log files. If COMMANDS are likely to produce binary 21084 output (including long lines) or large amounts of output, 21085 then logging the output can make it harder to locate details 21086 related to subsequent tests within the group, and could 21087 potentially corrupt terminal display of a user running 21088 `testsuite -v'. 21089 21090 `stdout' 21091 For the STDOUT parameter, capture the content of standard 21092 output to both the file `stdout' and the test group log. 21093 Subsequent commands in the test group can then post-process 21094 the file. This action is often used when it is desired to 21095 use `grep' to look for a substring in the output, or when the 21096 output must be post-processed to normalize error messages 21097 into a common form. 21098 21099 `stderr' 21100 Like `stdout', except that it only works for the STDERR 21101 parameter, and the standard error capture file will be named 21102 `stderr'. 21103 21104 `stdout-nolog' 21105 `stderr-nolog' 21106 Like `stdout' or `stderr', except that the captured output is 21107 not duplicated into the test group log. This action is 21108 particularly useful for an intermediate check that produces 21109 large amounts of data, which will be followed by another 21110 check that filters down to the relevant data, as it makes it 21111 easier to locate details in the log. 21112 21113 `expout' 21114 For the STDOUT parameter, compare standard output contents 21115 with the previously created file `expout', and list any 21116 differences in the testsuite log. 21117 21118 `experr' 21119 Like `expout', except that it only works for the STDERR 21120 parameter, and the standard error contents are compared with 21121 `experr'. 21122 21123 -- Macro: AT_CHECK_EUNIT (MODULE, TEST-SPEC, [ERLFLAGS], 21124 [RUN-IF-FAIL], [RUN-IF-PASS]) 21125 Initialize and execute an Erlang module named MODULE that performs 21126 tests following the TEST-SPEC EUnit test specification. TEST-SPEC 21127 must be a valid EUnit test specification, as defined in the EUnit 21128 Reference Manual (http://erlang.org/doc/apps/eunit/index.html). 21129 ERLFLAGS are optional command-line options passed to the Erlang 21130 interpreter to execute the test Erlang module. Typically, 21131 ERLFLAGS defines at least the paths to directories containing the 21132 compiled Erlang modules under test, as `-pa path1 path2 ...'. 21133 21134 For example, the unit tests associated with Erlang module `testme', 21135 which compiled code is in subdirectory `src', can be performed 21136 with: 21137 21138 AT_CHECK_EUNIT([testme_testsuite], [{module, testme}], 21139 [-pa "${abs_top_builddir}/src"]) 21140 21141 This macro must be invoked in between `AT_SETUP' and `AT_CLEANUP'. 21142 21143 Variables `ERL', `ERLC', and (optionally) `ERLCFLAGS' must be 21144 defined as the path of the Erlang interpreter, the path of the 21145 Erlang compiler, and the command-line flags to pass to the 21146 compiler, respectively. Those variables should be configured in 21147 `configure.ac' using the `AC_ERLANG_PATH_ERL' and 21148 `AC_ERLANG_PATH_ERLC' macros, and the configured values of those 21149 variables are automatically defined in the testsuite. If `ERL' or 21150 `ERLC' is not defined, the test group is skipped. 21151 21152 If the EUnit library cannot be found, i.e. if module `eunit' cannot 21153 be loaded, the test group is skipped. Otherwise, if TEST-SPEC is 21154 an invalid EUnit test specification, the test group fails. 21155 Otherwise, if the EUnit test passes, shell commands RUN-IF-PASS 21156 are executed or, if the EUnit test fails, shell commands 21157 RUN-IF-FAIL are executed and the test group fails. 21158 21159 Only the generated test Erlang module is automatically compiled and 21160 executed. If TEST-SPEC involves testing other Erlang modules, 21161 e.g. module `testme' in the example above, those modules must be 21162 already compiled. 21163 21164 If the testsuite is run in verbose mode, with option `--verbose', 21165 EUnit is also run in verbose mode to output more details about 21166 individual unit tests. 21167 21168 21169File: autoconf.info, Node: testsuite Invocation, Next: Making testsuite Scripts, Prev: Writing Testsuites, Up: Using Autotest 21170 2117119.3 Running `testsuite' Scripts 21172================================ 21173 21174Autotest test suites support the following options: 21175 21176`--help' 21177`-h' 21178 Display the list of options and exit successfully. 21179 21180`--version' 21181`-V' 21182 Display the version of the test suite and exit successfully. 21183 21184`--directory=DIR' 21185`-C DIR' 21186 Change the current directory to DIR before creating any files. 21187 Useful for running the testsuite in a subdirectory from a top-level 21188 Makefile. 21189 21190`--jobs[=N]' 21191`-j[N]' 21192 Run N tests in parallel, if possible. If N is not given, run all 21193 given tests in parallel. Note that there should be no space 21194 before the argument to `-j', as `-j NUMBER' denotes the separate 21195 arguments `-j' and `NUMBER', see below. 21196 21197 In parallel mode, the standard input device of the testsuite 21198 script is not available to commands inside a test group. 21199 Furthermore, banner lines are not printed, and the summary line 21200 for each test group is output after the test group completes. 21201 Summary lines may appear unordered. If verbose and trace output 21202 are enabled (see below), they may appear intermixed from 21203 concurrently running tests. 21204 21205 Parallel mode requires the `mkfifo' command to work, and will be 21206 silently disabled otherwise. 21207 21208`--clean' 21209`-c' 21210 Remove all the files the test suite might have created and exit. 21211 Meant for `clean' Make targets. 21212 21213`--list' 21214`-l' 21215 List all the tests (or only the selection), including their 21216 possible keywords. 21217 21218 21219 By default all tests are performed (or described with `--list') 21220silently in the default environment, but the environment, set of tests, 21221and verbosity level can be tuned: 21222 21223`VARIABLE=VALUE' 21224 Set the environment VARIABLE to VALUE. Use this rather than 21225 `FOO=foo ./testsuite' as debugging scripts would then run in a 21226 different environment. 21227 21228 The variable `AUTOTEST_PATH' specifies the testing path to prepend 21229 to `PATH'. Relative directory names (not starting with `/') are 21230 considered to be relative to the top level of the package being 21231 built. All directories are made absolute, first starting from the 21232 top level _build_ tree, then from the _source_ tree. For instance 21233 `./testsuite AUTOTEST_PATH=tests:bin' for a `/src/foo-1.0' source 21234 package built in `/tmp/foo' results in 21235 `/tmp/foo/tests:/tmp/foo/bin' and then 21236 `/src/foo-1.0/tests:/src/foo-1.0/bin' being prepended to `PATH'. 21237 21238`NUMBER' 21239`NUMBER-NUMBER' 21240`NUMBER-' 21241`-NUMBER' 21242 Add the corresponding test groups, with obvious semantics, to the 21243 selection. 21244 21245`--keywords=KEYWORDS' 21246`-k KEYWORDS' 21247 Add to the selection the test groups with title or keywords 21248 (arguments to `AT_SETUP' or `AT_KEYWORDS') that match _all_ 21249 keywords of the comma separated list KEYWORDS, case-insensitively. 21250 Use `!' immediately before the keyword to invert the selection for 21251 this keyword. By default, the keywords match whole words; enclose 21252 them in `.*' to also match parts of words. 21253 21254 For example, running 21255 21256 ./testsuite -k 'autoupdate,.*FUNC.*' 21257 21258 selects all tests tagged `autoupdate' _and_ with tags containing 21259 `FUNC' (as in `AC_CHECK_FUNC', `AC_FUNC_ALLOCA', etc.), while 21260 21261 ./testsuite -k '!autoupdate' -k '.*FUNC.*' 21262 21263 selects all tests not tagged `autoupdate' _or_ with tags 21264 containing `FUNC'. 21265 21266`--errexit' 21267`-e' 21268 If any test fails, immediately abort testing. This implies 21269 `--debug': post test group clean up, and top-level logging are 21270 inhibited. This option is meant for the full test suite, it is 21271 not really useful for generated debugging scripts. If the 21272 testsuite is run in parallel mode using `--jobs', then 21273 concurrently running tests will finish before exiting. 21274 21275`--verbose' 21276`-v' 21277 Force more verbosity in the detailed output of what is being done. 21278 This is the default for debugging scripts. 21279 21280`--color' 21281`--color[=never|auto|always]' 21282 Enable colored test results. Without an argument, or with 21283 `always', test results will be colored. With `never', color mode 21284 is turned off. Otherwise, if either the macro `AT_COLOR_TESTS' is 21285 used by the testsuite author, or the argument `auto' is given, 21286 then test results are colored if standard output is connected to a 21287 terminal. 21288 21289`--debug' 21290`-d' 21291 Do not remove the files after a test group was performed--but they 21292 are still removed _before_, therefore using this option is sane 21293 when running several test groups. Create debugging scripts. Do 21294 not overwrite the top-level log (in order to preserve a supposedly 21295 existing full log file). This is the default for debugging 21296 scripts, but it can also be useful to debug the testsuite itself. 21297 21298`--recheck' 21299 Add to the selection all test groups that failed or passed 21300 unexpectedly during the last non-debugging test run. 21301 21302`--trace' 21303`-x' 21304 Trigger shell tracing of the test groups. 21305 21306 Besides these options accepted by every Autotest testsuite, the 21307testsuite author might have added package-specific options via the 21308`AT_ARG_OPTION' and `AT_ARG_OPTION_ARG' macros (*note Writing 21309Testsuites::); refer to `testsuite --help' and the package 21310documentation for details. 21311 21312 21313File: autoconf.info, Node: Making testsuite Scripts, Prev: testsuite Invocation, Up: Using Autotest 21314 2131519.4 Making `testsuite' Scripts 21316=============================== 21317 21318For putting Autotest into movement, you need some configuration and 21319makefile machinery. We recommend, at least if your package uses deep or 21320shallow hierarchies, that you use `tests/' as the name of the directory 21321holding all your tests and their makefile. Here is a check list of 21322things to do. 21323 21324 - Make sure to create the file `package.m4', which defines the 21325 identity of the package. It must define `AT_PACKAGE_STRING', the 21326 full signature of the package, and `AT_PACKAGE_BUGREPORT', the 21327 address to which bug reports should be sent. For sake of 21328 completeness, we suggest that you also define `AT_PACKAGE_NAME', 21329 `AT_PACKAGE_TARNAME', `AT_PACKAGE_VERSION', and `AT_PACKAGE_URL'. 21330 *Note Initializing configure::, for a description of these 21331 variables. Be sure to distribute `package.m4' and to put it into 21332 the source hierarchy: the test suite ought to be shipped! See 21333 below for an example `Makefile' excerpt. 21334 21335 - Invoke `AC_CONFIG_TESTDIR'. 21336 21337 -- Macro: AC_CONFIG_TESTDIR (DIRECTORY, [TEST-PATH = `directory']) 21338 An Autotest test suite is to be configured in DIRECTORY. This 21339 macro causes `DIRECTORY/atconfig' to be created by 21340 `config.status' and sets the default `AUTOTEST_PATH' to 21341 TEST-PATH (*note testsuite Invocation::). 21342 21343 - Still within `configure.ac', as appropriate, ensure that some 21344 `AC_CONFIG_FILES' command includes substitution for 21345 `tests/atlocal'. 21346 21347 - The appropriate `Makefile' should be modified so the validation in 21348 your package is triggered by `make check'. An example is provided 21349 below. 21350 21351 With Automake, here is a minimal example for inclusion in 21352`tests/Makefile.am', in order to link `make check' with a validation 21353suite. 21354 21355 # The `:;' works around a Bash 3.2 bug when the output is not writable. 21356 $(srcdir)/package.m4: $(top_srcdir)/configure.ac 21357 :;{ \ 21358 echo '# Signature of the current package.' && \ 21359 echo 'm4_define([AT_PACKAGE_NAME],' && \ 21360 echo ' [$(PACKAGE_NAME)])' && \ 21361 echo 'm4_define([AT_PACKAGE_TARNAME],' && \ 21362 echo ' [$(PACKAGE_TARNAME)])' && \ 21363 echo 'm4_define([AT_PACKAGE_VERSION],' && \ 21364 echo ' [$(PACKAGE_VERSION)])' && \ 21365 echo 'm4_define([AT_PACKAGE_STRING],' && \ 21366 echo ' [$(PACKAGE_STRING)])' && \ 21367 echo 'm4_define([AT_PACKAGE_BUGREPORT],' && \ 21368 echo ' [$(PACKAGE_BUGREPORT)])'; \ 21369 echo 'm4_define([AT_PACKAGE_URL],' && \ 21370 echo ' [$(PACKAGE_URL)])'; \ 21371 } >'$(srcdir)/package.m4' 21372 21373 EXTRA_DIST = testsuite.at $(srcdir)/package.m4 $(TESTSUITE) atlocal.in 21374 TESTSUITE = $(srcdir)/testsuite 21375 21376 check-local: atconfig atlocal $(TESTSUITE) 21377 $(SHELL) '$(TESTSUITE)' $(TESTSUITEFLAGS) 21378 21379 installcheck-local: atconfig atlocal $(TESTSUITE) 21380 $(SHELL) '$(TESTSUITE)' AUTOTEST_PATH='$(bindir)' \ 21381 $(TESTSUITEFLAGS) 21382 21383 clean-local: 21384 test ! -f '$(TESTSUITE)' || \ 21385 $(SHELL) '$(TESTSUITE)' --clean 21386 21387 AUTOM4TE = $(SHELL) $(srcdir)/build-aux/missing --run autom4te 21388 AUTOTEST = $(AUTOM4TE) --language=autotest 21389 $(TESTSUITE): $(srcdir)/testsuite.at $(srcdir)/package.m4 21390 $(AUTOTEST) -I '$(srcdir)' -o $@.tmp $@.at 21391 mv $@.tmp $@ 21392 21393 Note that the built testsuite is distributed; this is necessary 21394because users might not have Autoconf installed, and thus would not be 21395able to rebuild it. Likewise, the use of `missing' provides the user 21396with a nicer error message if they modify a source file to the 21397testsuite, and accidentally trigger the rebuild rules. 21398 21399 You might want to list explicitly the dependencies, i.e., the list of 21400the files `testsuite.at' includes. 21401 21402 If you don't use Automake, you should include the above example in 21403`tests/Makefile.in', along with additional lines inspired from the 21404following: 21405 21406 subdir = tests 21407 PACKAGE_NAME = @PACKAGE_NAME@ 21408 PACKAGE_TARNAME = @PACKAGE_TARNAME@ 21409 PACKAGE_VERSION = @PACKAGE_VERSION@ 21410 PACKAGE_STRING = @PACKAGE_STRING@ 21411 PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ 21412 PACKAGE_URL = @PACKAGE_URL@ 21413 21414 atconfig: $(top_builddir)/config.status 21415 cd $(top_builddir) && \ 21416 $(SHELL) ./config.status $(subdir)/$@ 21417 21418 atlocal: $(srcdir)/atlocal.in $(top_builddir)/config.status 21419 cd $(top_builddir) && \ 21420 $(SHELL) ./config.status $(subdir)/$@ 21421 21422and manage to have `$(EXTRA_DIST)' distributed. You will also want to 21423distribute the file `build-aux/missing' from the Automake project; a 21424copy of this file resides in the Autoconf source tree. 21425 21426 With all this in place, and if you have not initialized 21427`TESTSUITEFLAGS' within your makefile, you can fine-tune test suite 21428execution with this variable, for example: 21429 21430 make check TESTSUITEFLAGS='-v -d -x 75 -k AC_PROG_CC CFLAGS=-g' 21431 21432 21433File: autoconf.info, Node: FAQ, Next: History, Prev: Using Autotest, Up: Top 21434 2143520 Frequent Autoconf Questions, with answers 21436******************************************** 21437 21438Several questions about Autoconf come up occasionally. Here some of 21439them are addressed. 21440 21441* Menu: 21442 21443* Distributing:: Distributing `configure' scripts 21444* Why GNU M4:: Why not use the standard M4? 21445* Bootstrapping:: Autoconf and GNU M4 require each other? 21446* Why Not Imake:: Why GNU uses `configure' instead of Imake 21447* Defining Directories:: Passing `datadir' to program 21448* Autom4te Cache:: What is it? Can I remove it? 21449* Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree 21450* Expanded Before Required:: Expanded Before Required 21451* Debugging:: Debugging `configure' scripts 21452 21453 21454File: autoconf.info, Node: Distributing, Next: Why GNU M4, Up: FAQ 21455 2145620.1 Distributing `configure' Scripts 21457===================================== 21458 21459 What are the restrictions on distributing `configure' 21460 scripts that Autoconf generates? How does that affect my 21461 programs that use them? 21462 21463 There are no restrictions on how the configuration scripts that 21464Autoconf produces may be distributed or used. In Autoconf version 1, 21465they were covered by the GNU General Public License. We still encourage 21466software authors to distribute their work under terms like those of the 21467GPL, but doing so is not required to use Autoconf. 21468 21469 Of the other files that might be used with `configure', 21470`config.h.in' is under whatever copyright you use for your 21471`configure.ac'. `config.sub' and `config.guess' have an exception to 21472the GPL when they are used with an Autoconf-generated `configure' 21473script, which permits you to distribute them under the same terms as 21474the rest of your package. `install-sh' is from the X Consortium and is 21475not copyrighted. 21476 21477 21478File: autoconf.info, Node: Why GNU M4, Next: Bootstrapping, Prev: Distributing, Up: FAQ 21479 2148020.2 Why Require GNU M4? 21481======================== 21482 21483 Why does Autoconf require GNU M4? 21484 21485 Many M4 implementations have hard-coded limitations on the size and 21486number of macros that Autoconf exceeds. They also lack several builtin 21487macros that it would be difficult to get along without in a 21488sophisticated application like Autoconf, including: 21489 21490 m4_builtin 21491 m4_indir 21492 m4_bpatsubst 21493 __file__ 21494 __line__ 21495 21496 Autoconf requires version 1.4.6 or later of GNU M4. 21497 21498 Since only software maintainers need to use Autoconf, and since GNU 21499M4 is simple to configure and install, it seems reasonable to require 21500GNU M4 to be installed also. Many maintainers of GNU and other free 21501software already have most of the GNU utilities installed, since they 21502prefer them. 21503 21504 21505File: autoconf.info, Node: Bootstrapping, Next: Why Not Imake, Prev: Why GNU M4, Up: FAQ 21506 2150720.3 How Can I Bootstrap? 21508========================= 21509 21510 If Autoconf requires GNU M4 and GNU M4 has an Autoconf 21511 `configure' script, how do I bootstrap? It seems like a chicken 21512 and egg problem! 21513 21514 This is a misunderstanding. Although GNU M4 does come with a 21515`configure' script produced by Autoconf, Autoconf is not required in 21516order to run the script and install GNU M4. Autoconf is only required 21517if you want to change the M4 `configure' script, which few people have 21518to do (mainly its maintainer). 21519 21520 21521File: autoconf.info, Node: Why Not Imake, Next: Defining Directories, Prev: Bootstrapping, Up: FAQ 21522 2152320.4 Why Not Imake? 21524=================== 21525 21526 Why not use Imake instead of `configure' scripts? 21527 21528 Several people have written addressing this question, so adaptations 21529of their explanations are included here. 21530 21531 The following answer is based on one written by Richard Pixley: 21532 21533 Autoconf generated scripts frequently work on machines that it has 21534 never been set up to handle before. That is, it does a good job of 21535 inferring a configuration for a new system. Imake cannot do this. 21536 21537 Imake uses a common database of host specific data. For X11, this 21538 makes sense because the distribution is made as a collection of 21539 tools, by one central authority who has control over the database. 21540 21541 GNU tools are not released this way. Each GNU tool has a 21542 maintainer; these maintainers are scattered across the world. 21543 Using a common database would be a maintenance nightmare. 21544 Autoconf may appear to be this kind of database, but in fact it is 21545 not. Instead of listing host dependencies, it lists program 21546 requirements. 21547 21548 If you view the GNU suite as a collection of native tools, then the 21549 problems are similar. But the GNU development tools can be 21550 configured as cross tools in almost any host+target permutation. 21551 All of these configurations can be installed concurrently. They 21552 can even be configured to share host independent files across 21553 hosts. Imake doesn't address these issues. 21554 21555 Imake templates are a form of standardization. The GNU coding 21556 standards address the same issues without necessarily imposing the 21557 same restrictions. 21558 21559 Here is some further explanation, written by Per Bothner: 21560 21561 One of the advantages of Imake is that it is easy to generate large 21562 makefiles using the `#include' and macro mechanisms of `cpp'. 21563 However, `cpp' is not programmable: it has limited conditional 21564 facilities, and no looping. And `cpp' cannot inspect its 21565 environment. 21566 21567 All of these problems are solved by using `sh' instead of `cpp'. 21568 The shell is fully programmable, has macro substitution, can 21569 execute (or source) other shell scripts, and can inspect its 21570 environment. 21571 21572 Paul Eggert elaborates more: 21573 21574 With Autoconf, installers need not assume that Imake itself is 21575 already installed and working well. This may not seem like much 21576 of an advantage to people who are accustomed to Imake. But on 21577 many hosts Imake is not installed or the default installation is 21578 not working well, and requiring Imake to install a package hinders 21579 the acceptance of that package on those hosts. For example, the 21580 Imake template and configuration files might not be installed 21581 properly on a host, or the Imake build procedure might wrongly 21582 assume that all source files are in one big directory tree, or the 21583 Imake configuration might assume one compiler whereas the package 21584 or the installer needs to use another, or there might be a version 21585 mismatch between the Imake expected by the package and the Imake 21586 supported by the host. These problems are much rarer with 21587 Autoconf, where each package comes with its own independent 21588 configuration processor. 21589 21590 Also, Imake often suffers from unexpected interactions between 21591 `make' and the installer's C preprocessor. The fundamental problem 21592 here is that the C preprocessor was designed to preprocess C 21593 programs, not makefiles. This is much less of a problem with 21594 Autoconf, which uses the general-purpose preprocessor M4, and 21595 where the package's author (rather than the installer) does the 21596 preprocessing in a standard way. 21597 21598 Finally, Mark Eichin notes: 21599 21600 Imake isn't all that extensible, either. In order to add new 21601 features to Imake, you need to provide your own project template, 21602 and duplicate most of the features of the existing one. This 21603 means that for a sophisticated project, using the vendor-provided 21604 Imake templates fails to provide any leverage--since they don't 21605 cover anything that your own project needs (unless it is an X11 21606 program). 21607 21608 On the other side, though: 21609 21610 The one advantage that Imake has over `configure': `Imakefile' 21611 files tend to be much shorter (likewise, less redundant) than 21612 `Makefile.in' files. There is a fix to this, however--at least 21613 for the Kerberos V5 tree, we've modified things to call in common 21614 `post.in' and `pre.in' makefile fragments for the entire tree. 21615 This means that a lot of common things don't have to be 21616 duplicated, even though they normally are in `configure' setups. 21617 21618 21619File: autoconf.info, Node: Defining Directories, Next: Autom4te Cache, Prev: Why Not Imake, Up: FAQ 21620 2162120.5 How Do I `#define' Installation Directories? 21622================================================= 21623 21624 My program needs library files, installed in `datadir' and 21625 similar. If I use 21626 AC_DEFINE_UNQUOTED([DATADIR], [$datadir], 21627 [Define to the read-only architecture-independent 21628 data directory.]) 21629 21630 I get 21631 #define DATADIR "${prefix}/share" 21632 21633As already explained, this behavior is on purpose, mandated by the GNU 21634Coding Standards, see *note Installation Directory Variables::. There 21635are several means to achieve a similar goal: 21636 21637 - Do not use `AC_DEFINE' but use your makefile to pass the actual 21638 value of `datadir' via compilation flags. *Note Installation 21639 Directory Variables::, for the details. 21640 21641 - This solution can be simplified when compiling a program: you may 21642 either extend the `CPPFLAGS': 21643 21644 CPPFLAGS = -DDATADIR='"$(datadir)"' @CPPFLAGS@ 21645 21646 If you are using Automake, you should use `AM_CPPFLAGS' instead: 21647 21648 AM_CPPFLAGS = -DDATADIR='"$(datadir)"' 21649 21650 Alternatively, create a dedicated header file: 21651 21652 DISTCLEANFILES = myprog-paths.h 21653 myprog-paths.h: Makefile 21654 echo '#define DATADIR "$(datadir)"' >$@ 21655 21656 The gnulib module `configmake' provides such a header with all the 21657 standard directory variables defined, *note configmake: 21658 (gnulib)configmake. 21659 21660 - Use `AC_DEFINE' but have `configure' compute the literal value of 21661 `datadir' and others. Many people have wrapped macros to automate 21662 this task; for an example, see the macro `AC_DEFINE_DIR' from the 21663 Autoconf Macro Archive 21664 (http://www.gnu.org/software/autoconf-archive/). 21665 21666 This solution does not conform to the GNU Coding Standards. 21667 21668 - Note that all the previous solutions hard wire the absolute name of 21669 these directories in the executables, which is not a good 21670 property. You may try to compute the names relative to `prefix', 21671 and try to find `prefix' at runtime, this way your package is 21672 relocatable. 21673 21674 21675File: autoconf.info, Node: Autom4te Cache, Next: Present But Cannot Be Compiled, Prev: Defining Directories, Up: FAQ 21676 2167720.6 What is `autom4te.cache'? 21678============================== 21679 21680 What is this directory `autom4te.cache'? Can I safely remove it? 21681 21682 In the GNU Build System, `configure.ac' plays a central role and is 21683read by many tools: `autoconf' to create `configure', `autoheader' to 21684create `config.h.in', `automake' to create `Makefile.in', `autoscan' to 21685check the completeness of `configure.ac', `autoreconf' to check the GNU 21686Build System components that are used. To "read `configure.ac'" 21687actually means to compile it with M4, which can be a long process for 21688complex `configure.ac'. 21689 21690 This is why all these tools, instead of running directly M4, invoke 21691`autom4te' (*note autom4te Invocation::) which, while answering to a 21692specific demand, stores additional information in `autom4te.cache' for 21693future runs. For instance, if you run `autoconf', behind the scenes, 21694`autom4te' also stores information for the other tools, so that when 21695you invoke `autoheader' or `automake' etc., reprocessing `configure.ac' 21696is not needed. The speed up is frequently 30%, and is increasing with 21697the size of `configure.ac'. 21698 21699 But it is and remains being simply a cache: you can safely remove it. 21700 21701 21702 Can I permanently get rid of it? 21703 21704 The creation of this cache can be disabled from `~/.autom4te.cfg', 21705see *note Customizing autom4te::, for more details. You should be 21706aware that disabling the cache slows down the Autoconf test suite by 2170740%. The more GNU Build System components are used, the more the cache 21708is useful; for instance running `autoreconf -f' on the Core Utilities 21709is twice slower without the cache _although `--force' implies that the 21710cache is not fully exploited_, and eight times slower than without 21711`--force'. 21712 21713 21714File: autoconf.info, Node: Present But Cannot Be Compiled, Next: Expanded Before Required, Prev: Autom4te Cache, Up: FAQ 21715 2171620.7 Header Present But Cannot Be Compiled 21717========================================== 21718 21719The most important guideline to bear in mind when checking for features 21720is to mimic as much as possible the intended use. Unfortunately, old 21721versions of `AC_CHECK_HEADER' and `AC_CHECK_HEADERS' failed to follow 21722this idea, and called the preprocessor, instead of the compiler, to 21723check for headers. As a result, incompatibilities between headers went 21724unnoticed during configuration, and maintainers finally had to deal 21725with this issue elsewhere. 21726 21727 The transition began with Autoconf 2.56. As of Autoconf 2.64 both 21728checks are performed, and `configure' complains loudly if the compiler 21729and the preprocessor do not agree. However, only the compiler result 21730is considered. 21731 21732 Consider the following example: 21733 21734 $ cat number.h 21735 typedef int number; 21736 $ cat pi.h 21737 const number pi = 3; 21738 $ cat configure.ac 21739 AC_INIT([Example], [1.0], [bug-example@example.org]) 21740 AC_CHECK_HEADERS([pi.h]) 21741 $ autoconf -Wall 21742 $ ./configure 21743 checking for gcc... gcc 21744 checking for C compiler default output file name... a.out 21745 checking whether the C compiler works... yes 21746 checking whether we are cross compiling... no 21747 checking for suffix of executables... 21748 checking for suffix of object files... o 21749 checking whether we are using the GNU C compiler... yes 21750 checking whether gcc accepts -g... yes 21751 checking for gcc option to accept ISO C89... none needed 21752 checking how to run the C preprocessor... gcc -E 21753 checking for grep that handles long lines and -e... grep 21754 checking for egrep... grep -E 21755 checking for ANSI C header files... yes 21756 checking for sys/types.h... yes 21757 checking for sys/stat.h... yes 21758 checking for stdlib.h... yes 21759 checking for string.h... yes 21760 checking for memory.h... yes 21761 checking for strings.h... yes 21762 checking for inttypes.h... yes 21763 checking for stdint.h... yes 21764 checking for unistd.h... yes 21765 checking pi.h usability... no 21766 checking pi.h presence... yes 21767 configure: WARNING: pi.h: present but cannot be compiled 21768 configure: WARNING: pi.h: check for missing prerequisite headers? 21769 configure: WARNING: pi.h: see the Autoconf documentation 21770 configure: WARNING: pi.h: section "Present But Cannot Be Compiled" 21771 configure: WARNING: pi.h: proceeding with the compiler's result 21772 configure: WARNING: ## -------------------------------------- ## 21773 configure: WARNING: ## Report this to bug-example@example.org ## 21774 configure: WARNING: ## -------------------------------------- ## 21775 checking for pi.h... yes 21776 21777The proper way the handle this case is using the fourth argument (*note 21778Generic Headers::): 21779 21780 $ cat configure.ac 21781 AC_INIT([Example], [1.0], [bug-example@example.org]) 21782 AC_CHECK_HEADERS([number.h pi.h], [], [], 21783 [[#ifdef HAVE_NUMBER_H 21784 # include <number.h> 21785 #endif 21786 ]]) 21787 $ autoconf -Wall 21788 $ ./configure 21789 checking for gcc... gcc 21790 checking for C compiler default output... a.out 21791 checking whether the C compiler works... yes 21792 checking whether we are cross compiling... no 21793 checking for suffix of executables... 21794 checking for suffix of object files... o 21795 checking whether we are using the GNU C compiler... yes 21796 checking whether gcc accepts -g... yes 21797 checking for gcc option to accept ANSI C... none needed 21798 checking for number.h... yes 21799 checking for pi.h... yes 21800 21801 See *note Particular Headers::, for a list of headers with their 21802prerequisites. 21803 21804 21805File: autoconf.info, Node: Expanded Before Required, Next: Debugging, Prev: Present But Cannot Be Compiled, Up: FAQ 21806 2180720.8 Expanded Before Required 21808============================= 21809 21810Older versions of Autoconf silently built files with incorrect ordering 21811between dependent macros if an outer macro first expanded, then later 21812indirectly required, an inner macro. Starting with Autoconf 2.64, this 21813situation no longer generates out-of-order code, but results in 21814duplicate output and a syntax warning: 21815 21816 $ cat configure.ac 21817 =>AC_DEFUN([TESTA], [[echo in A 21818 =>if test -n "$SEEN_A" ; then echo duplicate ; fi 21819 =>SEEN_A=:]]) 21820 =>AC_DEFUN([TESTB], [AC_REQUIRE([TESTA])[echo in B 21821 =>if test -z "$SEEN_A" ; then echo bug ; fi]]) 21822 =>AC_DEFUN([TESTC], [AC_REQUIRE([TESTB])[echo in C]]) 21823 =>AC_DEFUN([OUTER], [[echo in OUTER] 21824 =>TESTA 21825 =>TESTC]) 21826 =>AC_INIT 21827 =>OUTER 21828 =>AC_OUTPUT 21829 $ autoconf 21830 =>configure.ac:11: warning: AC_REQUIRE: 21831 => `TESTA' was expanded before it was required 21832 =>configure.ac:4: TESTB is expanded from... 21833 =>configure.ac:6: TESTC is expanded from... 21834 =>configure.ac:7: OUTER is expanded from... 21835 =>configure.ac:11: the top level 21836 21837To avoid this warning, decide what purpose the macro in question serves. 21838If it only needs to be expanded once (for example, if it provides 21839initialization text used by later macros), then the simplest fix is to 21840change the macro to be declared with `AC_DEFUN_ONCE' (*note One-Shot 21841Macros::), although this only works in Autoconf 2.64 and newer. A more 21842portable fix is to change all instances of direct calls to instead go 21843through `AC_REQUIRE' (*note Prerequisite Macros::). If, instead, the 21844macro is parameterized by arguments or by the current definition of 21845other macros in the m4 environment, then the macro should always be 21846directly expanded instead of required. 21847 21848 For another case study, consider this example trimmed down from an 21849actual package. Originally, the package contained shell code and 21850multiple macro invocations at the top level of `configure.ac': 21851 21852 AC_DEFUN([FOO], [AC_COMPILE_IFELSE([...])]) 21853 foobar= 21854 AC_PROG_CC 21855 FOO 21856 21857but that was getting complex, so the author wanted to offload some of 21858the text into a new macro in another file included via `aclocal.m4'. 21859The nai"ve approach merely wraps the text in a new macro: 21860 21861 AC_DEFUN([FOO], [AC_COMPILE_IFELSE([...])]) 21862 AC_DEFUN([BAR], [ 21863 foobar= 21864 AC_PROG_CC 21865 FOO 21866 ]) 21867 BAR 21868 21869With older versions of Autoconf, the setting of `foobar=' occurs before 21870the single compiler check, as the author intended. But with Autoconf 218712.64, this issues the "expanded before it was required" warning for 21872`AC_PROG_CC', and outputs two copies of the compiler check, one before 21873`foobar=', and one after. To understand why this is happening, 21874remember that the use of `AC_COMPILE_IFELSE' includes a call to 21875`AC_REQUIRE([AC_PROG_CC])' under the hood. According to the documented 21876semantics of `AC_REQUIRE', this means that `AC_PROG_CC' _must_ occur 21877before the body of the outermost `AC_DEFUN', which in this case is 21878`BAR', thus preceding the use of `foobar='. The older versions of 21879Autoconf were broken with regards to the rules of `AC_REQUIRE', which 21880explains why the code changed from one over to two copies of 21881`AC_PROG_CC' when upgrading autoconf. In other words, the author was 21882unknowingly relying on a bug exploit to get the desired results, and 21883that exploit broke once the bug was fixed. 21884 21885 So, what recourse does the author have, to restore their intended 21886semantics of setting `foobar=' prior to a single compiler check, 21887regardless of whether Autoconf 2.63 or 2.64 is used? One idea is to 21888remember that only `AC_DEFUN' is impacted by `AC_REQUIRE'; there is 21889always the possibility of using the lower-level `m4_define': 21890 21891 AC_DEFUN([FOO], [AC_COMPILE_IFELSE([...])]) 21892 m4_define([BAR], [ 21893 foobar= 21894 AC_PROG_CC 21895 FOO 21896 ]) 21897 BAR 21898 21899This works great if everything is in the same file. However, it does 21900not help in the case where the author wants to have `aclocal' find the 21901definition of `BAR' from its own file, since `aclocal' requires the use 21902of `AC_DEFUN'. In this case, a better fix is to recognize that if 21903`BAR' also uses `AC_REQUIRE', then there will no longer be direct 21904expansion prior to a subsequent require. Then, by creating yet another 21905helper macro, the author can once again guarantee a single invocation of 21906`AC_PROG_CC', which will still occur after `foobar='. The author can 21907also use `AC_BEFORE' to make sure no other macro appearing before `BAR' 21908has triggered an unwanted expansion of `AC_PROG_CC'. 21909 21910 AC_DEFUN([FOO], [AC_COMPILE_IFELSE([...])]) 21911 AC_DEFUN([BEFORE_CC], [ 21912 foobar= 21913 ]) 21914 AC_DEFUN([BAR], [ 21915 AC_BEFORE([$0], [AC_PROG_CC])dnl 21916 AC_REQUIRE([BEFORE_CC])dnl 21917 AC_REQUIRE([AC_PROG_CC])dnl 21918 FOO 21919 ]) 21920 BAR 21921 21922 21923File: autoconf.info, Node: Debugging, Prev: Expanded Before Required, Up: FAQ 21924 2192520.9 Debugging `configure' scripts 21926================================== 21927 21928While in general, `configure' scripts generated by Autoconf strive to 21929be fairly portable to various systems, compilers, shells, and other 21930tools, it may still be necessary to debug a failing test, broken script 21931or makefile, or fix or override an incomplete, faulty, or erroneous 21932test, especially during macro development. Failures can occur at all 21933levels, in M4 syntax or semantics, shell script issues, or due to bugs 21934in the test or the tools invoked by `configure'. Together with the 21935rather arcane error message that `m4' and `make' may produce when their 21936input contains syntax errors, this can make debugging rather painful. 21937 21938 Nevertheless, here is a list of hints and strategies that may help: 21939 21940 * When `autoconf' fails, common causes for error include: 21941 21942 * mismatched or unbalanced parentheses or braces (*note 21943 Balancing Parentheses::), 21944 21945 * under- or overquoted macro arguments (*note Autoconf 21946 Language::, *note Quoting and Parameters::, *note Quotation 21947 and Nested Macros::), 21948 21949 * spaces between macro name and opening parenthesis (*note 21950 Autoconf Language::). 21951 21952 Typically, it helps to go back to the last working version of the 21953 input and compare the differences for each of these errors. 21954 Another possibility is to sprinkle pairs of `m4_traceon' and 21955 `m4_traceoff' judiciously in the code, either without a parameter 21956 or listing some macro names and watch `m4' expand its input 21957 verbosely (*note Debugging via autom4te::). 21958 21959 * Sometimes `autoconf' succeeds but the generated `configure' script 21960 has invalid shell syntax. You can detect this case by running 21961 `bash -n configure' or `sh -n configure'. If this command fails, 21962 the same tips apply, as if `autoconf' had failed. 21963 21964 * Debugging `configure' script execution may be done by sprinkling 21965 pairs of `set -x' and `set +x' into the shell script before and 21966 after the region that contains a bug. Running the whole script 21967 with `SHELL -vx ./configure 2>&1 | tee LOG-FILE' with a decent 21968 SHELL may work, but produces lots of output. Here, it can help to 21969 search for markers like `checking for' a particular test in the 21970 LOG-FILE. 21971 21972 * Alternatively, you might use a shell with debugging capabilities 21973 like bashdb (http://bashdb.sourceforge.net/). 21974 21975 * When `configure' tests produce invalid results for your system, it 21976 may be necessary to override them: 21977 21978 * For programs, tools or libraries variables, preprocessor, 21979 compiler, or linker flags, it is often sufficient to override 21980 them at `make' run time with some care (*note Macros and 21981 Submakes::). Since this normally won't cause `configure' to 21982 be run again with these changed settings, it may fail if the 21983 changed variable would have caused different test results 21984 from `configure', so this may work only for simple 21985 differences. 21986 21987 * Most tests which produce their result in a substituted 21988 variable allow to override the test by setting the variable 21989 on the `configure' command line (*note Compilers and 21990 Options::, *note Defining Variables::, *note Particular 21991 Systems::). 21992 21993 * Many tests store their result in a cache variable (*note 21994 Caching Results::). This lets you override them either on the 21995 `configure' command line as above, or through a primed cache 21996 or site file (*note Cache Files::, *note Site Defaults::). 21997 The name of a cache variable is documented with a test macro 21998 or may be inferred from *note Cache Variable Names::; the 21999 precise semantics of undocumented variables are often 22000 internal details, subject to change. 22001 22002 * Alternatively, `configure' may produce invalid results because of 22003 uncaught programming errors, in your package or in an upstream 22004 library package. For example, when `AC_CHECK_LIB' fails to find a 22005 library with a specified function, always check `config.log'. This 22006 will reveal the exact error that produced the failing result: the 22007 library linked by `AC_CHECK_LIB' probably has a fatal bug. 22008 22009 Conversely, as macro author, you can make it easier for users of your 22010macro: 22011 22012 * by minimizing dependencies between tests and between test results 22013 as far as possible, 22014 22015 * by using `make' variables to factorize and allow override of 22016 settings at `make' run time, 22017 22018 * by honoring the GNU Coding Standards and not overriding flags 22019 reserved for the user except temporarily during `configure' tests, 22020 22021 * by not requiring users of your macro to use the cache variables. 22022 Instead, expose the result of the test via RUN-IF-TRUE and 22023 RUN-IF-FALSE parameters. If the result is not a boolean, then 22024 provide it through documented shell variables. 22025 22026 22027File: autoconf.info, Node: History, Next: GNU Free Documentation License, Prev: FAQ, Up: Top 22028 2202921 History of Autoconf 22030********************** 22031 22032_This chapter was written by the original author, David MacKenzie._ 22033 22034 You may be wondering, Why was Autoconf originally written? How did 22035it get into its present form? (Why does it look like gorilla spit?) If 22036you're not wondering, then this chapter contains no information useful 22037to you, and you might as well skip it. If you _are_ wondering, then 22038let there be light... 22039 22040* Menu: 22041 22042* Genesis:: Prehistory and naming of `configure' 22043* Exodus:: The plagues of M4 and Perl 22044* Leviticus:: The priestly code of portability arrives 22045* Numbers:: Growth and contributors 22046* Deuteronomy:: Approaching the promises of easy configuration 22047 22048 22049File: autoconf.info, Node: Genesis, Next: Exodus, Up: History 22050 2205121.1 Genesis 22052============ 22053 22054In June 1991 I was maintaining many of the GNU utilities for the Free 22055Software Foundation. As they were ported to more platforms and more 22056programs were added, the number of `-D' options that users had to 22057select in the makefile (around 20) became burdensome. Especially for 22058me--I had to test each new release on a bunch of different systems. So 22059I wrote a little shell script to guess some of the correct settings for 22060the fileutils package, and released it as part of fileutils 2.0. That 22061`configure' script worked well enough that the next month I adapted it 22062(by hand) to create similar `configure' scripts for several other GNU 22063utilities packages. Brian Berliner also adapted one of my scripts for 22064his CVS revision control system. 22065 22066 Later that summer, I learned that Richard Stallman and Richard Pixley 22067were developing similar scripts to use in the GNU compiler tools; so I 22068adapted my `configure' scripts to support their evolving interface: 22069using the file name `Makefile.in' as the templates; adding `+srcdir', 22070the first option (of many); and creating `config.status' files. 22071 22072 22073File: autoconf.info, Node: Exodus, Next: Leviticus, Prev: Genesis, Up: History 22074 2207521.2 Exodus 22076=========== 22077 22078As I got feedback from users, I incorporated many improvements, using 22079Emacs to search and replace, cut and paste, similar changes in each of 22080the scripts. As I adapted more GNU utilities packages to use 22081`configure' scripts, updating them all by hand became impractical. 22082Rich Murphey, the maintainer of the GNU graphics utilities, sent me 22083mail saying that the `configure' scripts were great, and asking if I 22084had a tool for generating them that I could send him. No, I thought, 22085but I should! So I started to work out how to generate them. And the 22086journey from the slavery of hand-written `configure' scripts to the 22087abundance and ease of Autoconf began. 22088 22089 Cygnus `configure', which was being developed at around that time, 22090is table driven; it is meant to deal mainly with a discrete number of 22091system types with a small number of mainly unguessable features (such as 22092details of the object file format). The automatic configuration system 22093that Brian Fox had developed for Bash takes a similar approach. For 22094general use, it seems to me a hopeless cause to try to maintain an 22095up-to-date database of which features each variant of each operating 22096system has. It's easier and more reliable to check for most features on 22097the fly--especially on hybrid systems that people have hacked on 22098locally or that have patches from vendors installed. 22099 22100 I considered using an architecture similar to that of Cygnus 22101`configure', where there is a single `configure' script that reads 22102pieces of `configure.in' when run. But I didn't want to have to 22103distribute all of the feature tests with every package, so I settled on 22104having a different `configure' made from each `configure.in' by a 22105preprocessor. That approach also offered more control and flexibility. 22106 22107 I looked briefly into using the Metaconfig package, by Larry Wall, 22108Harlan Stenn, and Raphael Manfredi, but I decided not to for several 22109reasons. The `Configure' scripts it produces are interactive, which I 22110find quite inconvenient; I didn't like the ways it checked for some 22111features (such as library functions); I didn't know that it was still 22112being maintained, and the `Configure' scripts I had seen didn't work on 22113many modern systems (such as System V R4 and NeXT); it wasn't flexible 22114in what it could do in response to a feature's presence or absence; I 22115found it confusing to learn; and it was too big and complex for my 22116needs (I didn't realize then how much Autoconf would eventually have to 22117grow). 22118 22119 I considered using Perl to generate my style of `configure' scripts, 22120but decided that M4 was better suited to the job of simple textual 22121substitutions: it gets in the way less, because output is implicit. 22122Plus, everyone already has it. (Initially I didn't rely on the GNU 22123extensions to M4.) Also, some of my friends at the University of 22124Maryland had recently been putting M4 front ends on several programs, 22125including `tvtwm', and I was interested in trying out a new language. 22126 22127 22128File: autoconf.info, Node: Leviticus, Next: Numbers, Prev: Exodus, Up: History 22129 2213021.3 Leviticus 22131============== 22132 22133Since my `configure' scripts determine the system's capabilities 22134automatically, with no interactive user intervention, I decided to call 22135the program that generates them Autoconfig. But with a version number 22136tacked on, that name would be too long for old Unix file systems, so I 22137shortened it to Autoconf. 22138 22139 In the fall of 1991 I called together a group of fellow questers 22140after the Holy Grail of portability (er, that is, alpha testers) to 22141give me feedback as I encapsulated pieces of my handwritten scripts in 22142M4 macros and continued to add features and improve the techniques used 22143in the checks. Prominent among the testers were Franc,ois Pinard, who 22144came up with the idea of making an Autoconf shell script to run M4 and 22145check for unresolved macro calls; Richard Pixley, who suggested running 22146the compiler instead of searching the file system to find include files 22147and symbols, for more accurate results; Karl Berry, who got Autoconf to 22148configure TeX and added the macro index to the documentation; and Ian 22149Lance Taylor, who added support for creating a C header file as an 22150alternative to putting `-D' options in a makefile, so he could use 22151Autoconf for his UUCP package. The alpha testers cheerfully adjusted 22152their files again and again as the names and calling conventions of the 22153Autoconf macros changed from release to release. They all contributed 22154many specific checks, great ideas, and bug fixes. 22155 22156 22157File: autoconf.info, Node: Numbers, Next: Deuteronomy, Prev: Leviticus, Up: History 22158 2215921.4 Numbers 22160============ 22161 22162In July 1992, after months of alpha testing, I released Autoconf 1.0, 22163and converted many GNU packages to use it. I was surprised by how 22164positive the reaction to it was. More people started using it than I 22165could keep track of, including people working on software that wasn't 22166part of the GNU Project (such as TCL, FSP, and Kerberos V5). Autoconf 22167continued to improve rapidly, as many people using the `configure' 22168scripts reported problems they encountered. 22169 22170 Autoconf turned out to be a good torture test for M4 implementations. 22171Unix M4 started to dump core because of the length of the macros that 22172Autoconf defined, and several bugs showed up in GNU M4 as well. 22173Eventually, we realized that we needed to use some features that only 22174GNU M4 has. 4.3BSD M4, in particular, has an impoverished set of 22175builtin macros; the System V version is better, but still doesn't 22176provide everything we need. 22177 22178 More development occurred as people put Autoconf under more stresses 22179(and to uses I hadn't anticipated). Karl Berry added checks for X11. 22180david zuhn contributed C++ support. Franc,ois Pinard made it diagnose 22181invalid arguments. Jim Blandy bravely coerced it into configuring GNU 22182Emacs, laying the groundwork for several later improvements. Roland 22183McGrath got it to configure the GNU C Library, wrote the `autoheader' 22184script to automate the creation of C header file templates, and added a 22185`--verbose' option to `configure'. Noah Friedman added the 22186`--autoconf-dir' option and `AC_MACRODIR' environment variable. (He 22187also coined the term "autoconfiscate" to mean "adapt a software package 22188to use Autoconf".) Roland and Noah improved the quoting protection in 22189`AC_DEFINE' and fixed many bugs, especially when I got sick of dealing 22190with portability problems from February through June, 1993. 22191 22192 22193File: autoconf.info, Node: Deuteronomy, Prev: Numbers, Up: History 22194 2219521.5 Deuteronomy 22196================ 22197 22198A long wish list for major features had accumulated, and the effect of 22199several years of patching by various people had left some residual 22200cruft. In April 1994, while working for Cygnus Support, I began a major 22201revision of Autoconf. I added most of the features of the Cygnus 22202`configure' that Autoconf had lacked, largely by adapting the relevant 22203parts of Cygnus `configure' with the help of david zuhn and Ken 22204Raeburn. These features include support for using `config.sub', 22205`config.guess', `--host', and `--target'; making links to files; and 22206running `configure' scripts in subdirectories. Adding these features 22207enabled Ken to convert GNU `as', and Rob Savoye to convert DejaGNU, to 22208using Autoconf. 22209 22210 I added more features in response to other peoples' requests. Many 22211people had asked for `configure' scripts to share the results of the 22212checks between runs, because (particularly when configuring a large 22213source tree, like Cygnus does) they were frustratingly slow. Mike 22214Haertel suggested adding site-specific initialization scripts. People 22215distributing software that had to unpack on MS-DOS asked for a way to 22216override the `.in' extension on the file names, which produced file 22217names like `config.h.in' containing two dots. Jim Avera did an 22218extensive examination of the problems with quoting in `AC_DEFINE' and 22219`AC_SUBST'; his insights led to significant improvements. Richard 22220Stallman asked that compiler output be sent to `config.log' instead of 22221`/dev/null', to help people debug the Emacs `configure' script. 22222 22223 I made some other changes because of my dissatisfaction with the 22224quality of the program. I made the messages showing results of the 22225checks less ambiguous, always printing a result. I regularized the 22226names of the macros and cleaned up coding style inconsistencies. I 22227added some auxiliary utilities that I had developed to help convert 22228source code packages to use Autoconf. With the help of Franc,ois 22229Pinard, I made the macros not interrupt each others' messages. (That 22230feature revealed some performance bottlenecks in GNU M4, which he 22231hastily corrected!) I reorganized the documentation around problems 22232people want to solve. And I began a test suite, because experience had 22233shown that Autoconf has a pronounced tendency to regress when we change 22234it. 22235 22236 Again, several alpha testers gave invaluable feedback, especially 22237Franc,ois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn, 22238and Mark Eichin. 22239 22240 Finally, version 2.0 was ready. And there was much rejoicing. (And 22241I have free time again. I think. Yeah, right.) 22242 22243 22244File: autoconf.info, Node: GNU Free Documentation License, Next: Indices, Prev: History, Up: Top 22245 22246Appendix A GNU Free Documentation License 22247***************************************** 22248 22249 Version 1.3, 3 November 2008 22250 22251 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. 22252 `http://fsf.org/' 22253 22254 Everyone is permitted to copy and distribute verbatim copies 22255 of this license document, but changing it is not allowed. 22256 22257 0. PREAMBLE 22258 22259 The purpose of this License is to make a manual, textbook, or other 22260 functional and useful document "free" in the sense of freedom: to 22261 assure everyone the effective freedom to copy and redistribute it, 22262 with or without modifying it, either commercially or 22263 noncommercially. Secondarily, this License preserves for the 22264 author and publisher a way to get credit for their work, while not 22265 being considered responsible for modifications made by others. 22266 22267 This License is a kind of "copyleft", which means that derivative 22268 works of the document must themselves be free in the same sense. 22269 It complements the GNU General Public License, which is a copyleft 22270 license designed for free software. 22271 22272 We have designed this License in order to use it for manuals for 22273 free software, because free software needs free documentation: a 22274 free program should come with manuals providing the same freedoms 22275 that the software does. But this License is not limited to 22276 software manuals; it can be used for any textual work, regardless 22277 of subject matter or whether it is published as a printed book. 22278 We recommend this License principally for works whose purpose is 22279 instruction or reference. 22280 22281 1. APPLICABILITY AND DEFINITIONS 22282 22283 This License applies to any manual or other work, in any medium, 22284 that contains a notice placed by the copyright holder saying it 22285 can be distributed under the terms of this License. Such a notice 22286 grants a world-wide, royalty-free license, unlimited in duration, 22287 to use that work under the conditions stated herein. The 22288 "Document", below, refers to any such manual or work. Any member 22289 of the public is a licensee, and is addressed as "you". You 22290 accept the license if you copy, modify or distribute the work in a 22291 way requiring permission under copyright law. 22292 22293 A "Modified Version" of the Document means any work containing the 22294 Document or a portion of it, either copied verbatim, or with 22295 modifications and/or translated into another language. 22296 22297 A "Secondary Section" is a named appendix or a front-matter section 22298 of the Document that deals exclusively with the relationship of the 22299 publishers or authors of the Document to the Document's overall 22300 subject (or to related matters) and contains nothing that could 22301 fall directly within that overall subject. (Thus, if the Document 22302 is in part a textbook of mathematics, a Secondary Section may not 22303 explain any mathematics.) The relationship could be a matter of 22304 historical connection with the subject or with related matters, or 22305 of legal, commercial, philosophical, ethical or political position 22306 regarding them. 22307 22308 The "Invariant Sections" are certain Secondary Sections whose 22309 titles are designated, as being those of Invariant Sections, in 22310 the notice that says that the Document is released under this 22311 License. If a section does not fit the above definition of 22312 Secondary then it is not allowed to be designated as Invariant. 22313 The Document may contain zero Invariant Sections. If the Document 22314 does not identify any Invariant Sections then there are none. 22315 22316 The "Cover Texts" are certain short passages of text that are 22317 listed, as Front-Cover Texts or Back-Cover Texts, in the notice 22318 that says that the Document is released under this License. A 22319 Front-Cover Text may be at most 5 words, and a Back-Cover Text may 22320 be at most 25 words. 22321 22322 A "Transparent" copy of the Document means a machine-readable copy, 22323 represented in a format whose specification is available to the 22324 general public, that is suitable for revising the document 22325 straightforwardly with generic text editors or (for images 22326 composed of pixels) generic paint programs or (for drawings) some 22327 widely available drawing editor, and that is suitable for input to 22328 text formatters or for automatic translation to a variety of 22329 formats suitable for input to text formatters. A copy made in an 22330 otherwise Transparent file format whose markup, or absence of 22331 markup, has been arranged to thwart or discourage subsequent 22332 modification by readers is not Transparent. An image format is 22333 not Transparent if used for any substantial amount of text. A 22334 copy that is not "Transparent" is called "Opaque". 22335 22336 Examples of suitable formats for Transparent copies include plain 22337 ASCII without markup, Texinfo input format, LaTeX input format, 22338 SGML or XML using a publicly available DTD, and 22339 standard-conforming simple HTML, PostScript or PDF designed for 22340 human modification. Examples of transparent image formats include 22341 PNG, XCF and JPG. Opaque formats include proprietary formats that 22342 can be read and edited only by proprietary word processors, SGML or 22343 XML for which the DTD and/or processing tools are not generally 22344 available, and the machine-generated HTML, PostScript or PDF 22345 produced by some word processors for output purposes only. 22346 22347 The "Title Page" means, for a printed book, the title page itself, 22348 plus such following pages as are needed to hold, legibly, the 22349 material this License requires to appear in the title page. For 22350 works in formats which do not have any title page as such, "Title 22351 Page" means the text near the most prominent appearance of the 22352 work's title, preceding the beginning of the body of the text. 22353 22354 The "publisher" means any person or entity that distributes copies 22355 of the Document to the public. 22356 22357 A section "Entitled XYZ" means a named subunit of the Document 22358 whose title either is precisely XYZ or contains XYZ in parentheses 22359 following text that translates XYZ in another language. (Here XYZ 22360 stands for a specific section name mentioned below, such as 22361 "Acknowledgements", "Dedications", "Endorsements", or "History".) 22362 To "Preserve the Title" of such a section when you modify the 22363 Document means that it remains a section "Entitled XYZ" according 22364 to this definition. 22365 22366 The Document may include Warranty Disclaimers next to the notice 22367 which states that this License applies to the Document. These 22368 Warranty Disclaimers are considered to be included by reference in 22369 this License, but only as regards disclaiming warranties: any other 22370 implication that these Warranty Disclaimers may have is void and 22371 has no effect on the meaning of this License. 22372 22373 2. VERBATIM COPYING 22374 22375 You may copy and distribute the Document in any medium, either 22376 commercially or noncommercially, provided that this License, the 22377 copyright notices, and the license notice saying this License 22378 applies to the Document are reproduced in all copies, and that you 22379 add no other conditions whatsoever to those of this License. You 22380 may not use technical measures to obstruct or control the reading 22381 or further copying of the copies you make or distribute. However, 22382 you may accept compensation in exchange for copies. If you 22383 distribute a large enough number of copies you must also follow 22384 the conditions in section 3. 22385 22386 You may also lend copies, under the same conditions stated above, 22387 and you may publicly display copies. 22388 22389 3. COPYING IN QUANTITY 22390 22391 If you publish printed copies (or copies in media that commonly 22392 have printed covers) of the Document, numbering more than 100, and 22393 the Document's license notice requires Cover Texts, you must 22394 enclose the copies in covers that carry, clearly and legibly, all 22395 these Cover Texts: Front-Cover Texts on the front cover, and 22396 Back-Cover Texts on the back cover. Both covers must also clearly 22397 and legibly identify you as the publisher of these copies. The 22398 front cover must present the full title with all words of the 22399 title equally prominent and visible. You may add other material 22400 on the covers in addition. Copying with changes limited to the 22401 covers, as long as they preserve the title of the Document and 22402 satisfy these conditions, can be treated as verbatim copying in 22403 other respects. 22404 22405 If the required texts for either cover are too voluminous to fit 22406 legibly, you should put the first ones listed (as many as fit 22407 reasonably) on the actual cover, and continue the rest onto 22408 adjacent pages. 22409 22410 If you publish or distribute Opaque copies of the Document 22411 numbering more than 100, you must either include a 22412 machine-readable Transparent copy along with each Opaque copy, or 22413 state in or with each Opaque copy a computer-network location from 22414 which the general network-using public has access to download 22415 using public-standard network protocols a complete Transparent 22416 copy of the Document, free of added material. If you use the 22417 latter option, you must take reasonably prudent steps, when you 22418 begin distribution of Opaque copies in quantity, to ensure that 22419 this Transparent copy will remain thus accessible at the stated 22420 location until at least one year after the last time you 22421 distribute an Opaque copy (directly or through your agents or 22422 retailers) of that edition to the public. 22423 22424 It is requested, but not required, that you contact the authors of 22425 the Document well before redistributing any large number of 22426 copies, to give them a chance to provide you with an updated 22427 version of the Document. 22428 22429 4. MODIFICATIONS 22430 22431 You may copy and distribute a Modified Version of the Document 22432 under the conditions of sections 2 and 3 above, provided that you 22433 release the Modified Version under precisely this License, with 22434 the Modified Version filling the role of the Document, thus 22435 licensing distribution and modification of the Modified Version to 22436 whoever possesses a copy of it. In addition, you must do these 22437 things in the Modified Version: 22438 22439 A. Use in the Title Page (and on the covers, if any) a title 22440 distinct from that of the Document, and from those of 22441 previous versions (which should, if there were any, be listed 22442 in the History section of the Document). You may use the 22443 same title as a previous version if the original publisher of 22444 that version gives permission. 22445 22446 B. List on the Title Page, as authors, one or more persons or 22447 entities responsible for authorship of the modifications in 22448 the Modified Version, together with at least five of the 22449 principal authors of the Document (all of its principal 22450 authors, if it has fewer than five), unless they release you 22451 from this requirement. 22452 22453 C. State on the Title page the name of the publisher of the 22454 Modified Version, as the publisher. 22455 22456 D. Preserve all the copyright notices of the Document. 22457 22458 E. Add an appropriate copyright notice for your modifications 22459 adjacent to the other copyright notices. 22460 22461 F. Include, immediately after the copyright notices, a license 22462 notice giving the public permission to use the Modified 22463 Version under the terms of this License, in the form shown in 22464 the Addendum below. 22465 22466 G. Preserve in that license notice the full lists of Invariant 22467 Sections and required Cover Texts given in the Document's 22468 license notice. 22469 22470 H. Include an unaltered copy of this License. 22471 22472 I. Preserve the section Entitled "History", Preserve its Title, 22473 and add to it an item stating at least the title, year, new 22474 authors, and publisher of the Modified Version as given on 22475 the Title Page. If there is no section Entitled "History" in 22476 the Document, create one stating the title, year, authors, 22477 and publisher of the Document as given on its Title Page, 22478 then add an item describing the Modified Version as stated in 22479 the previous sentence. 22480 22481 J. Preserve the network location, if any, given in the Document 22482 for public access to a Transparent copy of the Document, and 22483 likewise the network locations given in the Document for 22484 previous versions it was based on. These may be placed in 22485 the "History" section. You may omit a network location for a 22486 work that was published at least four years before the 22487 Document itself, or if the original publisher of the version 22488 it refers to gives permission. 22489 22490 K. For any section Entitled "Acknowledgements" or "Dedications", 22491 Preserve the Title of the section, and preserve in the 22492 section all the substance and tone of each of the contributor 22493 acknowledgements and/or dedications given therein. 22494 22495 L. Preserve all the Invariant Sections of the Document, 22496 unaltered in their text and in their titles. Section numbers 22497 or the equivalent are not considered part of the section 22498 titles. 22499 22500 M. Delete any section Entitled "Endorsements". Such a section 22501 may not be included in the Modified Version. 22502 22503 N. Do not retitle any existing section to be Entitled 22504 "Endorsements" or to conflict in title with any Invariant 22505 Section. 22506 22507 O. Preserve any Warranty Disclaimers. 22508 22509 If the Modified Version includes new front-matter sections or 22510 appendices that qualify as Secondary Sections and contain no 22511 material copied from the Document, you may at your option 22512 designate some or all of these sections as invariant. To do this, 22513 add their titles to the list of Invariant Sections in the Modified 22514 Version's license notice. These titles must be distinct from any 22515 other section titles. 22516 22517 You may add a section Entitled "Endorsements", provided it contains 22518 nothing but endorsements of your Modified Version by various 22519 parties--for example, statements of peer review or that the text 22520 has been approved by an organization as the authoritative 22521 definition of a standard. 22522 22523 You may add a passage of up to five words as a Front-Cover Text, 22524 and a passage of up to 25 words as a Back-Cover Text, to the end 22525 of the list of Cover Texts in the Modified Version. Only one 22526 passage of Front-Cover Text and one of Back-Cover Text may be 22527 added by (or through arrangements made by) any one entity. If the 22528 Document already includes a cover text for the same cover, 22529 previously added by you or by arrangement made by the same entity 22530 you are acting on behalf of, you may not add another; but you may 22531 replace the old one, on explicit permission from the previous 22532 publisher that added the old one. 22533 22534 The author(s) and publisher(s) of the Document do not by this 22535 License give permission to use their names for publicity for or to 22536 assert or imply endorsement of any Modified Version. 22537 22538 5. COMBINING DOCUMENTS 22539 22540 You may combine the Document with other documents released under 22541 this License, under the terms defined in section 4 above for 22542 modified versions, provided that you include in the combination 22543 all of the Invariant Sections of all of the original documents, 22544 unmodified, and list them all as Invariant Sections of your 22545 combined work in its license notice, and that you preserve all 22546 their Warranty Disclaimers. 22547 22548 The combined work need only contain one copy of this License, and 22549 multiple identical Invariant Sections may be replaced with a single 22550 copy. If there are multiple Invariant Sections with the same name 22551 but different contents, make the title of each such section unique 22552 by adding at the end of it, in parentheses, the name of the 22553 original author or publisher of that section if known, or else a 22554 unique number. Make the same adjustment to the section titles in 22555 the list of Invariant Sections in the license notice of the 22556 combined work. 22557 22558 In the combination, you must combine any sections Entitled 22559 "History" in the various original documents, forming one section 22560 Entitled "History"; likewise combine any sections Entitled 22561 "Acknowledgements", and any sections Entitled "Dedications". You 22562 must delete all sections Entitled "Endorsements." 22563 22564 6. COLLECTIONS OF DOCUMENTS 22565 22566 You may make a collection consisting of the Document and other 22567 documents released under this License, and replace the individual 22568 copies of this License in the various documents with a single copy 22569 that is included in the collection, provided that you follow the 22570 rules of this License for verbatim copying of each of the 22571 documents in all other respects. 22572 22573 You may extract a single document from such a collection, and 22574 distribute it individually under this License, provided you insert 22575 a copy of this License into the extracted document, and follow 22576 this License in all other respects regarding verbatim copying of 22577 that document. 22578 22579 7. AGGREGATION WITH INDEPENDENT WORKS 22580 22581 A compilation of the Document or its derivatives with other 22582 separate and independent documents or works, in or on a volume of 22583 a storage or distribution medium, is called an "aggregate" if the 22584 copyright resulting from the compilation is not used to limit the 22585 legal rights of the compilation's users beyond what the individual 22586 works permit. When the Document is included in an aggregate, this 22587 License does not apply to the other works in the aggregate which 22588 are not themselves derivative works of the Document. 22589 22590 If the Cover Text requirement of section 3 is applicable to these 22591 copies of the Document, then if the Document is less than one half 22592 of the entire aggregate, the Document's Cover Texts may be placed 22593 on covers that bracket the Document within the aggregate, or the 22594 electronic equivalent of covers if the Document is in electronic 22595 form. Otherwise they must appear on printed covers that bracket 22596 the whole aggregate. 22597 22598 8. TRANSLATION 22599 22600 Translation is considered a kind of modification, so you may 22601 distribute translations of the Document under the terms of section 22602 4. Replacing Invariant Sections with translations requires special 22603 permission from their copyright holders, but you may include 22604 translations of some or all Invariant Sections in addition to the 22605 original versions of these Invariant Sections. You may include a 22606 translation of this License, and all the license notices in the 22607 Document, and any Warranty Disclaimers, provided that you also 22608 include the original English version of this License and the 22609 original versions of those notices and disclaimers. In case of a 22610 disagreement between the translation and the original version of 22611 this License or a notice or disclaimer, the original version will 22612 prevail. 22613 22614 If a section in the Document is Entitled "Acknowledgements", 22615 "Dedications", or "History", the requirement (section 4) to 22616 Preserve its Title (section 1) will typically require changing the 22617 actual title. 22618 22619 9. TERMINATION 22620 22621 You may not copy, modify, sublicense, or distribute the Document 22622 except as expressly provided under this License. Any attempt 22623 otherwise to copy, modify, sublicense, or distribute it is void, 22624 and will automatically terminate your rights under this License. 22625 22626 However, if you cease all violation of this License, then your 22627 license from a particular copyright holder is reinstated (a) 22628 provisionally, unless and until the copyright holder explicitly 22629 and finally terminates your license, and (b) permanently, if the 22630 copyright holder fails to notify you of the violation by some 22631 reasonable means prior to 60 days after the cessation. 22632 22633 Moreover, your license from a particular copyright holder is 22634 reinstated permanently if the copyright holder notifies you of the 22635 violation by some reasonable means, this is the first time you have 22636 received notice of violation of this License (for any work) from 22637 that copyright holder, and you cure the violation prior to 30 days 22638 after your receipt of the notice. 22639 22640 Termination of your rights under this section does not terminate 22641 the licenses of parties who have received copies or rights from 22642 you under this License. If your rights have been terminated and 22643 not permanently reinstated, receipt of a copy of some or all of 22644 the same material does not give you any rights to use it. 22645 22646 10. FUTURE REVISIONS OF THIS LICENSE 22647 22648 The Free Software Foundation may publish new, revised versions of 22649 the GNU Free Documentation License from time to time. Such new 22650 versions will be similar in spirit to the present version, but may 22651 differ in detail to address new problems or concerns. See 22652 `http://www.gnu.org/copyleft/'. 22653 22654 Each version of the License is given a distinguishing version 22655 number. If the Document specifies that a particular numbered 22656 version of this License "or any later version" applies to it, you 22657 have the option of following the terms and conditions either of 22658 that specified version or of any later version that has been 22659 published (not as a draft) by the Free Software Foundation. If 22660 the Document does not specify a version number of this License, 22661 you may choose any version ever published (not as a draft) by the 22662 Free Software Foundation. If the Document specifies that a proxy 22663 can decide which future versions of this License can be used, that 22664 proxy's public statement of acceptance of a version permanently 22665 authorizes you to choose that version for the Document. 22666 22667 11. RELICENSING 22668 22669 "Massive Multiauthor Collaboration Site" (or "MMC Site") means any 22670 World Wide Web server that publishes copyrightable works and also 22671 provides prominent facilities for anybody to edit those works. A 22672 public wiki that anybody can edit is an example of such a server. 22673 A "Massive Multiauthor Collaboration" (or "MMC") contained in the 22674 site means any set of copyrightable works thus published on the MMC 22675 site. 22676 22677 "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 22678 license published by Creative Commons Corporation, a not-for-profit 22679 corporation with a principal place of business in San Francisco, 22680 California, as well as future copyleft versions of that license 22681 published by that same organization. 22682 22683 "Incorporate" means to publish or republish a Document, in whole or 22684 in part, as part of another Document. 22685 22686 An MMC is "eligible for relicensing" if it is licensed under this 22687 License, and if all works that were first published under this 22688 License somewhere other than this MMC, and subsequently 22689 incorporated in whole or in part into the MMC, (1) had no cover 22690 texts or invariant sections, and (2) were thus incorporated prior 22691 to November 1, 2008. 22692 22693 The operator of an MMC Site may republish an MMC contained in the 22694 site under CC-BY-SA on the same site at any time before August 1, 22695 2009, provided the MMC is eligible for relicensing. 22696 22697 22698ADDENDUM: How to use this License for your documents 22699==================================================== 22700 22701To use this License in a document you have written, include a copy of 22702the License in the document and put the following copyright and license 22703notices just after the title page: 22704 22705 Copyright (C) YEAR YOUR NAME. 22706 Permission is granted to copy, distribute and/or modify this document 22707 under the terms of the GNU Free Documentation License, Version 1.3 22708 or any later version published by the Free Software Foundation; 22709 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 22710 Texts. A copy of the license is included in the section entitled ``GNU 22711 Free Documentation License''. 22712 22713 If you have Invariant Sections, Front-Cover Texts and Back-Cover 22714Texts, replace the "with...Texts." line with this: 22715 22716 with the Invariant Sections being LIST THEIR TITLES, with 22717 the Front-Cover Texts being LIST, and with the Back-Cover Texts 22718 being LIST. 22719 22720 If you have Invariant Sections without Cover Texts, or some other 22721combination of the three, merge those two alternatives to suit the 22722situation. 22723 22724 If your document contains nontrivial examples of program code, we 22725recommend releasing these examples in parallel under your choice of 22726free software license, such as the GNU General Public License, to 22727permit their use in free software. 22728 22729 22730File: autoconf.info, Node: Indices, Prev: GNU Free Documentation License, Up: Top 22731 22732Appendix B Indices 22733****************** 22734 22735* Menu: 22736 22737* Environment Variable Index:: Index of environment variables used 22738* Output Variable Index:: Index of variables set in output files 22739* Preprocessor Symbol Index:: Index of C preprocessor symbols defined 22740* Cache Variable Index:: Index of documented cache variables 22741* Autoconf Macro Index:: Index of Autoconf macros 22742* M4 Macro Index:: Index of M4, M4sugar, and M4sh macros 22743* Autotest Macro Index:: Index of Autotest macros 22744* Program & Function Index:: Index of those with portability problems 22745* Concept Index:: General index 22746 22747 22748File: autoconf.info, Node: Environment Variable Index, Next: Output Variable Index, Up: Indices 22749 22750B.1 Environment Variable Index 22751============================== 22752 22753This is an alphabetical list of the environment variables that might 22754influence Autoconf checks. 22755 22756�[index�] 22757* Menu: 22758 22759* _: Special Shell Variables. 22760 (line 36) 22761* BIN_SH: Special Shell Variables. 22762 (line 40) 22763* CC: C Compiler. (line 61) 22764* CDPATH: Special Shell Variables. 22765 (line 44) 22766* CFLAGS <1>: C Compiler. (line 61) 22767* CFLAGS: Preset Output Variables. 22768 (line 23) 22769* CLICOLOR_FORCE: Special Shell Variables. 22770 (line 67) 22771* CONFIG_COMMANDS: Obsolete config.status Use. 22772 (line 11) 22773* CONFIG_FILES: Obsolete config.status Use. 22774 (line 15) 22775* CONFIG_HEADERS: Obsolete config.status Use. 22776 (line 20) 22777* CONFIG_LINKS: Obsolete config.status Use. 22778 (line 25) 22779* CONFIG_SHELL: config.status Invocation. 22780 (line 102) 22781* CONFIG_SITE: Site Defaults. (line 10) 22782* CONFIG_STATUS: config.status Invocation. 22783 (line 108) 22784* CPP: C Compiler. (line 113) 22785* CPPFLAGS: Preset Output Variables. 22786 (line 72) 22787* CXX: C++ Compiler. (line 7) 22788* CXXCPP: C++ Compiler. (line 35) 22789* CXXFLAGS <1>: C++ Compiler. (line 7) 22790* CXXFLAGS: Preset Output Variables. 22791 (line 94) 22792* CYGWIN: Obsolete Macros. (line 124) 22793* DUALCASE: Special Shell Variables. 22794 (line 74) 22795* ENV: Special Shell Variables. 22796 (line 84) 22797* ERL: Erlang Compiler and Interpreter. 22798 (line 29) 22799* ERLC: Erlang Compiler and Interpreter. 22800 (line 10) 22801* ERLCFLAGS <1>: Erlang Compiler and Interpreter. 22802 (line 10) 22803* ERLCFLAGS: Preset Output Variables. 22804 (line 120) 22805* F77: Fortran Compiler. (line 19) 22806* FC: Fortran Compiler. (line 44) 22807* FCFLAGS <1>: Fortran Compiler. (line 44) 22808* FCFLAGS: Preset Output Variables. 22809 (line 126) 22810* FFLAGS <1>: Fortran Compiler. (line 19) 22811* FFLAGS: Preset Output Variables. 22812 (line 133) 22813* FPATH: Special Shell Variables. 22814 (line 101) 22815* GOFLAGS: Preset Output Variables. 22816 (line 170) 22817* GREP_OPTIONS: Special Shell Variables. 22818 (line 108) 22819* IFS: Special Shell Variables. 22820 (line 116) 22821* LANG: Special Shell Variables. 22822 (line 160) 22823* LANGUAGE: Special Shell Variables. 22824 (line 167) 22825* LC_ADDRESS: Special Shell Variables. 22826 (line 177) 22827* LC_ALL <1>: Special Shell Variables. 22828 (line 160) 22829* LC_ALL: Initialization Macros. 22830 (line 14) 22831* LC_COLLATE: Special Shell Variables. 22832 (line 160) 22833* LC_CTYPE: Special Shell Variables. 22834 (line 160) 22835* LC_IDENTIFICATION: Special Shell Variables. 22836 (line 177) 22837* LC_MEASUREMENT: Special Shell Variables. 22838 (line 177) 22839* LC_MESSAGES: Special Shell Variables. 22840 (line 160) 22841* LC_MONETARY: Special Shell Variables. 22842 (line 160) 22843* LC_NAME: Special Shell Variables. 22844 (line 177) 22845* LC_NUMERIC: Special Shell Variables. 22846 (line 160) 22847* LC_PAPER: Special Shell Variables. 22848 (line 177) 22849* LC_TELEPHONE: Special Shell Variables. 22850 (line 177) 22851* LC_TIME: Special Shell Variables. 22852 (line 160) 22853* LDFLAGS: Preset Output Variables. 22854 (line 140) 22855* LIBS: Preset Output Variables. 22856 (line 154) 22857* LINENO <1>: Special Shell Variables. 22858 (line 182) 22859* LINENO: Initialization Macros. 22860 (line 67) 22861* M4: autom4te Invocation. (line 10) 22862* MAIL: Special Shell Variables. 22863 (line 84) 22864* MAILPATH: Special Shell Variables. 22865 (line 84) 22866* NULLCMD: Special Shell Variables. 22867 (line 311) 22868* OBJC: Objective C Compiler. 22869 (line 7) 22870* OBJCFLAGS <1>: Objective C Compiler. 22871 (line 7) 22872* OBJCFLAGS: Preset Output Variables. 22873 (line 162) 22874* OBJCPP: Objective C Compiler. 22875 (line 26) 22876* OBJCXX: Objective C++ Compiler. 22877 (line 7) 22878* OBJCXXCPP: Objective C++ Compiler. 22879 (line 27) 22880* OBJCXXFLAGS <1>: Objective C++ Compiler. 22881 (line 7) 22882* OBJCXXFLAGS: Preset Output Variables. 22883 (line 166) 22884* options: Special Shell Variables. 22885 (line 318) 22886* PATH_SEPARATOR: Special Shell Variables. 22887 (line 322) 22888* POSIXLY_CORRECT: Special Shell Variables. 22889 (line 331) 22890* PS1: Special Shell Variables. 22891 (line 84) 22892* PS2: Special Shell Variables. 22893 (line 84) 22894* PS4: Special Shell Variables. 22895 (line 84) 22896* PWD: Special Shell Variables. 22897 (line 346) 22898* RANDOM: Special Shell Variables. 22899 (line 355) 22900* SHELL: Initialization Macros. 22901 (line 14) 22902* SIMPLE_BACKUP_SUFFIX: autoupdate Invocation. 22903 (line 16) 22904* status: Special Shell Variables. 22905 (line 363) 22906* TMPDIR: Initialization Macros. 22907 (line 77) 22908* WARNINGS <1>: autom4te Invocation. (line 58) 22909* WARNINGS <2>: autoheader Invocation. 22910 (line 83) 22911* WARNINGS <3>: autoreconf Invocation. 22912 (line 97) 22913* WARNINGS: autoconf Invocation. (line 62) 22914* XMKMF: System Services. (line 10) 22915* YACC: Particular Programs. (line 200) 22916* YFLAGS: Particular Programs. (line 200) 22917 22918 22919File: autoconf.info, Node: Output Variable Index, Next: Preprocessor Symbol Index, Prev: Environment Variable Index, Up: Indices 22920 22921B.2 Output Variable Index 22922========================= 22923 22924This is an alphabetical list of the variables that Autoconf can 22925substitute into files that it creates, typically one or more makefiles. 22926*Note Setting Output Variables::, for more information on how this is 22927done. 22928 22929�[index�] 22930* Menu: 22931 22932* abs_builddir: Preset Output Variables. 22933 (line 177) 22934* abs_srcdir: Preset Output Variables. 22935 (line 199) 22936* abs_top_builddir: Preset Output Variables. 22937 (line 192) 22938* abs_top_srcdir: Preset Output Variables. 22939 (line 206) 22940* ac_empty: Fortran Compiler. (line 465) 22941* ALLOCA: Particular Functions. 22942 (line 10) 22943* AWK: Particular Programs. (line 10) 22944* bindir: Installation Directory Variables. 22945 (line 15) 22946* build: Canonicalizing. (line 26) 22947* build_alias: Canonicalizing. (line 9) 22948* build_cpu: Canonicalizing. (line 26) 22949* build_os: Canonicalizing. (line 26) 22950* build_vendor: Canonicalizing. (line 26) 22951* builddir: Preset Output Variables. 22952 (line 174) 22953* CC <1>: System Services. (line 49) 22954* CC: C Compiler. (line 61) 22955* CFLAGS <1>: C Compiler. (line 61) 22956* CFLAGS: Preset Output Variables. 22957 (line 23) 22958* configure_input: Preset Output Variables. 22959 (line 58) 22960* CPP: C Compiler. (line 113) 22961* CPPFLAGS: Preset Output Variables. 22962 (line 72) 22963* cross_compiling: Runtime. (line 71) 22964* CXX: C++ Compiler. (line 7) 22965* CXXCPP: C++ Compiler. (line 35) 22966* CXXFLAGS <1>: C++ Compiler. (line 7) 22967* CXXFLAGS: Preset Output Variables. 22968 (line 94) 22969* datadir: Installation Directory Variables. 22970 (line 18) 22971* datarootdir: Installation Directory Variables. 22972 (line 22) 22973* DEFS: Preset Output Variables. 22974 (line 98) 22975* docdir: Installation Directory Variables. 22976 (line 26) 22977* dvidir: Installation Directory Variables. 22978 (line 30) 22979* ECHO_C: Preset Output Variables. 22980 (line 108) 22981* ECHO_N: Preset Output Variables. 22982 (line 108) 22983* ECHO_T: Preset Output Variables. 22984 (line 108) 22985* EGREP: Particular Programs. (line 29) 22986* ERL <1>: Running the Compiler. 22987 (line 30) 22988* ERL <2>: Language Choice. (line 40) 22989* ERL: Erlang Compiler and Interpreter. 22990 (line 29) 22991* ERLANG_ERTS_VER: Erlang Libraries. (line 12) 22992* ERLANG_INSTALL_LIB_DIR <1>: Erlang Libraries. (line 86) 22993* ERLANG_INSTALL_LIB_DIR: Installation Directory Variables. 22994 (line 201) 22995* ERLANG_INSTALL_LIB_DIR_LIBRARY <1>: Erlang Libraries. (line 93) 22996* ERLANG_INSTALL_LIB_DIR_LIBRARY: Installation Directory Variables. 22997 (line 206) 22998* ERLANG_LIB_DIR: Erlang Libraries. (line 28) 22999* ERLANG_LIB_DIR_LIBRARY: Erlang Libraries. (line 36) 23000* ERLANG_LIB_VER_LIBRARY: Erlang Libraries. (line 36) 23001* ERLANG_ROOT_DIR: Erlang Libraries. (line 22) 23002* ERLC <1>: Language Choice. (line 40) 23003* ERLC: Erlang Compiler and Interpreter. 23004 (line 10) 23005* ERLCFLAGS <1>: Language Choice. (line 40) 23006* ERLCFLAGS <2>: Erlang Compiler and Interpreter. 23007 (line 10) 23008* ERLCFLAGS: Preset Output Variables. 23009 (line 120) 23010* exec_prefix: Installation Directory Variables. 23011 (line 33) 23012* EXEEXT <1>: Obsolete Macros. (line 178) 23013* EXEEXT: Compilers and Preprocessors. 23014 (line 6) 23015* F77: Fortran Compiler. (line 19) 23016* FC: Fortran Compiler. (line 44) 23017* FC_MODEXT: Fortran Compiler. (line 438) 23018* FC_MODINC: Fortran Compiler. (line 465) 23019* FC_MODOUT: Fortran Compiler. (line 501) 23020* FCFLAGS <1>: Fortran Compiler. (line 44) 23021* FCFLAGS: Preset Output Variables. 23022 (line 126) 23023* FCLIBS: Fortran Compiler. (line 92) 23024* FFLAGS <1>: Fortran Compiler. (line 19) 23025* FFLAGS: Preset Output Variables. 23026 (line 133) 23027* FGREP: Particular Programs. (line 36) 23028* FLIBS: Fortran Compiler. (line 92) 23029* GETGROUPS_LIBS: Particular Functions. 23030 (line 155) 23031* GETLOADAVG_LIBS: Particular Functions. 23032 (line 161) 23033* GOFLAGS: Preset Output Variables. 23034 (line 170) 23035* GREP: Particular Programs. (line 20) 23036* host: Canonicalizing. (line 34) 23037* host_alias: Canonicalizing. (line 9) 23038* host_cpu: Canonicalizing. (line 34) 23039* host_os: Canonicalizing. (line 34) 23040* host_vendor: Canonicalizing. (line 34) 23041* htmldir: Installation Directory Variables. 23042 (line 40) 23043* includedir: Installation Directory Variables. 23044 (line 43) 23045* infodir: Installation Directory Variables. 23046 (line 46) 23047* INSTALL: Particular Programs. (line 43) 23048* INSTALL_DATA: Particular Programs. (line 43) 23049* INSTALL_PROGRAM: Particular Programs. (line 43) 23050* INSTALL_SCRIPT: Particular Programs. (line 43) 23051* KMEM_GROUP: Particular Functions. 23052 (line 161) 23053* LDFLAGS: Preset Output Variables. 23054 (line 140) 23055* LEX: Particular Programs. (line 114) 23056* LEX_OUTPUT_ROOT: Particular Programs. (line 114) 23057* LEXLIB: Particular Programs. (line 114) 23058* libdir: Installation Directory Variables. 23059 (line 49) 23060* libexecdir: Installation Directory Variables. 23061 (line 52) 23062* LIBOBJDIR: AC_LIBOBJ vs LIBOBJS. 23063 (line 35) 23064* LIBOBJS <1>: Particular Structures. 23065 (line 26) 23066* LIBOBJS <2>: Generic Functions. (line 56) 23067* LIBOBJS: Particular Functions. 23068 (line 161) 23069* LIBS <1>: Obsolete Macros. (line 295) 23070* LIBS: Preset Output Variables. 23071 (line 154) 23072* LN_S: Particular Programs. (line 168) 23073* localedir: Installation Directory Variables. 23074 (line 55) 23075* localstatedir: Installation Directory Variables. 23076 (line 60) 23077* mandir: Installation Directory Variables. 23078 (line 63) 23079* MKDIR_P: Particular Programs. (line 80) 23080* NEED_SETGID: Particular Functions. 23081 (line 161) 23082* OBJC: Objective C Compiler. 23083 (line 7) 23084* OBJCFLAGS <1>: Objective C Compiler. 23085 (line 7) 23086* OBJCFLAGS: Preset Output Variables. 23087 (line 162) 23088* OBJCPP: Objective C Compiler. 23089 (line 26) 23090* OBJCXX: Objective C++ Compiler. 23091 (line 7) 23092* OBJCXXCPP: Objective C++ Compiler. 23093 (line 27) 23094* OBJCXXFLAGS <1>: Objective C++ Compiler. 23095 (line 7) 23096* OBJCXXFLAGS: Preset Output Variables. 23097 (line 166) 23098* OBJEXT <1>: Obsolete Macros. (line 384) 23099* OBJEXT: Compilers and Preprocessors. 23100 (line 11) 23101* oldincludedir: Installation Directory Variables. 23102 (line 66) 23103* OPENMP_CFLAGS: Generic Compiler Characteristics. 23104 (line 64) 23105* OPENMP_CXXFLAGS: Generic Compiler Characteristics. 23106 (line 64) 23107* OPENMP_FCFLAGS: Generic Compiler Characteristics. 23108 (line 64) 23109* OPENMP_FFLAGS: Generic Compiler Characteristics. 23110 (line 64) 23111* PACKAGE_BUGREPORT: Initializing configure. 23112 (line 57) 23113* PACKAGE_NAME: Initializing configure. 23114 (line 45) 23115* PACKAGE_STRING: Initializing configure. 23116 (line 54) 23117* PACKAGE_TARNAME: Initializing configure. 23118 (line 48) 23119* PACKAGE_URL: Initializing configure. 23120 (line 61) 23121* PACKAGE_VERSION: Initializing configure. 23122 (line 51) 23123* pdfdir: Installation Directory Variables. 23124 (line 69) 23125* POW_LIB: Particular Functions. 23126 (line 408) 23127* prefix: Installation Directory Variables. 23128 (line 72) 23129* program_transform_name: Transforming Names. (line 11) 23130* psdir: Installation Directory Variables. 23131 (line 77) 23132* RANLIB: Particular Programs. (line 187) 23133* sbindir: Installation Directory Variables. 23134 (line 80) 23135* SED: Particular Programs. (line 191) 23136* SET_MAKE: Output. (line 45) 23137* sharedstatedir: Installation Directory Variables. 23138 (line 84) 23139* srcdir: Preset Output Variables. 23140 (line 195) 23141* subdirs: Subdirectories. (line 12) 23142* sysconfdir: Installation Directory Variables. 23143 (line 88) 23144* target: Canonicalizing. (line 41) 23145* target_alias: Canonicalizing. (line 9) 23146* target_cpu: Canonicalizing. (line 41) 23147* target_os: Canonicalizing. (line 41) 23148* target_vendor: Canonicalizing. (line 41) 23149* tmp: Initialization Macros. 23150 (line 77) 23151* top_build_prefix: Preset Output Variables. 23152 (line 184) 23153* top_builddir: Preset Output Variables. 23154 (line 180) 23155* top_srcdir: Preset Output Variables. 23156 (line 202) 23157* X_CFLAGS: System Services. (line 30) 23158* X_EXTRA_LIBS: System Services. (line 30) 23159* X_LIBS: System Services. (line 30) 23160* X_PRE_LIBS: System Services. (line 30) 23161* YACC: Particular Programs. (line 200) 23162 23163 23164File: autoconf.info, Node: Preprocessor Symbol Index, Next: Cache Variable Index, Prev: Output Variable Index, Up: Indices 23165 23166B.3 Preprocessor Symbol Index 23167============================= 23168 23169This is an alphabetical list of the C preprocessor symbols that the 23170Autoconf macros define. To work with Autoconf, C source code needs to 23171use these names in `#if' or `#ifdef' directives. 23172 23173�[index�] 23174* Menu: 23175 23176* __CHAR_UNSIGNED__: C Compiler. (line 291) 23177* __EXTENSIONS__: Posix Variants. (line 10) 23178* __PROTOTYPES: C Compiler. (line 351) 23179* _ALL_SOURCE <1>: Obsolete Macros. (line 20) 23180* _ALL_SOURCE: Posix Variants. (line 10) 23181* _FILE_OFFSET_BITS: System Services. (line 49) 23182* _GNU_SOURCE <1>: Obsolete Macros. (line 234) 23183* _GNU_SOURCE: Posix Variants. (line 10) 23184* _LARGE_FILES: System Services. (line 49) 23185* _LARGEFILE_SOURCE: Particular Functions. 23186 (line 147) 23187* _MINIX <1>: Obsolete Macros. (line 371) 23188* _MINIX: Posix Variants. (line 10) 23189* _OPENMP: Generic Compiler Characteristics. 23190 (line 64) 23191* _POSIX_1_SOURCE <1>: Obsolete Macros. (line 371) 23192* _POSIX_1_SOURCE: Posix Variants. (line 10) 23193* _POSIX_PTHREAD_SEMANTICS: Posix Variants. (line 10) 23194* _POSIX_SOURCE <1>: Obsolete Macros. (line 371) 23195* _POSIX_SOURCE: Posix Variants. (line 10) 23196* _POSIX_VERSION: Particular Headers. (line 228) 23197* _TANDEM_SOURCE: Posix Variants. (line 10) 23198* ALIGNOF_TYPE: Generic Compiler Characteristics. 23199 (line 30) 23200* C_ALLOCA: Particular Functions. 23201 (line 10) 23202* C_GETLOADAVG: Particular Functions. 23203 (line 161) 23204* CLOSEDIR_VOID: Particular Functions. 23205 (line 69) 23206* const: C Compiler. (line 217) 23207* CXX_NO_MINUS_C_MINUS_O: C++ Compiler. (line 48) 23208* DGUX: Particular Functions. 23209 (line 161) 23210* DIRENT: Obsolete Macros. (line 158) 23211* F77_DUMMY_MAIN: Fortran Compiler. (line 130) 23212* F77_FUNC: Fortran Compiler. (line 202) 23213* F77_FUNC_: Fortran Compiler. (line 202) 23214* F77_MAIN: Fortran Compiler. (line 176) 23215* F77_NO_MINUS_C_MINUS_O: Fortran Compiler. (line 76) 23216* FC_DUMMY_MAIN: Fortran Compiler. (line 130) 23217* FC_FUNC: Fortran Compiler. (line 202) 23218* FC_FUNC_: Fortran Compiler. (line 202) 23219* FC_MAIN: Fortran Compiler. (line 176) 23220* FC_NO_MINUS_C_MINUS_O: Fortran Compiler. (line 76) 23221* FLEXIBLE_ARRAY_MEMBER: C Compiler. (line 315) 23222* GETGROUPS_T: Particular Types. (line 14) 23223* GETLOADAVG_PRIVILEGED: Particular Functions. 23224 (line 161) 23225* GETPGRP_VOID: Particular Functions. 23226 (line 205) 23227* gid_t: Particular Types. (line 126) 23228* GWINSZ_IN_SYS_IOCTL: Particular Headers. (line 270) 23229* HAVE__BOOL: Particular Headers. (line 10) 23230* HAVE_AGGREGATE_MEMBER: Generic Structures. (line 29) 23231* HAVE_ALLOCA_H: Particular Functions. 23232 (line 10) 23233* HAVE_C_BACKSLASH_A: C Compiler. (line 176) 23234* HAVE_C_VARARRAYS: C Compiler. (line 339) 23235* HAVE_CHOWN: Particular Functions. 23236 (line 63) 23237* HAVE_CONFIG_H: Configuration Headers. 23238 (line 33) 23239* HAVE_DECL_STRERROR_R: Particular Functions. 23240 (line 388) 23241* HAVE_DECL_SYMBOL: Generic Declarations. 23242 (line 34) 23243* HAVE_DECL_TZNAME: Particular Structures. 23244 (line 43) 23245* HAVE_DIRENT_H: Particular Headers. (line 25) 23246* HAVE_DOPRNT: Particular Functions. 23247 (line 443) 23248* HAVE_FSEEKO: Particular Functions. 23249 (line 147) 23250* HAVE_FUNCTION: Generic Functions. (line 27) 23251* HAVE_GETGROUPS: Particular Functions. 23252 (line 155) 23253* HAVE_GETMNTENT: Particular Functions. 23254 (line 195) 23255* HAVE_HEADER: Generic Headers. (line 46) 23256* HAVE_INT16_T: Particular Types. (line 40) 23257* HAVE_INT32_T: Particular Types. (line 43) 23258* HAVE_INT64_T: Particular Types. (line 46) 23259* HAVE_INT8_T: Particular Types. (line 21) 23260* HAVE_INTMAX_T: Particular Types. (line 49) 23261* HAVE_INTPTR_T: Particular Types. (line 54) 23262* HAVE_LONG_DOUBLE <1>: Obsolete Macros. (line 33) 23263* HAVE_LONG_DOUBLE: Particular Types. (line 59) 23264* HAVE_LONG_DOUBLE_WIDER: Particular Types. (line 70) 23265* HAVE_LONG_FILE_NAMES: System Services. (line 71) 23266* HAVE_LONG_LONG_INT: Particular Types. (line 78) 23267* HAVE_LSTAT_EMPTY_STRING_BUG: Particular Functions. 23268 (line 363) 23269* HAVE_MALLOC: Particular Functions. 23270 (line 247) 23271* HAVE_MBRTOWC: Particular Functions. 23272 (line 279) 23273* HAVE_MMAP: Particular Functions. 23274 (line 311) 23275* HAVE_NDIR_H: Particular Headers. (line 25) 23276* HAVE_NLIST_H: Particular Functions. 23277 (line 161) 23278* HAVE_OBSTACK: Particular Functions. 23279 (line 319) 23280* HAVE_REALLOC: Particular Functions. 23281 (line 326) 23282* HAVE_RESOLV_H: Particular Headers. (line 73) 23283* HAVE_RESTARTABLE_SYSCALLS: Obsolete Macros. (line 548) 23284* HAVE_ST_BLKSIZE: Obsolete Macros. (line 521) 23285* HAVE_ST_BLOCKS: Particular Structures. 23286 (line 26) 23287* HAVE_ST_RDEV: Obsolete Macros. (line 530) 23288* HAVE_STAT_EMPTY_STRING_BUG: Particular Functions. 23289 (line 363) 23290* HAVE_STDBOOL_H: Particular Headers. (line 101) 23291* HAVE_STRCOLL: Particular Functions. 23292 (line 379) 23293* HAVE_STRERROR_R: Particular Functions. 23294 (line 388) 23295* HAVE_STRFTIME: Particular Functions. 23296 (line 401) 23297* HAVE_STRINGIZE: C Compiler. (line 305) 23298* HAVE_STRNLEN: Particular Functions. 23299 (line 426) 23300* HAVE_STRTOLD: Particular Functions. 23301 (line 420) 23302* HAVE_STRUCT_DIRENT_D_INO: Particular Structures. 23303 (line 9) 23304* HAVE_STRUCT_DIRENT_D_TYPE: Particular Structures. 23305 (line 21) 23306* HAVE_STRUCT_STAT_ST_BLKSIZE: Obsolete Macros. (line 521) 23307* HAVE_STRUCT_STAT_ST_BLOCKS: Particular Structures. 23308 (line 26) 23309* HAVE_STRUCT_STAT_ST_RDEV: Obsolete Macros. (line 530) 23310* HAVE_STRUCT_TM_TM_ZONE: Particular Structures. 23311 (line 43) 23312* HAVE_SYS_DIR_H: Particular Headers. (line 25) 23313* HAVE_SYS_NDIR_H: Particular Headers. (line 25) 23314* HAVE_SYS_WAIT_H: Particular Headers. (line 204) 23315* HAVE_TM_ZONE: Particular Structures. 23316 (line 43) 23317* HAVE_TYPE: Generic Types. (line 28) 23318* HAVE_TYPEOF: C Compiler. (line 345) 23319* HAVE_TZNAME: Particular Structures. 23320 (line 43) 23321* HAVE_UINT16_T: Particular Types. (line 138) 23322* HAVE_UINT32_T: Particular Types. (line 141) 23323* HAVE_UINT64_T: Particular Types. (line 144) 23324* HAVE_UINT8_T: Particular Types. (line 132) 23325* HAVE_UINTMAX_T: Particular Types. (line 147) 23326* HAVE_UINTPTR_T: Particular Types. (line 152) 23327* HAVE_UNSIGNED_LONG_LONG_INT: Particular Types. (line 157) 23328* HAVE_UTIME_NULL: Particular Functions. 23329 (line 433) 23330* HAVE_VFORK_H: Particular Functions. 23331 (line 120) 23332* HAVE_VPRINTF: Particular Functions. 23333 (line 443) 23334* HAVE_WAIT3: Obsolete Macros. (line 216) 23335* HAVE_WORKING_FORK: Particular Functions. 23336 (line 120) 23337* HAVE_WORKING_VFORK: Particular Functions. 23338 (line 120) 23339* inline: C Compiler. (line 286) 23340* int16_t: Particular Types. (line 40) 23341* int32_t: Particular Types. (line 43) 23342* int64_t: Particular Types. (line 46) 23343* int8_t: Particular Types. (line 21) 23344* INT_16_BITS: Obsolete Macros. (line 275) 23345* intmax_t: Particular Types. (line 49) 23346* intptr_t: Particular Types. (line 54) 23347* LONG_64_BITS: Obsolete Macros. (line 337) 23348* LSTAT_FOLLOWS_SLASHED_SYMLINK: Particular Functions. 23349 (line 228) 23350* MAJOR_IN_MKDEV: Particular Headers. (line 68) 23351* MAJOR_IN_SYSMACROS: Particular Headers. (line 68) 23352* malloc: Particular Functions. 23353 (line 247) 23354* mbstate_t: Particular Types. (line 88) 23355* mode_t: Particular Types. (line 96) 23356* NDEBUG: Particular Headers. (line 20) 23357* NDIR: Obsolete Macros. (line 158) 23358* NEED_MEMORY_H: Obsolete Macros. (line 358) 23359* NEED_SETGID: Particular Functions. 23360 (line 161) 23361* NLIST_NAME_UNION: Particular Functions. 23362 (line 161) 23363* NO_MINUS_C_MINUS_O: C Compiler. (line 102) 23364* off_t: Particular Types. (line 102) 23365* PACKAGE_BUGREPORT: Initializing configure. 23366 (line 57) 23367* PACKAGE_NAME: Initializing configure. 23368 (line 45) 23369* PACKAGE_STRING: Initializing configure. 23370 (line 54) 23371* PACKAGE_TARNAME: Initializing configure. 23372 (line 48) 23373* PACKAGE_URL: Initializing configure. 23374 (line 61) 23375* PACKAGE_VERSION: Initializing configure. 23376 (line 51) 23377* PARAMS: C Compiler. (line 351) 23378* pid_t: Particular Types. (line 108) 23379* PROTOTYPES: C Compiler. (line 351) 23380* realloc: Particular Functions. 23381 (line 326) 23382* restrict: C Compiler. (line 247) 23383* RETSIGTYPE: Obsolete Macros. (line 662) 23384* SELECT_TYPE_ARG1: Particular Functions. 23385 (line 337) 23386* SELECT_TYPE_ARG234: Particular Functions. 23387 (line 337) 23388* SELECT_TYPE_ARG5: Particular Functions. 23389 (line 337) 23390* SETPGRP_VOID: Particular Functions. 23391 (line 348) 23392* SETVBUF_REVERSED: Obsolete Macros. (line 208) 23393* size_t: Particular Types. (line 114) 23394* SIZEOF_TYPE-OR-EXPR: Generic Compiler Characteristics. 23395 (line 8) 23396* ssize_t: Particular Types. (line 120) 23397* STAT_MACROS_BROKEN: Particular Headers. (line 92) 23398* STDC_HEADERS: Particular Headers. (line 135) 23399* STRERROR_R_CHAR_P: Particular Functions. 23400 (line 388) 23401* SVR4: Particular Functions. 23402 (line 161) 23403* SYS_SIGLIST_DECLARED: Obsolete Macros. (line 141) 23404* SYSDIR: Obsolete Macros. (line 158) 23405* SYSNDIR: Obsolete Macros. (line 158) 23406* TIME_WITH_SYS_TIME: Particular Headers. (line 244) 23407* TM_IN_SYS_TIME: Particular Structures. 23408 (line 35) 23409* typeof: C Compiler. (line 345) 23410* uid_t: Particular Types. (line 126) 23411* uint16_t: Particular Types. (line 138) 23412* uint32_t: Particular Types. (line 141) 23413* uint64_t: Particular Types. (line 144) 23414* uint8_t: Particular Types. (line 132) 23415* uintmax_t: Particular Types. (line 147) 23416* uintptr_t: Particular Types. (line 152) 23417* UMAX: Particular Functions. 23418 (line 161) 23419* UMAX4_3: Particular Functions. 23420 (line 161) 23421* USG: Obsolete Macros. (line 685) 23422* VARIABLE: Defining Symbols. (line 32) 23423* vfork: Particular Functions. 23424 (line 120) 23425* volatile: C Compiler. (line 265) 23426* WORDS_BIGENDIAN: C Compiler. (line 184) 23427* X_DISPLAY_MISSING: System Services. (line 30) 23428* YYTEXT_POINTER: Particular Programs. (line 114) 23429 23430 23431File: autoconf.info, Node: Cache Variable Index, Next: Autoconf Macro Index, Prev: Preprocessor Symbol Index, Up: Indices 23432 23433B.4 Cache Variable Index 23434======================== 23435 23436This is an alphabetical list of documented cache variables used by 23437macros defined in Autoconf. Autoconf macros may use additional cache 23438variables internally. 23439 23440�[index�] 23441* Menu: 23442 23443* ac_cv_alignof_TYPE-OR-EXPR: Generic Compiler Characteristics. 23444 (line 30) 23445* ac_cv_c_const: C Compiler. (line 217) 23446* ac_cv_c_int16_t: Particular Types. (line 40) 23447* ac_cv_c_int32_t: Particular Types. (line 43) 23448* ac_cv_c_int64_t: Particular Types. (line 46) 23449* ac_cv_c_int8_t: Particular Types. (line 21) 23450* ac_cv_c_restrict: C Compiler. (line 247) 23451* ac_cv_c_uint16_t: Particular Types. (line 138) 23452* ac_cv_c_uint32_t: Particular Types. (line 141) 23453* ac_cv_c_uint64_t: Particular Types. (line 144) 23454* ac_cv_c_uint8_t: Particular Types. (line 132) 23455* ac_cv_f77_compiler_gnu: Fortran Compiler. (line 19) 23456* ac_cv_f77_dummy_main: Fortran Compiler. (line 130) 23457* ac_cv_f77_implicit_none: Fortran Compiler. (line 427) 23458* ac_cv_f77_libs: Fortran Compiler. (line 92) 23459* ac_cv_f77_main: Fortran Compiler. (line 176) 23460* ac_cv_f77_mangling: Fortran Compiler. (line 202) 23461* ac_cv_fc_check_bounds: Fortran Compiler. (line 413) 23462* ac_cv_fc_compiler_gnu: Fortran Compiler. (line 44) 23463* ac_cv_fc_dummy_main: Fortran Compiler. (line 130) 23464* ac_cv_fc_fixedform: Fortran Compiler. (line 375) 23465* ac_cv_fc_freeform: Fortran Compiler. (line 351) 23466* ac_cv_fc_implicit_none: Fortran Compiler. (line 427) 23467* ac_cv_fc_libs: Fortran Compiler. (line 92) 23468* ac_cv_fc_line_length: Fortran Compiler. (line 396) 23469* ac_cv_fc_main: Fortran Compiler. (line 176) 23470* ac_cv_fc_mangling: Fortran Compiler. (line 202) 23471* ac_cv_fc_module_ext: Fortran Compiler. (line 438) 23472* ac_cv_fc_module_flag: Fortran Compiler. (line 465) 23473* ac_cv_fc_module_output_flag: Fortran Compiler. (line 501) 23474* ac_cv_fc_pp_define: Fortran Compiler. (line 336) 23475* ac_cv_fc_pp_srcext_EXT: Fortran Compiler. (line 279) 23476* ac_cv_fc_srcext_EXT: Fortran Compiler. (line 279) 23477* ac_cv_file_FILE: Files. (line 13) 23478* ac_cv_func_chown_works: Particular Functions. 23479 (line 63) 23480* ac_cv_func_closedir_void: Particular Functions. 23481 (line 69) 23482* ac_cv_func_fnmatch_gnu: Particular Functions. 23483 (line 109) 23484* ac_cv_func_fnmatch_works: Particular Functions. 23485 (line 94) 23486* ac_cv_func_FUNCTION: Generic Functions. (line 15) 23487* ac_cv_func_getgroups_works: Particular Functions. 23488 (line 155) 23489* ac_cv_func_getpgrp_void: Particular Functions. 23490 (line 205) 23491* ac_cv_func_lstat_dereferences_slashed_symlink: Particular Functions. 23492 (line 228) 23493* ac_cv_func_lstat_empty_string_bug: Particular Functions. 23494 (line 363) 23495* ac_cv_func_malloc_0_nonnull: Particular Functions. 23496 (line 247) 23497* ac_cv_func_mbrtowc: Particular Functions. 23498 (line 279) 23499* ac_cv_func_memcmp_working: Particular Functions. 23500 (line 286) 23501* ac_cv_func_mmap_fixed_mapped: Particular Functions. 23502 (line 311) 23503* ac_cv_func_obstack: Particular Functions. 23504 (line 319) 23505* ac_cv_func_pow: Particular Functions. 23506 (line 408) 23507* ac_cv_func_realloc_0_nonnull: Particular Functions. 23508 (line 326) 23509* ac_cv_func_setpgrp_void: Particular Functions. 23510 (line 348) 23511* ac_cv_func_stat_empty_string_bug: Particular Functions. 23512 (line 363) 23513* ac_cv_func_strcoll_works: Particular Functions. 23514 (line 379) 23515* ac_cv_func_strerror_r_char_p: Particular Functions. 23516 (line 388) 23517* ac_cv_func_strnlen_working: Particular Functions. 23518 (line 426) 23519* ac_cv_func_strtod: Particular Functions. 23520 (line 408) 23521* ac_cv_func_strtold: Particular Functions. 23522 (line 420) 23523* ac_cv_func_utime_null: Particular Functions. 23524 (line 433) 23525* ac_cv_func_working_mktime: Particular Functions. 23526 (line 299) 23527* ac_cv_have_decl_SYMBOL: Generic Declarations. 23528 (line 11) 23529* ac_cv_header_HEADER-FILE: Generic Headers. (line 13) 23530* ac_cv_header_stdbool_h: Particular Headers. (line 10) 23531* ac_cv_header_stdc: Particular Headers. (line 135) 23532* ac_cv_header_sys_wait_h: Particular Headers. (line 204) 23533* ac_cv_header_time: Particular Headers. (line 244) 23534* ac_cv_lib_error_at_line: Particular Functions. 23535 (line 84) 23536* ac_cv_lib_LIBRARY_FUNCTION: Libraries. (line 11) 23537* ac_cv_member_AGGREGATE_MEMBER: Generic Structures. (line 11) 23538* ac_cv_member_struct_stat_st_blocks: Particular Structures. 23539 (line 26) 23540* ac_cv_path_install: Particular Programs. (line 43) 23541* ac_cv_path_mkdir: Particular Programs. (line 80) 23542* ac_cv_path_SED: Particular Programs. (line 191) 23543* ac_cv_path_VARIABLE: Generic Programs. (line 108) 23544* ac_cv_prog_AWK: Particular Programs. (line 10) 23545* ac_cv_prog_c_openmp: Generic Compiler Characteristics. 23546 (line 64) 23547* ac_cv_prog_cc_c89: C Compiler. (line 61) 23548* ac_cv_prog_cc_c99: C Compiler. (line 161) 23549* ac_cv_prog_cc_COMPILER_c_o: C Compiler. (line 102) 23550* ac_cv_prog_cc_stdc: C Compiler. (line 137) 23551* ac_cv_prog_cxx_openmp: Generic Compiler Characteristics. 23552 (line 64) 23553* ac_cv_prog_EGREP: Particular Programs. (line 29) 23554* ac_cv_prog_f77_c_o: Fortran Compiler. (line 76) 23555* ac_cv_prog_f77_g: Fortran Compiler. (line 19) 23556* ac_cv_prog_f77_openmp: Generic Compiler Characteristics. 23557 (line 64) 23558* ac_cv_prog_f77_v: Fortran Compiler. (line 92) 23559* ac_cv_prog_fc_c_o: Fortran Compiler. (line 76) 23560* ac_cv_prog_fc_g: Fortran Compiler. (line 44) 23561* ac_cv_prog_fc_openmp: Generic Compiler Characteristics. 23562 (line 64) 23563* ac_cv_prog_fc_v: Fortran Compiler. (line 92) 23564* ac_cv_prog_FGREP: Particular Programs. (line 36) 23565* ac_cv_prog_GREP: Particular Programs. (line 20) 23566* ac_cv_prog_LEX: Particular Programs. (line 114) 23567* ac_cv_prog_VARIABLE: Generic Programs. (line 24) 23568* ac_cv_prog_YACC: Particular Programs. (line 200) 23569* ac_cv_search_FUNCTION: Libraries. (line 52) 23570* ac_cv_search_getmntent: Particular Functions. 23571 (line 195) 23572* ac_cv_sizeof_TYPE-OR-EXPR: Generic Compiler Characteristics. 23573 (line 8) 23574* ac_cv_sys_posix_termios: System Services. (line 75) 23575* ac_cv_type_getgroups: Particular Types. (line 14) 23576* ac_cv_type_long_double: Particular Types. (line 59) 23577* ac_cv_type_long_double_wider: Particular Types. (line 70) 23578* ac_cv_type_long_long_int: Particular Types. (line 78) 23579* ac_cv_type_mbstate_t: Particular Types. (line 88) 23580* ac_cv_type_mode_t: Particular Types. (line 96) 23581* ac_cv_type_off_t: Particular Types. (line 102) 23582* ac_cv_type_pid_t: Particular Types. (line 108) 23583* ac_cv_type_size_t: Particular Types. (line 114) 23584* ac_cv_type_ssize_t: Particular Types. (line 120) 23585* ac_cv_type_TYPE: Generic Types. (line 11) 23586* ac_cv_type_uid_t: Particular Types. (line 126) 23587* ac_cv_type_unsigned_long_long_int: Particular Types. (line 157) 23588 23589 23590File: autoconf.info, Node: Autoconf Macro Index, Next: M4 Macro Index, Prev: Cache Variable Index, Up: Indices 23591 23592B.5 Autoconf Macro Index 23593======================== 23594 23595This is an alphabetical list of the Autoconf macros. 23596 23597�[index�] 23598* Menu: 23599 23600* AC_ACT_IFELSE: AC_ACT_IFELSE vs AC_TRY_ACT. 23601 (line 6) 23602* AC_AIX: Obsolete Macros. (line 20) 23603* AC_ALLOCA: Obsolete Macros. (line 24) 23604* AC_ARG_ARRAY: Obsolete Macros. (line 27) 23605* AC_ARG_ENABLE: Package Options. (line 35) 23606* AC_ARG_PROGRAM: Transforming Names. (line 11) 23607* AC_ARG_VAR: Setting Output Variables. 23608 (line 79) 23609* AC_ARG_WITH: External Software. (line 36) 23610* AC_AUTOCONF_VERSION: Versioning. (line 21) 23611* AC_BEFORE: Suggested Ordering. (line 28) 23612* AC_C_BACKSLASH_A: C Compiler. (line 176) 23613* AC_C_BIGENDIAN: C Compiler. (line 184) 23614* AC_C_CHAR_UNSIGNED: C Compiler. (line 291) 23615* AC_C_CONST: C Compiler. (line 217) 23616* AC_C_CROSS: Obsolete Macros. (line 30) 23617* AC_C_FLEXIBLE_ARRAY_MEMBER: C Compiler. (line 315) 23618* AC_C_INLINE: C Compiler. (line 286) 23619* AC_C_LONG_DOUBLE: Obsolete Macros. (line 33) 23620* AC_C_PROTOTYPES: C Compiler. (line 351) 23621* AC_C_RESTRICT: C Compiler. (line 247) 23622* AC_C_STRINGIZE: C Compiler. (line 305) 23623* AC_C_TYPEOF: C Compiler. (line 345) 23624* AC_C_VARARRAYS: C Compiler. (line 339) 23625* AC_C_VOLATILE: C Compiler. (line 265) 23626* AC_CACHE_CHECK: Caching Results. (line 30) 23627* AC_CACHE_LOAD: Cache Checkpointing. (line 13) 23628* AC_CACHE_SAVE: Cache Checkpointing. (line 17) 23629* AC_CACHE_VAL: Caching Results. (line 16) 23630* AC_CANONICAL_BUILD: Canonicalizing. (line 26) 23631* AC_CANONICAL_HOST: Canonicalizing. (line 34) 23632* AC_CANONICAL_SYSTEM: Obsolete Macros. (line 41) 23633* AC_CANONICAL_TARGET: Canonicalizing. (line 41) 23634* AC_CHAR_UNSIGNED: Obsolete Macros. (line 51) 23635* AC_CHECK_ALIGNOF: Generic Compiler Characteristics. 23636 (line 30) 23637* AC_CHECK_DECL: Generic Declarations. 23638 (line 11) 23639* AC_CHECK_DECLS: Generic Declarations. 23640 (line 34) 23641* AC_CHECK_DECLS_ONCE: Generic Declarations. 23642 (line 79) 23643* AC_CHECK_FILE: Files. (line 13) 23644* AC_CHECK_FILES: Files. (line 21) 23645* AC_CHECK_FUNC: Generic Functions. (line 15) 23646* AC_CHECK_FUNCS: Generic Functions. (line 27) 23647* AC_CHECK_FUNCS_ONCE: Generic Functions. (line 38) 23648* AC_CHECK_HEADER: Generic Headers. (line 13) 23649* AC_CHECK_HEADER_STDBOOL: Particular Headers. (line 10) 23650* AC_CHECK_HEADERS: Generic Headers. (line 46) 23651* AC_CHECK_HEADERS_ONCE: Generic Headers. (line 87) 23652* AC_CHECK_LIB: Libraries. (line 11) 23653* AC_CHECK_MEMBER: Generic Structures. (line 11) 23654* AC_CHECK_MEMBERS: Generic Structures. (line 29) 23655* AC_CHECK_PROG: Generic Programs. (line 24) 23656* AC_CHECK_PROGS: Generic Programs. (line 36) 23657* AC_CHECK_SIZEOF: Generic Compiler Characteristics. 23658 (line 8) 23659* AC_CHECK_TARGET_TOOL: Generic Programs. (line 48) 23660* AC_CHECK_TARGET_TOOLS: Generic Programs. (line 79) 23661* AC_CHECK_TOOL: Generic Programs. (line 64) 23662* AC_CHECK_TOOLS: Generic Programs. (line 92) 23663* AC_CHECK_TYPE <1>: Obsolete Macros. (line 54) 23664* AC_CHECK_TYPE: Generic Types. (line 11) 23665* AC_CHECK_TYPES: Generic Types. (line 28) 23666* AC_CHECKING: Obsolete Macros. (line 101) 23667* AC_COMPILE_CHECK: Obsolete Macros. (line 109) 23668* AC_COMPILE_IFELSE: Running the Compiler. 23669 (line 13) 23670* AC_COMPUTE_INT: Generic Compiler Characteristics. 23671 (line 42) 23672* AC_CONFIG_AUX_DIR: Input. (line 20) 23673* AC_CONFIG_COMMANDS: Configuration Commands. 23674 (line 13) 23675* AC_CONFIG_COMMANDS_POST: Configuration Commands. 23676 (line 41) 23677* AC_CONFIG_COMMANDS_PRE: Configuration Commands. 23678 (line 35) 23679* AC_CONFIG_FILES: Configuration Files. (line 9) 23680* AC_CONFIG_HEADERS: Configuration Headers. 23681 (line 33) 23682* AC_CONFIG_ITEMS: Configuration Actions. 23683 (line 12) 23684* AC_CONFIG_LIBOBJ_DIR: Generic Functions. (line 97) 23685* AC_CONFIG_LINKS: Configuration Links. (line 12) 23686* AC_CONFIG_MACRO_DIR: Input. (line 48) 23687* AC_CONFIG_SRCDIR: Input. (line 7) 23688* AC_CONFIG_SUBDIRS: Subdirectories. (line 12) 23689* AC_CONFIG_TESTDIR: Making testsuite Scripts. 23690 (line 26) 23691* AC_CONST: Obsolete Macros. (line 117) 23692* AC_COPYRIGHT: Notices. (line 10) 23693* AC_CROSS_CHECK: Obsolete Macros. (line 120) 23694* AC_CYGWIN: Obsolete Macros. (line 124) 23695* AC_DATAROOTDIR_CHECKED: Changed Directory Variables. 23696 (line 58) 23697* AC_DECL_SYS_SIGLIST: Obsolete Macros. (line 141) 23698* AC_DECL_YYTEXT: Obsolete Macros. (line 154) 23699* AC_DEFINE: Defining Symbols. (line 32) 23700* AC_DEFINE_UNQUOTED: Defining Symbols. (line 74) 23701* AC_DEFUN: Macro Definitions. (line 7) 23702* AC_DEFUN_ONCE: One-Shot Macros. (line 14) 23703* AC_DIAGNOSE: Reporting Messages. (line 18) 23704* AC_DIR_HEADER: Obsolete Macros. (line 158) 23705* AC_DISABLE_OPTION_CHECKING: Option Checking. (line 28) 23706* AC_DYNIX_SEQ: Obsolete Macros. (line 170) 23707* AC_EGREP_CPP: Running the Preprocessor. 23708 (line 74) 23709* AC_EGREP_HEADER: Running the Preprocessor. 23710 (line 67) 23711* AC_EMXOS2: Obsolete Macros. (line 183) 23712* AC_ENABLE: Obsolete Macros. (line 189) 23713* AC_ERLANG_CHECK_LIB: Erlang Libraries. (line 36) 23714* AC_ERLANG_NEED_ERL: Erlang Compiler and Interpreter. 23715 (line 41) 23716* AC_ERLANG_NEED_ERLC: Erlang Compiler and Interpreter. 23717 (line 24) 23718* AC_ERLANG_PATH_ERL: Erlang Compiler and Interpreter. 23719 (line 29) 23720* AC_ERLANG_PATH_ERLC: Erlang Compiler and Interpreter. 23721 (line 10) 23722* AC_ERLANG_SUBST_ERTS_VER: Erlang Libraries. (line 12) 23723* AC_ERLANG_SUBST_INSTALL_LIB_DIR <1>: Erlang Libraries. (line 86) 23724* AC_ERLANG_SUBST_INSTALL_LIB_DIR: Installation Directory Variables. 23725 (line 201) 23726* AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR <1>: Erlang Libraries. (line 93) 23727* AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR: Installation Directory Variables. 23728 (line 206) 23729* AC_ERLANG_SUBST_LIB_DIR: Erlang Libraries. (line 28) 23730* AC_ERLANG_SUBST_ROOT_DIR: Erlang Libraries. (line 22) 23731* AC_ERROR: Obsolete Macros. (line 193) 23732* AC_EXEEXT: Obsolete Macros. (line 178) 23733* AC_F77_DUMMY_MAIN: Fortran Compiler. (line 130) 23734* AC_F77_FUNC: Fortran Compiler. (line 266) 23735* AC_F77_IMPLICIT_NONE: Fortran Compiler. (line 427) 23736* AC_F77_LIBRARY_LDFLAGS: Fortran Compiler. (line 92) 23737* AC_F77_MAIN: Fortran Compiler. (line 176) 23738* AC_F77_WRAPPERS: Fortran Compiler. (line 202) 23739* AC_FATAL: Reporting Messages. (line 34) 23740* AC_FC_CHECK_BOUNDS: Fortran Compiler. (line 413) 23741* AC_FC_DUMMY_MAIN: Fortran Compiler. (line 130) 23742* AC_FC_FIXEDFORM: Fortran Compiler. (line 375) 23743* AC_FC_FREEFORM: Fortran Compiler. (line 351) 23744* AC_FC_FUNC: Fortran Compiler. (line 266) 23745* AC_FC_IMPLICIT_NONE: Fortran Compiler. (line 427) 23746* AC_FC_LIBRARY_LDFLAGS: Fortran Compiler. (line 92) 23747* AC_FC_LINE_LENGTH: Fortran Compiler. (line 396) 23748* AC_FC_MAIN: Fortran Compiler. (line 176) 23749* AC_FC_MODULE_EXTENSION: Fortran Compiler. (line 438) 23750* AC_FC_MODULE_FLAG: Fortran Compiler. (line 465) 23751* AC_FC_MODULE_OUTPUT_FLAG: Fortran Compiler. (line 501) 23752* AC_FC_PP_DEFINE: Fortran Compiler. (line 336) 23753* AC_FC_PP_SRCEXT: Fortran Compiler. (line 279) 23754* AC_FC_SRCEXT: Fortran Compiler. (line 279) 23755* AC_FC_WRAPPERS: Fortran Compiler. (line 202) 23756* AC_FIND_X: Obsolete Macros. (line 196) 23757* AC_FIND_XTRA: Obsolete Macros. (line 199) 23758* AC_FOREACH: Obsolete Macros. (line 202) 23759* AC_FUNC_ALLOCA: Particular Functions. 23760 (line 10) 23761* AC_FUNC_CHECK: Obsolete Macros. (line 205) 23762* AC_FUNC_CHOWN: Particular Functions. 23763 (line 63) 23764* AC_FUNC_CLOSEDIR_VOID: Particular Functions. 23765 (line 69) 23766* AC_FUNC_ERROR_AT_LINE: Particular Functions. 23767 (line 84) 23768* AC_FUNC_FNMATCH: Particular Functions. 23769 (line 94) 23770* AC_FUNC_FNMATCH_GNU: Particular Functions. 23771 (line 109) 23772* AC_FUNC_FORK: Particular Functions. 23773 (line 120) 23774* AC_FUNC_FSEEKO: Particular Functions. 23775 (line 147) 23776* AC_FUNC_GETGROUPS: Particular Functions. 23777 (line 155) 23778* AC_FUNC_GETLOADAVG: Particular Functions. 23779 (line 161) 23780* AC_FUNC_GETMNTENT: Particular Functions. 23781 (line 195) 23782* AC_FUNC_GETPGRP: Particular Functions. 23783 (line 205) 23784* AC_FUNC_LSTAT: Particular Functions. 23785 (line 363) 23786* AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK: Particular Functions. 23787 (line 228) 23788* AC_FUNC_MALLOC: Particular Functions. 23789 (line 247) 23790* AC_FUNC_MBRTOWC: Particular Functions. 23791 (line 279) 23792* AC_FUNC_MEMCMP: Particular Functions. 23793 (line 286) 23794* AC_FUNC_MKTIME: Particular Functions. 23795 (line 299) 23796* AC_FUNC_MMAP: Particular Functions. 23797 (line 311) 23798* AC_FUNC_OBSTACK: Particular Functions. 23799 (line 319) 23800* AC_FUNC_REALLOC: Particular Functions. 23801 (line 326) 23802* AC_FUNC_SELECT_ARGTYPES: Particular Functions. 23803 (line 337) 23804* AC_FUNC_SETPGRP: Particular Functions. 23805 (line 348) 23806* AC_FUNC_SETVBUF_REVERSED: Obsolete Macros. (line 208) 23807* AC_FUNC_STAT: Particular Functions. 23808 (line 363) 23809* AC_FUNC_STRCOLL: Particular Functions. 23810 (line 379) 23811* AC_FUNC_STRERROR_R: Particular Functions. 23812 (line 388) 23813* AC_FUNC_STRFTIME: Particular Functions. 23814 (line 401) 23815* AC_FUNC_STRNLEN: Particular Functions. 23816 (line 426) 23817* AC_FUNC_STRTOD: Particular Functions. 23818 (line 408) 23819* AC_FUNC_STRTOLD: Particular Functions. 23820 (line 420) 23821* AC_FUNC_UTIME_NULL: Particular Functions. 23822 (line 433) 23823* AC_FUNC_VPRINTF: Particular Functions. 23824 (line 443) 23825* AC_FUNC_WAIT3: Obsolete Macros. (line 216) 23826* AC_GCC_TRADITIONAL: Obsolete Macros. (line 224) 23827* AC_GETGROUPS_T: Obsolete Macros. (line 228) 23828* AC_GETLOADAVG: Obsolete Macros. (line 231) 23829* AC_GNU_SOURCE: Obsolete Macros. (line 234) 23830* AC_HAVE_FUNCS: Obsolete Macros. (line 238) 23831* AC_HAVE_HEADERS: Obsolete Macros. (line 241) 23832* AC_HAVE_LIBRARY: Obsolete Macros. (line 245) 23833* AC_HAVE_POUNDBANG: Obsolete Macros. (line 252) 23834* AC_HEADER_ASSERT: Particular Headers. (line 20) 23835* AC_HEADER_CHECK: Obsolete Macros. (line 255) 23836* AC_HEADER_DIRENT: Particular Headers. (line 25) 23837* AC_HEADER_EGREP: Obsolete Macros. (line 258) 23838* AC_HEADER_MAJOR: Particular Headers. (line 68) 23839* AC_HEADER_RESOLV: Particular Headers. (line 73) 23840* AC_HEADER_STAT: Particular Headers. (line 92) 23841* AC_HEADER_STDBOOL: Particular Headers. (line 101) 23842* AC_HEADER_STDC: Particular Headers. (line 135) 23843* AC_HEADER_SYS_WAIT: Particular Headers. (line 204) 23844* AC_HEADER_TIME: Particular Headers. (line 244) 23845* AC_HEADER_TIOCGWINSZ: Particular Headers. (line 270) 23846* AC_HELP_STRING: Obsolete Macros. (line 261) 23847* AC_INCLUDES_DEFAULT: Default Includes. (line 29) 23848* AC_INIT <1>: Obsolete Macros. (line 264) 23849* AC_INIT: Initializing configure. 23850 (line 14) 23851* AC_INLINE: Obsolete Macros. (line 272) 23852* AC_INT_16_BITS: Obsolete Macros. (line 275) 23853* AC_IRIX_SUN: Obsolete Macros. (line 279) 23854* AC_ISC_POSIX: Obsolete Macros. (line 295) 23855* AC_LANG: Language Choice. (line 14) 23856* AC_LANG_ASSERT: Language Choice. (line 79) 23857* AC_LANG_C: Obsolete Macros. (line 302) 23858* AC_LANG_CALL: Generating Sources. (line 142) 23859* AC_LANG_CONFTEST: Generating Sources. (line 12) 23860* AC_LANG_CPLUSPLUS: Obsolete Macros. (line 305) 23861* AC_LANG_DEFINES_PROVIDED: Generating Sources. (line 31) 23862* AC_LANG_FORTRAN77: Obsolete Macros. (line 308) 23863* AC_LANG_FUNC_LINK_TRY: Generating Sources. (line 154) 23864* AC_LANG_POP: Language Choice. (line 66) 23865* AC_LANG_PROGRAM: Generating Sources. (line 78) 23866* AC_LANG_PUSH: Language Choice. (line 61) 23867* AC_LANG_RESTORE: Obsolete Macros. (line 311) 23868* AC_LANG_SAVE: Obsolete Macros. (line 317) 23869* AC_LANG_SOURCE: Generating Sources. (line 40) 23870* AC_LANG_WERROR: Generic Compiler Characteristics. 23871 (line 54) 23872* AC_LIBOBJ: Generic Functions. (line 56) 23873* AC_LIBSOURCE: Generic Functions. (line 65) 23874* AC_LIBSOURCES: Generic Functions. (line 89) 23875* AC_LINK_FILES: Obsolete Macros. (line 322) 23876* AC_LINK_IFELSE: Running the Linker. (line 24) 23877* AC_LN_S: Obsolete Macros. (line 334) 23878* AC_LONG_64_BITS: Obsolete Macros. (line 337) 23879* AC_LONG_DOUBLE: Obsolete Macros. (line 342) 23880* AC_LONG_FILE_NAMES: Obsolete Macros. (line 350) 23881* AC_MAJOR_HEADER: Obsolete Macros. (line 355) 23882* AC_MEMORY_H: Obsolete Macros. (line 358) 23883* AC_MINGW32: Obsolete Macros. (line 365) 23884* AC_MINIX: Obsolete Macros. (line 371) 23885* AC_MINUS_C_MINUS_O: Obsolete Macros. (line 375) 23886* AC_MMAP: Obsolete Macros. (line 378) 23887* AC_MODE_T: Obsolete Macros. (line 381) 23888* AC_MSG_CHECKING: Printing Messages. (line 24) 23889* AC_MSG_ERROR: Printing Messages. (line 56) 23890* AC_MSG_FAILURE: Printing Messages. (line 66) 23891* AC_MSG_NOTICE: Printing Messages. (line 46) 23892* AC_MSG_RESULT: Printing Messages. (line 35) 23893* AC_MSG_WARN: Printing Messages. (line 72) 23894* AC_OBJEXT: Obsolete Macros. (line 384) 23895* AC_OBSOLETE: Obsolete Macros. (line 390) 23896* AC_OFF_T: Obsolete Macros. (line 405) 23897* AC_OPENMP: Generic Compiler Characteristics. 23898 (line 64) 23899* AC_OUTPUT <1>: Obsolete Macros. (line 408) 23900* AC_OUTPUT: Output. (line 13) 23901* AC_OUTPUT_COMMANDS: Obsolete Macros. (line 420) 23902* AC_PACKAGE_BUGREPORT: Initializing configure. 23903 (line 57) 23904* AC_PACKAGE_NAME: Initializing configure. 23905 (line 45) 23906* AC_PACKAGE_STRING: Initializing configure. 23907 (line 54) 23908* AC_PACKAGE_TARNAME: Initializing configure. 23909 (line 48) 23910* AC_PACKAGE_URL: Initializing configure. 23911 (line 61) 23912* AC_PACKAGE_VERSION: Initializing configure. 23913 (line 51) 23914* AC_PATH_PROG: Generic Programs. (line 108) 23915* AC_PATH_PROGS: Generic Programs. (line 115) 23916* AC_PATH_PROGS_FEATURE_CHECK: Generic Programs. (line 123) 23917* AC_PATH_TARGET_TOOL: Generic Programs. (line 159) 23918* AC_PATH_TOOL: Generic Programs. (line 164) 23919* AC_PATH_X: System Services. (line 10) 23920* AC_PATH_XTRA: System Services. (line 30) 23921* AC_PID_T: Obsolete Macros. (line 450) 23922* AC_PREFIX: Obsolete Macros. (line 453) 23923* AC_PREFIX_DEFAULT: Default Prefix. (line 16) 23924* AC_PREFIX_PROGRAM: Default Prefix. (line 25) 23925* AC_PREPROC_IFELSE: Running the Preprocessor. 23926 (line 20) 23927* AC_PREREQ: Versioning. (line 11) 23928* AC_PRESERVE_HELP_ORDER: Help Formatting. (line 20) 23929* AC_PROG_AWK: Particular Programs. (line 10) 23930* AC_PROG_CC: C Compiler. (line 61) 23931* AC_PROG_CC_C89: C Compiler. (line 147) 23932* AC_PROG_CC_C99: C Compiler. (line 161) 23933* AC_PROG_CC_C_O: C Compiler. (line 102) 23934* AC_PROG_CC_STDC: C Compiler. (line 137) 23935* AC_PROG_CPP: C Compiler. (line 113) 23936* AC_PROG_CPP_WERROR: C Compiler. (line 126) 23937* AC_PROG_CXX: C++ Compiler. (line 7) 23938* AC_PROG_CXX_C_O: C++ Compiler. (line 48) 23939* AC_PROG_CXXCPP: C++ Compiler. (line 35) 23940* AC_PROG_EGREP: Particular Programs. (line 29) 23941* AC_PROG_F77: Fortran Compiler. (line 19) 23942* AC_PROG_F77_C_O: Fortran Compiler. (line 76) 23943* AC_PROG_FC: Fortran Compiler. (line 44) 23944* AC_PROG_FC_C_O: Fortran Compiler. (line 76) 23945* AC_PROG_FGREP: Particular Programs. (line 36) 23946* AC_PROG_GCC_TRADITIONAL: C Compiler. (line 361) 23947* AC_PROG_GREP: Particular Programs. (line 20) 23948* AC_PROG_INSTALL: Particular Programs. (line 43) 23949* AC_PROG_LEX: Particular Programs. (line 114) 23950* AC_PROG_LN_S: Particular Programs. (line 168) 23951* AC_PROG_MAKE_SET: Output. (line 45) 23952* AC_PROG_MKDIR_P: Particular Programs. (line 80) 23953* AC_PROG_OBJC: Objective C Compiler. 23954 (line 7) 23955* AC_PROG_OBJCPP: Objective C Compiler. 23956 (line 26) 23957* AC_PROG_OBJCXX: Objective C++ Compiler. 23958 (line 7) 23959* AC_PROG_OBJCXXCPP: Objective C++ Compiler. 23960 (line 27) 23961* AC_PROG_RANLIB: Particular Programs. (line 187) 23962* AC_PROG_SED: Particular Programs. (line 191) 23963* AC_PROG_YACC: Particular Programs. (line 200) 23964* AC_PROGRAM_CHECK: Obsolete Macros. (line 462) 23965* AC_PROGRAM_EGREP: Obsolete Macros. (line 465) 23966* AC_PROGRAM_PATH: Obsolete Macros. (line 468) 23967* AC_PROGRAMS_CHECK: Obsolete Macros. (line 456) 23968* AC_PROGRAMS_PATH: Obsolete Macros. (line 459) 23969* AC_REMOTE_TAPE: Obsolete Macros. (line 471) 23970* AC_REPLACE_FNMATCH: Particular Functions. 23971 (line 452) 23972* AC_REPLACE_FUNCS: Generic Functions. (line 117) 23973* AC_REQUIRE: Prerequisite Macros. (line 17) 23974* AC_REQUIRE_AUX_FILE: Input. (line 37) 23975* AC_REQUIRE_CPP: Language Choice. (line 94) 23976* AC_RESTARTABLE_SYSCALLS: Obsolete Macros. (line 474) 23977* AC_RETSIGTYPE: Obsolete Macros. (line 482) 23978* AC_REVISION: Notices. (line 18) 23979* AC_RSH: Obsolete Macros. (line 486) 23980* AC_RUN_IFELSE: Runtime. (line 20) 23981* AC_SCO_INTL: Obsolete Macros. (line 489) 23982* AC_SEARCH_LIBS: Libraries. (line 52) 23983* AC_SET_MAKE: Obsolete Macros. (line 503) 23984* AC_SETVBUF_REVERSED: Obsolete Macros. (line 498) 23985* AC_SIZE_T: Obsolete Macros. (line 509) 23986* AC_SIZEOF_TYPE: Obsolete Macros. (line 506) 23987* AC_ST_BLKSIZE: Obsolete Macros. (line 539) 23988* AC_ST_BLOCKS: Obsolete Macros. (line 542) 23989* AC_ST_RDEV: Obsolete Macros. (line 545) 23990* AC_STAT_MACROS_BROKEN: Obsolete Macros. (line 512) 23991* AC_STDC_HEADERS: Obsolete Macros. (line 515) 23992* AC_STRCOLL: Obsolete Macros. (line 518) 23993* AC_STRUCT_DIRENT_D_INO: Particular Structures. 23994 (line 9) 23995* AC_STRUCT_DIRENT_D_TYPE: Particular Structures. 23996 (line 21) 23997* AC_STRUCT_ST_BLKSIZE: Obsolete Macros. (line 521) 23998* AC_STRUCT_ST_BLOCKS: Particular Structures. 23999 (line 26) 24000* AC_STRUCT_ST_RDEV: Obsolete Macros. (line 530) 24001* AC_STRUCT_TIMEZONE: Particular Structures. 24002 (line 43) 24003* AC_STRUCT_TM: Particular Structures. 24004 (line 35) 24005* AC_SUBST: Setting Output Variables. 24006 (line 13) 24007* AC_SUBST_FILE: Setting Output Variables. 24008 (line 38) 24009* AC_SYS_INTERPRETER: System Services. (line 42) 24010* AC_SYS_LARGEFILE: System Services. (line 49) 24011* AC_SYS_LONG_FILE_NAMES: System Services. (line 71) 24012* AC_SYS_POSIX_TERMIOS: System Services. (line 75) 24013* AC_SYS_RESTARTABLE_SYSCALLS: Obsolete Macros. (line 548) 24014* AC_SYS_SIGLIST_DECLARED: Obsolete Macros. (line 563) 24015* AC_TEST_CPP: Obsolete Macros. (line 568) 24016* AC_TEST_PROGRAM: Obsolete Macros. (line 572) 24017* AC_TIME_WITH_SYS_TIME: Obsolete Macros. (line 579) 24018* AC_TIMEZONE: Obsolete Macros. (line 576) 24019* AC_TRY_ACT: AC_ACT_IFELSE vs AC_TRY_ACT. 24020 (line 6) 24021* AC_TRY_COMPILE: Obsolete Macros. (line 583) 24022* AC_TRY_CPP: Obsolete Macros. (line 602) 24023* AC_TRY_LINK: Obsolete Macros. (line 615) 24024* AC_TRY_LINK_FUNC: Obsolete Macros. (line 644) 24025* AC_TRY_RUN: Obsolete Macros. (line 651) 24026* AC_TYPE_GETGROUPS: Particular Types. (line 14) 24027* AC_TYPE_INT16_T: Particular Types. (line 40) 24028* AC_TYPE_INT32_T: Particular Types. (line 43) 24029* AC_TYPE_INT64_T: Particular Types. (line 46) 24030* AC_TYPE_INT8_T: Particular Types. (line 21) 24031* AC_TYPE_INTMAX_T: Particular Types. (line 49) 24032* AC_TYPE_INTPTR_T: Particular Types. (line 54) 24033* AC_TYPE_LONG_DOUBLE: Particular Types. (line 59) 24034* AC_TYPE_LONG_DOUBLE_WIDER: Particular Types. (line 70) 24035* AC_TYPE_LONG_LONG_INT: Particular Types. (line 78) 24036* AC_TYPE_MBSTATE_T: Particular Types. (line 88) 24037* AC_TYPE_MODE_T: Particular Types. (line 96) 24038* AC_TYPE_OFF_T: Particular Types. (line 102) 24039* AC_TYPE_PID_T: Particular Types. (line 108) 24040* AC_TYPE_SIGNAL: Obsolete Macros. (line 662) 24041* AC_TYPE_SIZE_T: Particular Types. (line 114) 24042* AC_TYPE_SSIZE_T: Particular Types. (line 120) 24043* AC_TYPE_UID_T: Particular Types. (line 126) 24044* AC_TYPE_UINT16_T: Particular Types. (line 138) 24045* AC_TYPE_UINT32_T: Particular Types. (line 141) 24046* AC_TYPE_UINT64_T: Particular Types. (line 144) 24047* AC_TYPE_UINT8_T: Particular Types. (line 132) 24048* AC_TYPE_UINTMAX_T: Particular Types. (line 147) 24049* AC_TYPE_UINTPTR_T: Particular Types. (line 152) 24050* AC_TYPE_UNSIGNED_LONG_LONG_INT: Particular Types. (line 157) 24051* AC_UID_T: Obsolete Macros. (line 679) 24052* AC_UNISTD_H: Obsolete Macros. (line 682) 24053* AC_USE_SYSTEM_EXTENSIONS: Posix Variants. (line 10) 24054* AC_USG: Obsolete Macros. (line 685) 24055* AC_UTIME_NULL: Obsolete Macros. (line 690) 24056* AC_VALIDATE_CACHED_SYSTEM_TUPLE: Obsolete Macros. (line 693) 24057* AC_VERBOSE: Obsolete Macros. (line 698) 24058* AC_VFORK: Obsolete Macros. (line 701) 24059* AC_VPRINTF: Obsolete Macros. (line 704) 24060* AC_WAIT3: Obsolete Macros. (line 707) 24061* AC_WARN: Obsolete Macros. (line 712) 24062* AC_WARNING: Reporting Messages. (line 26) 24063* AC_WITH: Obsolete Macros. (line 715) 24064* AC_WORDS_BIGENDIAN: Obsolete Macros. (line 719) 24065* AC_XENIX_DIR: Obsolete Macros. (line 722) 24066* AC_YYTEXT_POINTER: Obsolete Macros. (line 739) 24067* AH_BOTTOM: Autoheader Macros. (line 50) 24068* AH_HEADER: Configuration Headers. 24069 (line 54) 24070* AH_TEMPLATE: Autoheader Macros. (line 19) 24071* AH_TOP: Autoheader Macros. (line 47) 24072* AH_VERBATIM: Autoheader Macros. (line 40) 24073* AU_ALIAS: Obsoleting Macros. (line 34) 24074* AU_DEFUN: Obsoleting Macros. (line 18) 24075 24076 24077File: autoconf.info, Node: M4 Macro Index, Next: Autotest Macro Index, Prev: Autoconf Macro Index, Up: Indices 24078 24079B.6 M4 Macro Index 24080================== 24081 24082This is an alphabetical list of the M4, M4sugar, and M4sh macros. 24083 24084�[index�] 24085* Menu: 24086 24087* __file__: Redefined M4 Macros. (line 65) 24088* __line__: Redefined M4 Macros. (line 65) 24089* __oline__: Redefined M4 Macros. (line 69) 24090* AS_BOURNE_COMPATIBLE: Initialization Macros. 24091 (line 7) 24092* AS_BOX: Common Shell Constructs. 24093 (line 10) 24094* AS_CASE: Common Shell Constructs. 24095 (line 19) 24096* AS_DIRNAME: Common Shell Constructs. 24097 (line 26) 24098* AS_ECHO: Common Shell Constructs. 24099 (line 34) 24100* AS_ECHO_N: Common Shell Constructs. 24101 (line 42) 24102* AS_ESCAPE: Common Shell Constructs. 24103 (line 50) 24104* AS_EXECUTABLE_P: Common Shell Constructs. 24105 (line 90) 24106* AS_EXIT: Common Shell Constructs. 24107 (line 95) 24108* AS_HELP_STRING: Pretty Help Strings. (line 15) 24109* AS_IF: Common Shell Constructs. 24110 (line 101) 24111* AS_INIT: Initialization Macros. 24112 (line 14) 24113* AS_INIT_GENERATED: Initialization Macros. 24114 (line 26) 24115* AS_LINENO_PREPARE: Initialization Macros. 24116 (line 67) 24117* AS_LITERAL_IF: Polymorphic Variables. 24118 (line 21) 24119* AS_LITERAL_WORD_IF: Polymorphic Variables. 24120 (line 21) 24121* AS_ME_PREPARE: Initialization Macros. 24122 (line 72) 24123* AS_MESSAGE_FD: File Descriptor Macros. 24124 (line 17) 24125* AS_MESSAGE_LOG_FD: File Descriptor Macros. 24126 (line 29) 24127* AS_MKDIR_P: Common Shell Constructs. 24128 (line 115) 24129* AS_ORIGINAL_STDIN_FD: File Descriptor Macros. 24130 (line 39) 24131* AS_SET_CATFILE: Common Shell Constructs. 24132 (line 155) 24133* AS_SET_STATUS: Common Shell Constructs. 24134 (line 127) 24135* AS_SHELL_SANITIZE: Initialization Macros. 24136 (line 101) 24137* AS_TMPDIR: Initialization Macros. 24138 (line 77) 24139* AS_TR_CPP: Common Shell Constructs. 24140 (line 135) 24141* AS_TR_SH: Common Shell Constructs. 24142 (line 144) 24143* AS_UNSET: Common Shell Constructs. 24144 (line 159) 24145* AS_VAR_APPEND: Polymorphic Variables. 24146 (line 63) 24147* AS_VAR_ARITH: Polymorphic Variables. 24148 (line 85) 24149* AS_VAR_COPY: Polymorphic Variables. 24150 (line 103) 24151* AS_VAR_IF: Polymorphic Variables. 24152 (line 122) 24153* AS_VAR_POPDEF: Polymorphic Variables. 24154 (line 131) 24155* AS_VAR_PUSHDEF: Polymorphic Variables. 24156 (line 131) 24157* AS_VAR_SET: Polymorphic Variables. 24158 (line 173) 24159* AS_VAR_SET_IF: Polymorphic Variables. 24160 (line 183) 24161* AS_VAR_TEST_SET: Polymorphic Variables. 24162 (line 188) 24163* AS_VERSION_COMPARE: Common Shell Constructs. 24164 (line 165) 24165* dnl: Redefined M4 Macros. (line 76) 24166* m4_append: Text processing Macros. 24167 (line 16) 24168* m4_append_uniq: Text processing Macros. 24169 (line 16) 24170* m4_append_uniq_w: Text processing Macros. 24171 (line 69) 24172* m4_apply: Evaluation Macros. (line 10) 24173* m4_argn: Looping constructs. (line 29) 24174* m4_assert: Diagnostic Macros. (line 11) 24175* m4_bmatch: Conditional constructs. 24176 (line 11) 24177* m4_bpatsubst: Redefined M4 Macros. (line 79) 24178* m4_bpatsubsts: Conditional constructs. 24179 (line 18) 24180* m4_bregexp: Redefined M4 Macros. (line 84) 24181* m4_builtin: Redefined M4 Macros. (line 6) 24182* m4_car: Looping constructs. (line 35) 24183* m4_case: Conditional constructs. 24184 (line 33) 24185* m4_cdr: Looping constructs. (line 41) 24186* m4_changecom: Redefined M4 Macros. (line 6) 24187* m4_changequote: Redefined M4 Macros. (line 6) 24188* m4_chomp: Text processing Macros. 24189 (line 80) 24190* m4_chomp_all: Text processing Macros. 24191 (line 80) 24192* m4_cleardivert: Diversion support. (line 125) 24193* m4_cmp: Number processing Macros. 24194 (line 11) 24195* m4_combine: Text processing Macros. 24196 (line 88) 24197* m4_cond: Conditional constructs. 24198 (line 42) 24199* m4_copy: Redefined M4 Macros. (line 92) 24200* m4_copy_force: Redefined M4 Macros. (line 92) 24201* m4_count: Evaluation Macros. (line 26) 24202* m4_curry: Evaluation Macros. (line 30) 24203* m4_debugfile: Redefined M4 Macros. (line 6) 24204* m4_debugmode: Redefined M4 Macros. (line 6) 24205* m4_decr: Redefined M4 Macros. (line 6) 24206* m4_default: Conditional constructs. 24207 (line 73) 24208* m4_default_nblank: Conditional constructs. 24209 (line 73) 24210* m4_default_nblank_quoted: Conditional constructs. 24211 (line 73) 24212* m4_default_quoted: Conditional constructs. 24213 (line 73) 24214* m4_define: Redefined M4 Macros. (line 6) 24215* m4_define_default: Conditional constructs. 24216 (line 122) 24217* m4_defn: Redefined M4 Macros. (line 111) 24218* m4_divert: Redefined M4 Macros. (line 119) 24219* m4_divert_once: Diversion support. (line 128) 24220* m4_divert_pop: Diversion support. (line 133) 24221* m4_divert_push: Diversion support. (line 139) 24222* m4_divert_text: Diversion support. (line 145) 24223* m4_divnum: Redefined M4 Macros. (line 6) 24224* m4_do: Evaluation Macros. (line 45) 24225* m4_dquote: Evaluation Macros. (line 65) 24226* m4_dquote_elt: Evaluation Macros. (line 70) 24227* m4_dumpdef: Redefined M4 Macros. (line 131) 24228* m4_dumpdefs: Redefined M4 Macros. (line 131) 24229* m4_echo: Evaluation Macros. (line 75) 24230* m4_errprint: Redefined M4 Macros. (line 6) 24231* m4_errprintn: Diagnostic Macros. (line 16) 24232* m4_escape: Text processing Macros. 24233 (line 108) 24234* m4_esyscmd: Redefined M4 Macros. (line 6) 24235* m4_esyscmd_s: Redefined M4 Macros. (line 148) 24236* m4_eval: Redefined M4 Macros. (line 6) 24237* m4_exit: Redefined M4 Macros. (line 154) 24238* m4_expand: Evaluation Macros. (line 79) 24239* m4_fatal: Diagnostic Macros. (line 20) 24240* m4_flatten: Text processing Macros. 24241 (line 113) 24242* m4_for: Looping constructs. (line 59) 24243* m4_foreach: Looping constructs. (line 69) 24244* m4_foreach_w: Looping constructs. (line 83) 24245* m4_format: Redefined M4 Macros. (line 6) 24246* m4_if: Redefined M4 Macros. (line 160) 24247* m4_ifblank: Conditional constructs. 24248 (line 127) 24249* m4_ifdef: Redefined M4 Macros. (line 6) 24250* m4_ifnblank: Conditional constructs. 24251 (line 127) 24252* m4_ifndef: Conditional constructs. 24253 (line 135) 24254* m4_ifset: Conditional constructs. 24255 (line 139) 24256* m4_ifval: Conditional constructs. 24257 (line 145) 24258* m4_ifvaln: Conditional constructs. 24259 (line 150) 24260* m4_ignore: Evaluation Macros. (line 129) 24261* m4_include: Redefined M4 Macros. (line 167) 24262* m4_incr: Redefined M4 Macros. (line 6) 24263* m4_index: Redefined M4 Macros. (line 6) 24264* m4_indir: Redefined M4 Macros. (line 6) 24265* m4_init: Diversion support. (line 171) 24266* m4_join: Text processing Macros. 24267 (line 119) 24268* m4_joinall: Text processing Macros. 24269 (line 119) 24270* m4_len: Redefined M4 Macros. (line 6) 24271* m4_list_cmp: Number processing Macros. 24272 (line 16) 24273* m4_location: Diagnostic Macros. (line 24) 24274* m4_make_list: Evaluation Macros. (line 142) 24275* m4_maketemp: Redefined M4 Macros. (line 171) 24276* m4_map: Looping constructs. (line 93) 24277* m4_map_args: Looping constructs. (line 130) 24278* m4_map_args_pair: Looping constructs. (line 166) 24279* m4_map_args_sep: Looping constructs. (line 178) 24280* m4_map_args_w: Looping constructs. (line 189) 24281* m4_map_sep: Looping constructs. (line 93) 24282* m4_mapall: Looping constructs. (line 93) 24283* m4_mapall_sep: Looping constructs. (line 93) 24284* m4_max: Number processing Macros. 24285 (line 38) 24286* m4_min: Number processing Macros. 24287 (line 42) 24288* m4_mkstemp: Redefined M4 Macros. (line 171) 24289* m4_n: Conditional constructs. 24290 (line 154) 24291* m4_newline: Text processing Macros. 24292 (line 134) 24293* m4_normalize: Text processing Macros. 24294 (line 140) 24295* m4_pattern_allow: Forbidden Patterns. (line 30) 24296* m4_pattern_forbid: Forbidden Patterns. (line 17) 24297* m4_popdef: Redefined M4 Macros. (line 182) 24298* m4_pushdef: Redefined M4 Macros. (line 6) 24299* m4_quote: Evaluation Macros. (line 161) 24300* m4_re_escape: Text processing Macros. 24301 (line 148) 24302* m4_rename: Redefined M4 Macros. (line 92) 24303* m4_rename_force: Redefined M4 Macros. (line 92) 24304* m4_reverse: Evaluation Macros. (line 167) 24305* m4_set_add: Set manipulation Macros. 24306 (line 19) 24307* m4_set_add_all: Set manipulation Macros. 24308 (line 25) 24309* m4_set_contains: Set manipulation Macros. 24310 (line 29) 24311* m4_set_contents: Set manipulation Macros. 24312 (line 49) 24313* m4_set_delete: Set manipulation Macros. 24314 (line 79) 24315* m4_set_difference: Set manipulation Macros. 24316 (line 86) 24317* m4_set_dump: Set manipulation Macros. 24318 (line 49) 24319* m4_set_empty: Set manipulation Macros. 24320 (line 109) 24321* m4_set_foreach: Set manipulation Macros. 24322 (line 115) 24323* m4_set_intersection: Set manipulation Macros. 24324 (line 86) 24325* m4_set_list: Set manipulation Macros. 24326 (line 136) 24327* m4_set_listc: Set manipulation Macros. 24328 (line 136) 24329* m4_set_map: Set manipulation Macros. 24330 (line 171) 24331* m4_set_map_sep: Set manipulation Macros. 24332 (line 184) 24333* m4_set_remove: Set manipulation Macros. 24334 (line 195) 24335* m4_set_size: Set manipulation Macros. 24336 (line 206) 24337* m4_set_union: Set manipulation Macros. 24338 (line 86) 24339* m4_shift: Redefined M4 Macros. (line 6) 24340* m4_shift2: Looping constructs. (line 199) 24341* m4_shift3: Looping constructs. (line 199) 24342* m4_shiftn: Looping constructs. (line 199) 24343* m4_sign: Number processing Macros. 24344 (line 46) 24345* m4_sinclude: Redefined M4 Macros. (line 167) 24346* m4_split: Text processing Macros. 24347 (line 152) 24348* m4_stack_foreach: Looping constructs. (line 208) 24349* m4_stack_foreach_lifo: Looping constructs. (line 208) 24350* m4_stack_foreach_sep: Looping constructs. (line 230) 24351* m4_stack_foreach_sep_lifo: Looping constructs. (line 230) 24352* m4_strip: Text processing Macros. 24353 (line 158) 24354* m4_substr: Redefined M4 Macros. (line 6) 24355* m4_syscmd: Redefined M4 Macros. (line 6) 24356* m4_sysval: Redefined M4 Macros. (line 6) 24357* m4_text_box: Text processing Macros. 24358 (line 167) 24359* m4_text_wrap: Text processing Macros. 24360 (line 182) 24361* m4_tolower: Text processing Macros. 24362 (line 213) 24363* m4_toupper: Text processing Macros. 24364 (line 213) 24365* m4_traceoff: Redefined M4 Macros. (line 6) 24366* m4_traceon: Redefined M4 Macros. (line 6) 24367* m4_translit: Redefined M4 Macros. (line 6) 24368* m4_undefine: Redefined M4 Macros. (line 186) 24369* m4_undivert: Redefined M4 Macros. (line 194) 24370* m4_unquote: Evaluation Macros. (line 176) 24371* m4_version_compare: Number processing Macros. 24372 (line 50) 24373* m4_version_prereq: Number processing Macros. 24374 (line 90) 24375* m4_warn: Diagnostic Macros. (line 28) 24376* m4_wrap: Redefined M4 Macros. (line 204) 24377* m4_wrap_lifo: Redefined M4 Macros. (line 204) 24378 24379 24380File: autoconf.info, Node: Autotest Macro Index, Next: Program & Function Index, Prev: M4 Macro Index, Up: Indices 24381 24382B.7 Autotest Macro Index 24383======================== 24384 24385This is an alphabetical list of the Autotest macros. 24386 24387�[index�] 24388* Menu: 24389 24390* AT_ARG_OPTION: Writing Testsuites. (line 50) 24391* AT_ARG_OPTION_ARG: Writing Testsuites. (line 79) 24392* AT_BANNER: Writing Testsuites. (line 124) 24393* AT_CAPTURE_FILE: Writing Testsuites. (line 155) 24394* AT_CHECK: Writing Testsuites. (line 212) 24395* AT_CHECK_EUNIT: Writing Testsuites. (line 302) 24396* AT_CHECK_UNQUOTED: Writing Testsuites. (line 212) 24397* AT_CLEANUP: Writing Testsuites. (line 198) 24398* AT_COLOR_TESTS: Writing Testsuites. (line 105) 24399* AT_COPYRIGHT: Writing Testsuites. (line 41) 24400* AT_DATA: Writing Testsuites. (line 202) 24401* AT_FAIL_IF: Writing Testsuites. (line 160) 24402* AT_INIT: Writing Testsuites. (line 31) 24403* AT_KEYWORDS: Writing Testsuites. (line 142) 24404* AT_PACKAGE_BUGREPORT: Making testsuite Scripts. 24405 (line 12) 24406* AT_PACKAGE_NAME: Making testsuite Scripts. 24407 (line 12) 24408* AT_PACKAGE_STRING: Making testsuite Scripts. 24409 (line 12) 24410* AT_PACKAGE_TARNAME: Making testsuite Scripts. 24411 (line 12) 24412* AT_PACKAGE_URL: Making testsuite Scripts. 24413 (line 12) 24414* AT_PACKAGE_VERSION: Making testsuite Scripts. 24415 (line 12) 24416* AT_SETUP: Writing Testsuites. (line 134) 24417* AT_SKIP_IF: Writing Testsuites. (line 175) 24418* AT_TESTED: Writing Testsuites. (line 109) 24419* AT_XFAIL_IF: Writing Testsuites. (line 190) 24420 24421 24422File: autoconf.info, Node: Program & Function Index, Next: Concept Index, Prev: Autotest Macro Index, Up: Indices 24423 24424B.8 Program and Function Index 24425============================== 24426 24427This is an alphabetical list of the programs and functions whose 24428portability is discussed in this document. 24429 24430�[index�] 24431* Menu: 24432 24433* !: Limitations of Builtins. 24434 (line 41) 24435* .: Limitations of Builtins. 24436 (line 17) 24437* /usr/bin/ksh on Solaris: Shellology. (line 63) 24438* /usr/dt/bin/dtksh on Solaris: Shellology. (line 66) 24439* /usr/xpg4/bin/sh on Solaris: Shellology. (line 64) 24440* alloca: Particular Functions. 24441 (line 10) 24442* alloca.h: Particular Functions. 24443 (line 10) 24444* assert.h: Particular Headers. (line 20) 24445* awk: Limitations of Usual Tools. 24446 (line 10) 24447* basename: Limitations of Usual Tools. 24448 (line 142) 24449* break: Limitations of Builtins. 24450 (line 107) 24451* case: Limitations of Builtins. 24452 (line 110) 24453* cat: Limitations of Usual Tools. 24454 (line 146) 24455* cc: Limitations of Usual Tools. 24456 (line 149) 24457* cd: Limitations of Builtins. 24458 (line 203) 24459* chgrp: Limitations of Usual Tools. 24460 (line 183) 24461* chmod: Limitations of Usual Tools. 24462 (line 187) 24463* chown <1>: Limitations of Usual Tools. 24464 (line 183) 24465* chown: Particular Functions. 24466 (line 63) 24467* closedir: Particular Functions. 24468 (line 69) 24469* cmp: Limitations of Usual Tools. 24470 (line 197) 24471* cp: Limitations of Usual Tools. 24472 (line 204) 24473* ctype.h: Particular Headers. (line 135) 24474* date: Limitations of Usual Tools. 24475 (line 264) 24476* diff: Limitations of Usual Tools. 24477 (line 274) 24478* dirent.h: Particular Headers. (line 25) 24479* dirname: Limitations of Usual Tools. 24480 (line 280) 24481* echo: Limitations of Builtins. 24482 (line 233) 24483* egrep: Limitations of Usual Tools. 24484 (line 287) 24485* error_at_line: Particular Functions. 24486 (line 84) 24487* eval: Limitations of Builtins. 24488 (line 270) 24489* exec: Limitations of Builtins. 24490 (line 315) 24491* exit <1>: Limitations of Builtins. 24492 (line 355) 24493* exit: Function Portability. 24494 (line 17) 24495* export: Limitations of Builtins. 24496 (line 380) 24497* expr: Limitations of Usual Tools. 24498 (line 312) 24499* expr (|): Limitations of Usual Tools. 24500 (line 326) 24501* false: Limitations of Builtins. 24502 (line 428) 24503* fgrep: Limitations of Usual Tools. 24504 (line 435) 24505* find: Limitations of Usual Tools. 24506 (line 444) 24507* float.h: Particular Headers. (line 135) 24508* fnmatch: Particular Functions. 24509 (line 94) 24510* fnmatch.h: Particular Functions. 24511 (line 452) 24512* for: Limitations of Builtins. 24513 (line 432) 24514* fork: Particular Functions. 24515 (line 120) 24516* free: Function Portability. 24517 (line 27) 24518* fseeko: Particular Functions. 24519 (line 147) 24520* ftello: Particular Functions. 24521 (line 147) 24522* getgroups: Particular Functions. 24523 (line 155) 24524* getloadavg: Particular Functions. 24525 (line 161) 24526* getmntent: Particular Functions. 24527 (line 195) 24528* getpgid: Particular Functions. 24529 (line 205) 24530* getpgrp: Particular Functions. 24531 (line 205) 24532* grep: Limitations of Usual Tools. 24533 (line 458) 24534* if: Limitations of Builtins. 24535 (line 477) 24536* inttypes.h <1>: Particular Types. (line 6) 24537* inttypes.h: Header Portability. (line 20) 24538* isinf: Function Portability. 24539 (line 32) 24540* isnan: Function Portability. 24541 (line 32) 24542* join: Limitations of Usual Tools. 24543 (line 526) 24544* ksh: Shellology. (line 57) 24545* ksh88: Shellology. (line 57) 24546* ksh93: Shellology. (line 57) 24547* linux/irda.h: Header Portability. (line 27) 24548* linux/random.h: Header Portability. (line 30) 24549* ln: Limitations of Usual Tools. 24550 (line 543) 24551* ls: Limitations of Usual Tools. 24552 (line 555) 24553* lstat: Particular Functions. 24554 (line 228) 24555* make: Portable Make. (line 6) 24556* malloc <1>: Particular Functions. 24557 (line 247) 24558* malloc: Function Portability. 24559 (line 82) 24560* mbrtowc: Particular Functions. 24561 (line 279) 24562* memcmp: Particular Functions. 24563 (line 286) 24564* mkdir: Limitations of Usual Tools. 24565 (line 577) 24566* mkfifo: Limitations of Usual Tools. 24567 (line 611) 24568* mknod: Limitations of Usual Tools. 24569 (line 611) 24570* mktemp: Limitations of Usual Tools. 24571 (line 621) 24572* mktime: Particular Functions. 24573 (line 299) 24574* mmap: Particular Functions. 24575 (line 311) 24576* mv: Limitations of Usual Tools. 24577 (line 646) 24578* ndir.h: Particular Headers. (line 25) 24579* net/if.h: Header Portability. (line 33) 24580* netinet/if_ether.h: Header Portability. (line 53) 24581* nlist.h: Particular Functions. 24582 (line 178) 24583* od: Limitations of Usual Tools. 24584 (line 678) 24585* pdksh: Shellology. (line 77) 24586* printf: Limitations of Builtins. 24587 (line 516) 24588* putenv: Function Portability. 24589 (line 89) 24590* pwd: Limitations of Builtins. 24591 (line 543) 24592* read: Limitations of Builtins. 24593 (line 574) 24594* realloc <1>: Particular Functions. 24595 (line 326) 24596* realloc: Function Portability. 24597 (line 105) 24598* resolv.h: Particular Headers. (line 73) 24599* rm: Limitations of Usual Tools. 24600 (line 687) 24601* rmdir: Limitations of Usual Tools. 24602 (line 706) 24603* sed: Limitations of Usual Tools. 24604 (line 710) 24605* sed (t): Limitations of Usual Tools. 24606 (line 905) 24607* select: Particular Functions. 24608 (line 337) 24609* set: Limitations of Builtins. 24610 (line 580) 24611* setpgrp: Particular Functions. 24612 (line 348) 24613* setvbuf: Obsolete Macros. (line 208) 24614* shift: Limitations of Builtins. 24615 (line 732) 24616* sigaction: Function Portability. 24617 (line 110) 24618* signal: Function Portability. 24619 (line 110) 24620* signal.h: Obsolete Macros. (line 662) 24621* sleep: Limitations of Usual Tools. 24622 (line 965) 24623* snprintf: Function Portability. 24624 (line 124) 24625* sort: Limitations of Usual Tools. 24626 (line 971) 24627* source: Limitations of Builtins. 24628 (line 740) 24629* sprintf: Function Portability. 24630 (line 135) 24631* sscanf: Function Portability. 24632 (line 141) 24633* stat: Particular Functions. 24634 (line 363) 24635* stdarg.h: Particular Headers. (line 135) 24636* stdbool.h: Particular Headers. (line 10) 24637* stdint.h <1>: Particular Types. (line 6) 24638* stdint.h: Header Portability. (line 20) 24639* stdlib.h <1>: Particular Types. (line 6) 24640* stdlib.h <2>: Particular Headers. (line 135) 24641* stdlib.h: Header Portability. (line 76) 24642* strcoll: Particular Functions. 24643 (line 379) 24644* strerror_r <1>: Particular Functions. 24645 (line 388) 24646* strerror_r: Function Portability. 24647 (line 149) 24648* strftime: Particular Functions. 24649 (line 401) 24650* string.h: Particular Headers. (line 135) 24651* strings.h: Particular Headers. (line 154) 24652* strnlen <1>: Particular Functions. 24653 (line 426) 24654* strnlen: Function Portability. 24655 (line 155) 24656* strtod: Particular Functions. 24657 (line 408) 24658* strtold: Particular Functions. 24659 (line 420) 24660* sys/dir.h: Particular Headers. (line 25) 24661* sys/ioctl.h: Particular Headers. (line 270) 24662* sys/mkdev.h: Particular Headers. (line 68) 24663* sys/mount.h: Header Portability. (line 79) 24664* sys/ndir.h: Particular Headers. (line 25) 24665* sys/ptem.h: Header Portability. (line 83) 24666* sys/socket.h: Header Portability. (line 86) 24667* sys/stat.h: Particular Headers. (line 92) 24668* sys/sysmacros.h: Particular Headers. (line 68) 24669* sys/time.h <1>: Particular Structures. 24670 (line 35) 24671* sys/time.h: Particular Headers. (line 244) 24672* sys/types.h: Particular Types. (line 6) 24673* sys/ucred.h: Header Portability. (line 89) 24674* sys/wait.h: Particular Headers. (line 204) 24675* sysconf: Function Portability. 24676 (line 170) 24677* tar: Limitations of Usual Tools. 24678 (line 976) 24679* termios.h: Particular Headers. (line 270) 24680* test: Limitations of Builtins. 24681 (line 744) 24682* time.h <1>: Particular Structures. 24683 (line 35) 24684* time.h: Particular Headers. (line 244) 24685* touch: Limitations of Usual Tools. 24686 (line 981) 24687* tr: Limitations of Usual Tools. 24688 (line 994) 24689* trap: Limitations of Builtins. 24690 (line 856) 24691* true: Limitations of Builtins. 24692 (line 930) 24693* unistd.h: Particular Headers. (line 228) 24694* unlink: Function Portability. 24695 (line 174) 24696* unset: Limitations of Builtins. 24697 (line 946) 24698* unsetenv: Function Portability. 24699 (line 180) 24700* utime: Particular Functions. 24701 (line 433) 24702* va_copy: Function Portability. 24703 (line 185) 24704* va_list: Function Portability. 24705 (line 192) 24706* vfork: Particular Functions. 24707 (line 120) 24708* vfork.h: Particular Functions. 24709 (line 120) 24710* vprintf: Particular Functions. 24711 (line 443) 24712* vsnprintf: Function Portability. 24713 (line 124) 24714* vsprintf <1>: Particular Functions. 24715 (line 443) 24716* vsprintf: Function Portability. 24717 (line 135) 24718* wait: Limitations of Builtins. 24719 (line 973) 24720* wait3: Obsolete Macros. (line 216) 24721* wchar.h: Particular Types. (line 88) 24722* X11/extensions/scrnsaver.h: Header Portability. (line 92) 24723* {...}: Limitations of Builtins. 24724 (line 74) 24725 24726 24727File: autoconf.info, Node: Concept Index, Prev: Program & Function Index, Up: Indices 24728 24729B.9 Concept Index 24730================= 24731 24732This is an alphabetical list of the files, tools, and concepts 24733introduced in this document. 24734 24735�[index�] 24736* Menu: 24737 24738* "$@": Shell Substitutions. (line 70) 24739* $((EXPRESSION)): Shell Substitutions. (line 456) 24740* $(COMMANDS): Shell Substitutions. (line 423) 24741* $<, explicit rules, and VPATH: $< in Explicit Rules. 24742 (line 6) 24743* ${#VAR}: Shell Substitutions. (line 369) 24744* ${VAR##WORD}: Shell Substitutions. (line 369) 24745* ${VAR#WORD}: Shell Substitutions. (line 369) 24746* ${VAR%%WORD}: Shell Substitutions. (line 369) 24747* ${VAR%WORD}: Shell Substitutions. (line 369) 24748* ${VAR+VALUE}: Shell Substitutions. (line 148) 24749* ${VAR-VALUE}: Shell Substitutions. (line 140) 24750* ${VAR=EXPANDED-VALUE}: Shell Substitutions. (line 319) 24751* ${VAR=LITERAL}: Shell Substitutions. (line 295) 24752* ${VAR=VALUE}: Shell Substitutions. (line 215) 24753* 64-bit libraries: Site Defaults. (line 97) 24754* @&t@: Quadrigraphs. (line 6) 24755* @S|@: Quadrigraphs. (line 6) 24756* ^ quoting: Shell Substitutions. (line 496) 24757* _m4_divert_diversion: New Macros. (line 6) 24758* `COMMANDS`: Shell Substitutions. (line 377) 24759* abs_builddir: Preset Output Variables. 24760 (line 177) 24761* abs_srcdir: Preset Output Variables. 24762 (line 199) 24763* abs_top_builddir: Preset Output Variables. 24764 (line 192) 24765* abs_top_srcdir: Preset Output Variables. 24766 (line 206) 24767* absolute file names, detect: File System Conventions. 24768 (line 52) 24769* ac_objext: Generic Functions. (line 59) 24770* ac_path_VARIABLE: Generic Programs. (line 123) 24771* ac_path_VARIABLE_found: Generic Programs. (line 123) 24772* ac_srcdir: Configuration Actions. 24773 (line 85) 24774* ac_top_build_prefix: Configuration Actions. 24775 (line 80) 24776* ac_top_srcdir: Configuration Actions. 24777 (line 76) 24778* acconfig.h: acconfig Header. (line 6) 24779* aclocal.m4: Making configure Scripts. 24780 (line 6) 24781* Ash: Shellology. (line 16) 24782* at_arg_OPTION: Writing Testsuites. (line 50) 24783* at_optarg: Writing Testsuites. (line 62) 24784* at_optarg_OPTION: Writing Testsuites. (line 62) 24785* at_status: Writing Testsuites. (line 212) 24786* autoconf: autoconf Invocation. (line 6) 24787* Autoconf upgrading <1>: Autoconf 2.13. (line 6) 24788* Autoconf upgrading: Autoconf 1. (line 6) 24789* Autoconf version: Versioning. (line 6) 24790* autoheader: autoheader Invocation. 24791 (line 6) 24792* Autoheader macros: Autoheader Macros. (line 6) 24793* autom4te debugging tips: Debugging via autom4te. 24794 (line 6) 24795* Autom4te Library: autom4te Invocation. (line 225) 24796* autom4te.cache: autom4te Invocation. (line 130) 24797* autom4te.cfg: autom4te Invocation. (line 258) 24798* Automake: Automake. (line 19) 24799* Automatic remaking: Automatic Remaking. (line 6) 24800* automatic rule rewriting and VPATH: Automatic Rule Rewriting. 24801 (line 6) 24802* autopoint: autoreconf Invocation. 24803 (line 30) 24804* autoreconf: autoreconf Invocation. 24805 (line 6) 24806* autoscan: autoscan Invocation. (line 6) 24807* Autotest: Using Autotest. (line 6) 24808* AUTOTEST_PATH: testsuite Invocation. 24809 (line 60) 24810* autoupdate: autoupdate Invocation. 24811 (line 6) 24812* Back trace <1>: autom4te Invocation. (line 86) 24813* Back trace: autoconf Invocation. (line 86) 24814* balancing parentheses: Balancing Parentheses. 24815 (line 6) 24816* Bash: Shellology. (line 43) 24817* Bash 2.05 and later: Shellology. (line 49) 24818* bindir: Installation Directory Variables. 24819 (line 15) 24820* Bootstrap: Bootstrapping. (line 6) 24821* BSD make and obj/: obj/ and Make. (line 6) 24822* buffer overruns: Buffer Overruns. (line 6) 24823* Build directories: Build Directories. (line 6) 24824* builddir: Preset Output Variables. 24825 (line 174) 24826* C function portability: Function Portability. 24827 (line 6) 24828* C types: Types. (line 6) 24829* Cache: Caching Results. (line 6) 24830* Cache variable: Cache Variable Names. 24831 (line 6) 24832* Cache, enabling: configure Invocation. 24833 (line 25) 24834* Canonical system type: Canonicalizing. (line 6) 24835* carriage return, deleting: Limitations of Usual Tools. 24836 (line 994) 24837* CFLAGS: Preset Output Variables. 24838 (line 23) 24839* changequote: Changequote is Evil. (line 6) 24840* Coding style: Coding Style. (line 6) 24841* Command Substitution: Shell Substitutions. (line 377) 24842* command-line, macros set on: Command-line Macros and whitespace. 24843 (line 6) 24844* Commands for configuration: Configuration Commands. 24845 (line 6) 24846* Comments in Makefile macros: Comments in Make Macros. 24847 (line 6) 24848* Comments in Makefile rules: Comments in Make Rules. 24849 (line 6) 24850* Common autoconf behavior: Common Behavior. (line 6) 24851* Compilers: Compilers and Preprocessors. 24852 (line 6) 24853* composing variable names: Polymorphic Variables. 24854 (line 131) 24855* config.h: Configuration Headers. 24856 (line 6) 24857* config.h.bot: acconfig Header. (line 6) 24858* config.h.in: Header Templates. (line 6) 24859* config.h.top: acconfig Header. (line 6) 24860* config.site: Site Defaults. (line 6) 24861* config.status: config.status Invocation. 24862 (line 6) 24863* config.sub: Specifying Target Triplets. 24864 (line 59) 24865* CONFIG_COMMANDS: Obsolete config.status Use. 24866 (line 11) 24867* CONFIG_FILES: Obsolete config.status Use. 24868 (line 15) 24869* CONFIG_HEADERS: Obsolete config.status Use. 24870 (line 20) 24871* CONFIG_LINKS: Obsolete config.status Use. 24872 (line 25) 24873* CONFIG_SHELL: config.status Invocation. 24874 (line 102) 24875* CONFIG_STATUS: config.status Invocation. 24876 (line 108) 24877* Configuration actions: Configuration Actions. 24878 (line 6) 24879* Configuration commands: Configuration Commands. 24880 (line 6) 24881* Configuration file creation: Configuration Files. (line 6) 24882* Configuration Header: Configuration Headers. 24883 (line 6) 24884* Configuration Header Template: Header Templates. (line 6) 24885* Configuration links: Configuration Links. (line 6) 24886* configure <1>: Running configure Scripts. 24887 (line 6) 24888* configure: Making configure Scripts. 24889 (line 6) 24890* Configure subdirectories: Subdirectories. (line 6) 24891* configure.ac: Making configure Scripts. 24892 (line 27) 24893* configure.in: Making configure Scripts. 24894 (line 27) 24895* configure_input: Preset Output Variables. 24896 (line 58) 24897* Copyright Notice <1>: Writing Testsuites. (line 41) 24898* Copyright Notice: Notices. (line 10) 24899* CPPFLAGS: Preset Output Variables. 24900 (line 72) 24901* Creating configuration files: Configuration Files. (line 6) 24902* Creating temporary files: Limitations of Usual Tools. 24903 (line 621) 24904* Cross compilation: Hosts and Cross-Compilation. 24905 (line 6) 24906* CXXFLAGS: Preset Output Variables. 24907 (line 94) 24908* Darwin: Systemology. (line 23) 24909* Data structure, set: Set manipulation Macros. 24910 (line 6) 24911* datadir: Installation Directory Variables. 24912 (line 18) 24913* datarootdir <1>: Changed Directory Variables. 24914 (line 6) 24915* datarootdir: Installation Directory Variables. 24916 (line 22) 24917* debugging tips: Debugging via autom4te. 24918 (line 6) 24919* Declaration, checking: Declarations. (line 6) 24920* Default includes: Default Includes. (line 6) 24921* DEFS: Preset Output Variables. 24922 (line 98) 24923* deleting carriage return: Limitations of Usual Tools. 24924 (line 994) 24925* Dependencies between macros: Dependencies Between Macros. 24926 (line 6) 24927* Descriptors: File Descriptors. (line 6) 24928* descriptors: File Descriptor Macros. 24929 (line 6) 24930* Directories, build: Build Directories. (line 6) 24931* Directories, installation: Installation Directory Variables. 24932 (line 6) 24933* division, integer: Signed Integer Division. 24934 (line 6) 24935* dnl <1>: Coding Style. (line 42) 24936* dnl: Macro Definitions. (line 51) 24937* docdir: Installation Directory Variables. 24938 (line 26) 24939* double-colon rules and VPATH: VPATH and Double-colon. 24940 (line 6) 24941* dvidir: Installation Directory Variables. 24942 (line 30) 24943* ECHO_C: Preset Output Variables. 24944 (line 106) 24945* ECHO_N: Preset Output Variables. 24946 (line 107) 24947* ECHO_T: Preset Output Variables. 24948 (line 108) 24949* Endianness: C Compiler. (line 184) 24950* environment, macros set from: Command-line Macros and whitespace. 24951 (line 6) 24952* Erlang: Erlang Compiler and Interpreter. 24953 (line 6) 24954* Erlang, Library, checking: Erlang Libraries. (line 6) 24955* ERLANG_INSTALL_LIB_DIR: Installation Directory Variables. 24956 (line 201) 24957* ERLANG_INSTALL_LIB_DIR_: Installation Directory Variables. 24958 (line 206) 24959* ERLCFLAGS: Preset Output Variables. 24960 (line 120) 24961* exec_prefix: Installation Directory Variables. 24962 (line 33) 24963* exiting portably: Exiting Portably. (line 6) 24964* expanded before required: Expanded Before Required. 24965 (line 6) 24966* explicit rules, $<, and VPATH: $< in Explicit Rules. 24967 (line 6) 24968* External software: External Software. (line 6) 24969* F77: Fortran Compiler. (line 6) 24970* FCFLAGS: Preset Output Variables. 24971 (line 126) 24972* FFLAGS: Preset Output Variables. 24973 (line 133) 24974* FHS: Site Defaults. (line 83) 24975* File descriptors: File Descriptors. (line 6) 24976* file descriptors: File Descriptor Macros. 24977 (line 6) 24978* File system conventions: File System Conventions. 24979 (line 6) 24980* File, checking: Files. (line 6) 24981* Filesystem Hierarchy Standard: Site Defaults. (line 83) 24982* floating point: Floating Point Portability. 24983 (line 6) 24984* Forbidden patterns: Forbidden Patterns. (line 6) 24985* Fortran: Fortran Compiler. (line 6) 24986* Function, checking: Particular Functions. 24987 (line 6) 24988* Gettext: autoreconf Invocation. 24989 (line 30) 24990* GNU build system: The GNU Build System. 24991 (line 6) 24992* Gnulib: Gnulib. (line 11) 24993* Go: Go Compiler. (line 6) 24994* GOFLAGS: Preset Output Variables. 24995 (line 170) 24996* Header portability: Header Portability. (line 6) 24997* Header templates: Header Templates. (line 6) 24998* Header, checking: Header Files. (line 6) 24999* Help strings: Pretty Help Strings. (line 6) 25000* Here-documents: Here-Documents. (line 6) 25001* History of autoconf: History. (line 6) 25002* htmldir: Installation Directory Variables. 25003 (line 40) 25004* ifnames: ifnames Invocation. (line 6) 25005* Imake: Why Not Imake. (line 6) 25006* includedir: Installation Directory Variables. 25007 (line 43) 25008* Includes, default: Default Includes. (line 6) 25009* indirection, variable name: Polymorphic Variables. 25010 (line 6) 25011* infodir: Installation Directory Variables. 25012 (line 46) 25013* input: File Descriptor Macros. 25014 (line 6) 25015* Install prefix: Default Prefix. (line 6) 25016* Installation directories: Installation Directory Variables. 25017 (line 6) 25018* Instantiation: Output. (line 13) 25019* integer overflow <1>: Signed Overflow Advice. 25020 (line 6) 25021* integer overflow <2>: Signed Overflow Examples. 25022 (line 6) 25023* integer overflow <3>: Integer Overflow Basics. 25024 (line 6) 25025* integer overflow: Integer Overflow. (line 6) 25026* Introduction: Introduction. (line 6) 25027* invoking the shell: Invoking the Shell. (line 6) 25028* Korn shell: Shellology. (line 57) 25029* Ksh: Shellology. (line 57) 25030* Language: Language Choice. (line 6) 25031* Large file support: System Services. (line 49) 25032* LDFLAGS: Preset Output Variables. 25033 (line 140) 25034* LFS: System Services. (line 49) 25035* lib64: Site Defaults. (line 97) 25036* libdir: Installation Directory Variables. 25037 (line 49) 25038* libexecdir: Installation Directory Variables. 25039 (line 52) 25040* Library, checking: Libraries. (line 6) 25041* LIBS: Preset Output Variables. 25042 (line 154) 25043* Libtool: Libtool. (line 14) 25044* License: Distributing. (line 6) 25045* Limitations of make: Portable Make. (line 6) 25046* Limitations of shell builtins: Limitations of Builtins. 25047 (line 6) 25048* Limitations of usual tools: Limitations of Usual Tools. 25049 (line 6) 25050* Links: Configuration Links. (line 12) 25051* Links for configuration: Configuration Links. (line 6) 25052* Listing directories: Limitations of Usual Tools. 25053 (line 555) 25054* localedir: Installation Directory Variables. 25055 (line 55) 25056* localstatedir: Installation Directory Variables. 25057 (line 60) 25058* loop induction: Optimization and Wraparound. 25059 (line 6) 25060* low-level output: File Descriptor Macros. 25061 (line 6) 25062* M4: Programming in M4. (line 6) 25063* M4 quotation: M4 Quotation. (line 6) 25064* M4sugar: Programming in M4sugar. 25065 (line 6) 25066* m4sugar debugging tips: Debugging via autom4te. 25067 (line 6) 25068* Macro invocation stack <1>: autom4te Invocation. (line 86) 25069* Macro invocation stack: autoconf Invocation. (line 86) 25070* Macros, called once: One-Shot Macros. (line 6) 25071* Macros, obsoleting: Obsoleting Macros. (line 6) 25072* Macros, ordering: Suggested Ordering. (line 6) 25073* Macros, prerequisites: Prerequisite Macros. (line 6) 25074* make -k: make -k Status. (line 6) 25075* make and MAKEFLAGS: The Make Macro MAKEFLAGS. 25076 (line 6) 25077* make and SHELL: The Make Macro SHELL. 25078 (line 6) 25079* Makefile macros and comments: Comments in Make Macros. 25080 (line 6) 25081* Makefile macros and whitespace: Trailing whitespace in Make Macros. 25082 (line 6) 25083* Makefile rules and comments: Comments in Make Rules. 25084 (line 6) 25085* Makefile rules and newlines: Newlines in Make Rules. 25086 (line 6) 25087* Makefile substitutions: Makefile Substitutions. 25088 (line 6) 25089* MAKEFLAGS and make: The Make Macro MAKEFLAGS. 25090 (line 6) 25091* Making directories: Limitations of Usual Tools. 25092 (line 577) 25093* mandir: Installation Directory Variables. 25094 (line 63) 25095* Messages, from autoconf: Reporting Messages. (line 6) 25096* Messages, from configure: Printing Messages. (line 6) 25097* Messages, from M4sugar: Diagnostic Macros. (line 6) 25098* Moving open files: Limitations of Usual Tools. 25099 (line 646) 25100* newline, deleting: Limitations of Usual Tools. 25101 (line 994) 25102* Newlines in Makefile rules: Newlines in Make Rules. 25103 (line 6) 25104* Notices in configure: Notices. (line 6) 25105* null pointers: Null Pointers. (line 6) 25106* obj/, subdirectory: obj/ and Make. (line 6) 25107* OBJCFLAGS: Preset Output Variables. 25108 (line 162) 25109* OBJCXXFLAGS: Preset Output Variables. 25110 (line 166) 25111* Obsolete constructs: Obsolete Constructs. (line 6) 25112* Obsoleting macros: Obsoleting Macros. (line 6) 25113* obstack: Particular Functions. 25114 (line 319) 25115* oldincludedir: Installation Directory Variables. 25116 (line 66) 25117* One-shot macros: One-Shot Macros. (line 6) 25118* Options, Package: Option Checking. (line 6) 25119* Options, package: Package Options. (line 6) 25120* Ordering macros: Suggested Ordering. (line 6) 25121* Output variables <1>: Setting Output Variables. 25122 (line 6) 25123* Output variables: Preset Output Variables. 25124 (line 6) 25125* Output variables, special characters in: Special Chars in Variables. 25126 (line 6) 25127* output, low-level: File Descriptor Macros. 25128 (line 6) 25129* Outputting files: Output. (line 6) 25130* overflow, signed integer <1>: Signed Overflow Advice. 25131 (line 6) 25132* overflow, signed integer <2>: Signed Overflow Examples. 25133 (line 6) 25134* overflow, signed integer <3>: Integer Overflow Basics. 25135 (line 6) 25136* overflow, signed integer: Integer Overflow. (line 6) 25137* Package options: Package Options. (line 6) 25138* package.m4: Making testsuite Scripts. 25139 (line 12) 25140* Parallel make: Parallel Make. (line 6) 25141* parentheses, balancing: Balancing Parentheses. 25142 (line 6) 25143* Patterns, forbidden: Forbidden Patterns. (line 6) 25144* pdfdir: Installation Directory Variables. 25145 (line 69) 25146* polymorphic variable name: Polymorphic Variables. 25147 (line 6) 25148* portability: Varieties of Unportability. 25149 (line 6) 25150* Portability of C functions: Function Portability. 25151 (line 6) 25152* Portability of headers: Header Portability. (line 6) 25153* Portable C and C++ programming: Portable C and C++. (line 6) 25154* Portable shell programming: Portable Shell. (line 6) 25155* positional parameters: Shell Substitutions. (line 121) 25156* Posix termios headers: System Services. (line 75) 25157* Precious Variable: Setting Output Variables. 25158 (line 65) 25159* prefix: Installation Directory Variables. 25160 (line 72) 25161* Prefix for install: Default Prefix. (line 6) 25162* preprocessor arithmetic: Preprocessor Arithmetic. 25163 (line 6) 25164* Preprocessors: Compilers and Preprocessors. 25165 (line 6) 25166* prerequisite directories and VPATH: Tru64 Directory Magic. 25167 (line 6) 25168* Prerequisite macros: Prerequisite Macros. (line 6) 25169* Program names, transforming: Transforming Names. (line 6) 25170* Programs, checking: Alternative Programs. 25171 (line 6) 25172* psdir: Installation Directory Variables. 25173 (line 77) 25174* QNX 4.25: Systemology. (line 37) 25175* quadrigraphs: Quadrigraphs. (line 6) 25176* quotation <1>: M4 Quotation. (line 6) 25177* quotation: Autoconf Language. (line 6) 25178* Remaking automatically: Automatic Remaking. (line 6) 25179* Revision: Notices. (line 18) 25180* Rule, Single Suffix Inference: Single Suffix Rules. (line 6) 25181* sbindir: Installation Directory Variables. 25182 (line 80) 25183* Separated Dependencies: Single Suffix Rules. (line 9) 25184* set -b: Limitations of Builtins. 25185 (line 689) 25186* set -e: Limitations of Builtins. 25187 (line 605) 25188* set -m: Limitations of Builtins. 25189 (line 689) 25190* set -n: Limitations of Builtins. 25191 (line 713) 25192* Set manipulation: Set manipulation Macros. 25193 (line 6) 25194* sharedstatedir: Installation Directory Variables. 25195 (line 84) 25196* SHELL and make: The Make Macro SHELL. 25197 (line 6) 25198* Shell assignments: Assignments. (line 6) 25199* Shell builtins: Limitations of Builtins. 25200 (line 6) 25201* Shell file descriptors: File Descriptors. (line 6) 25202* Shell Functions: Shell Functions. (line 6) 25203* Shell here-documents: Here-Documents. (line 6) 25204* shell invocation: Invoking the Shell. (line 6) 25205* Shell parentheses: Parentheses. (line 6) 25206* Shell pattern matching: Shell Pattern Matching. 25207 (line 6) 25208* Shell slashes: Slashes. (line 6) 25209* Shell substitutions: Shell Substitutions. (line 6) 25210* Shell variables: Special Shell Variables. 25211 (line 6) 25212* Shellology: Shellology. (line 6) 25213* Signal handling in the shell: Signal Handling. (line 6) 25214* Signals, shells and: Signal Handling. (line 6) 25215* signed integer overflow <1>: Signed Overflow Advice. 25216 (line 6) 25217* signed integer overflow <2>: Signed Overflow Examples. 25218 (line 6) 25219* signed integer overflow <3>: Integer Overflow Basics. 25220 (line 6) 25221* signed integer overflow: Integer Overflow. (line 6) 25222* Single Suffix Inference Rule: Single Suffix Rules. (line 6) 25223* Site defaults: Site Defaults. (line 6) 25224* Site details: Site Details. (line 6) 25225* Special shell variables: Special Shell Variables. 25226 (line 6) 25227* srcdir <1>: Preset Output Variables. 25228 (line 195) 25229* srcdir: Configuration Actions. 25230 (line 71) 25231* standard input: File Descriptor Macros. 25232 (line 6) 25233* Standard symbols: Standard Symbols. (line 6) 25234* Structure, checking: Structures. (line 6) 25235* Subdirectory configure: Subdirectories. (line 6) 25236* Substitutions in makefiles: Makefile Substitutions. 25237 (line 6) 25238* Symbolic links: Limitations of Usual Tools. 25239 (line 543) 25240* sysconfdir: Installation Directory Variables. 25241 (line 88) 25242* System type <1>: Canonicalizing. (line 6) 25243* System type: Specifying Target Triplets. 25244 (line 6) 25245* Systemology: Systemology. (line 6) 25246* Target triplet: Specifying Target Triplets. 25247 (line 6) 25248* termios Posix headers: System Services. (line 75) 25249* test group: testsuite Scripts. (line 12) 25250* testsuite <1>: testsuite Invocation. 25251 (line 6) 25252* testsuite: testsuite Scripts. (line 6) 25253* timestamp resolution <1>: Timestamps and Make. (line 6) 25254* timestamp resolution: Limitations of Usual Tools. 25255 (line 226) 25256* tmp: Configuration Actions. 25257 (line 89) 25258* top_build_prefix: Preset Output Variables. 25259 (line 184) 25260* top_builddir: Preset Output Variables. 25261 (line 180) 25262* top_srcdir: Preset Output Variables. 25263 (line 202) 25264* Transforming program names: Transforming Names. (line 6) 25265* Tru64: Systemology. (line 44) 25266* Types: Types. (line 6) 25267* unbalanced parentheses, managing: Balancing Parentheses. 25268 (line 6) 25269* undefined macro: New Macros. (line 6) 25270* Unix version 7: Systemology. (line 49) 25271* Unordered set manipulation: Set manipulation Macros. 25272 (line 6) 25273* Upgrading autoconf <1>: Autoconf 2.13. (line 6) 25274* Upgrading autoconf: Autoconf 1. (line 6) 25275* V7: Systemology. (line 49) 25276* variable name indirection: Polymorphic Variables. 25277 (line 6) 25278* variable names, composing: Polymorphic Variables. 25279 (line 131) 25280* Variable, Precious: Setting Output Variables. 25281 (line 65) 25282* variables and VPATH: Variables listed in VPATH. 25283 (line 6) 25284* Version: Versioning. (line 11) 25285* version, Autoconf: Versioning. (line 6) 25286* volatile objects: Volatile Objects. (line 6) 25287* VPATH: VPATH and Make. (line 6) 25288* VPATH and automatic rule rewriting: Automatic Rule Rewriting. 25289 (line 6) 25290* VPATH and double-colon rules: VPATH and Double-colon. 25291 (line 6) 25292* VPATH and prerequisite directories: Tru64 Directory Magic. 25293 (line 6) 25294* VPATH and variables: Variables listed in VPATH. 25295 (line 6) 25296* VPATH, explicit rules, and $<: $< in Explicit Rules. 25297 (line 6) 25298* VPATH, resolving target pathnames: Make Target Lookup. (line 6) 25299* whitespace in command-line macros: Command-line Macros and whitespace. 25300 (line 6) 25301* whitespace in Makefile macros: Trailing whitespace in Make Macros. 25302 (line 6) 25303* wraparound arithmetic <1>: Signed Overflow Advice. 25304 (line 6) 25305* wraparound arithmetic <2>: Signed Overflow Examples. 25306 (line 6) 25307* wraparound arithmetic <3>: Integer Overflow Basics. 25308 (line 6) 25309* wraparound arithmetic: Integer Overflow. (line 6) 25310* X Window System: System Services. (line 10) 25311* Zsh: Shellology. (line 87) 25312 25313 25314 25315Tag Table: 25316Node: Top1954 25317Node: Introduction21371 25318Node: The GNU Build System27935 25319Node: Automake28914 25320Node: Gnulib30863 25321Node: Libtool32172 25322Node: Pointers33594 25323Ref: Pointers-Footnote-134895 25324Node: Making configure Scripts35055 25325Node: Writing Autoconf Input38404 25326Node: Shell Script Compiler39867 25327Node: Autoconf Language42228 25328Node: Autoconf Input Layout49397 25329Node: autoscan Invocation50805 25330Node: ifnames Invocation53361 25331Node: autoconf Invocation54561 25332Node: autoreconf Invocation59846 25333Node: Setup64607 25334Node: Initializing configure65929 25335Ref: AC_INIT66434 25336Node: Versioning69318 25337Node: Notices71179 25338Node: Input72354 25339Ref: AC_CONFIG_SRCDIR72495 25340Node: Output75442 25341Ref: AC_OUTPUT75877 25342Ref: AC_PROG_MAKE_SET77495 25343Node: Configuration Actions77920 25344Node: Configuration Files83208 25345Ref: AC_CONFIG_FILES83469 25346Node: Makefile Substitutions84688 25347Node: Preset Output Variables86431 25348Node: Installation Directory Variables95945 25349Node: Changed Directory Variables103793 25350Node: Build Directories106387 25351Node: Automatic Remaking108242 25352Node: Configuration Headers110410 25353Node: Header Templates113712 25354Node: autoheader Invocation116447 25355Node: Autoheader Macros120089 25356Node: Configuration Commands122354 25357Ref: AC_CONFIG_COMMANDS122866 25358Node: Configuration Links124151 25359Ref: AC_CONFIG_LINKS124602 25360Node: Subdirectories125575 25361Node: Default Prefix128055 25362Ref: AC_PREFIX_PROGRAM128946 25363Node: Existing Tests129477 25364Node: Common Behavior131279 25365Node: Standard Symbols131918 25366Node: Default Includes132499 25367Node: Alternative Programs134753 25368Node: Particular Programs135439 25369Ref: AC_PROG_LEX141187 25370Ref: AC_PROG_LN_S143798 25371Node: Generic Programs145416 25372Ref: AC_CHECK_PROG146388 25373Ref: AC_CHECK_PROGS147114 25374Ref: AC_PATH_PROG151114 25375Ref: AC_PATH_PROGS151488 25376Node: Files154567 25377Node: Libraries155767 25378Ref: AC_CHECK_LIB156008 25379Ref: AC_SEARCH_LIBS158267 25380Node: Library Functions159451 25381Node: Function Portability160074 25382Node: Particular Functions169586 25383Ref: AC_FUNC_ALLOCA169917 25384Ref: AC_FUNC_CLOSEDIR_VOID172306 25385Ref: AC_FUNC_FORK174296 25386Ref: AC_FUNC_GETLOADAVG176338 25387Ref: AC_FUNC_GETMNTENT177903 25388Ref: AC_FUNC_MMAP182145 25389Ref: AC_FUNC_STRCOLL185000 25390Ref: AC_FUNC_STRFTIME185975 25391Ref: AC_FUNC_UTIME_NULL187257 25392Ref: AC_FUNC_VPRINTF187605 25393Node: Generic Functions188821 25394Ref: AC_CHECK_FUNC189347 25395Ref: AC_CHECK_FUNCS189976 25396Node: Header Files194602 25397Node: Header Portability195235 25398Node: Particular Headers198330 25399Ref: AC_HEADER_DIRENT199369 25400Ref: AC_HEADER_MAJOR200899 25401Ref: AC_HEADER_STAT201683 25402Ref: AC_HEADER_STDC203189 25403Ref: AC_HEADER_TIME207928 25404Node: Generic Headers209315 25405Ref: AC_CHECK_HEADER209715 25406Ref: AC_CHECK_HEADERS211588 25407Node: Declarations214153 25408Node: Particular Declarations214749 25409Node: Generic Declarations214973 25410Ref: AC_CHECK_DECLS216358 25411Node: Structures218884 25412Node: Particular Structures219499 25413Ref: AC_STRUCT_ST_BLOCKS220568 25414Ref: AC_STRUCT_TIMEZONE221264 25415Node: Generic Structures221593 25416Ref: AC_CHECK_MEMBERS222584 25417Node: Types223417 25418Node: Particular Types223937 25419Ref: AC_TYPE_GETGROUPS224380 25420Ref: AC_TYPE_MODE_T227416 25421Ref: AC_TYPE_OFF_T227599 25422Ref: AC_TYPE_PID_T227779 25423Ref: AC_TYPE_SIZE_T227959 25424Ref: AC_TYPE_UID_T228328 25425Node: Generic Types229973 25426Node: Compilers and Preprocessors232128 25427Node: Specific Compiler Characteristics233402 25428Node: Generic Compiler Characteristics234507 25429Ref: AC_CHECK_SIZEOF234747 25430Node: C Compiler239537 25431Ref: AC_PROG_CC_C_O243988 25432Ref: AC_C_BIGENDIAN247796 25433Ref: AC_C_CONST249637 25434Ref: AC_C_INLINE252955 25435Ref: AC_C_CHAR_UNSIGNED253178 25436Ref: AC_PROG_GCC_TRADITIONAL255800 25437Node: C++ Compiler256212 25438Node: Objective C Compiler258609 25439Node: Objective C++ Compiler259983 25440Node: Erlang Compiler and Interpreter261433 25441Node: Fortran Compiler263478 25442Node: Go Compiler288878 25443Node: System Services289923 25444Ref: AC_PATH_X290168 25445Ref: AC_PATH_XTRA291161 25446Ref: AC_SYS_INTERPRETER291738 25447Ref: AC_SYS_LONG_FILE_NAMES293150 25448Node: Posix Variants293527 25449Ref: AC_USE_SYSTEM_EXTENSIONS293827 25450Node: Erlang Libraries294903 25451Node: Writing Tests299841 25452Node: Language Choice301865 25453Ref: AC_LANG302362 25454Ref: AC_LANG_PUSH304161 25455Ref: Language Choice-Footnote-1306034 25456Node: Writing Test Programs306190 25457Node: Guidelines306768 25458Node: Test Functions309028 25459Node: Generating Sources310426 25460Node: Running the Preprocessor316510 25461Ref: AC_PREPROC_IFELSE317242 25462Ref: AC_EGREP_HEADER319172 25463Ref: AC_EGREP_CPP319501 25464Node: Running the Compiler319926 25465Node: Running the Linker321681 25466Ref: AC_LINK_IFELSE322821 25467Node: Runtime323697 25468Ref: AC_RUN_IFELSE324472 25469Node: Systemology329322 25470Node: Multiple Cases331671 25471Node: Results333372 25472Node: Defining Symbols334191 25473Node: Setting Output Variables339082 25474Node: Special Chars in Variables344973 25475Node: Caching Results346233 25476Node: Cache Variable Names349951 25477Node: Cache Files351602 25478Node: Cache Checkpointing353927 25479Node: Printing Messages355301 25480Ref: AC_MSG_RESULT356815 25481Ref: AC_MSG_NOTICE357322 25482Ref: AC_MSG_ERROR357686 25483Ref: AC_MSG_WARN358519 25484Node: Programming in M4358942 25485Node: M4 Quotation359747 25486Node: Active Characters360716 25487Ref: Active Characters-Footnote-1362106 25488Ref: Active Characters-Footnote-2362220 25489Node: One Macro Call362242 25490Node: Quoting and Parameters363798 25491Node: Quotation and Nested Macros366134 25492Node: Changequote is Evil369144 25493Node: Quadrigraphs371674 25494Node: Balancing Parentheses374356 25495Node: Quotation Rule Of Thumb378450 25496Node: Using autom4te381348 25497Ref: Using autom4te-Footnote-1381999 25498Node: autom4te Invocation382048 25499Node: Customizing autom4te390550 25500Node: Programming in M4sugar391831 25501Node: Redefined M4 Macros393012 25502Node: Diagnostic Macros401342 25503Ref: m4_fatal402095 25504Ref: m4_warn402334 25505Node: Diversion support403102 25506Node: Conditional constructs410888 25507Node: Looping constructs417742 25508Ref: m4_foreach_w421354 25509Node: Evaluation Macros428706 25510Node: Text processing Macros437395 25511Node: Number processing Macros447105 25512Ref: m4_version_compare449057 25513Node: Set manipulation Macros451364 25514Node: Forbidden Patterns460480 25515Node: Debugging via autom4te461971 25516Node: Programming in M4sh463790 25517Node: Common Shell Constructs465163 25518Node: Polymorphic Variables473136 25519Node: Initialization Macros482725 25520Node: File Descriptor Macros488314 25521Ref: AS_MESSAGE_LOG_FD489466 25522Node: Writing Autoconf Macros490968 25523Node: Macro Definitions491773 25524Node: Macro Names495452 25525Node: Reporting Messages499213 25526Node: Dependencies Between Macros501057 25527Node: Prerequisite Macros501752 25528Node: Suggested Ordering507827 25529Node: One-Shot Macros509370 25530Node: Obsoleting Macros510723 25531Ref: AU_DEFUN511477 25532Node: Coding Style512506 25533Node: Portable Shell520313 25534Node: Shellology524621 25535Node: Invoking the Shell528792 25536Node: Here-Documents529974 25537Node: File Descriptors533594 25538Node: Signal Handling540032 25539Node: File System Conventions545240 25540Node: Shell Pattern Matching551052 25541Node: Shell Substitutions551616 25542Node: Assignments569492 25543Node: Parentheses571383 25544Node: Slashes572340 25545Node: Special Shell Variables573194 25546Node: Shell Functions586526 25547Node: Limitations of Builtins589933 25548Ref: case593955 25549Ref: echo599113 25550Ref: export606087 25551Ref: if609507 25552Ref: set613318 25553Ref: trap625040 25554Ref: unset628851 25555Node: Limitations of Usual Tools629946 25556Ref: awk630245 25557Ref: grep648349 25558Ref: mkdir653981 25559Ref: sed659801 25560Ref: touch670932 25561Node: Portable Make674207 25562Node: $< in Ordinary Make Rules675869 25563Node: Failure in Make Rules676335 25564Node: Special Chars in Names677363 25565Node: Backslash-Newline-Empty678335 25566Node: Backslash-Newline Comments679367 25567Node: Long Lines in Makefiles680256 25568Node: Macros and Submakes680632 25569Node: The Make Macro MAKEFLAGS683319 25570Node: The Make Macro SHELL684204 25571Node: Parallel Make686703 25572Node: Comments in Make Rules690387 25573Node: Newlines in Make Rules691557 25574Node: Comments in Make Macros692602 25575Node: Trailing whitespace in Make Macros693812 25576Node: Command-line Macros and whitespace694563 25577Node: obj/ and Make695233 25578Node: make -k Status695884 25579Node: VPATH and Make696506 25580Node: Variables listed in VPATH697830 25581Node: VPATH and Double-colon698369 25582Node: $< in Explicit Rules698775 25583Node: Automatic Rule Rewriting699242 25584Node: Tru64 Directory Magic705924 25585Node: Make Target Lookup706750 25586Node: Single Suffix Rules711192 25587Node: Timestamps and Make712538 25588Node: Portable C and C++714223 25589Node: Varieties of Unportability715864 25590Node: Integer Overflow717961 25591Node: Integer Overflow Basics718974 25592Node: Signed Overflow Examples720722 25593Node: Optimization and Wraparound724224 25594Node: Signed Overflow Advice727186 25595Node: Signed Integer Division729860 25596Node: Preprocessor Arithmetic730471 25597Node: Null Pointers731220 25598Node: Buffer Overruns731854 25599Node: Volatile Objects734643 25600Node: Floating Point Portability740321 25601Node: Exiting Portably740828 25602Node: Manual Configuration742304 25603Node: Specifying Target Triplets743137 25604Ref: Specifying Names743310 25605Node: Canonicalizing746185 25606Node: Using System Type748448 25607Node: Site Configuration751252 25608Node: Help Formatting752224 25609Node: External Software753168 25610Ref: AC_ARG_WITH754714 25611Node: Package Options759039 25612Ref: AC_ARG_ENABLE760494 25613Node: Pretty Help Strings761655 25614Ref: AS_HELP_STRING762241 25615Node: Option Checking764582 25616Node: Site Details766310 25617Node: Transforming Names767539 25618Node: Transformation Options768621 25619Node: Transformation Examples769098 25620Node: Transformation Rules770819 25621Node: Site Defaults772365 25622Node: Running configure Scripts777706 25623Node: Basic Installation778771 25624Node: Compilers and Options782868 25625Node: Multiple Architectures783522 25626Node: Installation Names785102 25627Node: Optional Features787997 25628Node: Particular Systems789351 25629Node: System Type790775 25630Node: Sharing Defaults792103 25631Node: Defining Variables792741 25632Node: configure Invocation793639 25633Node: config.status Invocation795345 25634Ref: CONFIG_SHELL799092 25635Node: Obsolete Constructs800258 25636Node: Obsolete config.status Use801221 25637Node: acconfig Header802999 25638Node: autoupdate Invocation805021 25639Node: Obsolete Macros806887 25640Ref: AC_FUNC_SETVBUF_REVERSED814529 25641Ref: AC_TYPE_SIGNAL831075 25642Node: Autoconf 1834053 25643Node: Changed File Names835119 25644Node: Changed Makefiles835869 25645Node: Changed Macros836957 25646Node: Changed Results838211 25647Node: Changed Macro Writing840335 25648Node: Autoconf 2.13841615 25649Node: Changed Quotation842823 25650Node: New Macros844741 25651Node: Hosts and Cross-Compilation846536 25652Node: AC_LIBOBJ vs LIBOBJS850691 25653Node: AC_ACT_IFELSE vs AC_TRY_ACT852306 25654Ref: AC_FOO_IFELSE vs AC_TRY_FOO852495 25655Node: Using Autotest854308 25656Node: Using an Autotest Test Suite856712 25657Node: testsuite Scripts857003 25658Node: Autotest Logs861485 25659Node: Writing Testsuites863826 25660Node: testsuite Invocation880858 25661Node: Making testsuite Scripts886205 25662Node: FAQ891343 25663Node: Distributing892203 25664Node: Why GNU M4893252 25665Node: Bootstrapping894121 25666Node: Why Not Imake894731 25667Node: Defining Directories899482 25668Node: Autom4te Cache901640 25669Node: Present But Cannot Be Compiled903478 25670Node: Expanded Before Required907195 25671Node: Debugging912093 25672Node: History917116 25673Node: Genesis917985 25674Node: Exodus919163 25675Node: Leviticus922208 25676Node: Numbers923736 25677Node: Deuteronomy925651 25678Node: GNU Free Documentation License928322 25679Node: Indices953487 25680Node: Environment Variable Index954206 25681Node: Output Variable Index965546 25682Node: Preprocessor Symbol Index982426 25683Node: Cache Variable Index1000695 25684Node: Autoconf Macro Index1011383 25685Node: M4 Macro Index1045712 25686Node: Autotest Macro Index1066462 25687Node: Program & Function Index1068865 25688Node: Concept Index1089579 25689 25690End Tag Table 25691