1This is autoconf.info, produced by makeinfo version 4.8 from 2autoconf.texi. 3 4 This manual is for GNU Autoconf (version 2.61, 16 November 2006), a 5package for creating scripts to configure source code packages using 6templates and an M4 macro package. 7 8 Copyright (C) 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 92002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc. 10 11 Permission is granted to copy, distribute and/or modify this 12 document under the terms of the GNU Free Documentation License, 13 Version 1.2 or any later version published by the Free Software 14 Foundation; with no Invariant Sections, with the Front-Cover texts 15 being "A GNU Manual," and with the Back-Cover Texts as in (a) 16 below. A copy of the license is included in the section entitled 17 "GNU Free Documentation License." 18 19 (a) The FSF's Back-Cover Text is: "You have freedom to copy and 20 modify this GNU Manual, like GNU software. Copies published by 21 the Free Software Foundation raise funds for GNU development." 22 23INFO-DIR-SECTION Software development 24START-INFO-DIR-ENTRY 25* Autoconf: (autoconf). Create source code configuration scripts. 26END-INFO-DIR-ENTRY 27 28INFO-DIR-SECTION Individual utilities 29START-INFO-DIR-ENTRY 30* autoscan: (autoconf)autoscan Invocation. 31 Semi-automatic `configure.ac' writing 32* ifnames: (autoconf)ifnames Invocation. Listing conditionals in source. 33* autoconf: (autoconf)autoconf Invocation. 34 How to create configuration scripts 35* autoreconf: (autoconf)autoreconf Invocation. 36 Remaking multiple `configure' scripts 37* autoheader: (autoconf)autoheader Invocation. 38 How to create configuration templates 39* autom4te: (autoconf)autom4te Invocation. 40 The Autoconf executables backbone 41* configure: (autoconf)configure Invocation. Configuring a package. 42* autoupdate: (autoconf)autoupdate Invocation. 43 Automatic update of `configure.ac' 44* config.status: (autoconf)config.status Invocation. Recreating configurations. 45* testsuite: (autoconf)testsuite Invocation. Running an Autotest test suite. 46END-INFO-DIR-ENTRY 47 48 49File: autoconf.info, Node: Top, Next: Introduction, Up: (dir) 50 51Autoconf 52******** 53 54This manual is for GNU Autoconf (version 2.61, 16 November 2006), a 55package for creating scripts to configure source code packages using 56templates and an M4 macro package. 57 58 Copyright (C) 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 592002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc. 60 61 Permission is granted to copy, distribute and/or modify this 62 document under the terms of the GNU Free Documentation License, 63 Version 1.2 or any later version published by the Free Software 64 Foundation; with no Invariant Sections, with the Front-Cover texts 65 being "A GNU Manual," and with the Back-Cover Texts as in (a) 66 below. A copy of the license is included in the section entitled 67 "GNU Free Documentation License." 68 69 (a) The FSF's Back-Cover Text is: "You have freedom to copy and 70 modify this GNU Manual, like GNU software. Copies published by 71 the Free Software Foundation raise funds for GNU development." 72 73* Menu: 74 75* Introduction:: Autoconf's purpose, strengths, and weaknesses 76* The GNU Build System:: A set of tools for portable software packages 77* Making configure Scripts:: How to organize and produce Autoconf scripts 78* Setup:: Initialization and output 79* Existing Tests:: Macros that check for particular features 80* Writing Tests:: How to write new feature checks 81* Results:: What to do with results from feature checks 82* Programming in M4:: Layers on top of which Autoconf is written 83* Writing Autoconf Macros:: Adding new macros to Autoconf 84* Portable Shell:: Shell script portability pitfalls 85* Portable Make:: Makefile portability pitfalls 86* Portable C and C++:: C and C++ portability pitfalls 87* Manual Configuration:: Selecting features that can't be guessed 88* Site Configuration:: Local defaults for `configure' 89* Running configure Scripts:: How to use the Autoconf output 90* config.status Invocation:: Recreating a configuration 91* Obsolete Constructs:: Kept for backward compatibility 92* Using Autotest:: Creating portable test suites 93* FAQ:: Frequent Autoconf Questions, with answers 94* History:: History of Autoconf 95* Copying This Manual:: How to make copies of this manual 96* Indices:: Indices of symbols, concepts, etc. 97 98 --- The Detailed Node Listing --- 99 100The GNU Build System 101 102* Automake:: Escaping makefile hell 103* Gnulib:: The GNU portability library 104* Libtool:: Building libraries portably 105* Pointers:: More info on the GNU build system 106 107Making `configure' Scripts 108 109* Writing configure.ac:: What to put in an Autoconf input file 110* autoscan Invocation:: Semi-automatic `configure.ac' writing 111* ifnames Invocation:: Listing the conditionals in source code 112* autoconf Invocation:: How to create configuration scripts 113* autoreconf Invocation:: Remaking multiple `configure' scripts 114 115Writing `configure.ac' 116 117* Shell Script Compiler:: Autoconf as solution of a problem 118* Autoconf Language:: Programming in Autoconf 119* configure.ac Layout:: Standard organization of `configure.ac' 120 121Initialization and Output Files 122 123* Initializing configure:: Option processing etc. 124* Notices:: Copyright, version numbers in `configure' 125* Input:: Where Autoconf should find files 126* Output:: Outputting results from the configuration 127* Configuration Actions:: Preparing the output based on results 128* Configuration Files:: Creating output files 129* Makefile Substitutions:: Using output variables in makefiles 130* Configuration Headers:: Creating a configuration header file 131* Configuration Commands:: Running arbitrary instantiation commands 132* Configuration Links:: Links depending on the configuration 133* Subdirectories:: Configuring independent packages together 134* Default Prefix:: Changing the default installation prefix 135 136Substitutions in Makefiles 137 138* Preset Output Variables:: Output variables that are always set 139* Installation Directory Variables:: Other preset output variables 140* Changed Directory Variables:: Warnings about `datarootdir' 141* Build Directories:: Supporting multiple concurrent compiles 142* Automatic Remaking:: Makefile rules for configuring 143 144Configuration Header Files 145 146* Header Templates:: Input for the configuration headers 147* autoheader Invocation:: How to create configuration templates 148* Autoheader Macros:: How to specify CPP templates 149 150Existing Tests 151 152* Common Behavior:: Macros' standard schemes 153* Alternative Programs:: Selecting between alternative programs 154* Files:: Checking for the existence of files 155* Libraries:: Library archives that might be missing 156* Library Functions:: C library functions that might be missing 157* Header Files:: Header files that might be missing 158* Declarations:: Declarations that may be missing 159* Structures:: Structures or members that might be missing 160* Types:: Types that might be missing 161* Compilers and Preprocessors:: Checking for compiling programs 162* System Services:: Operating system services 163* Posix Variants:: Special kludges for specific Posix variants 164* Erlang Libraries:: Checking for the existence of Erlang libraries 165 166Common Behavior 167 168* Standard Symbols:: Symbols defined by the macros 169* Default Includes:: Includes used by the generic macros 170 171Alternative Programs 172 173* Particular Programs:: Special handling to find certain programs 174* Generic Programs:: How to find other programs 175 176Library Functions 177 178* Function Portability:: Pitfalls with usual functions 179* Particular Functions:: Special handling to find certain functions 180* Generic Functions:: How to find other functions 181 182Header Files 183 184* Header Portability:: Collected knowledge on common headers 185* Particular Headers:: Special handling to find certain headers 186* Generic Headers:: How to find other headers 187 188Declarations 189 190* Particular Declarations:: Macros to check for certain declarations 191* Generic Declarations:: How to find other declarations 192 193Structures 194 195* Particular Structures:: Macros to check for certain structure members 196* Generic Structures:: How to find other structure members 197 198Types 199 200* Particular Types:: Special handling to find certain types 201* Generic Types:: How to find other types 202 203Compilers and Preprocessors 204 205* Specific Compiler Characteristics:: Some portability issues 206* Generic Compiler Characteristics:: Language independent tests and features 207* C Compiler:: Checking its characteristics 208* C++ Compiler:: Likewise 209* Objective C Compiler:: Likewise 210* Erlang Compiler and Interpreter:: Likewise 211* Fortran Compiler:: Likewise 212 213Writing Tests 214 215* Language Choice:: Selecting which language to use for testing 216* Writing Test Programs:: Forging source files for compilers 217* Running the Preprocessor:: Detecting preprocessor symbols 218* Running the Compiler:: Detecting language or header features 219* Running the Linker:: Detecting library features 220* Runtime:: Testing for runtime features 221* Systemology:: A zoology of operating systems 222* Multiple Cases:: Tests for several possible values 223 224Writing Test Programs 225 226* Guidelines:: General rules for writing test programs 227* Test Functions:: Avoiding pitfalls in test programs 228* Generating Sources:: Source program boilerplate 229 230Results of Tests 231 232* Defining Symbols:: Defining C preprocessor symbols 233* Setting Output Variables:: Replacing variables in output files 234* Special Chars in Variables:: Characters to beware of in variables 235* Caching Results:: Speeding up subsequent `configure' runs 236* Printing Messages:: Notifying `configure' users 237 238Caching Results 239 240* Cache Variable Names:: Shell variables used in caches 241* Cache Files:: Files `configure' uses for caching 242* Cache Checkpointing:: Loading and saving the cache file 243 244Programming in M4 245 246* M4 Quotation:: Protecting macros from unwanted expansion 247* Using autom4te:: The Autoconf executables backbone 248* Programming in M4sugar:: Convenient pure M4 macros 249* Programming in M4sh:: Common shell Constructs 250* File Descriptor Macros:: File descriptor macros for input and output 251 252M4 Quotation 253 254* Active Characters:: Characters that change the behavior of M4 255* One Macro Call:: Quotation and one macro call 256* Quotation and Nested Macros:: Macros calling macros 257* Changequote is Evil:: Worse than INTERCAL: M4 + changequote 258* Quadrigraphs:: Another way to escape special characters 259* Quotation Rule Of Thumb:: One parenthesis, one quote 260 261Using `autom4te' 262 263* autom4te Invocation:: A GNU M4 wrapper 264* Customizing autom4te:: Customizing the Autoconf package 265 266Programming in M4sugar 267 268* Redefined M4 Macros:: M4 builtins changed in M4sugar 269* Looping constructs:: Iteration in M4 270* Evaluation Macros:: More quotation and evaluation control 271* Text processing Macros:: String manipulation in M4 272* Forbidden Patterns:: Catching unexpanded macros 273 274Writing Autoconf Macros 275 276* Macro Definitions:: Basic format of an Autoconf macro 277* Macro Names:: What to call your new macros 278* Reporting Messages:: Notifying `autoconf' users 279* Dependencies Between Macros:: What to do when macros depend on other macros 280* Obsoleting Macros:: Warning about old ways of doing things 281* Coding Style:: Writing Autoconf macros a` la Autoconf 282 283Dependencies Between Macros 284 285* Prerequisite Macros:: Ensuring required information 286* Suggested Ordering:: Warning about possible ordering problems 287* One-Shot Macros:: Ensuring a macro is called only once 288 289Portable Shell Programming 290 291* Shellology:: A zoology of shells 292* Here-Documents:: Quirks and tricks 293* File Descriptors:: FDs and redirections 294* File System Conventions:: File names 295* Shell Substitutions:: Variable and command expansions 296* Assignments:: Varying side effects of assignments 297* Parentheses:: Parentheses in shell scripts 298* Slashes:: Slashes in shell scripts 299* Special Shell Variables:: Variables you should not change 300* Limitations of Builtins:: Portable use of not so portable /bin/sh 301* Limitations of Usual Tools:: Portable use of portable tools 302 303Portable Make Programming 304 305* $< in Ordinary Make Rules:: $< in ordinary rules 306* Failure in Make Rules:: Failing portably in rules 307* Special Chars in Names:: Special Characters in Macro Names 308* Backslash-Newline-Newline:: Empty last lines in macro definitions 309* Backslash-Newline Comments:: Spanning comments across line boundaries 310* Long Lines in Makefiles:: Line length limitations 311* Macros and Submakes:: `make macro=value' and submakes 312* The Make Macro MAKEFLAGS:: `$(MAKEFLAGS)' portability issues 313* The Make Macro SHELL:: `$(SHELL)' portability issues 314* Comments in Make Rules:: Other problems with Make comments 315* obj/ and Make:: Don't name a subdirectory `obj' 316* make -k Status:: Exit status of `make -k' 317* VPATH and Make:: `VPATH' woes 318* Single Suffix Rules:: Single suffix rules and separated dependencies 319* Timestamps and Make:: Subsecond timestamp resolution 320 321`VPATH' and Make 322 323* VPATH and Double-colon:: Problems with `::' on ancient hosts 324* $< in Explicit Rules:: `$<' does not work in ordinary rules 325* Automatic Rule Rewriting:: `VPATH' goes wild on Solaris 326* Tru64 Directory Magic:: `mkdir' goes wild on Tru64 327* Make Target Lookup:: More details about `VPATH' lookup 328 329Portable C and C++ Programming 330 331* Varieties of Unportability:: How to make your programs unportable 332* Integer Overflow:: When integers get too large 333* Null Pointers:: Properties of null pointers 334* Buffer Overruns:: Subscript errors and the like 335* Volatile Objects:: `volatile' and signals 336* Floating Point Portability:: Portable floating-point arithmetic 337* Exiting Portably:: Exiting and the exit status 338 339Manual Configuration 340 341* Specifying Names:: Specifying the system type 342* Canonicalizing:: Getting the canonical system type 343* Using System Type:: What to do with the system type 344 345Site Configuration 346 347* Help Formatting:: Customizing `configure --help' 348* External Software:: Working with other optional software 349* Package Options:: Selecting optional features 350* Pretty Help Strings:: Formatting help string 351* Site Details:: Configuring site details 352* Transforming Names:: Changing program names when installing 353* Site Defaults:: Giving `configure' local defaults 354 355Transforming Program Names When Installing 356 357* Transformation Options:: `configure' options to transform names 358* Transformation Examples:: Sample uses of transforming names 359* Transformation Rules:: Makefile uses of transforming names 360 361Running `configure' Scripts 362 363* Basic Installation:: Instructions for typical cases 364* Compilers and Options:: Selecting compilers and optimization 365* Multiple Architectures:: Compiling for multiple architectures at once 366* Installation Names:: Installing in different directories 367* Optional Features:: Selecting optional features 368* System Type:: Specifying the system type 369* Sharing Defaults:: Setting site-wide defaults for `configure' 370* Defining Variables:: Specifying the compiler etc. 371* configure Invocation:: Changing how `configure' runs 372 373Obsolete Constructs 374 375* Obsolete config.status Use:: Different calling convention 376* acconfig.h:: Additional entries in `config.h.in' 377* autoupdate Invocation:: Automatic update of `configure.ac' 378* Obsolete Macros:: Backward compatibility macros 379* Autoconf 1:: Tips for upgrading your files 380* Autoconf 2.13:: Some fresher tips 381 382Upgrading From Version 1 383 384* Changed File Names:: Files you might rename 385* Changed Makefiles:: New things to put in `Makefile.in' 386* Changed Macros:: Macro calls you might replace 387* Changed Results:: Changes in how to check test results 388* Changed Macro Writing:: Better ways to write your own macros 389 390Upgrading From Version 2.13 391 392* Changed Quotation:: Broken code which used to work 393* New Macros:: Interaction with foreign macros 394* Hosts and Cross-Compilation:: Bugward compatibility kludges 395* AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token 396* AC_FOO_IFELSE vs AC_TRY_FOO:: A more generic scheme for testing sources 397 398Generating Test Suites with Autotest 399 400* Using an Autotest Test Suite:: Autotest and the user 401* Writing testsuite.at:: Autotest macros 402* testsuite Invocation:: Running `testsuite' scripts 403* Making testsuite Scripts:: Using autom4te to create `testsuite' 404 405Using an Autotest Test Suite 406 407* testsuite Scripts:: The concepts of Autotest 408* Autotest Logs:: Their contents 409 410Frequent Autoconf Questions, with answers 411 412* Distributing:: Distributing `configure' scripts 413* Why GNU M4:: Why not use the standard M4? 414* Bootstrapping:: Autoconf and GNU M4 require each other? 415* Why Not Imake:: Why GNU uses `configure' instead of Imake 416* Defining Directories:: Passing `datadir' to program 417* autom4te.cache:: What is it? Can I remove it? 418* Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree 419 420History of Autoconf 421 422* Genesis:: Prehistory and naming of `configure' 423* Exodus:: The plagues of M4 and Perl 424* Leviticus:: The priestly code of portability arrives 425* Numbers:: Growth and contributors 426* Deuteronomy:: Approaching the promises of easy configuration 427 428Copying This Manual 429 430* GNU Free Documentation License:: License for copying this manual 431 432Indices 433 434* Environment Variable Index:: Index of environment variables used 435* Output Variable Index:: Index of variables set in output files 436* Preprocessor Symbol Index:: Index of C preprocessor symbols defined 437* Autoconf Macro Index:: Index of Autoconf macros 438* M4 Macro Index:: Index of M4, M4sugar, and M4sh macros 439* Autotest Macro Index:: Index of Autotest macros 440* Program & Function Index:: Index of those with portability problems 441* Concept Index:: General index 442 443 444File: autoconf.info, Node: Introduction, Next: The GNU Build System, Prev: Top, Up: Top 445 4461 Introduction 447************** 448 449 A physicist, an engineer, and a computer scientist were discussing the 450 nature of God. "Surely a Physicist," said the physicist, "because 451 early in the Creation, God made Light; and you know, Maxwell's 452 equations, the dual nature of electromagnetic waves, the relativistic 453 consequences..." "An Engineer!," said the engineer, "because 454before making Light, God split the Chaos into Land and Water; it takes a 455 hell of an engineer to handle that big amount of mud, and orderly 456 separation of solids from liquids..." The computer scientist 457 shouted: "And the Chaos, where do you think it was coming from, hmm?" 458 459 --Anonymous 460 461 Autoconf is a tool for producing shell scripts that automatically 462configure software source code packages to adapt to many kinds of 463Posix-like systems. The configuration scripts produced by Autoconf are 464independent of Autoconf when they are run, so their users do not need 465to have Autoconf. 466 467 The configuration scripts produced by Autoconf require no manual user 468intervention when run; they do not normally even need an argument 469specifying the system type. Instead, they individually test for the 470presence of each feature that the software package they are for might 471need. (Before each check, they print a one-line message stating what 472they are checking for, so the user doesn't get too bored while waiting 473for the script to finish.) As a result, they deal well with systems 474that are hybrids or customized from the more common Posix variants. 475There is no need to maintain files that list the features supported by 476each release of each variant of Posix. 477 478 For each software package that Autoconf is used with, it creates a 479configuration script from a template file that lists the system features 480that the package needs or can use. After the shell code to recognize 481and respond to a system feature has been written, Autoconf allows it to 482be shared by many software packages that can use (or need) that feature. 483If it later turns out that the shell code needs adjustment for some 484reason, it needs to be changed in only one place; all of the 485configuration scripts can be regenerated automatically to take advantage 486of the updated code. 487 488 The Metaconfig package is similar in purpose to Autoconf, but the 489scripts it produces require manual user intervention, which is quite 490inconvenient when configuring large source trees. Unlike Metaconfig 491scripts, Autoconf scripts can support cross-compiling, if some care is 492taken in writing them. 493 494 Autoconf does not solve all problems related to making portable 495software packages--for a more complete solution, it should be used in 496concert with other GNU build tools like Automake and Libtool. These 497other tools take on jobs like the creation of a portable, recursive 498makefile with all of the standard targets, linking of shared libraries, 499and so on. *Note The GNU Build System::, for more information. 500 501 Autoconf imposes some restrictions on the names of macros used with 502`#if' in C programs (*note Preprocessor Symbol Index::). 503 504 Autoconf requires GNU M4 in order to generate the scripts. It uses 505features that some versions of M4, including GNU M4 1.3, do not have. 506You should use version 1.4.7 or later of GNU M4. 507 508 *Note Autoconf 1::, for information about upgrading from version 1. 509*Note History::, for the story of Autoconf's development. *Note FAQ::, 510for answers to some common questions about Autoconf. 511 512 See the Autoconf web page (http://www.gnu.org/software/autoconf/) 513for up-to-date information, details on the mailing lists, pointers to a 514list of known bugs, etc. 515 516 Mail suggestions to the Autoconf mailing list <autoconf@gnu.org>. 517Past suggestions are archived 518(http://lists.gnu.org/archive/html/autoconf/). 519 520 Mail bug reports to the Autoconf Bugs mailing list 521<bug-autoconf@gnu.org>. Past bug reports are archived 522(http://lists.gnu.org/archive/html/bug-autoconf/). 523 524 If possible, first check that your bug is not already solved in 525current development versions, and that it has not been reported yet. 526Be sure to include all the needed information and a short 527`configure.ac' that demonstrates the problem. 528 529 Autoconf's development tree is accessible via anonymous CVS; see the 530Autoconf Summary (http://savannah.gnu.org/projects/autoconf/) for 531details. Patches relative to the current CVS version can be sent for 532review to the Autoconf Patches mailing list <autoconf-patches@gnu.org>. 533Past patches are archived 534(http://lists.gnu.org/archive/html/autoconf-patches/). 535 536 Because of its mission, the Autoconf package itself includes only a 537set of often-used macros that have already demonstrated their 538usefulness. Nevertheless, if you wish to share your macros, or find 539existing ones, see the Autoconf Macro Archive 540(http://autoconf-archive.cryp.to/), which is kindly run by Peter Simons 541<simons@cryp.to>. 542 543 544File: autoconf.info, Node: The GNU Build System, Next: Making configure Scripts, Prev: Introduction, Up: Top 545 5462 The GNU Build System 547********************** 548 549Autoconf solves an important problem--reliable discovery of 550system-specific build and runtime information--but this is only one 551piece of the puzzle for the development of portable software. To this 552end, the GNU project has developed a suite of integrated utilities to 553finish the job Autoconf started: the GNU build system, whose most 554important components are Autoconf, Automake, and Libtool. In this 555chapter, we introduce you to those tools, point you to sources of more 556information, and try to convince you to use the entire GNU build system 557for your software. 558 559* Menu: 560 561* Automake:: Escaping makefile hell 562* Gnulib:: The GNU portability library 563* Libtool:: Building libraries portably 564* Pointers:: More info on the GNU build system 565 566 567File: autoconf.info, Node: Automake, Next: Gnulib, Up: The GNU Build System 568 5692.1 Automake 570============ 571 572The ubiquity of `make' means that a makefile is almost the only viable 573way to distribute automatic build rules for software, but one quickly 574runs into its numerous limitations. Its lack of support for automatic 575dependency tracking, recursive builds in subdirectories, reliable 576timestamps (e.g., for network file systems), and so on, mean that 577developers must painfully (and often incorrectly) reinvent the wheel 578for each project. Portability is non-trivial, thanks to the quirks of 579`make' on many systems. On top of all this is the manual labor 580required to implement the many standard targets that users have come to 581expect (`make install', `make distclean', `make uninstall', etc.). 582Since you are, of course, using Autoconf, you also have to insert 583repetitive code in your `Makefile.in' to recognize `@CC@', `@CFLAGS@', 584and other substitutions provided by `configure'. Into this mess steps 585"Automake". 586 587 Automake allows you to specify your build needs in a `Makefile.am' 588file with a vastly simpler and more powerful syntax than that of a plain 589makefile, and then generates a portable `Makefile.in' for use with 590Autoconf. For example, the `Makefile.am' to build and install a simple 591"Hello world" program might look like: 592 593 bin_PROGRAMS = hello 594 hello_SOURCES = hello.c 595 596The resulting `Makefile.in' (~400 lines) automatically supports all the 597standard targets, the substitutions provided by Autoconf, automatic 598dependency tracking, `VPATH' building, and so on. `make' builds the 599`hello' program, and `make install' installs it in `/usr/local/bin' (or 600whatever prefix was given to `configure', if not `/usr/local'). 601 602 The benefits of Automake increase for larger packages (especially 603ones with subdirectories), but even for small programs the added 604convenience and portability can be substantial. And that's not all.... 605 606 607File: autoconf.info, Node: Gnulib, Next: Libtool, Prev: Automake, Up: The GNU Build System 608 6092.2 Gnulib 610========== 611 612GNU software has a well-deserved reputation for running on many 613different types of systems. While our primary goal is to write 614software for the GNU system, many users and developers have been 615introduced to us through the systems that they were already using. 616 617 Gnulib is a central location for common GNU code, intended to be 618shared among free software packages. Its components are typically 619shared at the source level, rather than being a library that gets built, 620installed, and linked against. The idea is to copy files from Gnulib 621into your own source tree. There is no distribution tarball; developers 622should just grab source modules from the repository. The source files 623are available online, under various licenses, mostly GNU GPL or GNU 624LGPL. 625 626 Gnulib modules typically contain C source code along with Autoconf 627macros used to configure the source code. For example, the Gnulib 628`stdbool' module implements a `stdbool.h' header that nearly conforms 629to C99, even on old-fashioned hosts that lack `stdbool.h'. This module 630contains a source file for the replacement header, along with an 631Autoconf macro that arranges to use the replacement header on 632old-fashioned systems. 633 634 635File: autoconf.info, Node: Libtool, Next: Pointers, Prev: Gnulib, Up: The GNU Build System 636 6372.3 Libtool 638=========== 639 640Often, one wants to build not only programs, but libraries, so that 641other programs can benefit from the fruits of your labor. Ideally, one 642would like to produce _shared_ (dynamically linked) libraries, which 643can be used by multiple programs without duplication on disk or in 644memory and can be updated independently of the linked programs. 645Producing shared libraries portably, however, is the stuff of 646nightmares--each system has its own incompatible tools, compiler flags, 647and magic incantations. Fortunately, GNU provides a solution: 648"Libtool". 649 650 Libtool handles all the requirements of building shared libraries for 651you, and at this time seems to be the _only_ way to do so with any 652portability. It also handles many other headaches, such as: the 653interaction of Make rules with the variable suffixes of shared 654libraries, linking reliably with shared libraries before they are 655installed by the superuser, and supplying a consistent versioning system 656(so that different versions of a library can be installed or upgraded 657without breaking binary compatibility). Although Libtool, like 658Autoconf, can be used without Automake, it is most simply utilized in 659conjunction with Automake--there, Libtool is used automatically 660whenever shared libraries are needed, and you need not know its syntax. 661 662 663File: autoconf.info, Node: Pointers, Prev: Libtool, Up: The GNU Build System 664 6652.4 Pointers 666============ 667 668Developers who are used to the simplicity of `make' for small projects 669on a single system might be daunted at the prospect of learning to use 670Automake and Autoconf. As your software is distributed to more and 671more users, however, you otherwise quickly find yourself putting lots 672of effort into reinventing the services that the GNU build tools 673provide, and making the same mistakes that they once made and overcame. 674(Besides, since you're already learning Autoconf, Automake is a piece 675of cake.) 676 677 There are a number of places that you can go to for more information 678on the GNU build tools. 679 680 - Web 681 682 The home pages for Autoconf 683 (http://www.gnu.org/software/autoconf/), Automake 684 (http://www.gnu.org/software/automake/), Gnulib 685 (http://www.gnu.org/software/gnulib/), and Libtool 686 (http://www.gnu.org/software/libtool/). 687 688 - Automake Manual 689 690 *Note Automake: (automake)Top, for more information on Automake. 691 692 - Books 693 694 The book `GNU Autoconf, Automake and Libtool'(1) describes the 695 complete GNU build environment. You can also find the entire book 696 on-line (http://sources.redhat.com/autobook/). 697 698 699 ---------- Footnotes ---------- 700 701 (1) `GNU Autoconf, Automake and Libtool', by G. V. Vaughan, B. 702Elliston, T. Tromey, and I. L. Taylor. SAMS (originally New Riders), 7032000, ISBN 1578701902. 704 705 706File: autoconf.info, Node: Making configure Scripts, Next: Setup, Prev: The GNU Build System, Up: Top 707 7083 Making `configure' Scripts 709**************************** 710 711The configuration scripts that Autoconf produces are by convention 712called `configure'. When run, `configure' creates several files, 713replacing configuration parameters in them with appropriate values. 714The files that `configure' creates are: 715 716 - one or more `Makefile' files, usually one in each subdirectory of 717 the package (*note Makefile Substitutions::); 718 719 - optionally, a C header file, the name of which is configurable, 720 containing `#define' directives (*note Configuration Headers::); 721 722 - a shell script called `config.status' that, when run, recreates 723 the files listed above (*note config.status Invocation::); 724 725 - an optional shell script normally called `config.cache' (created 726 when using `configure --config-cache') that saves the results of 727 running many of the tests (*note Cache Files::); 728 729 - a file called `config.log' containing any messages produced by 730 compilers, to help debugging if `configure' makes a mistake. 731 732 To create a `configure' script with Autoconf, you need to write an 733Autoconf input file `configure.ac' (or `configure.in') and run 734`autoconf' on it. If you write your own feature tests to supplement 735those that come with Autoconf, you might also write files called 736`aclocal.m4' and `acsite.m4'. If you use a C header file to contain 737`#define' directives, you might also run `autoheader', and you can 738distribute the generated file `config.h.in' with the package. 739 740 Here is a diagram showing how the files that can be used in 741configuration are produced. Programs that are executed are suffixed by 742`*'. Optional files are enclosed in square brackets (`[]'). 743`autoconf' and `autoheader' also read the installed Autoconf macro 744files (by reading `autoconf.m4'). 745 746Files used in preparing a software package for distribution: 747 your source files --> [autoscan*] --> [configure.scan] --> configure.ac 748 749 configure.ac --. 750 | .------> autoconf* -----> configure 751 [aclocal.m4] --+---+ 752 | `-----> [autoheader*] --> [config.h.in] 753 [acsite.m4] ---' 754 755 Makefile.in -------------------------------> Makefile.in 756 757Files used in configuring a software package: 758 .-------------> [config.cache] 759 configure* ------------+-------------> config.log 760 | 761 [config.h.in] -. v .-> [config.h] -. 762 +--> config.status* -+ +--> make* 763 Makefile.in ---' `-> Makefile ---' 764 765* Menu: 766 767* Writing configure.ac:: What to put in an Autoconf input file 768* autoscan Invocation:: Semi-automatic `configure.ac' writing 769* ifnames Invocation:: Listing the conditionals in source code 770* autoconf Invocation:: How to create configuration scripts 771* autoreconf Invocation:: Remaking multiple `configure' scripts 772 773 774File: autoconf.info, Node: Writing configure.ac, Next: autoscan Invocation, Up: Making configure Scripts 775 7763.1 Writing `configure.ac' 777========================== 778 779To produce a `configure' script for a software package, create a file 780called `configure.ac' that contains invocations of the Autoconf macros 781that test the system features your package needs or can use. Autoconf 782macros already exist to check for many features; see *Note Existing 783Tests::, for their descriptions. For most other features, you can use 784Autoconf template macros to produce custom checks; see *Note Writing 785Tests::, for information about them. For especially tricky or 786specialized features, `configure.ac' might need to contain some 787hand-crafted shell commands; see *Note Portable Shell::. The 788`autoscan' program can give you a good start in writing `configure.ac' 789(*note autoscan Invocation::, for more information). 790 791 Previous versions of Autoconf promoted the name `configure.in', 792which is somewhat ambiguous (the tool needed to process this file is not 793described by its extension), and introduces a slight confusion with 794`config.h.in' and so on (for which `.in' means "to be processed by 795`configure'"). Using `configure.ac' is now preferred. 796 797* Menu: 798 799* Shell Script Compiler:: Autoconf as solution of a problem 800* Autoconf Language:: Programming in Autoconf 801* configure.ac Layout:: Standard organization of `configure.ac' 802 803 804File: autoconf.info, Node: Shell Script Compiler, Next: Autoconf Language, Up: Writing configure.ac 805 8063.1.1 A Shell Script Compiler 807----------------------------- 808 809Just as for any other computer language, in order to properly program 810`configure.ac' in Autoconf you must understand _what_ problem the 811language tries to address and _how_ it does so. 812 813 The problem Autoconf addresses is that the world is a mess. After 814all, you are using Autoconf in order to have your package compile 815easily on all sorts of different systems, some of them being extremely 816hostile. Autoconf itself bears the price for these differences: 817`configure' must run on all those systems, and thus `configure' must 818limit itself to their lowest common denominator of features. 819 820 Naturally, you might then think of shell scripts; who needs 821`autoconf'? A set of properly written shell functions is enough to 822make it easy to write `configure' scripts by hand. Sigh! 823Unfortunately, shell functions do not belong to the least common 824denominator; therefore, where you would like to define a function and 825use it ten times, you would instead need to copy its body ten times. 826 827 So, what is really needed is some kind of compiler, `autoconf', that 828takes an Autoconf program, `configure.ac', and transforms it into a 829portable shell script, `configure'. 830 831 How does `autoconf' perform this task? 832 833 There are two obvious possibilities: creating a brand new language or 834extending an existing one. The former option is attractive: all sorts 835of optimizations could easily be implemented in the compiler and many 836rigorous checks could be performed on the Autoconf program (e.g., 837rejecting any non-portable construct). Alternatively, you can extend 838an existing language, such as the `sh' (Bourne shell) language. 839 840 Autoconf does the latter: it is a layer on top of `sh'. It was 841therefore most convenient to implement `autoconf' as a macro expander: 842a program that repeatedly performs "macro expansions" on text input, 843replacing macro calls with macro bodies and producing a pure `sh' 844script in the end. Instead of implementing a dedicated Autoconf macro 845expander, it is natural to use an existing general-purpose macro 846language, such as M4, and implement the extensions as a set of M4 847macros. 848 849 850File: autoconf.info, Node: Autoconf Language, Next: configure.ac Layout, Prev: Shell Script Compiler, Up: Writing configure.ac 851 8523.1.2 The Autoconf Language 853--------------------------- 854 855The Autoconf language differs from many other computer languages 856because it treats actual code the same as plain text. Whereas in C, 857for instance, data and instructions have different syntactic status, in 858Autoconf their status is rigorously the same. Therefore, we need a 859means to distinguish literal strings from text to be expanded: 860quotation. 861 862 When calling macros that take arguments, there must not be any white 863space between the macro name and the open parenthesis. Arguments should 864be enclosed within the M4 quote characters `[' and `]', and be 865separated by commas. Any leading blanks or newlines in arguments are 866ignored, unless they are quoted. You should always quote an argument 867that might contain a macro name, comma, parenthesis, or a leading blank 868or newline. This rule applies recursively for every macro call, 869including macros called from other macros. 870 871 For instance: 872 873 AC_CHECK_HEADER([stdio.h], 874 [AC_DEFINE([HAVE_STDIO_H], [1], 875 [Define to 1 if you have <stdio.h>.])], 876 [AC_MSG_ERROR([Sorry, can't do anything for you])]) 877 878is quoted properly. You may safely simplify its quotation to: 879 880 AC_CHECK_HEADER([stdio.h], 881 [AC_DEFINE([HAVE_STDIO_H], 1, 882 [Define to 1 if you have <stdio.h>.])], 883 [AC_MSG_ERROR([Sorry, can't do anything for you])]) 884 885because `1' cannot contain a macro call. Here, the argument of 886`AC_MSG_ERROR' must be quoted; otherwise, its comma would be 887interpreted as an argument separator. Also, the second and third 888arguments of `AC_CHECK_HEADER' must be quoted, since they contain macro 889calls. The three arguments `HAVE_STDIO_H', `stdio.h', and `Define to 1 890if you have <stdio.h>.' do not need quoting, but if you unwisely 891defined a macro with a name like `Define' or `stdio' then they would 892need quoting. Cautious Autoconf users would keep the quotes, but many 893Autoconf users find such precautions annoying, and would rewrite the 894example as follows: 895 896 AC_CHECK_HEADER(stdio.h, 897 [AC_DEFINE(HAVE_STDIO_H, 1, 898 [Define to 1 if you have <stdio.h>.])], 899 [AC_MSG_ERROR([Sorry, can't do anything for you])]) 900 901This is safe, so long as you adopt good naming conventions and do not 902define macros with names like `HAVE_STDIO_H', `stdio', or `h'. Though 903it is also safe here to omit the quotes around `Define to 1 if you have 904<stdio.h>.' this is not recommended, as message strings are more likely 905to inadvertently contain commas. 906 907 The following example is wrong and dangerous, as it is underquoted: 908 909 AC_CHECK_HEADER(stdio.h, 910 AC_DEFINE(HAVE_STDIO_H, 1, 911 Define to 1 if you have <stdio.h>.), 912 AC_MSG_ERROR([Sorry, can't do anything for you])) 913 914 In other cases, you may have to use text that also resembles a macro 915call. You must quote that text even when it is not passed as a macro 916argument: 917 918 echo "Hard rock was here! --[AC_DC]" 919 920which results in: 921 922 echo "Hard rock was here! --AC_DC" 923 924When you use the same text in a macro argument, you must therefore have 925an extra quotation level (since one is stripped away by the macro 926substitution). In general, then, it is a good idea to _use double 927quoting for all literal string arguments_: 928 929 AC_MSG_WARN([[AC_DC stinks --Iron Maiden]]) 930 931 You are now able to understand one of the constructs of Autoconf that 932has been continually misunderstood... The rule of thumb is that 933_whenever you expect macro expansion, expect quote expansion_; i.e., 934expect one level of quotes to be lost. For instance: 935 936 AC_COMPILE_IFELSE([char b[10];], [], [AC_MSG_ERROR([you lose])]) 937 938is incorrect: here, the first argument of `AC_COMPILE_IFELSE' is `char 939b[10];' and is expanded once, which results in `char b10;'. (There was 940an idiom common in Autoconf's past to address this issue via the M4 941`changequote' primitive, but do not use it!) Let's take a closer look: 942the author meant the first argument to be understood as a literal, and 943therefore it must be quoted twice: 944 945 AC_COMPILE_IFELSE([[char b[10];]], [], [AC_MSG_ERROR([you lose])]) 946 947Voila`, you actually produce `char b[10];' this time! 948 949 On the other hand, descriptions (e.g., the last parameter of 950`AC_DEFINE' or `AS_HELP_STRING') are not literals--they are subject to 951line breaking, for example--and should not be double quoted. Even if 952these descriptions are short and are not actually broken, double 953quoting them yields weird results. 954 955 Some macros take optional arguments, which this documentation 956represents as [ARG] (not to be confused with the quote characters). 957You may just leave them empty, or use `[]' to make the emptiness of the 958argument explicit, or you may simply omit the trailing commas. The 959three lines below are equivalent: 960 961 AC_CHECK_HEADERS([stdio.h], [], [], []) 962 AC_CHECK_HEADERS([stdio.h],,,) 963 AC_CHECK_HEADERS([stdio.h]) 964 965 It is best to put each macro call on its own line in `configure.ac'. 966Most of the macros don't add extra newlines; they rely on the newline 967after the macro call to terminate the commands. This approach makes 968the generated `configure' script a little easier to read by not 969inserting lots of blank lines. It is generally safe to set shell 970variables on the same line as a macro call, because the shell allows 971assignments without intervening newlines. 972 973 You can include comments in `configure.ac' files by starting them 974with the `#'. For example, it is helpful to begin `configure.ac' files 975with a line like this: 976 977 # Process this file with autoconf to produce a configure script. 978 979 980File: autoconf.info, Node: configure.ac Layout, Prev: Autoconf Language, Up: Writing configure.ac 981 9823.1.3 Standard `configure.ac' Layout 983------------------------------------ 984 985The order in which `configure.ac' calls the Autoconf macros is not 986important, with a few exceptions. Every `configure.ac' must contain a 987call to `AC_INIT' before the checks, and a call to `AC_OUTPUT' at the 988end (*note Output::). Additionally, some macros rely on other macros 989having been called first, because they check previously set values of 990some variables to decide what to do. These macros are noted in the 991individual descriptions (*note Existing Tests::), and they also warn 992you when `configure' is created if they are called out of order. 993 994 To encourage consistency, here is a suggested order for calling the 995Autoconf macros. Generally speaking, the things near the end of this 996list are those that could depend on things earlier in it. For example, 997library functions could be affected by types and libraries. 998 999 Autoconf requirements 1000 `AC_INIT(PACKAGE, VERSION, BUG-REPORT-ADDRESS)' 1001 information on the package 1002 checks for programs 1003 checks for libraries 1004 checks for header files 1005 checks for types 1006 checks for structures 1007 checks for compiler characteristics 1008 checks for library functions 1009 checks for system services 1010 `AC_CONFIG_FILES([FILE...])' 1011 `AC_OUTPUT' 1012 1013 1014File: autoconf.info, Node: autoscan Invocation, Next: ifnames Invocation, Prev: Writing configure.ac, Up: Making configure Scripts 1015 10163.2 Using `autoscan' to Create `configure.ac' 1017============================================= 1018 1019The `autoscan' program can help you create and/or maintain a 1020`configure.ac' file for a software package. `autoscan' examines source 1021files in the directory tree rooted at a directory given as a command 1022line argument, or the current directory if none is given. It searches 1023the source files for common portability problems and creates a file 1024`configure.scan' which is a preliminary `configure.ac' for that 1025package, and checks a possibly existing `configure.ac' for completeness. 1026 1027 When using `autoscan' to create a `configure.ac', you should 1028manually examine `configure.scan' before renaming it to `configure.ac'; 1029it probably needs some adjustments. Occasionally, `autoscan' outputs a 1030macro in the wrong order relative to another macro, so that `autoconf' 1031produces a warning; you need to move such macros manually. Also, if 1032you want the package to use a configuration header file, you must add a 1033call to `AC_CONFIG_HEADERS' (*note Configuration Headers::). You might 1034also have to change or add some `#if' directives to your program in 1035order to make it work with Autoconf (*note ifnames Invocation::, for 1036information about a program that can help with that job). 1037 1038 When using `autoscan' to maintain a `configure.ac', simply consider 1039adding its suggestions. The file `autoscan.log' contains detailed 1040information on why a macro is requested. 1041 1042 `autoscan' uses several data files (installed along with Autoconf) 1043to determine which macros to output when it finds particular symbols in 1044a package's source files. These data files all have the same format: 1045each line consists of a symbol, one or more blanks, and the Autoconf 1046macro to output if that symbol is encountered. Lines starting with `#' 1047are comments. 1048 1049 `autoscan' accepts the following options: 1050 1051`--help' 1052`-h' 1053 Print a summary of the command line options and exit. 1054 1055`--version' 1056`-V' 1057 Print the version number of Autoconf and exit. 1058 1059`--verbose' 1060`-v' 1061 Print the names of the files it examines and the potentially 1062 interesting symbols it finds in them. This output can be 1063 voluminous. 1064 1065`--include=DIR' 1066`-I DIR' 1067 Append DIR to the include path. Multiple invocations accumulate. 1068 1069`--prepend-include=DIR' 1070 1071`-B DIR' 1072 Prepend DIR to the include path. Multiple invocations accumulate. 1073 1074 1075File: autoconf.info, Node: ifnames Invocation, Next: autoconf Invocation, Prev: autoscan Invocation, Up: Making configure Scripts 1076 10773.3 Using `ifnames' to List Conditionals 1078======================================== 1079 1080`ifnames' can help you write `configure.ac' for a software package. It 1081prints the identifiers that the package already uses in C preprocessor 1082conditionals. If a package has already been set up to have some 1083portability, `ifnames' can thus help you figure out what its 1084`configure' needs to check for. It may help fill in some gaps in a 1085`configure.ac' generated by `autoscan' (*note autoscan Invocation::). 1086 1087 `ifnames' scans all of the C source files named on the command line 1088(or the standard input, if none are given) and writes to the standard 1089output a sorted list of all the identifiers that appear in those files 1090in `#if', `#elif', `#ifdef', or `#ifndef' directives. It prints each 1091identifier on a line, followed by a space-separated list of the files 1092in which that identifier occurs. 1093 1094`ifnames' accepts the following options: 1095 1096`--help' 1097`-h' 1098 Print a summary of the command line options and exit. 1099 1100`--version' 1101`-V' 1102 Print the version number of Autoconf and exit. 1103 1104 1105File: autoconf.info, Node: autoconf Invocation, Next: autoreconf Invocation, Prev: ifnames Invocation, Up: Making configure Scripts 1106 11073.4 Using `autoconf' to Create `configure' 1108========================================== 1109 1110To create `configure' from `configure.ac', run the `autoconf' program 1111with no arguments. `autoconf' processes `configure.ac' with the M4 1112macro processor, using the Autoconf macros. If you give `autoconf' an 1113argument, it reads that file instead of `configure.ac' and writes the 1114configuration script to the standard output instead of to `configure'. 1115If you give `autoconf' the argument `-', it reads from the standard 1116input instead of `configure.ac' and writes the configuration script to 1117the standard output. 1118 1119 The Autoconf macros are defined in several files. Some of the files 1120are distributed with Autoconf; `autoconf' reads them first. Then it 1121looks for the optional file `acsite.m4' in the directory that contains 1122the distributed Autoconf macro files, and for the optional file 1123`aclocal.m4' in the current directory. Those files can contain your 1124site's or the package's own Autoconf macro definitions (*note Writing 1125Autoconf Macros::, for more information). If a macro is defined in 1126more than one of the files that `autoconf' reads, the last definition 1127it reads overrides the earlier ones. 1128 1129 `autoconf' accepts the following options: 1130 1131`--help' 1132`-h' 1133 Print a summary of the command line options and exit. 1134 1135`--version' 1136`-V' 1137 Print the version number of Autoconf and exit. 1138 1139`--verbose' 1140`-v' 1141 Report processing steps. 1142 1143`--debug' 1144`-d' 1145 Don't remove the temporary files. 1146 1147`--force' 1148`-f' 1149 Remake `configure' even if newer than its input files. 1150 1151`--include=DIR' 1152`-I DIR' 1153 Append DIR to the include path. Multiple invocations accumulate. 1154 1155`--prepend-include=DIR' 1156 1157`-B DIR' 1158 Prepend DIR to the include path. Multiple invocations accumulate. 1159 1160`--output=FILE' 1161`-o FILE' 1162 Save output (script or trace) to FILE. The file `-' stands for 1163 the standard output. 1164 1165`--warnings=CATEGORY' 1166`-W CATEGORY' 1167 Report the warnings related to CATEGORY (which can actually be a 1168 comma separated list). *Note Reporting Messages::, macro 1169 `AC_DIAGNOSE', for a comprehensive list of categories. Special 1170 values include: 1171 1172 `all' 1173 report all the warnings 1174 1175 `none' 1176 report none 1177 1178 `error' 1179 treats warnings as errors 1180 1181 `no-CATEGORY' 1182 disable warnings falling into CATEGORY 1183 1184 Warnings about `syntax' are enabled by default, and the environment 1185 variable `WARNINGS', a comma separated list of categories, is 1186 honored as well. Passing `-W CATEGORY' actually behaves as if you 1187 had passed `--warnings=syntax,$WARNINGS,CATEGORY'. If you want to 1188 disable the defaults and `WARNINGS', but (for example) enable the 1189 warnings about obsolete constructs, you would use `-W 1190 none,obsolete'. 1191 1192 Because `autoconf' uses `autom4te' behind the scenes, it displays 1193 a back trace for errors, but not for warnings; if you want them, 1194 just pass `-W error'. *Note autom4te Invocation::, for some 1195 examples. 1196 1197`--trace=MACRO[:FORMAT]' 1198`-t MACRO[:FORMAT]' 1199 Do not create the `configure' script, but list the calls to MACRO 1200 according to the FORMAT. Multiple `--trace' arguments can be used 1201 to list several macros. Multiple `--trace' arguments for a single 1202 macro are not cumulative; instead, you should just make FORMAT as 1203 long as needed. 1204 1205 The FORMAT is a regular string, with newlines if desired, and 1206 several special escape codes. It defaults to `$f:$l:$n:$%'; see 1207 *Note autom4te Invocation::, for details on the FORMAT. 1208 1209`--initialization' 1210`-i' 1211 By default, `--trace' does not trace the initialization of the 1212 Autoconf macros (typically the `AC_DEFUN' definitions). This 1213 results in a noticeable speedup, but can be disabled by this 1214 option. 1215 1216 It is often necessary to check the content of a `configure.ac' file, 1217but parsing it yourself is extremely fragile and error-prone. It is 1218suggested that you rely upon `--trace' to scan `configure.ac'. For 1219instance, to find the list of variables that are substituted, use: 1220 1221 $ autoconf -t AC_SUBST 1222 configure.ac:2:AC_SUBST:ECHO_C 1223 configure.ac:2:AC_SUBST:ECHO_N 1224 configure.ac:2:AC_SUBST:ECHO_T 1225 More traces deleted 1226 1227The example below highlights the difference between `$@', `$*', and 1228`$%'. 1229 1230 $ cat configure.ac 1231 AC_DEFINE(This, is, [an 1232 [example]]) 1233 $ autoconf -t 'AC_DEFINE:@: $@ 1234 *: $* 1235 %: $%' 1236 @: [This],[is],[an 1237 [example]] 1238 *: This,is,an 1239 [example] 1240 %: This:is:an [example] 1241 1242The FORMAT gives you a lot of freedom: 1243 1244 $ autoconf -t 'AC_SUBST:$$ac_subst{"$1"} = "$f:$l";' 1245 $ac_subst{"ECHO_C"} = "configure.ac:2"; 1246 $ac_subst{"ECHO_N"} = "configure.ac:2"; 1247 $ac_subst{"ECHO_T"} = "configure.ac:2"; 1248 More traces deleted 1249 1250A long SEPARATOR can be used to improve the readability of complex 1251structures, and to ease their parsing (for instance when no single 1252character is suitable as a separator): 1253 1254 $ autoconf -t 'AM_MISSING_PROG:${|:::::|}*' 1255 ACLOCAL|:::::|aclocal|:::::|$missing_dir 1256 AUTOCONF|:::::|autoconf|:::::|$missing_dir 1257 AUTOMAKE|:::::|automake|:::::|$missing_dir 1258 More traces deleted 1259 1260 1261File: autoconf.info, Node: autoreconf Invocation, Prev: autoconf Invocation, Up: Making configure Scripts 1262 12633.5 Using `autoreconf' to Update `configure' Scripts 1264==================================================== 1265 1266Installing the various components of the GNU Build System can be 1267tedious: running `autopoint' for Gettext, `automake' for `Makefile.in' 1268etc. in each directory. It may be needed either because some tools 1269such as `automake' have been updated on your system, or because some of 1270the sources such as `configure.ac' have been updated, or finally, 1271simply in order to install the GNU Build System in a fresh tree. 1272 1273 `autoreconf' runs `autoconf', `autoheader', `aclocal', `automake', 1274`libtoolize', and `autopoint' (when appropriate) repeatedly to update 1275the GNU Build System in the specified directories and their 1276subdirectories (*note Subdirectories::). By default, it only remakes 1277those files that are older than their sources. 1278 1279 If you install a new version of some tool, you can make `autoreconf' 1280remake _all_ of the files by giving it the `--force' option. 1281 1282 *Note Automatic Remaking::, for Make rules to automatically remake 1283`configure' scripts when their source files change. That method 1284handles the timestamps of configuration header templates properly, but 1285does not pass `--autoconf-dir=DIR' or `--localdir=DIR'. 1286 1287 Gettext supplies the `autopoint' command to add translation 1288infrastructure to a source package. If you use `autopoint', your 1289`configure.ac' should invoke both `AM_GNU_GETTEXT' and 1290`AM_GNU_GETTEXT_VERSION(GETTEXT-VERSION)'. *Note Invoking the 1291`autopoint' Program: (gettext)autopoint Invocation, for further details. 1292 1293`autoreconf' accepts the following options: 1294 1295`--help' 1296`-h' 1297 Print a summary of the command line options and exit. 1298 1299`--version' 1300`-V' 1301 Print the version number of Autoconf and exit. 1302 1303`--verbose' 1304 Print the name of each directory `autoreconf' examines and the 1305 commands it runs. If given two or more times, pass `--verbose' to 1306 subordinate tools that support it. 1307 1308`--debug' 1309`-d' 1310 Don't remove the temporary files. 1311 1312`--force' 1313`-f' 1314 Remake even `configure' scripts and configuration headers that are 1315 newer than their input files (`configure.ac' and, if present, 1316 `aclocal.m4'). 1317 1318`--install' 1319`-i' 1320 Install the missing auxiliary files in the package. By default, 1321 files are copied; this can be changed with `--symlink'. 1322 1323 If deemed appropriate, this option triggers calls to `automake 1324 --add-missing', `libtoolize', `autopoint', etc. 1325 1326`--no-recursive' 1327 Do not rebuild files in subdirectories to configure (see *Note 1328 Subdirectories::, macro `AC_CONFIG_SUBDIRS'). 1329 1330`--symlink' 1331`-s' 1332 When used with `--install', install symbolic links to the missing 1333 auxiliary files instead of copying them. 1334 1335`--make' 1336`-m' 1337 When the directories were configured, update the configuration by 1338 running `./config.status --recheck && ./config.status', and then 1339 run `make'. 1340 1341`--include=DIR' 1342`-I DIR' 1343 Append DIR to the include path. Multiple invocations accumulate. 1344 Passed on to `autoconf' and `autoheader' internally. 1345 1346`--prepend-include=DIR' 1347 1348`-B DIR' 1349 Prepend DIR to the include path. Multiple invocations accumulate. 1350 Passed on to `autoconf' and `autoheader' internally. 1351 1352`--warnings=CATEGORY' 1353`-W CATEGORY' 1354 Report the warnings related to CATEGORY (which can actually be a 1355 comma separated list). 1356 1357 `cross' 1358 related to cross compilation issues. 1359 1360 `obsolete' 1361 report the uses of obsolete constructs. 1362 1363 `portability' 1364 portability issues 1365 1366 `syntax' 1367 dubious syntactic constructs. 1368 1369 `all' 1370 report all the warnings 1371 1372 `none' 1373 report none 1374 1375 `error' 1376 treats warnings as errors 1377 1378 `no-CATEGORY' 1379 disable warnings falling into CATEGORY 1380 1381 Warnings about `syntax' are enabled by default, and the environment 1382 variable `WARNINGS', a comma separated list of categories, is 1383 honored as well. Passing `-W CATEGORY' actually behaves as if you 1384 had passed `--warnings=syntax,$WARNINGS,CATEGORY'. If you want to 1385 disable the defaults and `WARNINGS', but (for example) enable the 1386 warnings about obsolete constructs, you would use `-W 1387 none,obsolete'. 1388 1389 If you want `autoreconf' to pass flags that are not listed here on 1390to `aclocal', set `ACLOCAL_AMFLAGS' in your `Makefile.am'. 1391 1392 1393File: autoconf.info, Node: Setup, Next: Existing Tests, Prev: Making configure Scripts, Up: Top 1394 13954 Initialization and Output Files 1396********************************* 1397 1398Autoconf-generated `configure' scripts need some information about how 1399to initialize, such as how to find the package's source files and about 1400the output files to produce. The following sections describe the 1401initialization and the creation of output files. 1402 1403* Menu: 1404 1405* Initializing configure:: Option processing etc. 1406* Notices:: Copyright, version numbers in `configure' 1407* Input:: Where Autoconf should find files 1408* Output:: Outputting results from the configuration 1409* Configuration Actions:: Preparing the output based on results 1410* Configuration Files:: Creating output files 1411* Makefile Substitutions:: Using output variables in makefiles 1412* Configuration Headers:: Creating a configuration header file 1413* Configuration Commands:: Running arbitrary instantiation commands 1414* Configuration Links:: Links depending on the configuration 1415* Subdirectories:: Configuring independent packages together 1416* Default Prefix:: Changing the default installation prefix 1417 1418 1419File: autoconf.info, Node: Initializing configure, Next: Notices, Up: Setup 1420 14214.1 Initializing `configure' 1422============================ 1423 1424Every `configure' script must call `AC_INIT' before doing anything 1425else. The only other required macro is `AC_OUTPUT' (*note Output::). 1426 1427 -- Macro: AC_INIT (PACKAGE, VERSION, [BUG-REPORT], [TARNAME]) 1428 Process any command-line arguments and perform various 1429 initializations and verifications. 1430 1431 Set the name of the PACKAGE and its VERSION. These are typically 1432 used in `--version' support, including that of `configure'. The 1433 optional argument BUG-REPORT should be the email to which users 1434 should send bug reports. The package TARNAME differs from 1435 PACKAGE: the latter designates the full package name (e.g., `GNU 1436 Autoconf'), while the former is meant for distribution tar ball 1437 names (e.g., `autoconf'). It defaults to PACKAGE with `GNU ' 1438 stripped, lower-cased, and all characters other than alphanumerics 1439 and underscores are changed to `-'. 1440 1441 It is preferable that the arguments of `AC_INIT' be static, i.e., 1442 there should not be any shell computation, but they can be 1443 computed by M4. 1444 1445 The following M4 macros (e.g., `AC_PACKAGE_NAME'), output variables 1446 (e.g., `PACKAGE_NAME'), and preprocessor symbols (e.g., 1447 `PACKAGE_NAME') are defined by `AC_INIT': 1448 1449 `AC_PACKAGE_NAME', `PACKAGE_NAME' 1450 Exactly PACKAGE. 1451 1452 `AC_PACKAGE_TARNAME', `PACKAGE_TARNAME' 1453 Exactly TARNAME. 1454 1455 `AC_PACKAGE_VERSION', `PACKAGE_VERSION' 1456 Exactly VERSION. 1457 1458 `AC_PACKAGE_STRING', `PACKAGE_STRING' 1459 Exactly `PACKAGE VERSION'. 1460 1461 `AC_PACKAGE_BUGREPORT', `PACKAGE_BUGREPORT' 1462 Exactly BUG-REPORT. 1463 1464 If your `configure' script does its own option processing, it should 1465inspect `$@' or `$*' immediately after calling `AC_INIT', because other 1466Autoconf macros liberally use the `set' command to process strings, and 1467this has the side effect of updating `$@' and `$*'. However, we 1468suggest that you use standard macros like `AC_ARG_ENABLE' instead of 1469attempting to implement your own option processing. *Note Site 1470Configuration::. 1471 1472 1473File: autoconf.info, Node: Notices, Next: Input, Prev: Initializing configure, Up: Setup 1474 14754.2 Notices in `configure' 1476========================== 1477 1478The following macros manage version numbers for `configure' scripts. 1479Using them is optional. 1480 1481 -- Macro: AC_PREREQ (VERSION) 1482 Ensure that a recent enough version of Autoconf is being used. If 1483 the version of Autoconf being used to create `configure' is 1484 earlier than VERSION, print an error message to the standard error 1485 output and exit with failure (exit status is 63). For example: 1486 1487 AC_PREREQ([2.61]) 1488 1489 This macro is the only macro that may be used before `AC_INIT', but 1490 for consistency, you are invited not to do so. 1491 1492 -- Macro: AC_COPYRIGHT (COPYRIGHT-NOTICE) 1493 State that, in addition to the Free Software Foundation's 1494 copyright on the Autoconf macros, parts of your `configure' are 1495 covered by the COPYRIGHT-NOTICE. 1496 1497 The COPYRIGHT-NOTICE shows up in both the head of `configure' and 1498 in `configure --version'. 1499 1500 -- Macro: AC_REVISION (REVISION-INFO) 1501 Copy revision stamp REVISION-INFO into the `configure' script, 1502 with any dollar signs or double-quotes removed. This macro lets 1503 you put a revision stamp from `configure.ac' into `configure' 1504 without RCS or CVS changing it when you check in `configure'. 1505 That way, you can determine easily which revision of 1506 `configure.ac' a particular `configure' corresponds to. 1507 1508 For example, this line in `configure.ac': 1509 1510 AC_REVISION([$Revision: 1.30 $]) 1511 1512 produces this in `configure': 1513 1514 #!/bin/sh 1515 # From configure.ac Revision: 1.30 1516 1517 1518File: autoconf.info, Node: Input, Next: Output, Prev: Notices, Up: Setup 1519 15204.3 Finding `configure' Input 1521============================= 1522 1523 -- Macro: AC_CONFIG_SRCDIR (UNIQUE-FILE-IN-SOURCE-DIR) 1524 UNIQUE-FILE-IN-SOURCE-DIR is some file that is in the package's 1525 source directory; `configure' checks for this file's existence to 1526 make sure that the directory that it is told contains the source 1527 code in fact does. Occasionally people accidentally specify the 1528 wrong directory with `--srcdir'; this is a safety check. *Note 1529 configure Invocation::, for more information. 1530 1531 Packages that do manual configuration or use the `install' program 1532might need to tell `configure' where to find some other shell scripts 1533by calling `AC_CONFIG_AUX_DIR', though the default places it looks are 1534correct for most cases. 1535 1536 -- Macro: AC_CONFIG_AUX_DIR (DIR) 1537 Use the auxiliary build tools (e.g., `install-sh', `config.sub', 1538 `config.guess', Cygnus `configure', Automake and Libtool scripts, 1539 etc.) that are in directory DIR. These are auxiliary files used 1540 in configuration. DIR can be either absolute or relative to 1541 `SRCDIR'. The default is `SRCDIR' or `SRCDIR/..' or 1542 `SRCDIR/../..', whichever is the first that contains `install-sh'. 1543 The other files are not checked for, so that using 1544 `AC_PROG_INSTALL' does not automatically require distributing the 1545 other auxiliary files. It checks for `install.sh' also, but that 1546 name is obsolete because some `make' have a rule that creates 1547 `install' from it if there is no makefile. 1548 1549 The auxiliary directory is commonly named `build-aux'. If you 1550 need portability to DOS variants, do not name the auxiliary 1551 directory `aux'. *Note File System Conventions::. 1552 1553 -- Macro: AC_REQUIRE_AUX_FILE (FILE) 1554 Declares that FILE is expected in the directory defined above. In 1555 Autoconf proper, this macro does nothing: its sole purpose is to be 1556 traced by third-party tools to produce a list of expected auxiliary 1557 files. For instance it is called by macros like `AC_PROG_INSTALL' 1558 (*note Particular Programs::) or `AC_CANONICAL_BUILD' (*note 1559 Canonicalizing::) to register the auxiliary files they need. 1560 1561 Similarly, packages that use `aclocal' should declare where local 1562macros can be found using `AC_CONFIG_MACRO_DIR'. 1563 1564 -- Macro: AC_CONFIG_MACRO_DIR (DIR) 1565 Specify DIR as the location of additional local Autoconf macros. 1566 This macro is intended for use by future versions of commands like 1567 `autoreconf' that trace macro calls. It should be called directly 1568 from `configure.ac' so that tools that install macros for 1569 `aclocal' can find the macros' declarations. 1570 1571 1572File: autoconf.info, Node: Output, Next: Configuration Actions, Prev: Input, Up: Setup 1573 15744.4 Outputting Files 1575==================== 1576 1577Every Autoconf script, e.g., `configure.ac', should finish by calling 1578`AC_OUTPUT'. That is the macro that generates and runs 1579`config.status', which in turn creates the makefiles and any other 1580files resulting from configuration. This is the only required macro 1581besides `AC_INIT' (*note Input::). 1582 1583 -- Macro: AC_OUTPUT 1584 Generate `config.status' and launch it. Call this macro once, at 1585 the end of `configure.ac'. 1586 1587 `config.status' performs all the configuration actions: all the 1588 output files (see *Note Configuration Files::, macro 1589 `AC_CONFIG_FILES'), header files (see *Note Configuration 1590 Headers::, macro `AC_CONFIG_HEADERS'), commands (see *Note 1591 Configuration Commands::, macro `AC_CONFIG_COMMANDS'), links (see 1592 *Note Configuration Links::, macro `AC_CONFIG_LINKS'), 1593 subdirectories to configure (see *Note Subdirectories::, macro 1594 `AC_CONFIG_SUBDIRS') are honored. 1595 1596 The location of your `AC_OUTPUT' invocation is the exact point 1597 where configuration actions are taken: any code afterwards is 1598 executed by `configure' once `config.status' was run. If you want 1599 to bind actions to `config.status' itself (independently of 1600 whether `configure' is being run), see *Note Running Arbitrary 1601 Configuration Commands: Configuration Commands. 1602 1603 Historically, the usage of `AC_OUTPUT' was somewhat different. 1604*Note Obsolete Macros::, for a description of the arguments that 1605`AC_OUTPUT' used to support. 1606 1607 If you run `make' in subdirectories, you should run it using the 1608`make' variable `MAKE'. Most versions of `make' set `MAKE' to the name 1609of the `make' program plus any options it was given. (But many do not 1610include in it the values of any variables set on the command line, so 1611those are not passed on automatically.) Some old versions of `make' do 1612not set this variable. The following macro allows you to use it even 1613with those versions. 1614 1615 -- Macro: AC_PROG_MAKE_SET 1616 If the Make command, `$MAKE' if set or else `make', predefines 1617 `$(MAKE)', define output variable `SET_MAKE' to be empty. 1618 Otherwise, define `SET_MAKE' to a macro definition that sets 1619 `$(MAKE)', such as `MAKE=make'. Calls `AC_SUBST' for `SET_MAKE'. 1620 1621 If you use this macro, place a line like this in each `Makefile.in' 1622that runs `MAKE' on other directories: 1623 1624 @SET_MAKE@ 1625 1626 1627File: autoconf.info, Node: Configuration Actions, Next: Configuration Files, Prev: Output, Up: Setup 1628 16294.5 Performing Configuration Actions 1630==================================== 1631 1632`configure' is designed so that it appears to do everything itself, but 1633there is actually a hidden slave: `config.status'. `configure' is in 1634charge of examining your system, but it is `config.status' that 1635actually takes the proper actions based on the results of `configure'. 1636The most typical task of `config.status' is to _instantiate_ files. 1637 1638 This section describes the common behavior of the four standard 1639instantiating macros: `AC_CONFIG_FILES', `AC_CONFIG_HEADERS', 1640`AC_CONFIG_COMMANDS' and `AC_CONFIG_LINKS'. They all have this 1641prototype: 1642 1643 AC_CONFIG_FOOS(TAG..., [COMMANDS], [INIT-CMDS]) 1644 1645where the arguments are: 1646 1647TAG... 1648 A blank-or-newline-separated list of tags, which are typically the 1649 names of the files to instantiate. 1650 1651 You are encouraged to use literals as TAGS. In particular, you 1652 should avoid 1653 1654 ... && my_foos="$my_foos fooo" 1655 ... && my_foos="$my_foos foooo" 1656 AC_CONFIG_FOOS([$my_foos]) 1657 1658 and use this instead: 1659 1660 ... && AC_CONFIG_FOOS([fooo]) 1661 ... && AC_CONFIG_FOOS([foooo]) 1662 1663 The macros `AC_CONFIG_FILES' and `AC_CONFIG_HEADERS' use special 1664 TAG values: they may have the form `OUTPUT' or `OUTPUT:INPUTS'. 1665 The file OUTPUT is instantiated from its templates, INPUTS 1666 (defaulting to `OUTPUT.in'). 1667 1668 `AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk)]', for 1669 example, asks for the creation of the file `Makefile' that 1670 contains the expansion of the output variables in the 1671 concatenation of `boiler/top.mk' and `boiler/bot.mk'. 1672 1673 The special value `-' might be used to denote the standard output 1674 when used in OUTPUT, or the standard input when used in the 1675 INPUTS. You most probably don't need to use this in 1676 `configure.ac', but it is convenient when using the command line 1677 interface of `./config.status', see *Note config.status 1678 Invocation::, for more details. 1679 1680 The INPUTS may be absolute or relative file names. In the latter 1681 case they are first looked for in the build tree, and then in the 1682 source tree. 1683 1684COMMANDS 1685 Shell commands output literally into `config.status', and 1686 associated with a tag that the user can use to tell `config.status' 1687 which the commands to run. The commands are run each time a TAG 1688 request is given to `config.status', typically each time the file 1689 `TAG' is created. 1690 1691 The variables set during the execution of `configure' are _not_ 1692 available here: you first need to set them via the INIT-CMDS. 1693 Nonetheless the following variables are precomputed: 1694 1695 `srcdir' 1696 The name of the top source directory, assuming that the 1697 working directory is the top build directory. This is what 1698 the `configure' option `--srcdir' sets. 1699 1700 `ac_top_srcdir' 1701 The name of the top source directory, assuming that the 1702 working directory is the current build directory. 1703 1704 `ac_top_build_prefix' 1705 The name of the top build directory, assuming that the working 1706 directory is the current build directory. It can be empty, 1707 or else ends with a slash, so that you may concatenate it. 1708 1709 `ac_srcdir' 1710 The name of the corresponding source directory, assuming that 1711 the working directory is the current build directory. 1712 1713 The "current" directory refers to the directory (or 1714 pseudo-directory) containing the input part of TAGS. For 1715 instance, running 1716 1717 AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [...], [...]) 1718 1719 with `--srcdir=../package' produces the following values: 1720 1721 # Argument of --srcdir 1722 srcdir='../package' 1723 # Reversing deep/dir 1724 ac_top_build_prefix='../../' 1725 # Concatenation of $ac_top_build_prefix and srcdir 1726 ac_top_srcdir='../../../package' 1727 # Concatenation of $ac_top_srcdir and deep/dir 1728 ac_srcdir='../../../package/deep/dir' 1729 1730 independently of `in/in.in'. 1731 1732INIT-CMDS 1733 Shell commands output _unquoted_ near the beginning of 1734 `config.status', and executed each time `config.status' runs 1735 (regardless of the tag). Because they are unquoted, for example, 1736 `$var' is output as the value of `var'. INIT-CMDS is typically 1737 used by `configure' to give `config.status' some variables it 1738 needs to run the COMMANDS. 1739 1740 You should be extremely cautious in your variable names: all the 1741 INIT-CMDS share the same name space and may overwrite each other 1742 in unpredictable ways. Sorry.... 1743 1744 All these macros can be called multiple times, with different TAG 1745values, of course! 1746 1747 1748File: autoconf.info, Node: Configuration Files, Next: Makefile Substitutions, Prev: Configuration Actions, Up: Setup 1749 17504.6 Creating Configuration Files 1751================================ 1752 1753Be sure to read the previous section, *Note Configuration Actions::. 1754 1755 -- Macro: AC_CONFIG_FILES (FILE..., [CMDS], [INIT-CMDS]) 1756 Make `AC_OUTPUT' create each `FILE' by copying an input file (by 1757 default `FILE.in'), substituting the output variable values. This 1758 macro is one of the instantiating macros; see *Note Configuration 1759 Actions::. *Note Makefile Substitutions::, for more information 1760 on using output variables. *Note Setting Output Variables::, for 1761 more information on creating them. This macro creates the 1762 directory that the file is in if it doesn't exist. Usually, 1763 makefiles are created this way, but other files, such as 1764 `.gdbinit', can be specified as well. 1765 1766 Typical calls to `AC_CONFIG_FILES' look like this: 1767 1768 AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile]) 1769 AC_CONFIG_FILES([autoconf], [chmod +x autoconf]) 1770 1771 You can override an input file name by appending to FILE a 1772 colon-separated list of input files. Examples: 1773 1774 AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk] 1775 [lib/Makefile:boiler/lib.mk]) 1776 1777 Doing this allows you to keep your file names acceptable to DOS 1778 variants, or to prepend and/or append boilerplate to the file. 1779 1780 1781File: autoconf.info, Node: Makefile Substitutions, Next: Configuration Headers, Prev: Configuration Files, Up: Setup 1782 17834.7 Substitutions in Makefiles 1784============================== 1785 1786Each subdirectory in a distribution that contains something to be 1787compiled or installed should come with a file `Makefile.in', from which 1788`configure' creates a file `Makefile' in that directory. To create 1789`Makefile', `configure' performs a simple variable substitution, 1790replacing occurrences of `@VARIABLE@' in `Makefile.in' with the value 1791that `configure' has determined for that variable. Variables that are 1792substituted into output files in this way are called "output 1793variables". They are ordinary shell variables that are set in 1794`configure'. To make `configure' substitute a particular variable into 1795the output files, the macro `AC_SUBST' must be called with that 1796variable name as an argument. Any occurrences of `@VARIABLE@' for 1797other variables are left unchanged. *Note Setting Output Variables::, 1798for more information on creating output variables with `AC_SUBST'. 1799 1800 A software package that uses a `configure' script should be 1801distributed with a file `Makefile.in', but no makefile; that way, the 1802user has to properly configure the package for the local system before 1803compiling it. 1804 1805 *Note Makefile Conventions: (standards)Makefile Conventions, for 1806more information on what to put in makefiles. 1807 1808* Menu: 1809 1810* Preset Output Variables:: Output variables that are always set 1811* Installation Directory Variables:: Other preset output variables 1812* Changed Directory Variables:: Warnings about `datarootdir' 1813* Build Directories:: Supporting multiple concurrent compiles 1814* Automatic Remaking:: Makefile rules for configuring 1815 1816 1817File: autoconf.info, Node: Preset Output Variables, Next: Installation Directory Variables, Up: Makefile Substitutions 1818 18194.7.1 Preset Output Variables 1820----------------------------- 1821 1822Some output variables are preset by the Autoconf macros. Some of the 1823Autoconf macros set additional output variables, which are mentioned in 1824the descriptions for those macros. *Note Output Variable Index::, for a 1825complete list of output variables. *Note Installation Directory 1826Variables::, for the list of the preset ones related to installation 1827directories. Below are listed the other preset ones. They all are 1828precious variables (*note Setting Output Variables::, `AC_ARG_VAR'). 1829 1830 -- Variable: CFLAGS 1831 Debugging and optimization options for the C compiler. If it is 1832 not set in the environment when `configure' runs, the default 1833 value is set when you call `AC_PROG_CC' (or empty if you don't). 1834 `configure' uses this variable when compiling or linking programs 1835 to test for C features. 1836 1837 If a compiler option affects only the behavior of the preprocessor 1838 (e.g., `-D NAME'), it should be put into `CPPFLAGS' instead. If 1839 it affects only the linker (e.g., `-L DIRECTORY'), it should be 1840 put into `LDFLAGS' instead. If it affects only the compiler 1841 proper, `CFLAGS' is the natural home for it. If an option affects 1842 multiple phases of the compiler, though, matters get tricky. One 1843 approach to put such options directly into `CC', e.g., `CC='gcc 1844 -m64''. Another is to put them into both `CPPFLAGS' and 1845 `LDFLAGS', but not into `CFLAGS'. 1846 1847 1848 -- Variable: configure_input 1849 A comment saying that the file was generated automatically by 1850 `configure' and giving the name of the input file. `AC_OUTPUT' 1851 adds a comment line containing this variable to the top of every 1852 makefile it creates. For other files, you should reference this 1853 variable in a comment at the top of each input file. For example, 1854 an input shell script should begin like this: 1855 1856 #!/bin/sh 1857 # @configure_input@ 1858 1859 The presence of that line also reminds people editing the file 1860 that it needs to be processed by `configure' in order to be used. 1861 1862 -- Variable: CPPFLAGS 1863 Preprocessor options for the C, C++, and Objective C preprocessors 1864 and compilers. If it is not set in the environment when 1865 `configure' runs, the default value is empty. `configure' uses 1866 this variable when preprocessing or compiling programs to test for 1867 C, C++, and Objective C features. 1868 1869 This variable's contents should contain options like `-I', `-D', 1870 and `-U' that affect only the behavior of the preprocessor. 1871 Please see the explanation of `CFLAGS' for what you can do if an 1872 option affects other phases of the compiler as well. 1873 1874 Currently, `configure' always links as part of a single invocation 1875 of the compiler that also preprocesses and compiles, so it uses 1876 this variable also when linking programs. However, it is unwise to 1877 depend on this behavior because the GNU coding standards do not 1878 require it and many packages do not use `CPPFLAGS' when linking 1879 programs. 1880 1881 *Note Special Chars in Variables::, for limitations that `CPPFLAGS' 1882 might run into. 1883 1884 -- Variable: CXXFLAGS 1885 Debugging and optimization options for the C++ compiler. It acts 1886 like `CFLAGS', but for C++ instead of C. 1887 1888 -- Variable: DEFS 1889 `-D' options to pass to the C compiler. If `AC_CONFIG_HEADERS' is 1890 called, `configure' replaces `@DEFS@' with `-DHAVE_CONFIG_H' 1891 instead (*note Configuration Headers::). This variable is not 1892 defined while `configure' is performing its tests, only when 1893 creating the output files. *Note Setting Output Variables::, for 1894 how to check the results of previous tests. 1895 1896 -- Variable: ECHO_C 1897 -- Variable: ECHO_N 1898 -- Variable: ECHO_T 1899 How does one suppress the trailing newline from `echo' for 1900 question-answer message pairs? These variables provide a way: 1901 1902 echo $ECHO_N "And the winner is... $ECHO_C" 1903 sleep 100000000000 1904 echo "${ECHO_T}dead." 1905 1906 Some old and uncommon `echo' implementations offer no means to 1907 achieve this, in which case `ECHO_T' is set to tab. You might not 1908 want to use it. 1909 1910 -- Variable: ERLCFLAGS 1911 Debugging and optimization options for the Erlang compiler. If it 1912 is not set in the environment when `configure' runs, the default 1913 value is empty. `configure' uses this variable when compiling 1914 programs to test for Erlang features. 1915 1916 -- Variable: FCFLAGS 1917 Debugging and optimization options for the Fortran compiler. If it 1918 is not set in the environment when `configure' runs, the default 1919 value is set when you call `AC_PROG_FC' (or empty if you don't). 1920 `configure' uses this variable when compiling or linking programs 1921 to test for Fortran features. 1922 1923 -- Variable: FFLAGS 1924 Debugging and optimization options for the Fortran 77 compiler. 1925 If it is not set in the environment when `configure' runs, the 1926 default value is set when you call `AC_PROG_F77' (or empty if you 1927 don't). `configure' uses this variable when compiling or linking 1928 programs to test for Fortran 77 features. 1929 1930 -- Variable: LDFLAGS 1931 Options for the linker. If it is not set in the environment when 1932 `configure' runs, the default value is empty. `configure' uses 1933 this variable when linking programs to test for C, C++, Objective 1934 C, and Fortran features. 1935 1936 This variable's contents should contain options like `-s' and `-L' 1937 that affect only the behavior of the linker. Please see the 1938 explanation of `CFLAGS' for what you can do if an option also 1939 affects other phases of the compiler. 1940 1941 Don't use this variable to pass library names (`-l') to the 1942 linker; use `LIBS' instead. 1943 1944 -- Variable: LIBS 1945 `-l' options to pass to the linker. The default value is empty, 1946 but some Autoconf macros may prepend extra libraries to this 1947 variable if those libraries are found and provide necessary 1948 functions, see *Note Libraries::. `configure' uses this variable 1949 when linking programs to test for C, C++, and Fortran features. 1950 1951 -- Variable: OBJCFLAGS 1952 Debugging and optimization options for the Objective C compiler. 1953 It acts like `CFLAGS', but for Objective C instead of C. 1954 1955 -- Variable: builddir 1956 Rigorously equal to `.'. Added for symmetry only. 1957 1958 -- Variable: abs_builddir 1959 Absolute name of `builddir'. 1960 1961 -- Variable: top_builddir 1962 The relative name of the top level of the current build tree. In 1963 the top-level directory, this is the same as `builddir'. 1964 1965 -- Variable: abs_top_builddir 1966 Absolute name of `top_builddir'. 1967 1968 -- Variable: srcdir 1969 The name of the directory that contains the source code for that 1970 makefile. 1971 1972 -- Variable: abs_srcdir 1973 Absolute name of `srcdir'. 1974 1975 -- Variable: top_srcdir 1976 The name of the top-level source code directory for the package. 1977 In the top-level directory, this is the same as `srcdir'. 1978 1979 -- Variable: abs_top_srcdir 1980 Absolute name of `top_srcdir'. 1981 1982 1983File: autoconf.info, Node: Installation Directory Variables, Next: Changed Directory Variables, Prev: Preset Output Variables, Up: Makefile Substitutions 1984 19854.7.2 Installation Directory Variables 1986-------------------------------------- 1987 1988The following variables specify the directories for package 1989installation, see *Note Variables for Installation Directories: 1990(standards)Directory Variables, for more information. See the end of 1991this section for details on when and how to use these variables. 1992 1993 -- Variable: bindir 1994 The directory for installing executables that users run. 1995 1996 -- Variable: datadir 1997 The directory for installing idiosyncratic read-only 1998 architecture-independent data. 1999 2000 -- Variable: datarootdir 2001 The root of the directory tree for read-only 2002 architecture-independent data files. 2003 2004 -- Variable: docdir 2005 The directory for installing documentation files (other than Info 2006 and man). 2007 2008 -- Variable: dvidir 2009 The directory for installing documentation files in DVI format. 2010 2011 -- Variable: exec_prefix 2012 The installation prefix for architecture-dependent files. By 2013 default it's the same as PREFIX. You should avoid installing 2014 anything directly to EXEC_PREFIX. However, the default value for 2015 directories containing architecture-dependent files should be 2016 relative to EXEC_PREFIX. 2017 2018 -- Variable: htmldir 2019 The directory for installing HTML documentation. 2020 2021 -- Variable: includedir 2022 The directory for installing C header files. 2023 2024 -- Variable: infodir 2025 The directory for installing documentation in Info format. 2026 2027 -- Variable: libdir 2028 The directory for installing object code libraries. 2029 2030 -- Variable: libexecdir 2031 The directory for installing executables that other programs run. 2032 2033 -- Variable: localedir 2034 The directory for installing locale-dependent but 2035 architecture-independent data, such as message catalogs. This 2036 directory usually has a subdirectory per locale. 2037 2038 -- Variable: localstatedir 2039 The directory for installing modifiable single-machine data. 2040 2041 -- Variable: mandir 2042 The top-level directory for installing documentation in man format. 2043 2044 -- Variable: oldincludedir 2045 The directory for installing C header files for non-GCC compilers. 2046 2047 -- Variable: pdfdir 2048 The directory for installing PDF documentation. 2049 2050 -- Variable: prefix 2051 The common installation prefix for all files. If EXEC_PREFIX is 2052 defined to a different value, PREFIX is used only for 2053 architecture-independent files. 2054 2055 -- Variable: psdir 2056 The directory for installing PostScript documentation. 2057 2058 -- Variable: sbindir 2059 The directory for installing executables that system 2060 administrators run. 2061 2062 -- Variable: sharedstatedir 2063 The directory for installing modifiable architecture-independent 2064 data. 2065 2066 -- Variable: sysconfdir 2067 The directory for installing read-only single-machine data. 2068 2069 Most of these variables have values that rely on `prefix' or 2070`exec_prefix'. It is deliberate that the directory output variables 2071keep them unexpanded: typically `@datarootdir@' is replaced by 2072`${prefix}/share', not `/usr/local/share', and `@datadir@' is replaced 2073by `${datarootdir}'. 2074 2075 This behavior is mandated by the GNU coding standards, so that when 2076the user runs: 2077 2078`make' 2079 she can still specify a different prefix from the one specified to 2080 `configure', in which case, if needed, the package should hard 2081 code dependencies corresponding to the make-specified prefix. 2082 2083`make install' 2084 she can specify a different installation location, in which case 2085 the package _must_ still depend on the location which was compiled 2086 in (i.e., never recompile when `make install' is run). This is an 2087 extremely important feature, as many people may decide to install 2088 all the files of a package grouped together, and then install 2089 links from the final locations to there. 2090 2091 In order to support these features, it is essential that 2092`datarootdir' remains being defined as `${prefix}/share' to depend upon 2093the current value of `prefix'. 2094 2095 A corollary is that you should not use these variables except in 2096makefiles. For instance, instead of trying to evaluate `datadir' in 2097`configure' and hard-coding it in makefiles using e.g., 2098`AC_DEFINE_UNQUOTED([DATADIR], ["$datadir"], [Data directory.])', you 2099should add `-DDATADIR='$(datadir)'' to your makefile's definition of 2100`CPPFLAGS' (`AM_CPPFLAGS' if you are also using Automake). 2101 2102 Similarly, you should not rely on `AC_CONFIG_FILES' to replace 2103`datadir' and friends in your shell scripts and other files; instead, 2104let `make' manage their replacement. For instance Autoconf ships 2105templates of its shell scripts ending with `.in', and uses a makefile 2106snippet similar to the following to build scripts like `autoheader' and 2107`autom4te': 2108 2109 edit = sed \ 2110 -e 's|@datadir[@]|$(pkgdatadir)|g' \ 2111 -e 's|@prefix[@]|$(prefix)|g' 2112 2113 autoheader autom4te: Makefile 2114 rm -f $@ $@.tmp 2115 $(edit) '$(srcdir)/$@.in' >$@.tmp 2116 chmod +x $@.tmp 2117 chmod a-w $@.tmp 2118 mv $@.tmp $@ 2119 2120 autoheader: $(srcdir)/autoheader.in 2121 autom4te: $(srcdir)/autom4te.in 2122 2123 Some details are noteworthy: 2124 2125`@datadir[@]' 2126 The brackets prevent `configure' from replacing `@datadir@' in the 2127 Sed expression itself. Brackets are preferable to a backslash 2128 here, since Posix says `\@' is not portable. 2129 2130`$(pkgdatadir)' 2131 Don't use `@pkgdatadir@'! Use the matching makefile variable 2132 instead. 2133 2134`/' 2135 Don't use `/' in the Sed expressions that replace file names since 2136 most likely the variables you use, such as `$(pkgdatadir)', 2137 contain `/'. Use a shell metacharacter instead, such as `|'. 2138 2139special characters 2140 File names, file name components, and the value of `VPATH' should 2141 not contain shell metacharacters or white space. *Note Special 2142 Chars in Variables::. 2143 2144dependency on `Makefile' 2145 Since `edit' uses values that depend on the configuration specific 2146 values (`prefix', etc.) and not only on `VERSION' and so forth, 2147 the output depends on `Makefile', not `configure.ac'. 2148 2149`$@' 2150 The main rule is generic, and uses `$@' extensively to avoid the 2151 need for multiple copies of the rule. 2152 2153Separated dependencies and single suffix rules 2154 You can't use them! The above snippet cannot be (portably) 2155 rewritten as: 2156 2157 autoconf autoheader: Makefile 2158 .in: 2159 rm -f $@ $@.tmp 2160 $(edit) $< >$@.tmp 2161 chmod +x $@.tmp 2162 mv $@.tmp $@ 2163 2164 *Note Single Suffix Rules::, for details. 2165 2166`$(srcdir)' 2167 Be sure to specify the name of the source directory, otherwise the 2168 package won't support separated builds. 2169 2170 For the more specific installation of Erlang libraries, the 2171following variables are defined: 2172 2173 -- Variable: ERLANG_INSTALL_LIB_DIR 2174 The common parent directory of Erlang library installation 2175 directories. This variable is set by calling the 2176 `AC_ERLANG_SUBST_INSTALL_LIB_DIR' macro in `configure.ac'. 2177 2178 -- Variable: ERLANG_INSTALL_LIB_DIR_LIBRARY 2179 The installation directory for Erlang library LIBRARY. This 2180 variable is set by calling the 2181 `AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR(LIBRARY, VERSION' macro in 2182 `configure.ac'. 2183 2184 *Note Erlang Libraries::, for details. 2185 2186 2187File: autoconf.info, Node: Changed Directory Variables, Next: Build Directories, Prev: Installation Directory Variables, Up: Makefile Substitutions 2188 21894.7.3 Changed Directory Variables 2190--------------------------------- 2191 2192In Autoconf 2.60, the set of directory variables has changed, and the 2193defaults of some variables have been adjusted (*note Installation 2194Directory Variables::) to changes in the GNU Coding Standards. 2195Notably, `datadir', `infodir', and `mandir' are now expressed in terms 2196of `datarootdir'. If you are upgrading from an earlier Autoconf 2197version, you may need to adjust your files to ensure that the directory 2198variables are substituted correctly (*note Defining Directories::), and 2199that a definition of `datarootdir' is in place. For example, in a 2200`Makefile.in', adding 2201 2202 datarootdir = @datarootdir@ 2203 2204is usually sufficient. If you use Automake to create `Makefile.in', it 2205will add this for you. 2206 2207 To help with the transition, Autoconf warns about files that seem to 2208use `datarootdir' without defining it. In some cases, it then expands 2209the value of `$datarootdir' in substitutions of the directory 2210variables. The following example shows such a warning: 2211 2212 $ cat configure.ac 2213 AC_INIT 2214 AC_CONFIG_FILES([Makefile]) 2215 AC_OUTPUT 2216 $ cat Makefile.in 2217 prefix = @prefix@ 2218 datadir = @datadir@ 2219 $ autoconf 2220 $ configure 2221 configure: creating ./config.status 2222 config.status: creating Makefile 2223 config.status: WARNING: 2224 Makefile.in seems to ignore the --datarootdir setting 2225 $ cat Makefile 2226 prefix = /usr/local 2227 datadir = ${prefix}/share 2228 2229 Usually one can easily change the file to accommodate both older and 2230newer Autoconf releases: 2231 2232 $ cat Makefile.in 2233 prefix = @prefix@ 2234 datarootdir = @datarootdir@ 2235 datadir = @datadir@ 2236 $ configure 2237 configure: creating ./config.status 2238 config.status: creating Makefile 2239 $ cat Makefile 2240 prefix = /usr/local 2241 datarootdir = ${prefix}/share 2242 datadir = ${datarootdir} 2243 2244 In some cases, however, the checks may not be able to detect that a 2245suitable initialization of `datarootdir' is in place, or they may fail 2246to detect that such an initialization is necessary in the output file. 2247If, after auditing your package, there are still spurious `configure' 2248warnings about `datarootdir', you may add the line 2249 2250 AC_DEFUN([AC_DATAROOTDIR_CHECKED]) 2251 2252to your `configure.ac' to disable the warnings. This is an exception 2253to the usual rule that you should not define a macro whose name begins 2254with `AC_' (*note Macro Names::). 2255 2256 2257File: autoconf.info, Node: Build Directories, Next: Automatic Remaking, Prev: Changed Directory Variables, Up: Makefile Substitutions 2258 22594.7.4 Build Directories 2260----------------------- 2261 2262You can support compiling a software package for several architectures 2263simultaneously from the same copy of the source code. The object files 2264for each architecture are kept in their own directory. 2265 2266 To support doing this, `make' uses the `VPATH' variable to find the 2267files that are in the source directory. GNU Make and most other recent 2268`make' programs can do this. Older `make' programs do not support 2269`VPATH'; when using them, the source code must be in the same directory 2270as the object files. 2271 2272 To support `VPATH', each `Makefile.in' should contain two lines that 2273look like: 2274 2275 srcdir = @srcdir@ 2276 VPATH = @srcdir@ 2277 2278 Do not set `VPATH' to the value of another variable, for example 2279`VPATH = $(srcdir)', because some versions of `make' do not do variable 2280substitutions on the value of `VPATH'. 2281 2282 `configure' substitutes the correct value for `srcdir' when it 2283produces `Makefile'. 2284 2285 Do not use the `make' variable `$<', which expands to the file name 2286of the file in the source directory (found with `VPATH'), except in 2287implicit rules. (An implicit rule is one such as `.c.o', which tells 2288how to create a `.o' file from a `.c' file.) Some versions of `make' 2289do not set `$<' in explicit rules; they expand it to an empty value. 2290 2291 Instead, Make command lines should always refer to source files by 2292prefixing them with `$(srcdir)/'. For example: 2293 2294 time.info: time.texinfo 2295 $(MAKEINFO) '$(srcdir)/time.texinfo' 2296 2297 2298File: autoconf.info, Node: Automatic Remaking, Prev: Build Directories, Up: Makefile Substitutions 2299 23004.7.5 Automatic Remaking 2301------------------------ 2302 2303You can put rules like the following in the top-level `Makefile.in' for 2304a package to automatically update the configuration information when 2305you change the configuration files. This example includes all of the 2306optional files, such as `aclocal.m4' and those related to configuration 2307header files. Omit from the `Makefile.in' rules for any of these files 2308that your package does not use. 2309 2310 The `$(srcdir)/' prefix is included because of limitations in the 2311`VPATH' mechanism. 2312 2313 The `stamp-' files are necessary because the timestamps of 2314`config.h.in' and `config.h' are not changed if remaking them does not 2315change their contents. This feature avoids unnecessary recompilation. 2316You should include the file `stamp-h.in' your package's distribution, 2317so that `make' considers `config.h.in' up to date. Don't use `touch' 2318(*note Limitations of Usual Tools::); instead, use `echo' (using `date' 2319would cause needless differences, hence CVS conflicts, etc.). 2320 2321 $(srcdir)/configure: configure.ac aclocal.m4 2322 cd '$(srcdir)' && autoconf 2323 2324 # autoheader might not change config.h.in, so touch a stamp file. 2325 $(srcdir)/config.h.in: stamp-h.in 2326 $(srcdir)/stamp-h.in: configure.ac aclocal.m4 2327 cd '$(srcdir)' && autoheader 2328 echo timestamp > '$(srcdir)/stamp-h.in' 2329 2330 config.h: stamp-h 2331 stamp-h: config.h.in config.status 2332 ./config.status 2333 2334 Makefile: Makefile.in config.status 2335 ./config.status 2336 2337 config.status: configure 2338 ./config.status --recheck 2339 2340(Be careful if you copy these lines directly into your makefile, as you 2341need to convert the indented lines to start with the tab character.) 2342 2343 In addition, you should use 2344 2345 AC_CONFIG_FILES([stamp-h], [echo timestamp > stamp-h]) 2346 2347so `config.status' ensures that `config.h' is considered up to date. 2348*Note Output::, for more information about `AC_OUTPUT'. 2349 2350 *Note config.status Invocation::, for more examples of handling 2351configuration-related dependencies. 2352 2353 2354File: autoconf.info, Node: Configuration Headers, Next: Configuration Commands, Prev: Makefile Substitutions, Up: Setup 2355 23564.8 Configuration Header Files 2357============================== 2358 2359When a package contains more than a few tests that define C preprocessor 2360symbols, the command lines to pass `-D' options to the compiler can get 2361quite long. This causes two problems. One is that the `make' output 2362is hard to visually scan for errors. More seriously, the command lines 2363can exceed the length limits of some operating systems. As an 2364alternative to passing `-D' options to the compiler, `configure' 2365scripts can create a C header file containing `#define' directives. 2366The `AC_CONFIG_HEADERS' macro selects this kind of output. Though it 2367can be called anywhere between `AC_INIT' and `AC_OUTPUT', it is 2368customary to call it right after `AC_INIT'. 2369 2370 The package should `#include' the configuration header file before 2371any other header files, to prevent inconsistencies in declarations (for 2372example, if it redefines `const'). 2373 2374 To provide for VPATH builds, remember to pass the C compiler a `-I.' 2375option (or `-I..'; whichever directory contains `config.h'). Even if 2376you use `#include "config.h"', the preprocessor searches only the 2377directory of the currently read file, i.e., the source directory, not 2378the build directory. 2379 2380 With the appropriate `-I' option, you can use `#include <config.h>'. 2381Actually, it's a good habit to use it, because in the rare case when 2382the source directory contains another `config.h', the build directory 2383should be searched first. 2384 2385 -- Macro: AC_CONFIG_HEADERS (HEADER ..., [CMDS], [INIT-CMDS]) 2386 This macro is one of the instantiating macros; see *Note 2387 Configuration Actions::. Make `AC_OUTPUT' create the file(s) in 2388 the blank-or-newline-separated list HEADER containing C 2389 preprocessor `#define' statements, and replace `@DEFS@' in 2390 generated files with `-DHAVE_CONFIG_H' instead of the value of 2391 `DEFS'. The usual name for HEADER is `config.h'. 2392 2393 If HEADER already exists and its contents are identical to what 2394 `AC_OUTPUT' would put in it, it is left alone. Doing this allows 2395 making some changes in the configuration without needlessly causing 2396 object files that depend on the header file to be recompiled. 2397 2398 Usually the input file is named `HEADER.in'; however, you can 2399 override the input file name by appending to HEADER a 2400 colon-separated list of input files. Examples: 2401 2402 AC_CONFIG_HEADERS([config.h:config.hin]) 2403 AC_CONFIG_HEADERS([defines.h:defs.pre:defines.h.in:defs.post]) 2404 2405 Doing this allows you to keep your file names acceptable to DOS 2406 variants, or to prepend and/or append boilerplate to the file. 2407 2408 -- Macro: AH_HEADER 2409 This macro is defined as the name of the first declared config 2410 header and undefined if no config headers have been declared up to 2411 this point. A third-party macro may, for example, require use of 2412 a config header without invoking AC_CONFIG_HEADERS twice, like 2413 this: 2414 2415 AC_CONFIG_COMMANDS_PRE( 2416 [m4_ifndef([AH_HEADER], [AC_CONFIG_HEADERS([config.h])])]) 2417 2418 2419 *Note Configuration Actions::, for more details on HEADER. 2420 2421* Menu: 2422 2423* Header Templates:: Input for the configuration headers 2424* autoheader Invocation:: How to create configuration templates 2425* Autoheader Macros:: How to specify CPP templates 2426 2427 2428File: autoconf.info, Node: Header Templates, Next: autoheader Invocation, Up: Configuration Headers 2429 24304.8.1 Configuration Header Templates 2431------------------------------------ 2432 2433Your distribution should contain a template file that looks as you want 2434the final header file to look, including comments, with `#undef' 2435statements which are used as hooks. For example, suppose your 2436`configure.ac' makes these calls: 2437 2438 AC_CONFIG_HEADERS([conf.h]) 2439 AC_CHECK_HEADERS([unistd.h]) 2440 2441Then you could have code like the following in `conf.h.in'. On systems 2442that have `unistd.h', `configure' defines `HAVE_UNISTD_H' to 1. On 2443other systems, the whole line is commented out (in case the system 2444predefines that symbol). 2445 2446 /* Define as 1 if you have unistd.h. */ 2447 #undef HAVE_UNISTD_H 2448 2449 Pay attention that `#undef' is in the first column, and there is 2450nothing after `HAVE_UNISTD_H', not even white space. You can then 2451decode the configuration header using the preprocessor directives: 2452 2453 #include <conf.h> 2454 2455 #ifdef HAVE_UNISTD_H 2456 # include <unistd.h> 2457 #else 2458 /* We are in trouble. */ 2459 #endif 2460 2461 The use of old form templates, with `#define' instead of `#undef' is 2462strongly discouraged. Similarly with old templates with comments on 2463the same line as the `#undef'. Anyway, putting comments in 2464preprocessor macros has never been a good idea. 2465 2466 Since it is a tedious task to keep a template header up to date, you 2467may use `autoheader' to generate it, see *Note autoheader Invocation::. 2468 2469 2470File: autoconf.info, Node: autoheader Invocation, Next: Autoheader Macros, Prev: Header Templates, Up: Configuration Headers 2471 24724.8.2 Using `autoheader' to Create `config.h.in' 2473------------------------------------------------ 2474 2475The `autoheader' program can create a template file of C `#define' 2476statements for `configure' to use. If `configure.ac' invokes 2477`AC_CONFIG_HEADERS(FILE)', `autoheader' creates `FILE.in'; if multiple 2478file arguments are given, the first one is used. Otherwise, 2479`autoheader' creates `config.h.in'. 2480 2481 In order to do its job, `autoheader' needs you to document all of 2482the symbols that you might use. Typically this is done via an 2483`AC_DEFINE' or `AC_DEFINE_UNQUOTED' call whose first argument is a 2484literal symbol and whose third argument describes the symbol (*note 2485Defining Symbols::). Alternatively, you can use `AH_TEMPLATE' (*note 2486Autoheader Macros::), or you can supply a suitable input file for a 2487subsequent configuration header file. Symbols defined by Autoconf's 2488builtin tests are already documented properly; you need to document 2489only those that you define yourself. 2490 2491 You might wonder why `autoheader' is needed: after all, why would 2492`configure' need to "patch" a `config.h.in' to produce a `config.h' 2493instead of just creating `config.h' from scratch? Well, when 2494everything rocks, the answer is just that we are wasting our time 2495maintaining `autoheader': generating `config.h' directly is all that is 2496needed. When things go wrong, however, you'll be thankful for the 2497existence of `autoheader'. 2498 2499 The fact that the symbols are documented is important in order to 2500_check_ that `config.h' makes sense. The fact that there is a 2501well-defined list of symbols that should be defined (or not) is also 2502important for people who are porting packages to environments where 2503`configure' cannot be run: they just have to _fill in the blanks_. 2504 2505 But let's come back to the point: the invocation of `autoheader'... 2506 2507 If you give `autoheader' an argument, it uses that file instead of 2508`configure.ac' and writes the header file to the standard output 2509instead of to `config.h.in'. If you give `autoheader' an argument of 2510`-', it reads the standard input instead of `configure.ac' and writes 2511the header file to the standard output. 2512 2513 `autoheader' accepts the following options: 2514 2515`--help' 2516`-h' 2517 Print a summary of the command line options and exit. 2518 2519`--version' 2520`-V' 2521 Print the version number of Autoconf and exit. 2522 2523`--verbose' 2524`-v' 2525 Report processing steps. 2526 2527`--debug' 2528`-d' 2529 Don't remove the temporary files. 2530 2531`--force' 2532`-f' 2533 Remake the template file even if newer than its input files. 2534 2535`--include=DIR' 2536`-I DIR' 2537 Append DIR to the include path. Multiple invocations accumulate. 2538 2539`--prepend-include=DIR' 2540 2541`-B DIR' 2542 Prepend DIR to the include path. Multiple invocations accumulate. 2543 2544`--warnings=CATEGORY' 2545`-W CATEGORY' 2546 Report the warnings related to CATEGORY (which can actually be a 2547 comma separated list). Current categories include: 2548 2549 `obsolete' 2550 report the uses of obsolete constructs 2551 2552 `all' 2553 report all the warnings 2554 2555 `none' 2556 report none 2557 2558 `error' 2559 treats warnings as errors 2560 2561 `no-CATEGORY' 2562 disable warnings falling into CATEGORY 2563 2564 2565 2566File: autoconf.info, Node: Autoheader Macros, Prev: autoheader Invocation, Up: Configuration Headers 2567 25684.8.3 Autoheader Macros 2569----------------------- 2570 2571`autoheader' scans `configure.ac' and figures out which C preprocessor 2572symbols it might define. It knows how to generate templates for 2573symbols defined by `AC_CHECK_HEADERS', `AC_CHECK_FUNCS' etc., but if 2574you `AC_DEFINE' any additional symbol, you must define a template for 2575it. If there are missing templates, `autoheader' fails with an error 2576message. 2577 2578 The template for a SYMBOL is created by `autoheader' from the 2579DESCRIPTION argument to an `AC_DEFINE'; see *Note Defining Symbols::. 2580 2581 For special needs, you can use the following macros. 2582 2583 -- Macro: AH_TEMPLATE (KEY, DESCRIPTION) 2584 Tell `autoheader' to generate a template for KEY. This macro 2585 generates standard templates just like `AC_DEFINE' when a 2586 DESCRIPTION is given. 2587 2588 For example: 2589 2590 AH_TEMPLATE([CRAY_STACKSEG_END], 2591 [Define to one of _getb67, GETB67, getb67 2592 for Cray-2 and Cray-YMP systems. This 2593 function is required for alloca.c support 2594 on those systems.]) 2595 2596 generates the following template, with the description properly 2597 justified. 2598 2599 /* Define to one of _getb67, GETB67, getb67 for Cray-2 and 2600 Cray-YMP systems. This function is required for alloca.c 2601 support on those systems. */ 2602 #undef CRAY_STACKSEG_END 2603 2604 -- Macro: AH_VERBATIM (KEY, TEMPLATE) 2605 Tell `autoheader' to include the TEMPLATE as-is in the header 2606 template file. This TEMPLATE is associated with the KEY, which is 2607 used to sort all the different templates and guarantee their 2608 uniqueness. It should be a symbol that can be defined via 2609 `AC_DEFINE'. 2610 2611 -- Macro: AH_TOP (TEXT) 2612 Include TEXT at the top of the header template file. 2613 2614 -- Macro: AH_BOTTOM (TEXT) 2615 Include TEXT at the bottom of the header template file. 2616 2617 Please note that TEXT gets included "verbatim" to the template file, 2618not to the resulting config header, so it can easily get mangled when 2619the template is processed. There is rarely a need for something other 2620than 2621 2622 AH_BOTTOM([#include <custom.h>]) 2623 2624 2625File: autoconf.info, Node: Configuration Commands, Next: Configuration Links, Prev: Configuration Headers, Up: Setup 2626 26274.9 Running Arbitrary Configuration Commands 2628============================================ 2629 2630You can execute arbitrary commands before, during, and after 2631`config.status' is run. The three following macros accumulate the 2632commands to run when they are called multiple times. 2633`AC_CONFIG_COMMANDS' replaces the obsolete macro `AC_OUTPUT_COMMANDS'; 2634see *Note Obsolete Macros::, for details. 2635 2636 -- Macro: AC_CONFIG_COMMANDS (TAG..., [CMDS], [INIT-CMDS]) 2637 Specify additional shell commands to run at the end of 2638 `config.status', and shell commands to initialize any variables 2639 from `configure'. Associate the commands with TAG. Since 2640 typically the CMDS create a file, TAG should naturally be the name 2641 of that file. If needed, the directory hosting TAG is created. 2642 This macro is one of the instantiating macros; see *Note 2643 Configuration Actions::. 2644 2645 Here is an unrealistic example: 2646 fubar=42 2647 AC_CONFIG_COMMANDS([fubar], 2648 [echo this is extra $fubar, and so on.], 2649 [fubar=$fubar]) 2650 2651 Here is a better one: 2652 AC_CONFIG_COMMANDS([timestamp], [date >timestamp]) 2653 2654 The following two macros look similar, but in fact they are not of 2655the same breed: they are executed directly by `configure', so you 2656cannot use `config.status' to rerun them. 2657 2658 -- Macro: AC_CONFIG_COMMANDS_PRE (CMDS) 2659 Execute the CMDS right before creating `config.status'. 2660 2661 This macro presents the last opportunity to call `AC_SUBST', 2662 `AC_DEFINE', or `AC_CONFIG_FOOS' macros. 2663 2664 -- Macro: AC_CONFIG_COMMANDS_POST (CMDS) 2665 Execute the CMDS right after creating `config.status'. 2666 2667 2668File: autoconf.info, Node: Configuration Links, Next: Subdirectories, Prev: Configuration Commands, Up: Setup 2669 26704.10 Creating Configuration Links 2671================================= 2672 2673You may find it convenient to create links whose destinations depend 2674upon results of tests. One can use `AC_CONFIG_COMMANDS' but the 2675creation of relative symbolic links can be delicate when the package is 2676built in a directory different from the source directory. 2677 2678 -- Macro: AC_CONFIG_LINKS (DEST:SOURCE..., [CMDS], [INIT-CMDS]) 2679 Make `AC_OUTPUT' link each of the existing files SOURCE to the 2680 corresponding link name DEST. Makes a symbolic link if possible, 2681 otherwise a hard link if possible, otherwise a copy. The DEST and 2682 SOURCE names should be relative to the top level source or build 2683 directory. This macro is one of the instantiating macros; see 2684 *Note Configuration Actions::. 2685 2686 For example, this call: 2687 2688 AC_CONFIG_LINKS([host.h:config/$machine.h 2689 object.h:config/$obj_format.h]) 2690 2691 creates in the current directory `host.h' as a link to 2692 `SRCDIR/config/$machine.h', and `object.h' as a link to 2693 `SRCDIR/config/$obj_format.h'. 2694 2695 The tempting value `.' for DEST is invalid: it makes it impossible 2696 for `config.status' to guess the links to establish. 2697 2698 One can then run: 2699 ./config.status host.h object.h 2700 to create the links. 2701 2702 2703File: autoconf.info, Node: Subdirectories, Next: Default Prefix, Prev: Configuration Links, Up: Setup 2704 27054.11 Configuring Other Packages in Subdirectories 2706================================================= 2707 2708In most situations, calling `AC_OUTPUT' is sufficient to produce 2709makefiles in subdirectories. However, `configure' scripts that control 2710more than one independent package can use `AC_CONFIG_SUBDIRS' to run 2711`configure' scripts for other packages in subdirectories. 2712 2713 -- Macro: AC_CONFIG_SUBDIRS (DIR ...) 2714 Make `AC_OUTPUT' run `configure' in each subdirectory DIR in the 2715 given blank-or-newline-separated list. Each DIR should be a 2716 literal, i.e., please do not use: 2717 2718 if test "$package_foo_enabled" = yes; then 2719 $my_subdirs="$my_subdirs foo" 2720 fi 2721 AC_CONFIG_SUBDIRS([$my_subdirs]) 2722 2723 because this prevents `./configure --help=recursive' from 2724 displaying the options of the package `foo'. Instead, you should 2725 write: 2726 2727 if test "$package_foo_enabled" = yes; then 2728 AC_CONFIG_SUBDIRS([foo]) 2729 fi 2730 2731 If a given DIR is not found, an error is reported: if the 2732 subdirectory is optional, write: 2733 2734 if test -d "$srcdir/foo"; then 2735 AC_CONFIG_SUBDIRS([foo]) 2736 fi 2737 2738 If a given DIR contains `configure.gnu', it is run instead of 2739 `configure'. This is for packages that might use a non-Autoconf 2740 script `Configure', which can't be called through a wrapper 2741 `configure' since it would be the same file on case-insensitive 2742 file systems. Likewise, if a DIR contains `configure.in' but no 2743 `configure', the Cygnus `configure' script found by 2744 `AC_CONFIG_AUX_DIR' is used. 2745 2746 The subdirectory `configure' scripts are given the same command 2747 line options that were given to this `configure' script, with minor 2748 changes if needed, which include: 2749 2750 - adjusting a relative name for the cache file; 2751 2752 - adjusting a relative name for the source directory; 2753 2754 - propagating the current value of `$prefix', including if it 2755 was defaulted, and if the default values of the top level and 2756 of the subdirectory `configure' differ. 2757 2758 This macro also sets the output variable `subdirs' to the list of 2759 directories `DIR ...'. Make rules can use this variable to 2760 determine which subdirectories to recurse into. 2761 2762 This macro may be called multiple times. 2763 2764 2765File: autoconf.info, Node: Default Prefix, Prev: Subdirectories, Up: Setup 2766 27674.12 Default Prefix 2768=================== 2769 2770By default, `configure' sets the prefix for files it installs to 2771`/usr/local'. The user of `configure' can select a different prefix 2772using the `--prefix' and `--exec-prefix' options. There are two ways 2773to change the default: when creating `configure', and when running it. 2774 2775 Some software packages might want to install in a directory other 2776than `/usr/local' by default. To accomplish that, use the 2777`AC_PREFIX_DEFAULT' macro. 2778 2779 -- Macro: AC_PREFIX_DEFAULT (PREFIX) 2780 Set the default installation prefix to PREFIX instead of 2781 `/usr/local'. 2782 2783 It may be convenient for users to have `configure' guess the 2784installation prefix from the location of a related program that they 2785have already installed. If you wish to do that, you can call 2786`AC_PREFIX_PROGRAM'. 2787 2788 -- Macro: AC_PREFIX_PROGRAM (PROGRAM) 2789 If the user did not specify an installation prefix (using the 2790 `--prefix' option), guess a value for it by looking for PROGRAM in 2791 `PATH', the way the shell does. If PROGRAM is found, set the 2792 prefix to the parent of the directory containing PROGRAM, else 2793 default the prefix as described above (`/usr/local' or 2794 `AC_PREFIX_DEFAULT'). For example, if PROGRAM is `gcc' and the 2795 `PATH' contains `/usr/local/gnu/bin/gcc', set the prefix to 2796 `/usr/local/gnu'. 2797 2798 2799File: autoconf.info, Node: Existing Tests, Next: Writing Tests, Prev: Setup, Up: Top 2800 28015 Existing Tests 2802**************** 2803 2804These macros test for particular system features that packages might 2805need or want to use. If you need to test for a kind of feature that 2806none of these macros check for, you can probably do it by calling 2807primitive test macros with appropriate arguments (*note Writing 2808Tests::). 2809 2810 These tests print messages telling the user which feature they're 2811checking for, and what they find. They cache their results for future 2812`configure' runs (*note Caching Results::). 2813 2814 Some of these macros set output variables. *Note Makefile 2815Substitutions::, for how to get their values. The phrase "define NAME" 2816is used below as a shorthand to mean "define the C preprocessor symbol 2817NAME to the value 1". *Note Defining Symbols::, for how to get those 2818symbol definitions into your program. 2819 2820* Menu: 2821 2822* Common Behavior:: Macros' standard schemes 2823* Alternative Programs:: Selecting between alternative programs 2824* Files:: Checking for the existence of files 2825* Libraries:: Library archives that might be missing 2826* Library Functions:: C library functions that might be missing 2827* Header Files:: Header files that might be missing 2828* Declarations:: Declarations that may be missing 2829* Structures:: Structures or members that might be missing 2830* Types:: Types that might be missing 2831* Compilers and Preprocessors:: Checking for compiling programs 2832* System Services:: Operating system services 2833* Posix Variants:: Special kludges for specific Posix variants 2834* Erlang Libraries:: Checking for the existence of Erlang libraries 2835 2836 2837File: autoconf.info, Node: Common Behavior, Next: Alternative Programs, Up: Existing Tests 2838 28395.1 Common Behavior 2840=================== 2841 2842Much effort has been expended to make Autoconf easy to learn. The most 2843obvious way to reach this goal is simply to enforce standard interfaces 2844and behaviors, avoiding exceptions as much as possible. Because of 2845history and inertia, unfortunately, there are still too many exceptions 2846in Autoconf; nevertheless, this section describes some of the common 2847rules. 2848 2849* Menu: 2850 2851* Standard Symbols:: Symbols defined by the macros 2852* Default Includes:: Includes used by the generic macros 2853 2854 2855File: autoconf.info, Node: Standard Symbols, Next: Default Includes, Up: Common Behavior 2856 28575.1.1 Standard Symbols 2858---------------------- 2859 2860All the generic macros that `AC_DEFINE' a symbol as a result of their 2861test transform their ARGUMENT values to a standard alphabet. First, 2862ARGUMENT is converted to upper case and any asterisks (`*') are each 2863converted to `P'. Any remaining characters that are not alphanumeric 2864are converted to underscores. 2865 2866 For instance, 2867 2868 AC_CHECK_TYPES([struct $Expensive*]) 2869 2870defines the symbol `HAVE_STRUCT__EXPENSIVEP' if the check succeeds. 2871 2872 2873File: autoconf.info, Node: Default Includes, Prev: Standard Symbols, Up: Common Behavior 2874 28755.1.2 Default Includes 2876---------------------- 2877 2878Several tests depend upon a set of header files. Since these headers 2879are not universally available, tests actually have to provide a set of 2880protected includes, such as: 2881 2882 #ifdef TIME_WITH_SYS_TIME 2883 # include <sys/time.h> 2884 # include <time.h> 2885 #else 2886 # ifdef HAVE_SYS_TIME_H 2887 # include <sys/time.h> 2888 # else 2889 # include <time.h> 2890 # endif 2891 #endif 2892 2893Unless you know exactly what you are doing, you should avoid using 2894unconditional includes, and check the existence of the headers you 2895include beforehand (*note Header Files::). 2896 2897 Most generic macros use the following macro to provide the default 2898set of includes: 2899 2900 -- Macro: AC_INCLUDES_DEFAULT ([INCLUDE-DIRECTIVES]) 2901 Expand to INCLUDE-DIRECTIVES if defined, otherwise to: 2902 2903 #include <stdio.h> 2904 #ifdef HAVE_SYS_TYPES_H 2905 # include <sys/types.h> 2906 #endif 2907 #ifdef HAVE_SYS_STAT_H 2908 # include <sys/stat.h> 2909 #endif 2910 #ifdef STDC_HEADERS 2911 # include <stdlib.h> 2912 # include <stddef.h> 2913 #else 2914 # ifdef HAVE_STDLIB_H 2915 # include <stdlib.h> 2916 # endif 2917 #endif 2918 #ifdef HAVE_STRING_H 2919 # if !defined STDC_HEADERS && defined HAVE_MEMORY_H 2920 # include <memory.h> 2921 # endif 2922 # include <string.h> 2923 #endif 2924 #ifdef HAVE_STRINGS_H 2925 # include <strings.h> 2926 #endif 2927 #ifdef HAVE_INTTYPES_H 2928 # include <inttypes.h> 2929 #endif 2930 #ifdef HAVE_STDINT_H 2931 # include <stdint.h> 2932 #endif 2933 #ifdef HAVE_UNISTD_H 2934 # include <unistd.h> 2935 #endif 2936 2937 If the default includes are used, then check for the presence of 2938 these headers and their compatibility, i.e., you don't need to run 2939 `AC_HEADER_STDC', nor check for `stdlib.h' etc. 2940 2941 These headers are checked for in the same order as they are 2942 included. For instance, on some systems `string.h' and 2943 `strings.h' both exist, but conflict. Then `HAVE_STRING_H' is 2944 defined, not `HAVE_STRINGS_H'. 2945 2946 2947File: autoconf.info, Node: Alternative Programs, Next: Files, Prev: Common Behavior, Up: Existing Tests 2948 29495.2 Alternative Programs 2950======================== 2951 2952These macros check for the presence or behavior of particular programs. 2953They are used to choose between several alternative programs and to 2954decide what to do once one has been chosen. If there is no macro 2955specifically defined to check for a program you need, and you don't need 2956to check for any special properties of it, then you can use one of the 2957general program-check macros. 2958 2959* Menu: 2960 2961* Particular Programs:: Special handling to find certain programs 2962* Generic Programs:: How to find other programs 2963 2964 2965File: autoconf.info, Node: Particular Programs, Next: Generic Programs, Up: Alternative Programs 2966 29675.2.1 Particular Program Checks 2968------------------------------- 2969 2970These macros check for particular programs--whether they exist, and in 2971some cases whether they support certain features. 2972 2973 -- Macro: AC_PROG_AWK 2974 Check for `gawk', `mawk', `nawk', and `awk', in that order, and 2975 set output variable `AWK' to the first one that is found. It 2976 tries `gawk' first because that is reported to be the best 2977 implementation. 2978 2979 -- Macro: AC_PROG_GREP 2980 Look for the best available `grep' or `ggrep' that accepts the 2981 longest input lines possible, and that supports multiple `-e' 2982 options. Set the output variable `GREP' to whatever is chosen. 2983 *Note Limitations of Usual Tools::, for more information about 2984 portability problems with the `grep' command family. 2985 2986 -- Macro: AC_PROG_EGREP 2987 Check whether `$GREP -E' works, or else look for the best available 2988 `egrep' or `gegrep' that accepts the longest input lines possible. 2989 Set the output variable `EGREP' to whatever is chosen. 2990 2991 -- Macro: AC_PROG_FGREP 2992 Check whether `$GREP -F' works, or else look for the best available 2993 `fgrep' or `gfgrep' that accepts the longest input lines possible. 2994 Set the output variable `FGREP' to whatever is chosen. 2995 2996 -- Macro: AC_PROG_INSTALL 2997 Set output variable `INSTALL' to the name of a BSD-compatible 2998 `install' program, if one is found in the current `PATH'. 2999 Otherwise, set `INSTALL' to `DIR/install-sh -c', checking the 3000 directories specified to `AC_CONFIG_AUX_DIR' (or its default 3001 directories) to determine DIR (*note Output::). Also set the 3002 variables `INSTALL_PROGRAM' and `INSTALL_SCRIPT' to `${INSTALL}' 3003 and `INSTALL_DATA' to `${INSTALL} -m 644'. 3004 3005 `@INSTALL@' is special, as its value may vary for different 3006 configuration files. 3007 3008 This macro screens out various instances of `install' known not to 3009 work. It prefers to find a C program rather than a shell script, 3010 for speed. Instead of `install-sh', it can also use `install.sh', 3011 but that name is obsolete because some `make' programs have a rule 3012 that creates `install' from it if there is no makefile. 3013 3014 Autoconf comes with a copy of `install-sh' that you can use. If 3015 you use `AC_PROG_INSTALL', you must include either `install-sh' or 3016 `install.sh' in your distribution; otherwise `configure' produces 3017 an error message saying it can't find them--even if the system 3018 you're on has a good `install' program. This check is a safety 3019 measure to prevent you from accidentally leaving that file out, 3020 which would prevent your package from installing on systems that 3021 don't have a BSD-compatible `install' program. 3022 3023 If you need to use your own installation program because it has 3024 features not found in standard `install' programs, there is no 3025 reason to use `AC_PROG_INSTALL'; just put the file name of your 3026 program into your `Makefile.in' files. 3027 3028 -- Macro: AC_PROG_MKDIR_P 3029 Set output variable `MKDIR_P' to a program that ensures that for 3030 each argument, a directory named by this argument exists, creating 3031 it and its parent directories if needed, and without race 3032 conditions when two instances of the program attempt to make the 3033 same directory at nearly the same time. 3034 3035 This macro uses the `mkdir -p' command if possible. Otherwise, it 3036 falls back on invoking `install-sh' with the `-d' option, so your 3037 package should contain `install-sh' as described under 3038 `AC_PROG_INSTALL'. An `install-sh' file that predates Autoconf 3039 2.60 or Automake 1.10 is vulnerable to race conditions, so if you 3040 want to support parallel installs from different packages into the 3041 same directory you need to make sure you have an up-to-date 3042 `install-sh'. In particular, be careful about using `autoreconf 3043 -if' if your Automake predates Automake 1.10. 3044 3045 This macro is related to the `AS_MKDIR_P' macro (*note Programming 3046 in M4sh::), but it sets an output variable intended for use in 3047 other files, whereas `AS_MKDIR_P' is intended for use in scripts 3048 like `configure'. Also, `AS_MKDIR_P' does not accept options, but 3049 `MKDIR_P' supports the `-m' option, e.g., a makefile might invoke 3050 `$(MKDIR_P) -m 0 dir' to create an inaccessible directory, and 3051 conversely a makefile should use `$(MKDIR_P) -- $(FOO)' if FOO 3052 might yield a value that begins with `-'. Finally, `AS_MKDIR_P' 3053 does not check for race condition vulnerability, whereas 3054 `AC_PROG_MKDIR_P' does. 3055 3056 `@MKDIR_P@' is special, as its value may vary for different 3057 configuration files. 3058 3059 -- Macro: AC_PROG_LEX 3060 If `flex' is found, set output variable `LEX' to `flex' and 3061 `LEXLIB' to `-lfl', if that library is in a standard place. 3062 Otherwise set `LEX' to `lex' and `LEXLIB' to `-ll'. 3063 3064 Define `YYTEXT_POINTER' if `yytext' defaults to `char *' instead 3065 of to `char []'. Also set output variable `LEX_OUTPUT_ROOT' to 3066 the base of the file name that the lexer generates; usually 3067 `lex.yy', but sometimes something else. These results vary 3068 according to whether `lex' or `flex' is being used. 3069 3070 You are encouraged to use Flex in your sources, since it is both 3071 more pleasant to use than plain Lex and the C source it produces 3072 is portable. In order to ensure portability, however, you must 3073 either provide a function `yywrap' or, if you don't use it (e.g., 3074 your scanner has no `#include'-like feature), simply include a 3075 `%noyywrap' statement in the scanner's source. Once this done, 3076 the scanner is portable (unless _you_ felt free to use nonportable 3077 constructs) and does not depend on any library. In this case, and 3078 in this case only, it is suggested that you use this Autoconf 3079 snippet: 3080 3081 AC_PROG_LEX 3082 if test "$LEX" != flex; then 3083 LEX="$SHELL $missing_dir/missing flex" 3084 AC_SUBST([LEX_OUTPUT_ROOT], [lex.yy]) 3085 AC_SUBST([LEXLIB], ['']) 3086 fi 3087 3088 The shell script `missing' can be found in the Automake 3089 distribution. 3090 3091 To ensure backward compatibility, Automake's `AM_PROG_LEX' invokes 3092 (indirectly) this macro twice, which causes an annoying but benign 3093 "`AC_PROG_LEX' invoked multiple times" warning. Future versions 3094 of Automake will fix this issue; meanwhile, just ignore this 3095 message. 3096 3097 As part of running the test, this macro may delete any file in the 3098 configuration directory named `lex.yy.c' or `lexyy.c'. 3099 3100 -- Macro: AC_PROG_LN_S 3101 If `ln -s' works on the current file system (the operating system 3102 and file system support symbolic links), set the output variable 3103 `LN_S' to `ln -s'; otherwise, if `ln' works, set `LN_S' to `ln', 3104 and otherwise set it to `cp -p'. 3105 3106 If you make a link in a directory other than the current 3107 directory, its meaning depends on whether `ln' or `ln -s' is used. 3108 To safely create links using `$(LN_S)', either find out which 3109 form is used and adjust the arguments, or always invoke `ln' in 3110 the directory where the link is to be created. 3111 3112 In other words, it does not work to do: 3113 $(LN_S) foo /x/bar 3114 3115 Instead, do: 3116 3117 (cd /x && $(LN_S) foo bar) 3118 3119 -- Macro: AC_PROG_RANLIB 3120 Set output variable `RANLIB' to `ranlib' if `ranlib' is found, and 3121 otherwise to `:' (do nothing). 3122 3123 -- Macro: AC_PROG_SED 3124 Set output variable `SED' to a Sed implementation that conforms to 3125 Posix and does not have arbitrary length limits. Report an error 3126 if no acceptable Sed is found. *Note Limitations of Usual 3127 Tools::, for more information about portability problems with Sed. 3128 3129 -- Macro: AC_PROG_YACC 3130 If `bison' is found, set output variable `YACC' to `bison -y'. 3131 Otherwise, if `byacc' is found, set `YACC' to `byacc'. Otherwise 3132 set `YACC' to `yacc'. 3133 3134 3135File: autoconf.info, Node: Generic Programs, Prev: Particular Programs, Up: Alternative Programs 3136 31375.2.2 Generic Program and File Checks 3138------------------------------------- 3139 3140These macros are used to find programs not covered by the "particular" 3141test macros. If you need to check the behavior of a program as well as 3142find out whether it is present, you have to write your own test for it 3143(*note Writing Tests::). By default, these macros use the environment 3144variable `PATH'. If you need to check for a program that might not be 3145in the user's `PATH', you can pass a modified path to use instead, like 3146this: 3147 3148 AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd], 3149 [$PATH:/usr/libexec:/usr/sbin:/usr/etc:/etc]) 3150 3151 You are strongly encouraged to declare the VARIABLE passed to 3152`AC_CHECK_PROG' etc. as precious, *Note Setting Output Variables::, 3153`AC_ARG_VAR', for more details. 3154 3155 -- Macro: AC_CHECK_PROG (VARIABLE, PROG-TO-CHECK-FOR, VALUE-IF-FOUND, 3156 [VALUE-IF-NOT-FOUND], [PATH], [REJECT]) 3157 Check whether program PROG-TO-CHECK-FOR exists in `PATH'. If it 3158 is found, set VARIABLE to VALUE-IF-FOUND, otherwise to 3159 VALUE-IF-NOT-FOUND, if given. Always pass over REJECT (an 3160 absolute file name) even if it is the first found in the search 3161 path; in that case, set VARIABLE using the absolute file name of 3162 the PROG-TO-CHECK-FOR found that is not REJECT. If VARIABLE was 3163 already set, do nothing. Calls `AC_SUBST' for VARIABLE. 3164 3165 -- Macro: AC_CHECK_PROGS (VARIABLE, PROGS-TO-CHECK-FOR, 3166 [VALUE-IF-NOT-FOUND], [PATH]) 3167 Check for each program in the blank-separated list 3168 PROGS-TO-CHECK-FOR existing in the `PATH'. If one is found, set 3169 VARIABLE to the name of that program. Otherwise, continue 3170 checking the next program in the list. If none of the programs in 3171 the list are found, set VARIABLE to VALUE-IF-NOT-FOUND; if 3172 VALUE-IF-NOT-FOUND is not specified, the value of VARIABLE is not 3173 changed. Calls `AC_SUBST' for VARIABLE. 3174 3175 -- Macro: AC_CHECK_TARGET_TOOL (VARIABLE, PROG-TO-CHECK-FOR, 3176 [VALUE-IF-NOT-FOUND], [PATH]) 3177 Like `AC_CHECK_PROG', but first looks for PROG-TO-CHECK-FOR with a 3178 prefix of the target type as determined by `AC_CANONICAL_TARGET', 3179 followed by a dash (*note Canonicalizing::). If the tool cannot 3180 be found with a prefix, and if the build and target types are 3181 equal, then it is also searched for without a prefix. 3182 3183 As noted in *Note Specifying the system type: Specifying Names, the 3184 target is rarely specified, because most of the time it is the same 3185 as the host: it is the type of system for which any compiler tool 3186 in the package produces code. What this macro looks for is, for 3187 example, _a tool (assembler, linker, etc.) that the compiler 3188 driver (`gcc' for the GNU C Compiler) uses to produce objects, 3189 archives or executables_. 3190 3191 -- Macro: AC_CHECK_TOOL (VARIABLE, PROG-TO-CHECK-FOR, 3192 [VALUE-IF-NOT-FOUND], [PATH]) 3193 Like `AC_CHECK_PROG', but first looks for PROG-TO-CHECK-FOR with a 3194 prefix of the host type as determined by `AC_CANONICAL_HOST', 3195 followed by a dash (*note Canonicalizing::). For example, if the 3196 user runs `configure --host=i386-gnu', then this call: 3197 AC_CHECK_TOOL([RANLIB], [ranlib], [:]) 3198 sets `RANLIB' to `i386-gnu-ranlib' if that program exists in 3199 `PATH', or otherwise to `ranlib' if that program exists in `PATH', 3200 or to `:' if neither program exists. 3201 3202 In the future, when cross-compiling this macro will _only_ accept 3203 program names that are prefixed with the host type. For more 3204 information, see *Note Specifying the system type: Specifying 3205 Names. 3206 3207 -- Macro: AC_CHECK_TARGET_TOOLS (VARIABLE, PROGS-TO-CHECK-FOR, 3208 [VALUE-IF-NOT-FOUND], [PATH]) 3209 Like `AC_CHECK_TARGET_TOOL', each of the tools in the list 3210 PROGS-TO-CHECK-FOR are checked with a prefix of the target type as 3211 determined by `AC_CANONICAL_TARGET', followed by a dash (*note 3212 Canonicalizing::). If none of the tools can be found with a 3213 prefix, and if the build and target types are equal, then the 3214 first one without a prefix is used. If a tool is found, set 3215 VARIABLE to the name of that program. If none of the tools in the 3216 list are found, set VARIABLE to VALUE-IF-NOT-FOUND; if 3217 VALUE-IF-NOT-FOUND is not specified, the value of VARIABLE is not 3218 changed. Calls `AC_SUBST' for VARIABLE. 3219 3220 -- Macro: AC_CHECK_TOOLS (VARIABLE, PROGS-TO-CHECK-FOR, 3221 [VALUE-IF-NOT-FOUND], [PATH]) 3222 Like `AC_CHECK_TOOL', each of the tools in the list 3223 PROGS-TO-CHECK-FOR are checked with a prefix of the host type as 3224 determined by `AC_CANONICAL_HOST', followed by a dash (*note 3225 Canonicalizing::). If none of the tools can be found with a 3226 prefix, then the first one without a prefix is used. If a tool is 3227 found, set VARIABLE to the name of that program. If none of the 3228 tools in the list are found, set VARIABLE to VALUE-IF-NOT-FOUND; if 3229 VALUE-IF-NOT-FOUND is not specified, the value of VARIABLE is not 3230 changed. Calls `AC_SUBST' for VARIABLE. 3231 3232 In the future, when cross-compiling this macro will _not_ accept 3233 program names that are not prefixed with the host type. 3234 3235 -- Macro: AC_PATH_PROG (VARIABLE, PROG-TO-CHECK-FOR, 3236 [VALUE-IF-NOT-FOUND], [PATH]) 3237 Like `AC_CHECK_PROG', but set VARIABLE to the absolute name of 3238 PROG-TO-CHECK-FOR if found. 3239 3240 -- Macro: AC_PATH_PROGS (VARIABLE, PROGS-TO-CHECK-FOR, 3241 [VALUE-IF-NOT-FOUND], [PATH]) 3242 Like `AC_CHECK_PROGS', but if any of PROGS-TO-CHECK-FOR are found, 3243 set VARIABLE to the absolute name of the program found. 3244 3245 -- Macro: AC_PATH_TARGET_TOOL (VARIABLE, PROG-TO-CHECK-FOR, 3246 [VALUE-IF-NOT-FOUND], [PATH]) 3247 Like `AC_CHECK_TARGET_TOOL', but set VARIABLE to the absolute name 3248 of the program if it is found. 3249 3250 -- Macro: AC_PATH_TOOL (VARIABLE, PROG-TO-CHECK-FOR, 3251 [VALUE-IF-NOT-FOUND], [PATH]) 3252 Like `AC_CHECK_TOOL', but set VARIABLE to the absolute name of the 3253 program if it is found. 3254 3255 In the future, when cross-compiling this macro will _not_ accept 3256 program names that are not prefixed with the host type. 3257 3258 3259File: autoconf.info, Node: Files, Next: Libraries, Prev: Alternative Programs, Up: Existing Tests 3260 32615.3 Files 3262========= 3263 3264You might also need to check for the existence of files. Before using 3265these macros, ask yourself whether a runtime test might not be a better 3266solution. Be aware that, like most Autoconf macros, they test a feature 3267of the host machine, and therefore, they die when cross-compiling. 3268 3269 -- Macro: AC_CHECK_FILE (FILE, [ACTION-IF-FOUND], 3270 [ACTION-IF-NOT-FOUND]) 3271 Check whether file FILE exists on the native system. If it is 3272 found, execute ACTION-IF-FOUND, otherwise do ACTION-IF-NOT-FOUND, 3273 if given. 3274 3275 -- Macro: AC_CHECK_FILES (FILES, [ACTION-IF-FOUND], 3276 [ACTION-IF-NOT-FOUND]) 3277 Executes `AC_CHECK_FILE' once for each file listed in FILES. 3278 Additionally, defines `HAVE_FILE' (*note Standard Symbols::) for 3279 each file found. 3280 3281 3282File: autoconf.info, Node: Libraries, Next: Library Functions, Prev: Files, Up: Existing Tests 3283 32845.4 Library Files 3285================= 3286 3287The following macros check for the presence of certain C, C++, or 3288Fortran library archive files. 3289 3290 -- Macro: AC_CHECK_LIB (LIBRARY, FUNCTION, [ACTION-IF-FOUND], 3291 [ACTION-IF-NOT-FOUND], [OTHER-LIBRARIES]) 3292 Test whether the library LIBRARY is available by trying to link a 3293 test program that calls function FUNCTION with the library. 3294 FUNCTION should be a function provided by the library. Use the 3295 base name of the library; e.g., to check for `-lmp', use `mp' as 3296 the LIBRARY argument. 3297 3298 ACTION-IF-FOUND is a list of shell commands to run if the link 3299 with the library succeeds; ACTION-IF-NOT-FOUND is a list of shell 3300 commands to run if the link fails. If ACTION-IF-FOUND is not 3301 specified, the default action prepends `-lLIBRARY' to `LIBS' and 3302 defines `HAVE_LIBLIBRARY' (in all capitals). This macro is 3303 intended to support building `LIBS' in a right-to-left 3304 (least-dependent to most-dependent) fashion such that library 3305 dependencies are satisfied as a natural side effect of consecutive 3306 tests. Linkers are sensitive to library ordering so the order in 3307 which `LIBS' is generated is important to reliable detection of 3308 libraries. 3309 3310 If linking with LIBRARY results in unresolved symbols that would 3311 be resolved by linking with additional libraries, give those 3312 libraries as the OTHER-LIBRARIES argument, separated by spaces: 3313 e.g., `-lXt -lX11'. Otherwise, this macro fails to detect that 3314 LIBRARY is present, because linking the test program always fails 3315 with unresolved symbols. The OTHER-LIBRARIES argument should be 3316 limited to cases where it is desirable to test for one library in 3317 the presence of another that is not already in `LIBS'. 3318 3319 `AC_CHECK_LIB' requires some care in usage, and should be avoided 3320 in some common cases. Many standard functions like `gethostbyname' 3321 appear the standard C library on some hosts, and in special 3322 libraries like `nsl' on other hosts. On some hosts the special 3323 libraries contain variant implementations that you may not want to 3324 use. These days it is normally better to use 3325 `AC_SEARCH_LIBS([gethostbyname], [nsl])' instead of 3326 `AC_CHECK_LIB([nsl], [gethostbyname])'. 3327 3328 -- Macro: AC_SEARCH_LIBS (FUNCTION, SEARCH-LIBS, [ACTION-IF-FOUND], 3329 [ACTION-IF-NOT-FOUND], [OTHER-LIBRARIES]) 3330 Search for a library defining FUNCTION if it's not already 3331 available. This equates to calling 3332 `AC_LINK_IFELSE([AC_LANG_CALL([], [FUNCTION])])' first with no 3333 libraries, then for each library listed in SEARCH-LIBS. 3334 3335 Add `-lLIBRARY' to `LIBS' for the first library found to contain 3336 FUNCTION, and run ACTION-IF-FOUND. If the function is not found, 3337 run ACTION-IF-NOT-FOUND. 3338 3339 If linking with LIBRARY results in unresolved symbols that would 3340 be resolved by linking with additional libraries, give those 3341 libraries as the OTHER-LIBRARIES argument, separated by spaces: 3342 e.g., `-lXt -lX11'. Otherwise, this macro fails to detect that 3343 FUNCTION is present, because linking the test program always fails 3344 with unresolved symbols. 3345 3346 3347File: autoconf.info, Node: Library Functions, Next: Header Files, Prev: Libraries, Up: Existing Tests 3348 33495.5 Library Functions 3350===================== 3351 3352The following macros check for particular C library functions. If 3353there is no macro specifically defined to check for a function you need, 3354and you don't need to check for any special properties of it, then you 3355can use one of the general function-check macros. 3356 3357* Menu: 3358 3359* Function Portability:: Pitfalls with usual functions 3360* Particular Functions:: Special handling to find certain functions 3361* Generic Functions:: How to find other functions 3362 3363 3364File: autoconf.info, Node: Function Portability, Next: Particular Functions, Up: Library Functions 3365 33665.5.1 Portability of C Functions 3367-------------------------------- 3368 3369Most usual functions can either be missing, or be buggy, or be limited 3370on some architectures. This section tries to make an inventory of these 3371portability issues. By definition, this list always requires 3372additions. Please help us keeping it as complete as possible. 3373 3374`exit' 3375 On ancient hosts, `exit' returned `int'. This is because `exit' 3376 predates `void', and there was a long tradition of it returning 3377 `int'. 3378 3379 On current hosts, the problem more likely is that `exit' is not 3380 declared, due to C++ problems of some sort or another. For this 3381 reason we suggest that test programs not invoke `exit', but return 3382 from `main' instead. 3383 3384`free' 3385 The C standard says a call `free (NULL)' does nothing, but some 3386 old systems don't support this (e.g., NextStep). 3387 3388`isinf' 3389`isnan' 3390 The C99 standard says that `isinf' and `isnan' are macros. On 3391 some systems just macros are available (e.g., HP-UX and Solaris 3392 10), on some systems both macros and functions (e.g., glibc 3393 2.3.2), and on some systems only functions (e.g., IRIX 6 and 3394 Solaris 9). In some cases these functions are declared in 3395 nonstandard headers like `<sunmath.h>' and defined in non-default 3396 libraries like `-lm' or `-lsunmath'. 3397 3398 The C99 `isinf' and `isnan' macros work correctly with `long 3399 double' arguments, but pre-C99 systems that use functions 3400 typically assume `double' arguments. On such a system, `isinf' 3401 incorrectly returns true for a finite `long double' argument that 3402 is outside the range of `double'. 3403 3404 To work around this porting mess, you can use code like the 3405 following. 3406 3407 #include <math.h> 3408 3409 #ifndef isnan 3410 # define isnan(x) \ 3411 (sizeof (x) == sizeof (long double) ? isnan_ld (x) \ 3412 : sizeof (x) == sizeof (double) ? isnan_d (x) \ 3413 : isnan_f (x)) 3414 static inline int isnan_f (float x) { return x != x; } 3415 static inline int isnan_d (double x) { return x != x; } 3416 static inline int isnan_ld (long double x) { return x != x; } 3417 #endif 3418 3419 #ifndef isinf 3420 # define isinf(x) \ 3421 (sizeof (x) == sizeof (long double) ? isinf_ld (x) \ 3422 : sizeof (x) == sizeof (double) ? isinf_d (x) \ 3423 : isinf_f (x)) 3424 static inline int isinf_f (float x) { return isnan (x - x); } 3425 static inline int isinf_d (double x) { return isnan (x - x); } 3426 static inline int isinf_ld (long double x) { return isnan (x - x); } 3427 #endif 3428 3429 Use `AC_C_INLINE' (*note C Compiler::) so that this code works on 3430 compilers that lack the `inline' keyword. Some optimizing 3431 compilers mishandle these definitions, but systems with that bug 3432 typically have missing or broken `isnan' functions anyway, so it's 3433 probably not worth worrying about. 3434 3435`malloc' 3436 The C standard says a call `malloc (0)' is implementation 3437 dependent. It can return either `NULL' or a new non-null pointer. 3438 The latter is more common (e.g., the GNU C Library) but is by no 3439 means universal. `AC_FUNC_MALLOC' can be used to insist on 3440 non-`NULL' (*note Particular Functions::). 3441 3442`putenv' 3443 Posix prefers `setenv' to `putenv'; among other things, `putenv' 3444 is not required of all Posix implementations, but `setenv' is. 3445 3446 Posix specifies that `putenv' puts the given string directly in 3447 `environ', but some systems make a copy of it instead (e.g., glibc 3448 2.0, or BSD). And when a copy is made, `unsetenv' might not free 3449 it, causing a memory leak (e.g., FreeBSD 4). 3450 3451 On some systems `putenv ("FOO")' removes `FOO' from the 3452 environment, but this is not standard usage and it dumps core on 3453 some systems (e.g., AIX). 3454 3455 On MinGW, a call `putenv ("FOO=")' removes `FOO' from the 3456 environment, rather than inserting it with an empty value. 3457 3458`realloc' 3459 The C standard says a call `realloc (NULL, size)' is equivalent to 3460 `malloc (size)', but some old systems don't support this (e.g., 3461 NextStep). 3462 3463`signal' handler 3464 Normally `signal' takes a handler function with a return type of 3465 `void', but some old systems required `int' instead. Any actual 3466 `int' value returned is not used; this is only a difference in the 3467 function prototype demanded. 3468 3469 All systems we know of in current use return `void'. The `int' 3470 was to support K&R C, where of course `void' is not available. 3471 `AC_TYPE_SIGNAL' (*note Particular Types::) can be used to 3472 establish the correct type in all cases. 3473 3474`snprintf' 3475 The C99 standard says that if the output array isn't big enough 3476 and if no other errors occur, `snprintf' and `vsnprintf' truncate 3477 the output and return the number of bytes that ought to have been 3478 produced. Some older systems return the truncated length (e.g., 3479 GNU C Library 2.0.x or IRIX 6.5), some a negative value (e.g., 3480 earlier GNU C Library versions), and some the buffer length 3481 without truncation (e.g., 32-bit Solaris 7). Also, some buggy 3482 older systems ignore the length and overrun the buffer (e.g., 3483 64-bit Solaris 7). 3484 3485`sprintf' 3486 The C standard says `sprintf' and `vsprintf' return the number of 3487 bytes written. On some ancient systems (SunOS 4 for instance) 3488 they return the buffer pointer instead, but these no longer need 3489 to be worried about. 3490 3491`sscanf' 3492 On various old systems, e.g., HP-UX 9, `sscanf' requires that its 3493 input string be writable (though it doesn't actually change it). 3494 This can be a problem when using `gcc' since it normally puts 3495 constant strings in read-only memory (*note Incompatibilities of 3496 GCC: (gcc)Incompatibilities.). Apparently in some cases even 3497 having format strings read-only can be a problem. 3498 3499`strerror_r' 3500 Posix specifies that `strerror_r' returns an `int', but many 3501 systems (e.g., GNU C Library version 2.2.4) provide a different 3502 version returning a `char *'. `AC_FUNC_STRERROR_R' can detect 3503 which is in use (*note Particular Functions::). 3504 3505`strnlen' 3506 AIX 4.3 provides a broken version which produces the following 3507 results: 3508 3509 strnlen ("foobar", 0) = 0 3510 strnlen ("foobar", 1) = 3 3511 strnlen ("foobar", 2) = 2 3512 strnlen ("foobar", 3) = 1 3513 strnlen ("foobar", 4) = 0 3514 strnlen ("foobar", 5) = 6 3515 strnlen ("foobar", 6) = 6 3516 strnlen ("foobar", 7) = 6 3517 strnlen ("foobar", 8) = 6 3518 strnlen ("foobar", 9) = 6 3519 3520`sysconf' 3521 `_SC_PAGESIZE' is standard, but some older systems (e.g., HP-UX 9) 3522 have `_SC_PAGE_SIZE' instead. This can be tested with `#ifdef'. 3523 3524`unlink' 3525 The Posix spec says that `unlink' causes the given file to be 3526 removed only after there are no more open file handles for it. 3527 Some non-Posix hosts have trouble with this requirement, though, 3528 and some DOS variants even corrupt the file system. 3529 3530`unsetenv' 3531 On MinGW, `unsetenv' is not available, but a variable `FOO' can be 3532 removed with a call `putenv ("FOO=")', as described under `putenv' 3533 above. 3534 3535`va_copy' 3536 The C99 standard provides `va_copy' for copying `va_list' 3537 variables. It may be available in older environments too, though 3538 possibly as `__va_copy' (e.g., `gcc' in strict pre-C99 mode). 3539 These can be tested with `#ifdef'. A fallback to `memcpy (&dst, 3540 &src, sizeof (va_list))' gives maximum portability. 3541 3542`va_list' 3543 `va_list' is not necessarily just a pointer. It can be a `struct' 3544 (e.g., `gcc' on Alpha), which means `NULL' is not portable. Or it 3545 can be an array (e.g., `gcc' in some PowerPC configurations), 3546 which means as a function parameter it can be effectively 3547 call-by-reference and library routines might modify the value back 3548 in the caller (e.g., `vsnprintf' in the GNU C Library 2.1). 3549 3550Signed `>>' 3551 Normally the C `>>' right shift of a signed type replicates the 3552 high bit, giving a so-called "arithmetic" shift. But care should 3553 be taken since Standard C doesn't require that behavior. On those 3554 few processors without a native arithmetic shift (for instance Cray 3555 vector systems) zero bits may be shifted in, the same as a shift 3556 of an unsigned type. 3557 3558Integer `/' 3559 C divides signed integers by truncating their quotient toward zero, 3560 yielding the same result as Fortran. However, before C99 the 3561 standard allowed C implementations to take the floor or ceiling of 3562 the quotient in some cases. Hardly any implementations took 3563 advantage of this freedom, though, and it's probably not worth 3564 worrying about this issue nowadays. 3565 3566 3567File: autoconf.info, Node: Particular Functions, Next: Generic Functions, Prev: Function Portability, Up: Library Functions 3568 35695.5.2 Particular Function Checks 3570-------------------------------- 3571 3572These macros check for particular C functions--whether they exist, and 3573in some cases how they respond when given certain arguments. 3574 3575 -- Macro: AC_FUNC_ALLOCA 3576 Check how to get `alloca'. Tries to get a builtin version by 3577 checking for `alloca.h' or the predefined C preprocessor macros 3578 `__GNUC__' and `_AIX'. If this macro finds `alloca.h', it defines 3579 `HAVE_ALLOCA_H'. 3580 3581 If those attempts fail, it looks for the function in the standard C 3582 library. If any of those methods succeed, it defines 3583 `HAVE_ALLOCA'. Otherwise, it sets the output variable `ALLOCA' to 3584 `${LIBOBJDIR}alloca.o' and defines `C_ALLOCA' (so programs can 3585 periodically call `alloca (0)' to garbage collect). This variable 3586 is separate from `LIBOBJS' so multiple programs can share the 3587 value of `ALLOCA' without needing to create an actual library, in 3588 case only some of them use the code in `LIBOBJS'. The 3589 `${LIBOBJDIR}' prefix serves the same purpose as in `LIBOBJS' 3590 (*note AC_LIBOBJ vs LIBOBJS::). 3591 3592 This macro does not try to get `alloca' from the System V R3 3593 `libPW' or the System V R4 `libucb' because those libraries 3594 contain some incompatible functions that cause trouble. Some 3595 versions do not even contain `alloca' or contain a buggy version. 3596 If you still want to use their `alloca', use `ar' to extract 3597 `alloca.o' from them instead of compiling `alloca.c'. 3598 3599 Source files that use `alloca' should start with a piece of code 3600 like the following, to declare it properly. 3601 3602 #ifdef HAVE_ALLOCA_H 3603 # include <alloca.h> 3604 #elif defined __GNUC__ 3605 # define alloca __builtin_alloca 3606 #elif defined _AIX 3607 # define alloca __alloca 3608 #elif defined _MSC_VER 3609 # include <malloc.h> 3610 # define alloca _alloca 3611 #else 3612 # include <stddef.h> 3613 # ifdef __cplusplus 3614 extern "C" 3615 # endif 3616 void *alloca (size_t); 3617 #endif 3618 3619 -- Macro: AC_FUNC_CHOWN 3620 If the `chown' function is available and works (in particular, it 3621 should accept `-1' for `uid' and `gid'), define `HAVE_CHOWN'. 3622 3623 -- Macro: AC_FUNC_CLOSEDIR_VOID 3624 If the `closedir' function does not return a meaningful value, 3625 define `CLOSEDIR_VOID'. Otherwise, callers ought to check its 3626 return value for an error indicator. 3627 3628 Currently this test is implemented by running a test program. When 3629 cross compiling the pessimistic assumption that `closedir' does not 3630 return a meaningful value is made. 3631 3632 This macro is obsolescent, as `closedir' returns a meaningful value 3633 on current systems. New programs need not use this macro. 3634 3635 -- Macro: AC_FUNC_ERROR_AT_LINE 3636 If the `error_at_line' function is not found, require an 3637 `AC_LIBOBJ' replacement of `error'. 3638 3639 -- Macro: AC_FUNC_FNMATCH 3640 If the `fnmatch' function conforms to Posix, define 3641 `HAVE_FNMATCH'. Detect common implementation bugs, for example, 3642 the bugs in Solaris 2.4. 3643 3644 Unlike the other specific `AC_FUNC' macros, `AC_FUNC_FNMATCH' does 3645 not replace a broken/missing `fnmatch'. This is for historical 3646 reasons. See `AC_REPLACE_FNMATCH' below. 3647 3648 This macro is obsolescent. New programs should use Gnulib's 3649 `fnmatch-posix' module. *Note Gnulib::. 3650 3651 -- Macro: AC_FUNC_FNMATCH_GNU 3652 Behave like `AC_REPLACE_FNMATCH' (_replace_) but also test whether 3653 `fnmatch' supports GNU extensions. Detect common implementation 3654 bugs, for example, the bugs in the GNU C Library 2.1. 3655 3656 This macro is obsolescent. New programs should use Gnulib's 3657 `fnmatch-gnu' module. *Note Gnulib::. 3658 3659 -- Macro: AC_FUNC_FORK 3660 This macro checks for the `fork' and `vfork' functions. If a 3661 working `fork' is found, define `HAVE_WORKING_FORK'. This macro 3662 checks whether `fork' is just a stub by trying to run it. 3663 3664 If `vfork.h' is found, define `HAVE_VFORK_H'. If a working 3665 `vfork' is found, define `HAVE_WORKING_VFORK'. Otherwise, define 3666 `vfork' to be `fork' for backward compatibility with previous 3667 versions of `autoconf'. This macro checks for several known 3668 errors in implementations of `vfork' and considers the system to 3669 not have a working `vfork' if it detects any of them. It is not 3670 considered to be an implementation error if a child's invocation 3671 of `signal' modifies the parent's signal handler, since child 3672 processes rarely change their signal handlers. 3673 3674 Since this macro defines `vfork' only for backward compatibility 3675 with previous versions of `autoconf' you're encouraged to define it 3676 yourself in new code: 3677 #ifndef HAVE_WORKING_VFORK 3678 # define vfork fork 3679 #endif 3680 3681 -- Macro: AC_FUNC_FSEEKO 3682 If the `fseeko' function is available, define `HAVE_FSEEKO'. 3683 Define `_LARGEFILE_SOURCE' if necessary to make the prototype 3684 visible on some systems (e.g., glibc 2.2). Otherwise linkage 3685 problems may occur when compiling with `AC_SYS_LARGEFILE' on 3686 largefile-sensitive systems where `off_t' does not default to a 3687 64bit entity. 3688 3689 -- Macro: AC_FUNC_GETGROUPS 3690 If the `getgroups' function is available and works (unlike on 3691 Ultrix 4.3, where `getgroups (0, 0)' always fails), define 3692 `HAVE_GETGROUPS'. Set `GETGROUPS_LIBS' to any libraries needed to 3693 get that function. This macro runs `AC_TYPE_GETGROUPS'. 3694 3695 -- Macro: AC_FUNC_GETLOADAVG 3696 Check how to get the system load averages. To perform its tests 3697 properly, this macro needs the file `getloadavg.c'; therefore, be 3698 sure to set the `AC_LIBOBJ' replacement directory properly (see 3699 *Note Generic Functions::, `AC_CONFIG_LIBOBJ_DIR'). 3700 3701 If the system has the `getloadavg' function, define 3702 `HAVE_GETLOADAVG', and set `GETLOADAVG_LIBS' to any libraries 3703 necessary to get that function. Also add `GETLOADAVG_LIBS' to 3704 `LIBS'. Otherwise, require an `AC_LIBOBJ' replacement for 3705 `getloadavg' with source code in `DIR/getloadavg.c', and possibly 3706 define several other C preprocessor macros and output variables: 3707 3708 1. Define `C_GETLOADAVG'. 3709 3710 2. Define `SVR4', `DGUX', `UMAX', or `UMAX4_3' if on those 3711 systems. 3712 3713 3. If `nlist.h' is found, define `HAVE_NLIST_H'. 3714 3715 4. If `struct nlist' has an `n_un.n_name' member, define 3716 `HAVE_STRUCT_NLIST_N_UN_N_NAME'. The obsolete symbol 3717 `NLIST_NAME_UNION' is still defined, but do not depend upon 3718 it. 3719 3720 5. Programs may need to be installed set-group-ID (or 3721 set-user-ID) for `getloadavg' to work. In this case, define 3722 `GETLOADAVG_PRIVILEGED', set the output variable `NEED_SETGID' 3723 to `true' (and otherwise to `false'), and set `KMEM_GROUP' to 3724 the name of the group that should own the installed program. 3725 3726 The `AC_FUNC_GETLOADVG' macro is obsolescent. New programs should 3727 use Gnulib's `getloadavg' module. *Note Gnulib::. 3728 3729 -- Macro: AC_FUNC_GETMNTENT 3730 Check for `getmntent' in the standard C library, and then in the 3731 `sun', `seq', and `gen' libraries, for UNICOS, IRIX 4, PTX, and 3732 UnixWare, respectively. Then, if `getmntent' is available, define 3733 `HAVE_GETMNTENT'. 3734 3735 -- Macro: AC_FUNC_GETPGRP 3736 Define `GETPGRP_VOID' if it is an error to pass 0 to `getpgrp'; 3737 this is the Posix behavior. On older BSD systems, you must pass 0 3738 to `getpgrp', as it takes an argument and behaves like Posix's 3739 `getpgid'. 3740 3741 #ifdef GETPGRP_VOID 3742 pid = getpgrp (); 3743 #else 3744 pid = getpgrp (0); 3745 #endif 3746 3747 This macro does not check whether `getpgrp' exists at all; if you 3748 need to work in that situation, first call `AC_CHECK_FUNC' for 3749 `getpgrp'. 3750 3751 This macro is obsolescent, as current systems have a `getpgrp' 3752 whose signature conforms to Posix. New programs need not use this 3753 macro. 3754 3755 -- Macro: AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK 3756 If `link' is a symbolic link, then `lstat' should treat `link/' 3757 the same as `link/.'. However, many older `lstat' implementations 3758 incorrectly ignore trailing slashes. 3759 3760 It is safe to assume that if `lstat' incorrectly ignores trailing 3761 slashes, then other symbolic-link-aware functions like `unlink' 3762 also incorrectly ignore trailing slashes. 3763 3764 If `lstat' behaves properly, define 3765 `LSTAT_FOLLOWS_SLASHED_SYMLINK', otherwise require an `AC_LIBOBJ' 3766 replacement of `lstat'. 3767 3768 -- Macro: AC_FUNC_MALLOC 3769 If the `malloc' function is compatible with the GNU C library 3770 `malloc' (i.e., `malloc (0)' returns a valid pointer), define 3771 `HAVE_MALLOC' to 1. Otherwise define `HAVE_MALLOC' to 0, ask for 3772 an `AC_LIBOBJ' replacement for `malloc', and define `malloc' to 3773 `rpl_malloc' so that the native `malloc' is not used in the main 3774 project. 3775 3776 Typically, the replacement file `malloc.c' should look like (note 3777 the `#undef malloc'): 3778 3779 3780 #ifdef HAVE_CONFIG_H 3781 # include <config.h> 3782 #endif 3783 #undef malloc 3784 3785 #include <sys/types.h> 3786 3787 void *malloc (); 3788 3789 /* Allocate an N-byte block of memory from the heap. 3790 If N is zero, allocate a 1-byte block. */ 3791 3792 void * 3793 rpl_malloc (size_t n) 3794 { 3795 if (n == 0) 3796 n = 1; 3797 return malloc (n); 3798 } 3799 3800 -- Macro: AC_FUNC_MEMCMP 3801 If the `memcmp' function is not available, or does not work on 3802 8-bit data (like the one on SunOS 4.1.3), or fails when comparing 3803 16 bytes or more and with at least one buffer not starting on a 3804 4-byte boundary (such as the one on NeXT x86 OpenStep), require an 3805 `AC_LIBOBJ' replacement for `memcmp'. 3806 3807 This macro is obsolescent, as current systems have a working 3808 `memcmp'. New programs need not use this macro. 3809 3810 -- Macro: AC_FUNC_MBRTOWC 3811 Define `HAVE_MBRTOWC' to 1 if the function `mbrtowc' and the type 3812 `mbstate_t' are properly declared. 3813 3814 -- Macro: AC_FUNC_MKTIME 3815 If the `mktime' function is not available, or does not work 3816 correctly, require an `AC_LIBOBJ' replacement for `mktime'. For 3817 the purposes of this test, `mktime' should conform to the Posix 3818 standard and should be the inverse of `localtime'. 3819 3820 -- Macro: AC_FUNC_MMAP 3821 If the `mmap' function exists and works correctly, define 3822 `HAVE_MMAP'. This checks only private fixed mapping of 3823 already-mapped memory. 3824 3825 -- Macro: AC_FUNC_OBSTACK 3826 If the obstacks are found, define `HAVE_OBSTACK', else require an 3827 `AC_LIBOBJ' replacement for `obstack'. 3828 3829 -- Macro: AC_FUNC_REALLOC 3830 If the `realloc' function is compatible with the GNU C library 3831 `realloc' (i.e., `realloc (NULL, 0)' returns a valid pointer), 3832 define `HAVE_REALLOC' to 1. Otherwise define `HAVE_REALLOC' to 0, 3833 ask for an `AC_LIBOBJ' replacement for `realloc', and define 3834 `realloc' to `rpl_realloc' so that the native `realloc' is not 3835 used in the main project. See `AC_FUNC_MALLOC' for details. 3836 3837 -- Macro: AC_FUNC_SELECT_ARGTYPES 3838 Determines the correct type to be passed for each of the `select' 3839 function's arguments, and defines those types in 3840 `SELECT_TYPE_ARG1', `SELECT_TYPE_ARG234', and `SELECT_TYPE_ARG5' 3841 respectively. `SELECT_TYPE_ARG1' defaults to `int', 3842 `SELECT_TYPE_ARG234' defaults to `int *', and `SELECT_TYPE_ARG5' 3843 defaults to `struct timeval *'. 3844 3845 This macro is obsolescent, as current systems have a `select' whose 3846 signature conforms to Posix. New programs need not use this macro. 3847 3848 -- Macro: AC_FUNC_SETPGRP 3849 If `setpgrp' takes no argument (the Posix version), define 3850 `SETPGRP_VOID'. Otherwise, it is the BSD version, which takes two 3851 process IDs as arguments. This macro does not check whether 3852 `setpgrp' exists at all; if you need to work in that situation, 3853 first call `AC_CHECK_FUNC' for `setpgrp'. 3854 3855 This macro is obsolescent, as current systems have a `setpgrp' 3856 whose signature conforms to Posix. New programs need not use this 3857 macro. 3858 3859 -- Macro: AC_FUNC_STAT 3860 -- Macro: AC_FUNC_LSTAT 3861 Determine whether `stat' or `lstat' have the bug that it succeeds 3862 when given the zero-length file name as argument. The `stat' and 3863 `lstat' from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do this. 3864 3865 If it does, then define `HAVE_STAT_EMPTY_STRING_BUG' (or 3866 `HAVE_LSTAT_EMPTY_STRING_BUG') and ask for an `AC_LIBOBJ' 3867 replacement of it. 3868 3869 These macros are obsolescent, as no current systems have the bug. 3870 New programs need not use these macros. 3871 3872 -- Macro: AC_FUNC_SETVBUF_REVERSED 3873 If `setvbuf' takes the buffering type as its second argument and 3874 the buffer pointer as the third, instead of the other way around, 3875 define `SETVBUF_REVERSED'. 3876 3877 This macro is obsolescent, as no current systems have the bug. 3878 New programs need not use this macro. 3879 3880 -- Macro: AC_FUNC_STRCOLL 3881 If the `strcoll' function exists and works correctly, define 3882 `HAVE_STRCOLL'. This does a bit more than 3883 `AC_CHECK_FUNCS(strcoll)', because some systems have incorrect 3884 definitions of `strcoll' that should not be used. 3885 3886 -- Macro: AC_FUNC_STRERROR_R 3887 If `strerror_r' is available, define `HAVE_STRERROR_R', and if it 3888 is declared, define `HAVE_DECL_STRERROR_R'. If it returns a `char 3889 *' message, define `STRERROR_R_CHAR_P'; otherwise it returns an 3890 `int' error number. The Thread-Safe Functions option of Posix 3891 requires `strerror_r' to return `int', but many systems 3892 (including, for example, version 2.2.4 of the GNU C Library) 3893 return a `char *' value that is not necessarily equal to the 3894 buffer argument. 3895 3896 -- Macro: AC_FUNC_STRFTIME 3897 Check for `strftime' in the `intl' library, for SCO Unix. Then, 3898 if `strftime' is available, define `HAVE_STRFTIME'. 3899 3900 This macro is obsolescent, as no current systems require the `intl' 3901 library for `strftime'. New programs need not use this macro. 3902 3903 -- Macro: AC_FUNC_STRTOD 3904 If the `strtod' function does not exist or doesn't work correctly, 3905 ask for an `AC_LIBOBJ' replacement of `strtod'. In this case, 3906 because `strtod.c' is likely to need `pow', set the output 3907 variable `POW_LIB' to the extra library needed. 3908 3909 -- Macro: AC_FUNC_STRTOLD 3910 If the `strtold' function exists and conforms to C99, define 3911 `HAVE_STRTOLD'. 3912 3913 -- Macro: AC_FUNC_STRNLEN 3914 If the `strnlen' function is not available, or is buggy (like the 3915 one from AIX 4.3), require an `AC_LIBOBJ' replacement for it. 3916 3917 -- Macro: AC_FUNC_UTIME_NULL 3918 If `utime (FILE, NULL)' sets FILE's timestamp to the present, 3919 define `HAVE_UTIME_NULL'. 3920 3921 This macro is obsolescent, as all current systems have a `utime' 3922 that behaves this way. New programs need not use this macro. 3923 3924 -- Macro: AC_FUNC_VPRINTF 3925 If `vprintf' is found, define `HAVE_VPRINTF'. Otherwise, if 3926 `_doprnt' is found, define `HAVE_DOPRNT'. (If `vprintf' is 3927 available, you may assume that `vfprintf' and `vsprintf' are also 3928 available.) 3929 3930 This macro is obsolescent, as all current systems have `vprintf'. 3931 New programs need not use this macro. 3932 3933 -- Macro: AC_REPLACE_FNMATCH 3934 If the `fnmatch' function does not conform to Posix (see 3935 `AC_FUNC_FNMATCH'), ask for its `AC_LIBOBJ' replacement. 3936 3937 The files `fnmatch.c', `fnmatch_loop.c', and `fnmatch_.h' in the 3938 `AC_LIBOBJ' replacement directory are assumed to contain a copy of 3939 the source code of GNU `fnmatch'. If necessary, this source code 3940 is compiled as an `AC_LIBOBJ' replacement, and the `fnmatch_.h' 3941 file is linked to `fnmatch.h' so that it can be included in place 3942 of the system `<fnmatch.h>'. 3943 3944 This macro is obsolescent, as it assumes the use of particular 3945 source files. New programs should use Gnulib's `fnmatch-posix' 3946 module, which provides this macro along with the source files. 3947 *Note Gnulib::. 3948 3949 3950File: autoconf.info, Node: Generic Functions, Prev: Particular Functions, Up: Library Functions 3951 39525.5.3 Generic Function Checks 3953----------------------------- 3954 3955These macros are used to find functions not covered by the "particular" 3956test macros. If the functions might be in libraries other than the 3957default C library, first call `AC_CHECK_LIB' for those libraries. If 3958you need to check the behavior of a function as well as find out 3959whether it is present, you have to write your own test for it (*note 3960Writing Tests::). 3961 3962 -- Macro: AC_CHECK_FUNC (FUNCTION, [ACTION-IF-FOUND], 3963 [ACTION-IF-NOT-FOUND]) 3964 If C function FUNCTION is available, run shell commands 3965 ACTION-IF-FOUND, otherwise ACTION-IF-NOT-FOUND. If you just want 3966 to define a symbol if the function is available, consider using 3967 `AC_CHECK_FUNCS' instead. This macro checks for functions with C 3968 linkage even when `AC_LANG(C++)' has been called, since C is more 3969 standardized than C++. (*note Language Choice::, for more 3970 information about selecting the language for checks.) 3971 3972 -- Macro: AC_CHECK_FUNCS (FUNCTION..., [ACTION-IF-FOUND], 3973 [ACTION-IF-NOT-FOUND]) 3974 For each FUNCTION enumerated in the blank-or-newline-separated 3975 argument list, define `HAVE_FUNCTION' (in all capitals) if it is 3976 available. If ACTION-IF-FOUND is given, it is additional shell 3977 code to execute when one of the functions is found. You can give 3978 it a value of `break' to break out of the loop on the first match. 3979 If ACTION-IF-NOT-FOUND is given, it is executed when one of the 3980 functions is not found. 3981 3982 -- Macro: AC_CHECK_FUNCS_ONCE (FUNCTION...) 3983 For each FUNCTION enumerated in the blank-or-newline-separated 3984 argument list, define `HAVE_FUNCTION' (in all capitals) if it is 3985 available. This is a once-only variant of `AC_CHECK_FUNCS'. It 3986 generates the checking code at most once, so that `configure' is 3987 smaller and faster; but the checks cannot be conditionalized and 3988 are always done once, early during the `configure' run. 3989 3990 3991 Autoconf follows a philosophy that was formed over the years by those 3992who have struggled for portability: isolate the portability issues in 3993specific files, and then program as if you were in a Posix environment. 3994Some functions may be missing or unfixable, and your package must be 3995ready to replace them. 3996 3997 Suitable replacements for many such problem functions are available 3998from Gnulib (*note Gnulib::). 3999 4000 -- Macro: AC_LIBOBJ (FUNCTION) 4001 Specify that `FUNCTION.c' must be included in the executables to 4002 replace a missing or broken implementation of FUNCTION. 4003 4004 Technically, it adds `FUNCTION.$ac_objext' to the output variable 4005 `LIBOBJS' if it is not already in, and calls `AC_LIBSOURCE' for 4006 `FUNCTION.c'. You should not directly change `LIBOBJS', since 4007 this is not traceable. 4008 4009 -- Macro: AC_LIBSOURCE (FILE) 4010 Specify that FILE might be needed to compile the project. If you 4011 need to know what files might be needed by a `configure.ac', you 4012 should trace `AC_LIBSOURCE'. FILE must be a literal. 4013 4014 This macro is called automatically from `AC_LIBOBJ', but you must 4015 call it explicitly if you pass a shell variable to `AC_LIBOBJ'. In 4016 that case, since shell variables cannot be traced statically, you 4017 must pass to `AC_LIBSOURCE' any possible files that the shell 4018 variable might cause `AC_LIBOBJ' to need. For example, if you 4019 want to pass a variable `$foo_or_bar' to `AC_LIBOBJ' that holds 4020 either `"foo"' or `"bar"', you should do: 4021 4022 AC_LIBSOURCE([foo.c]) 4023 AC_LIBSOURCE([bar.c]) 4024 AC_LIBOBJ([$foo_or_bar]) 4025 4026 There is usually a way to avoid this, however, and you are 4027 encouraged to simply call `AC_LIBOBJ' with literal arguments. 4028 4029 Note that this macro replaces the obsolete `AC_LIBOBJ_DECL', with 4030 slightly different semantics: the old macro took the function name, 4031 e.g., `foo', as its argument rather than the file name. 4032 4033 -- Macro: AC_LIBSOURCES (FILES) 4034 Like `AC_LIBSOURCE', but accepts one or more FILES in a 4035 comma-separated M4 list. Thus, the above example might be 4036 rewritten: 4037 4038 AC_LIBSOURCES([foo.c, bar.c]) 4039 AC_LIBOBJ([$foo_or_bar]) 4040 4041 -- Macro: AC_CONFIG_LIBOBJ_DIR (DIRECTORY) 4042 Specify that `AC_LIBOBJ' replacement files are to be found in 4043 DIRECTORY, a name relative to the top level of the source tree. 4044 The replacement directory defaults to `.', the top level 4045 directory, and the most typical value is `lib', corresponding to 4046 `AC_CONFIG_LIBOBJ_DIR([lib])'. 4047 4048 `configure' might need to know the replacement directory for the 4049 following reasons: (i) some checks use the replacement files, (ii) 4050 some macros bypass broken system headers by installing links to the 4051 replacement headers (iii) when used in conjunction with Automake, 4052 within each makefile, DIRECTORY is used as a relative path from 4053 `$(top_srcdir)' to each object named in `LIBOBJS' and `LTLIBOBJS', 4054 etc. 4055 4056 4057 It is common to merely check for the existence of a function, and ask 4058for its `AC_LIBOBJ' replacement if missing. The following macro is a 4059convenient shorthand. 4060 4061 -- Macro: AC_REPLACE_FUNCS (FUNCTION...) 4062 Like `AC_CHECK_FUNCS', but uses `AC_LIBOBJ(FUNCTION)' as 4063 ACTION-IF-NOT-FOUND. You can declare your replacement function by 4064 enclosing the prototype in `#ifndef HAVE_FUNCTION'. If the system 4065 has the function, it probably declares it in a header file you 4066 should be including, so you shouldn't redeclare it lest your 4067 declaration conflict. 4068 4069 4070File: autoconf.info, Node: Header Files, Next: Declarations, Prev: Library Functions, Up: Existing Tests 4071 40725.6 Header Files 4073================ 4074 4075The following macros check for the presence of certain C header files. 4076If there is no macro specifically defined to check for a header file 4077you need, and you don't need to check for any special properties of it, 4078then you can use one of the general header-file check macros. 4079 4080* Menu: 4081 4082* Header Portability:: Collected knowledge on common headers 4083* Particular Headers:: Special handling to find certain headers 4084* Generic Headers:: How to find other headers 4085 4086 4087File: autoconf.info, Node: Header Portability, Next: Particular Headers, Up: Header Files 4088 40895.6.1 Portability of Headers 4090---------------------------- 4091 4092This section tries to collect knowledge about common headers, and the 4093problems they cause. By definition, this list always requires 4094additions. Please help us keeping it as complete as possible. 4095 4096`limits.h' 4097 C99 says that `limits.h' defines `LLONG_MIN', `LLONG_MAX', and 4098 `ULLONG_MAX', but many almost-C99 environments (e.g., default GCC 4099 4.0.2 + glibc 2.4) do not define them. 4100 4101`inttypes.h' vs. `stdint.h' 4102 The C99 standard says that `inttypes.h' includes `stdint.h', so 4103 there's no need to include `stdint.h' separately in a standard 4104 environment. Some implementations have `inttypes.h' but not 4105 `stdint.h' (e.g., Solaris 7), but we don't know of any 4106 implementation that has `stdint.h' but not `inttypes.h'. 4107 4108`linux/irda.h' 4109 It requires `linux/types.h' and `sys/socket.h'. 4110 4111`linux/random.h' 4112 It requires `linux/types.h'. 4113 4114`net/if.h' 4115 On Darwin, this file requires that `sys/socket.h' be included 4116 beforehand. One should run: 4117 4118 AC_CHECK_HEADERS([sys/socket.h]) 4119 AC_CHECK_HEADERS([net/if.h], [], [], 4120 [#include <stdio.h> 4121 #ifdef STDC_HEADERS 4122 # include <stdlib.h> 4123 # include <stddef.h> 4124 #else 4125 # ifdef HAVE_STDLIB_H 4126 # include <stdlib.h> 4127 # endif 4128 #endif 4129 #ifdef HAVE_SYS_SOCKET_H 4130 # include <sys/socket.h> 4131 #endif 4132 ]) 4133 4134`netinet/if_ether.h' 4135 On Darwin, this file requires that `stdio.h' and `sys/socket.h' be 4136 included beforehand. One should run: 4137 4138 AC_CHECK_HEADERS([sys/socket.h]) 4139 AC_CHECK_HEADERS([netinet/if_ether.h], [], [], 4140 [#include <stdio.h> 4141 #ifdef STDC_HEADERS 4142 # include <stdlib.h> 4143 # include <stddef.h> 4144 #else 4145 # ifdef HAVE_STDLIB_H 4146 # include <stdlib.h> 4147 # endif 4148 #endif 4149 #ifdef HAVE_SYS_SOCKET_H 4150 # include <sys/socket.h> 4151 #endif 4152 ]) 4153 4154`stdint.h' 4155 See above, item `inttypes.h' vs. `stdint.h'. 4156 4157`stdlib.h' 4158 On many systems (e.g., Darwin), `stdio.h' is a prerequisite. 4159 4160`sys/mount.h' 4161 On FreeBSD 4.8 on ia32 and using gcc version 2.95.4, 4162 `sys/params.h' is a prerequisite. 4163 4164`sys/ptem.h' 4165 On Solaris 8, `sys/stream.h' is a prerequisite. 4166 4167`sys/socket.h' 4168 On Darwin, `stdlib.h' is a prerequisite. 4169 4170`sys/ucred.h' 4171 On Tru64 5.1, `sys/types.h' is a prerequisite. 4172 4173`X11/extensions/scrnsaver.h' 4174 Using XFree86, this header requires `X11/Xlib.h', which is probably 4175 so required that you might not even consider looking for it. 4176 4177 AC_CHECK_HEADERS([X11/extensions/scrnsaver.h], [], [], 4178 [[#include <X11/Xlib.h> 4179 ]]) 4180 4181 4182File: autoconf.info, Node: Particular Headers, Next: Generic Headers, Prev: Header Portability, Up: Header Files 4183 41845.6.2 Particular Header Checks 4185------------------------------ 4186 4187These macros check for particular system header files--whether they 4188exist, and in some cases whether they declare certain symbols. 4189 4190 -- Macro: AC_HEADER_ASSERT 4191 Check whether to enable assertions in the style of `assert.h'. 4192 Assertions are enabled by default, but the user can override this 4193 by invoking `configure' with the `--disable-assert' option. 4194 4195 -- Macro: AC_HEADER_DIRENT 4196 Check for the following header files. For the first one that is 4197 found and defines `DIR', define the listed C preprocessor macro: 4198 4199 `dirent.h' `HAVE_DIRENT_H' 4200 `sys/ndir.h' `HAVE_SYS_NDIR_H' 4201 `sys/dir.h' `HAVE_SYS_DIR_H' 4202 `ndir.h' `HAVE_NDIR_H' 4203 4204 The directory-library declarations in your source code should look 4205 something like the following: 4206 4207 #include <sys/types.h> 4208 #ifdef HAVE_DIRENT_H 4209 # include <dirent.h> 4210 # define NAMLEN(dirent) strlen ((dirent)->d_name) 4211 #else 4212 # define dirent direct 4213 # define NAMLEN(dirent) ((dirent)->d_namlen) 4214 # ifdef HAVE_SYS_NDIR_H 4215 # include <sys/ndir.h> 4216 # endif 4217 # ifdef HAVE_SYS_DIR_H 4218 # include <sys/dir.h> 4219 # endif 4220 # ifdef HAVE_NDIR_H 4221 # include <ndir.h> 4222 # endif 4223 #endif 4224 4225 Using the above declarations, the program would declare variables 4226 to be of type `struct dirent', not `struct direct', and would 4227 access the length of a directory entry name by passing a pointer 4228 to a `struct dirent' to the `NAMLEN' macro. 4229 4230 This macro also checks for the SCO Xenix `dir' and `x' libraries. 4231 4232 This macro is obsolescent, as all current systems with directory 4233 libraries have `<dirent.h>'. New programs need not use this macro. 4234 4235 Also see `AC_STRUCT_DIRENT_D_INO' and `AC_STRUCT_DIRENT_D_TYPE' 4236 (*note Particular Structures::). 4237 4238 -- Macro: AC_HEADER_MAJOR 4239 If `sys/types.h' does not define `major', `minor', and `makedev', 4240 but `sys/mkdev.h' does, define `MAJOR_IN_MKDEV'; otherwise, if 4241 `sys/sysmacros.h' does, define `MAJOR_IN_SYSMACROS'. 4242 4243 -- Macro: AC_HEADER_RESOLV 4244 Checks for header `resolv.h', checking for prerequisites first. 4245 To properly use `resolv.h', your code should contain something like 4246 the following: 4247 4248 4249 #ifdef HAVE_SYS_TYPES_H 4250 # include <sys/types.h> 4251 #endif 4252 #ifdef HAVE_NETINET_IN_H 4253 # include <netinet/in.h> /* inet_ functions / structs */ 4254 #endif 4255 #ifdef HAVE_ARPA_NAMESER_H 4256 # include <arpa/nameser.h> /* DNS HEADER struct */ 4257 #endif 4258 #ifdef HAVE_NETDB_H 4259 # include <netdb.h> 4260 #endif 4261 #include <resolv.h> 4262 4263 -- Macro: AC_HEADER_STAT 4264 If the macros `S_ISDIR', `S_ISREG', etc. defined in `sys/stat.h' 4265 do not work properly (returning false positives), define 4266 `STAT_MACROS_BROKEN'. This is the case on Tektronix UTekV, Amdahl 4267 UTS and Motorola System V/88. 4268 4269 This macro is obsolescent, as no current systems have the bug. 4270 New programs need not use this macro. 4271 4272 -- Macro: AC_HEADER_STDBOOL 4273 If `stdbool.h' exists and conforms to C99, define `HAVE_STDBOOL_H' 4274 to 1; if the type `_Bool' is defined, define `HAVE__BOOL' to 1. 4275 To fulfill the C99 requirements, your `system.h' could contain the 4276 following code: 4277 4278 4279 #ifdef HAVE_STDBOOL_H 4280 # include <stdbool.h> 4281 #else 4282 # ifndef HAVE__BOOL 4283 # ifdef __cplusplus 4284 typedef bool _Bool; 4285 # else 4286 # define _Bool signed char 4287 # endif 4288 # endif 4289 # define bool _Bool 4290 # define false 0 4291 # define true 1 4292 # define __bool_true_false_are_defined 1 4293 #endif 4294 4295 Alternatively you can use the `stdbool' package of Gnulib (*note 4296 Gnulib::); it packages the above code into a replacement header 4297 and contains a few other bells and whistles. 4298 4299 4300 -- Macro: AC_HEADER_STDC 4301 Define `STDC_HEADERS' if the system has C header files conforming 4302 to ANSI C89 (ISO C90). Specifically, this macro checks for 4303 `stdlib.h', `stdarg.h', `string.h', and `float.h'; if the system 4304 has those, it probably has the rest of the C89 header files. This 4305 macro also checks whether `string.h' declares `memchr' (and thus 4306 presumably the other `mem' functions), whether `stdlib.h' declare 4307 `free' (and thus presumably `malloc' and other related functions), 4308 and whether the `ctype.h' macros work on characters with the high 4309 bit set, as the C standard requires. 4310 4311 If you use this macro, your code can refer to `STDC_HEADERS' to 4312 determine whether the system has conforming header files (and 4313 probably C library functions). 4314 4315 This macro is obsolescent, as current systems have conforming 4316 header files. New programs need not use this macro. 4317 4318 Nowadays `string.h' is part of the C standard and declares 4319 functions like `strcpy', and `strings.h' is standardized by Posix 4320 and declares BSD functions like `bcopy'; but historically, string 4321 functions were a major sticking point in this area. If you still 4322 want to worry about portability to ancient systems without 4323 standard headers, there is so much variation that it is probably 4324 easier to declare the functions you use than to figure out exactly 4325 what the system header files declare. Some ancient systems 4326 contained a mix of functions from the C standard and from BSD; 4327 some were mostly standard but lacked `memmove'; some defined the 4328 BSD functions as macros in `string.h' or `strings.h'; some had 4329 only the BSD functions but `string.h'; some declared the memory 4330 functions in `memory.h', some in `string.h'; etc. It is probably 4331 sufficient to check for one string function and one memory 4332 function; if the library had the standard versions of those then 4333 it probably had most of the others. If you put the following in 4334 `configure.ac': 4335 4336 # This example is obsolescent. 4337 # Nowadays you can omit these macro calls. 4338 AC_HEADER_STDC 4339 AC_CHECK_FUNCS([strchr memcpy]) 4340 4341 then, in your code, you can use declarations like this: 4342 4343 /* This example is obsolescent. 4344 Nowadays you can just #include <string.h>. */ 4345 #ifdef STDC_HEADERS 4346 # include <string.h> 4347 #else 4348 # ifndef HAVE_STRCHR 4349 # define strchr index 4350 # define strrchr rindex 4351 # endif 4352 char *strchr (), *strrchr (); 4353 # ifndef HAVE_MEMCPY 4354 # define memcpy(d, s, n) bcopy ((s), (d), (n)) 4355 # define memmove(d, s, n) bcopy ((s), (d), (n)) 4356 # endif 4357 #endif 4358 4359 If you use a function like `memchr', `memset', `strtok', or 4360 `strspn', which have no BSD equivalent, then macros don't suffice 4361 to port to ancient hosts; you must provide an implementation of 4362 each function. An easy way to incorporate your implementations 4363 only when needed (since the ones in system C libraries may be hand 4364 optimized) is to, taking `memchr' for example, put it in 4365 `memchr.c' and use `AC_REPLACE_FUNCS([memchr])'. 4366 4367 -- Macro: AC_HEADER_SYS_WAIT 4368 If `sys/wait.h' exists and is compatible with Posix, define 4369 `HAVE_SYS_WAIT_H'. Incompatibility can occur if `sys/wait.h' does 4370 not exist, or if it uses the old BSD `union wait' instead of `int' 4371 to store a status value. If `sys/wait.h' is not Posix compatible, 4372 then instead of including it, define the Posix macros with their 4373 usual interpretations. Here is an example: 4374 4375 #include <sys/types.h> 4376 #ifdef HAVE_SYS_WAIT_H 4377 # include <sys/wait.h> 4378 #endif 4379 #ifndef WEXITSTATUS 4380 # define WEXITSTATUS(stat_val) ((unsigned int) (stat_val) >> 8) 4381 #endif 4382 #ifndef WIFEXITED 4383 # define WIFEXITED(stat_val) (((stat_val) & 255) == 0) 4384 #endif 4385 4386 This macro is obsolescent, as current systems are compatible with 4387 Posix. New programs need not use this macro. 4388 4389 `_POSIX_VERSION' is defined when `unistd.h' is included on Posix 4390systems. If there is no `unistd.h', it is definitely not a Posix 4391system. However, some non-Posix systems do have `unistd.h'. 4392 4393 The way to check whether the system supports Posix is: 4394 4395 #ifdef HAVE_UNISTD_H 4396 # include <sys/types.h> 4397 # include <unistd.h> 4398 #endif 4399 4400 #ifdef _POSIX_VERSION 4401 /* Code for Posix systems. */ 4402 #endif 4403 4404 -- Macro: AC_HEADER_TIME 4405 If a program may include both `time.h' and `sys/time.h', define 4406 `TIME_WITH_SYS_TIME'. On some ancient systems, `sys/time.h' 4407 included `time.h', but `time.h' was not protected against multiple 4408 inclusion, so programs could not explicitly include both files. 4409 This macro is useful in programs that use, for example, `struct 4410 timeval' as well as `struct tm'. It is best used in conjunction 4411 with `HAVE_SYS_TIME_H', which can be checked for using 4412 `AC_CHECK_HEADERS([sys/time.h])'. 4413 4414 #ifdef TIME_WITH_SYS_TIME 4415 # include <sys/time.h> 4416 # include <time.h> 4417 #else 4418 # ifdef HAVE_SYS_TIME_H 4419 # include <sys/time.h> 4420 # else 4421 # include <time.h> 4422 # endif 4423 #endif 4424 4425 This macro is obsolescent, as current systems can include both 4426 files when they exist. New programs need not use this macro. 4427 4428 -- Macro: AC_HEADER_TIOCGWINSZ 4429 If the use of `TIOCGWINSZ' requires `<sys/ioctl.h>', then define 4430 `GWINSZ_IN_SYS_IOCTL'. Otherwise `TIOCGWINSZ' can be found in 4431 `<termios.h>'. 4432 4433 Use: 4434 4435 #ifdef HAVE_TERMIOS_H 4436 # include <termios.h> 4437 #endif 4438 4439 #ifdef GWINSZ_IN_SYS_IOCTL 4440 # include <sys/ioctl.h> 4441 #endif 4442 4443 4444File: autoconf.info, Node: Generic Headers, Prev: Particular Headers, Up: Header Files 4445 44465.6.3 Generic Header Checks 4447--------------------------- 4448 4449These macros are used to find system header files not covered by the 4450"particular" test macros. If you need to check the contents of a header 4451as well as find out whether it is present, you have to write your own 4452test for it (*note Writing Tests::). 4453 4454 -- Macro: AC_CHECK_HEADER (HEADER-FILE, [ACTION-IF-FOUND], 4455 [ACTION-IF-NOT-FOUND], [INCLUDES = `default-includes']) 4456 If the system header file HEADER-FILE is compilable, execute shell 4457 commands ACTION-IF-FOUND, otherwise execute ACTION-IF-NOT-FOUND. 4458 If you just want to define a symbol if the header file is 4459 available, consider using `AC_CHECK_HEADERS' instead. 4460 4461 For compatibility issues with older versions of Autoconf, please 4462 read below. 4463 4464 -- Macro: AC_CHECK_HEADERS (HEADER-FILE..., [ACTION-IF-FOUND], 4465 [ACTION-IF-NOT-FOUND], [INCLUDES = `default-includes']) 4466 For each given system header file HEADER-FILE in the 4467 blank-separated argument list that exists, define 4468 `HAVE_HEADER-FILE' (in all capitals). If ACTION-IF-FOUND is 4469 given, it is additional shell code to execute when one of the 4470 header files is found. You can give it a value of `break' to 4471 break out of the loop on the first match. If ACTION-IF-NOT-FOUND 4472 is given, it is executed when one of the header files is not found. 4473 4474 For compatibility issues with older versions of Autoconf, please 4475 read below. 4476 4477 Previous versions of Autoconf merely checked whether the header was 4478accepted by the preprocessor. This was changed because the old test was 4479inappropriate for typical uses. Headers are typically used to compile, 4480not merely to preprocess, and the old behavior sometimes accepted 4481headers that clashed at compile-time. If you need to check whether a 4482header is preprocessable, you can use `AC_PREPROC_IFELSE' (*note 4483Running the Preprocessor::). 4484 4485 This scheme, which improves the robustness of the test, also requires 4486that you make sure that headers that must be included before the 4487HEADER-FILE be part of the INCLUDES, (*note Default Includes::). If 4488looking for `bar.h', which requires that `foo.h' be included before if 4489it exists, we suggest the following scheme: 4490 4491 4492AC_CHECK_HEADERS([foo.h]) 4493AC_CHECK_HEADERS([bar.h], [], [], 4494[#ifdef HAVE_FOO_H 4495# include <foo.h> 4496# endif 4497]) 4498 4499 The following variant generates smaller, faster `configure' files if 4500you do not need the full power of `AC_CHECK_HEADERS'. 4501 4502 -- Macro: AC_CHECK_HEADERS_ONCE (HEADER-FILE...) 4503 For each given system header file HEADER-FILE in the 4504 blank-separated argument list that exists, define 4505 `HAVE_HEADER-FILE' (in all capitals). This is a once-only variant 4506 of `AC_CHECK_HEADERS'. It generates the checking code at most 4507 once, so that `configure' is smaller and faster; but the checks 4508 cannot be conditionalized and are always done once, early during 4509 the `configure' run. 4510 4511 4512File: autoconf.info, Node: Declarations, Next: Structures, Prev: Header Files, Up: Existing Tests 4513 45145.7 Declarations 4515================ 4516 4517The following macros check for the declaration of variables and 4518functions. If there is no macro specifically defined to check for a 4519symbol you need, then you can use the general macros (*note Generic 4520Declarations::) or, for more complex tests, you may use 4521`AC_COMPILE_IFELSE' (*note Running the Compiler::). 4522 4523* Menu: 4524 4525* Particular Declarations:: Macros to check for certain declarations 4526* Generic Declarations:: How to find other declarations 4527 4528 4529File: autoconf.info, Node: Particular Declarations, Next: Generic Declarations, Up: Declarations 4530 45315.7.1 Particular Declaration Checks 4532----------------------------------- 4533 4534There are no specific macros for declarations. 4535 4536 4537File: autoconf.info, Node: Generic Declarations, Prev: Particular Declarations, Up: Declarations 4538 45395.7.2 Generic Declaration Checks 4540-------------------------------- 4541 4542These macros are used to find declarations not covered by the 4543"particular" test macros. 4544 4545 -- Macro: AC_CHECK_DECL (SYMBOL, [ACTION-IF-FOUND], 4546 [ACTION-IF-NOT-FOUND], [INCLUDES = `default-includes']) 4547 If SYMBOL (a function, variable, or constant) is not declared in 4548 INCLUDES and a declaration is needed, run the shell commands 4549 ACTION-IF-NOT-FOUND, otherwise ACTION-IF-FOUND. If no INCLUDES 4550 are specified, the default includes are used (*note Default 4551 Includes::). 4552 4553 This macro actually tests whether SYMBOL is defined as a macro or 4554 can be used as an r-value, not whether it is really declared, 4555 because it is much safer to avoid introducing extra declarations 4556 when they are not needed. 4557 4558 -- Macro: AC_CHECK_DECLS (SYMBOLS, [ACTION-IF-FOUND], 4559 [ACTION-IF-NOT-FOUND], [INCLUDES = `default-includes']) 4560 For each of the SYMBOLS (_comma_-separated list), define 4561 `HAVE_DECL_SYMBOL' (in all capitals) to `1' if SYMBOL is declared, 4562 otherwise to `0'. If ACTION-IF-NOT-FOUND is given, it is 4563 additional shell code to execute when one of the function 4564 declarations is needed, otherwise ACTION-IF-FOUND is executed. 4565 4566 This macro uses an M4 list as first argument: 4567 AC_CHECK_DECLS([strdup]) 4568 AC_CHECK_DECLS([strlen]) 4569 AC_CHECK_DECLS([malloc, realloc, calloc, free]) 4570 4571 Unlike the other `AC_CHECK_*S' macros, when a SYMBOL is not 4572 declared, `HAVE_DECL_SYMBOL' is defined to `0' instead of leaving 4573 `HAVE_DECL_SYMBOL' undeclared. When you are _sure_ that the check 4574 was performed, use `HAVE_DECL_SYMBOL' in `#if': 4575 4576 #if !HAVE_DECL_SYMBOL 4577 extern char *symbol; 4578 #endif 4579 4580 If the test may have not been performed, however, because it is 4581 safer _not_ to declare a symbol than to use a declaration that 4582 conflicts with the system's one, you should use: 4583 4584 #if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC 4585 void *malloc (size_t *s); 4586 #endif 4587 4588 You fall into the second category only in extreme situations: 4589 either your files may be used without being configured, or they 4590 are used during the configuration. In most cases the traditional 4591 approach is enough. 4592 4593 -- Macro: AC_CHECK_DECLS_ONCE (SYMBOLS) 4594 For each of the SYMBOLS (_comma_-separated list), define 4595 `HAVE_DECL_SYMBOL' (in all capitals) to `1' if SYMBOL is declared 4596 in the default include files, otherwise to `0'. This is a 4597 once-only variant of `AC_CHECK_DECLS'. It generates the checking 4598 code at most once, so that `configure' is smaller and faster; but 4599 the checks cannot be conditionalized and are always done once, 4600 early during the `configure' run. 4601 4602 4603File: autoconf.info, Node: Structures, Next: Types, Prev: Declarations, Up: Existing Tests 4604 46055.8 Structures 4606============== 4607 4608The following macros check for the presence of certain members in C 4609structures. If there is no macro specifically defined to check for a 4610member you need, then you can use the general structure-member macros 4611(*note Generic Structures::) or, for more complex tests, you may use 4612`AC_COMPILE_IFELSE' (*note Running the Compiler::). 4613 4614* Menu: 4615 4616* Particular Structures:: Macros to check for certain structure members 4617* Generic Structures:: How to find other structure members 4618 4619 4620File: autoconf.info, Node: Particular Structures, Next: Generic Structures, Up: Structures 4621 46225.8.1 Particular Structure Checks 4623--------------------------------- 4624 4625The following macros check for certain structures or structure members. 4626 4627 -- Macro: AC_STRUCT_DIRENT_D_INO 4628 Perform all the actions of `AC_HEADER_DIRENT' (*note Particular 4629 Headers::). Then, if `struct dirent' contains a `d_ino' member, 4630 define `HAVE_STRUCT_DIRENT_D_INO'. 4631 4632 `HAVE_STRUCT_DIRENT_D_INO' indicates only the presence of `d_ino', 4633 not whether its contents are always reliable. Traditionally, a 4634 zero `d_ino' indicated a deleted directory entry, though current 4635 systems hide this detail from the user and never return zero 4636 `d_ino' values. Many current systems report an incorrect `d_ino' 4637 for a directory entry that is a mount point. 4638 4639 -- Macro: AC_STRUCT_DIRENT_D_TYPE 4640 Perform all the actions of `AC_HEADER_DIRENT' (*note Particular 4641 Headers::). Then, if `struct dirent' contains a `d_type' member, 4642 define `HAVE_STRUCT_DIRENT_D_TYPE'. 4643 4644 -- Macro: AC_STRUCT_ST_BLKSIZE 4645 If `struct stat' contains an `st_blksize' member, define 4646 `HAVE_STRUCT_STAT_ST_BLKSIZE'. The former name, `HAVE_ST_BLKSIZE' 4647 is to be avoided, as its support will cease in the future. This 4648 macro is obsoleted, and should be replaced by 4649 4650 AC_CHECK_MEMBERS([struct stat.st_blksize]) 4651 4652 -- Macro: AC_STRUCT_ST_BLOCKS 4653 If `struct stat' contains an `st_blocks' member, define 4654 `HAVE_STRUCT_STAT_ST_BLOCKS'. Otherwise, require an `AC_LIBOBJ' 4655 replacement of `fileblocks'. The former name, `HAVE_ST_BLOCKS' is 4656 to be avoided, as its support will cease in the future. 4657 4658 -- Macro: AC_STRUCT_ST_RDEV 4659 If `struct stat' contains an `st_rdev' member, define 4660 `HAVE_STRUCT_STAT_ST_RDEV'. The former name for this macro, 4661 `HAVE_ST_RDEV', is to be avoided as it will cease to be supported 4662 in the future. Actually, even the new macro is obsolete and 4663 should be replaced by: 4664 AC_CHECK_MEMBERS([struct stat.st_rdev]) 4665 4666 -- Macro: AC_STRUCT_TM 4667 If `time.h' does not define `struct tm', define `TM_IN_SYS_TIME', 4668 which means that including `sys/time.h' had better define `struct 4669 tm'. 4670 4671 This macro is obsolescent, as `time.h' defines `struct tm' in 4672 current systems. New programs need not use this macro. 4673 4674 -- Macro: AC_STRUCT_TIMEZONE 4675 Figure out how to get the current timezone. If `struct tm' has a 4676 `tm_zone' member, define `HAVE_STRUCT_TM_TM_ZONE' (and the 4677 obsoleted `HAVE_TM_ZONE'). Otherwise, if the external array 4678 `tzname' is found, define `HAVE_TZNAME'; if it is declared, define 4679 `HAVE_DECL_TZNAME'. 4680 4681 4682File: autoconf.info, Node: Generic Structures, Prev: Particular Structures, Up: Structures 4683 46845.8.2 Generic Structure Checks 4685------------------------------ 4686 4687These macros are used to find structure members not covered by the 4688"particular" test macros. 4689 4690 -- Macro: AC_CHECK_MEMBER (AGGREGATE.MEMBER, [ACTION-IF-FOUND], 4691 [ACTION-IF-NOT-FOUND], [INCLUDES = `default-includes']) 4692 Check whether MEMBER is a member of the aggregate AGGREGATE. If 4693 no INCLUDES are specified, the default includes are used (*note 4694 Default Includes::). 4695 4696 AC_CHECK_MEMBER([struct passwd.pw_gecos], [], 4697 [AC_MSG_ERROR([We need `passwd.pw_gecos'!])], 4698 [#include <pwd.h>]) 4699 4700 You can use this macro for submembers: 4701 4702 AC_CHECK_MEMBER(struct top.middle.bot) 4703 4704 -- Macro: AC_CHECK_MEMBERS (MEMBERS, [ACTION-IF-FOUND], 4705 [ACTION-IF-NOT-FOUND], [INCLUDES = `default-includes']) 4706 Check for the existence of each `AGGREGATE.MEMBER' of MEMBERS 4707 using the previous macro. When MEMBER belongs to AGGREGATE, 4708 define `HAVE_AGGREGATE_MEMBER' (in all capitals, with spaces and 4709 dots replaced by underscores). If ACTION-IF-FOUND is given, it is 4710 executed for each of the found members. If ACTION-IF-NOT-FOUND is 4711 given, it is executed for each of the members that could not be 4712 found. 4713 4714 This macro uses M4 lists: 4715 AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize]) 4716 4717 4718File: autoconf.info, Node: Types, Next: Compilers and Preprocessors, Prev: Structures, Up: Existing Tests 4719 47205.9 Types 4721========= 4722 4723The following macros check for C types, either builtin or typedefs. If 4724there is no macro specifically defined to check for a type you need, and 4725you don't need to check for any special properties of it, then you can 4726use a general type-check macro. 4727 4728* Menu: 4729 4730* Particular Types:: Special handling to find certain types 4731* Generic Types:: How to find other types 4732 4733 4734File: autoconf.info, Node: Particular Types, Next: Generic Types, Up: Types 4735 47365.9.1 Particular Type Checks 4737---------------------------- 4738 4739These macros check for particular C types in `sys/types.h', `stdlib.h', 4740`stdint.h', `inttypes.h' and others, if they exist. 4741 4742 The Gnulib `stdint' module is an alternate way to define many of 4743these symbols; it is useful if you prefer your code to assume a 4744C99-or-better environment. *Note Gnulib::. 4745 4746 -- Macro: AC_TYPE_GETGROUPS 4747 Define `GETGROUPS_T' to be whichever of `gid_t' or `int' is the 4748 base type of the array argument to `getgroups'. 4749 4750 -- Macro: AC_TYPE_INT8_T 4751 If `stdint.h' or `inttypes.h' defines the type `int8_t', define 4752 `HAVE_INT8_T'. Otherwise, define `int8_t' to a signed integer 4753 type that is exactly 8 bits wide and that uses two's complement 4754 representation, if such a type exists. 4755 4756 -- Macro: AC_TYPE_INT16_T 4757 This is like `AC_TYPE_INT8_T', except for 16-bit integers. 4758 4759 -- Macro: AC_TYPE_INT32_T 4760 This is like `AC_TYPE_INT8_T', except for 32-bit integers. 4761 4762 -- Macro: AC_TYPE_INT64_T 4763 This is like `AC_TYPE_INT8_T', except for 64-bit integers. 4764 4765 -- Macro: AC_TYPE_INTMAX_T 4766 If `stdint.h' or `inttypes.h' defines the type `intmax_t', define 4767 `HAVE_INTMAX_T'. Otherwise, define `intmax_t' to the widest 4768 signed integer type. 4769 4770 -- Macro: AC_TYPE_INTPTR_T 4771 If `stdint.h' or `inttypes.h' defines the type `intptr_t', define 4772 `HAVE_INTPTR_T'. Otherwise, define `intptr_t' to a signed integer 4773 type wide enough to hold a pointer, if such a type exists. 4774 4775 -- Macro: AC_TYPE_LONG_DOUBLE 4776 If the C compiler supports a working `long double' type, define 4777 `HAVE_LONG_DOUBLE'. The `long double' type might have the same 4778 range and precision as `double'. 4779 4780 -- Macro: AC_TYPE_LONG_DOUBLE_WIDER 4781 If the C compiler supports a working `long double' type with more 4782 range or precision than the `double' type, define 4783 `HAVE_LONG_DOUBLE_WIDER'. 4784 4785 -- Macro: AC_TYPE_LONG_LONG_INT 4786 If the C compiler supports a working `long long int' type, define 4787 `HAVE_LONG_LONG_INT'. 4788 4789 -- Macro: AC_TYPE_MBSTATE_T 4790 Define `HAVE_MBSTATE_T' if `<wchar.h>' declares the `mbstate_t' 4791 type. Also, define `mbstate_t' to be a type if `<wchar.h>' does 4792 not declare it. 4793 4794 -- Macro: AC_TYPE_MODE_T 4795 Define `mode_t' to a suitable type, if standard headers do not 4796 define it. 4797 4798 -- Macro: AC_TYPE_OFF_T 4799 Define `off_t' to a suitable type, if standard headers do not 4800 define it. 4801 4802 -- Macro: AC_TYPE_PID_T 4803 Define `pid_t' to a suitable type, if standard headers do not 4804 define it. 4805 4806 -- Macro: AC_TYPE_SIGNAL 4807 If `signal.h' declares `signal' as returning a pointer to a 4808 function returning `void', define `RETSIGTYPE' to be `void'; 4809 otherwise, define it to be `int'. 4810 4811 Define signal handlers as returning type `RETSIGTYPE': 4812 4813 RETSIGTYPE 4814 hup_handler () 4815 { 4816 ... 4817 } 4818 4819 -- Macro: AC_TYPE_SIZE_T 4820 Define `size_t' to a suitable type, if standard headers do not 4821 define it. 4822 4823 -- Macro: AC_TYPE_SSIZE_T 4824 Define `ssize_t' to a suitable type, if standard headers do not 4825 define it. 4826 4827 -- Macro: AC_TYPE_UID_T 4828 Define `uid_t' and `gid_t' to suitable types, if standard headers 4829 do not define them. 4830 4831 -- Macro: AC_TYPE_UINT8_T 4832 If `stdint.h' or `inttypes.h' defines the type `uint8_t', define 4833 `HAVE_UINT8_T'. Otherwise, define `uint8_t' to an unsigned 4834 integer type that is exactly 8 bits wide, if such a type exists. 4835 4836 -- Macro: AC_TYPE_UINT16_T 4837 This is like `AC_TYPE_UINT8_T', except for 16-bit unsigned 4838 integers. 4839 4840 -- Macro: AC_TYPE_UINT32_T 4841 This is like `AC_TYPE_UINT8_T', except for 32-bit unsigned 4842 integers. 4843 4844 -- Macro: AC_TYPE_UINT64_T 4845 This is like `AC_TYPE_UINT8_T', except for 64-bit unsigned 4846 integers. 4847 4848 -- Macro: AC_TYPE_UINTMAX_T 4849 If `stdint.h' or `inttypes.h' defines the type `uintmax_t', define 4850 `HAVE_UINTMAX_T'. Otherwise, define `uintmax_t' to the widest 4851 unsigned integer type. 4852 4853 -- Macro: AC_TYPE_UINTPTR_T 4854 If `stdint.h' or `inttypes.h' defines the type `uintptr_t', define 4855 `HAVE_UINTPTR_T'. Otherwise, define `uintptr_t' to an unsigned 4856 integer type wide enough to hold a pointer, if such a type exists. 4857 4858 -- Macro: AC_TYPE_UNSIGNED_LONG_LONG_INT 4859 If the C compiler supports a working `unsigned long long int' type, 4860 define `HAVE_UNSIGNED_LONG_LONG_INT'. 4861 4862 4863File: autoconf.info, Node: Generic Types, Prev: Particular Types, Up: Types 4864 48655.9.2 Generic Type Checks 4866------------------------- 4867 4868These macros are used to check for types not covered by the "particular" 4869test macros. 4870 4871 -- Macro: AC_CHECK_TYPE (TYPE, [ACTION-IF-FOUND], 4872 [ACTION-IF-NOT-FOUND], [INCLUDES = `default-includes']) 4873 Check whether TYPE is defined. It may be a compiler builtin type 4874 or defined by the INCLUDES (*note Default Includes::). 4875 4876 -- Macro: AC_CHECK_TYPES (TYPES, [ACTION-IF-FOUND], 4877 [ACTION-IF-NOT-FOUND], [INCLUDES = `default-includes']) 4878 For each TYPE of the TYPES that is defined, define `HAVE_TYPE' (in 4879 all capitals). If no INCLUDES are specified, the default includes 4880 are used (*note Default Includes::). If ACTION-IF-FOUND is given, 4881 it is additional shell code to execute when one of the types is 4882 found. If ACTION-IF-NOT-FOUND is given, it is executed when one 4883 of the types is not found. 4884 4885 This macro uses M4 lists: 4886 AC_CHECK_TYPES([ptrdiff_t]) 4887 AC_CHECK_TYPES([unsigned long long int, uintmax_t]) 4888 4889 4890 Autoconf, up to 2.13, used to provide to another version of 4891`AC_CHECK_TYPE', broken by design. In order to keep backward 4892compatibility, a simple heuristics, quite safe but not totally, is 4893implemented. In case of doubt, read the documentation of the former 4894`AC_CHECK_TYPE', see *Note Obsolete Macros::. 4895 4896 4897File: autoconf.info, Node: Compilers and Preprocessors, Next: System Services, Prev: Types, Up: Existing Tests 4898 48995.10 Compilers and Preprocessors 4900================================ 4901 4902All the tests for compilers (`AC_PROG_CC', `AC_PROG_CXX', 4903`AC_PROG_F77') define the output variable `EXEEXT' based on the output 4904of the compiler, typically to the empty string if Posix and `.exe' if a 4905DOS variant. 4906 4907 They also define the output variable `OBJEXT' based on the output of 4908the compiler, after `.c' files have been excluded, typically to `o' if 4909Posix, `obj' if a DOS variant. 4910 4911 If the compiler being used does not produce executables, the tests 4912fail. If the executables can't be run, and cross-compilation is not 4913enabled, they fail too. *Note Manual Configuration::, for more on 4914support for cross compiling. 4915 4916* Menu: 4917 4918* Specific Compiler Characteristics:: Some portability issues 4919* Generic Compiler Characteristics:: Language independent tests and features 4920* C Compiler:: Checking its characteristics 4921* C++ Compiler:: Likewise 4922* Objective C Compiler:: Likewise 4923* Erlang Compiler and Interpreter:: Likewise 4924* Fortran Compiler:: Likewise 4925 4926 4927File: autoconf.info, Node: Specific Compiler Characteristics, Next: Generic Compiler Characteristics, Up: Compilers and Preprocessors 4928 49295.10.1 Specific Compiler Characteristics 4930---------------------------------------- 4931 4932Some compilers exhibit different behaviors. 4933 4934Static/Dynamic Expressions 4935 Autoconf relies on a trick to extract one bit of information from 4936 the C compiler: using negative array sizes. For instance the 4937 following excerpt of a C source demonstrates how to test whether 4938 `int' objects are 4 bytes wide: 4939 4940 static int test_array[sizeof (int) == 4 ? 1 : -1]; 4941 4942 To our knowledge, there is a single compiler that does not support 4943 this trick: the HP C compilers (the real ones, not only the 4944 "bundled") on HP-UX 11.00. They incorrectly reject the above 4945 program with the diagnostic "Variable-length arrays cannot have 4946 static storage." This bug comes from HP compilers' mishandling of 4947 `sizeof (int)', not from the `? 1 : -1', and Autoconf works around 4948 this problem by casting `sizeof (int)' to `long int' before 4949 comparing it. 4950 4951 4952File: autoconf.info, Node: Generic Compiler Characteristics, Next: C Compiler, Prev: Specific Compiler Characteristics, Up: Compilers and Preprocessors 4953 49545.10.2 Generic Compiler Characteristics 4955--------------------------------------- 4956 4957 -- Macro: AC_CHECK_SIZEOF (TYPE, [UNUSED], [INCLUDES = 4958 `default-includes']) 4959 Define `SIZEOF_TYPE' (*note Standard Symbols::) to be the size in 4960 bytes of TYPE. If `type' is unknown, it gets a size of 0. If no 4961 INCLUDES are specified, the default includes are used (*note 4962 Default Includes::). 4963 4964 This macro now works even when cross-compiling. The UNUSED 4965 argument was used when cross-compiling. 4966 4967 For example, the call 4968 4969 AC_CHECK_SIZEOF([int *]) 4970 4971 defines `SIZEOF_INT_P' to be 8 on DEC Alpha AXP systems. 4972 4973 -- Macro: AC_CHECK_ALIGNOF (TYPE, [INCLUDES = `default-includes']) 4974 Define `ALIGNOF_TYPE' (*note Standard Symbols::) to be the 4975 alignment in bytes of TYPE. If `type' is unknown, it gets a size 4976 of 0. If no INCLUDES are specified, the default includes are used 4977 (*note Default Includes::). 4978 4979 -- Macro: AC_COMPUTE_INT (VAR, EXPRESSION, [INCLUDES = 4980 `default-includes'], [ACTION-IF-FAILS]) 4981 Store into the shell variable VAR the value of the integer 4982 EXPRESSION. The value should fit in an initializer in a C 4983 variable of type `signed long'. To support cross compilation (in 4984 which case, the macro only works on hosts that use twos-complement 4985 arithmetic), it should be possible to evaluate the expression at 4986 compile-time. If no INCLUDES are specified, the default includes 4987 are used (*note Default Includes::). 4988 4989 Execute ACTION-IF-FAILS if the value cannot be determined 4990 correctly. 4991 4992 -- Macro: AC_LANG_WERROR 4993 Normally Autoconf ignores warnings generated by the compiler, 4994 linker, and preprocessor. If this macro is used, warnings count 4995 as fatal errors for the current language. This macro is useful 4996 when the results of configuration are used where warnings are 4997 unacceptable; for instance, if parts of a program are built with 4998 the GCC `-Werror' option. If the whole program is built using 4999 `-Werror' it is often simpler to put `-Werror' in the compiler 5000 flags (`CFLAGS', etc.). 5001 5002 5003File: autoconf.info, Node: C Compiler, Next: C++ Compiler, Prev: Generic Compiler Characteristics, Up: Compilers and Preprocessors 5004 50055.10.3 C Compiler Characteristics 5006--------------------------------- 5007 5008The following macros provide ways to find and exercise a C Compiler. 5009There are a few constructs that ought to be avoided, but do not deserve 5010being checked for, since they can easily be worked around. 5011 5012Don't use lines containing solitary backslashes 5013 They tickle a bug in the HP-UX C compiler (checked on HP-UX 10.20, 5014 11.00, and 11i). When given the following source: 5015 5016 #ifdef __STDC__ 5017 /\ 5018 * A comment with backslash-newlines in it. %{ %} *\ 5019 \ 5020 / 5021 char str[] = "\\ 5022 " A string with backslash-newlines in it %{ %} \\ 5023 ""; 5024 char apostrophe = '\\ 5025 \ 5026 '\ 5027 '; 5028 #endif 5029 5030 the compiler incorrectly fails with the diagnostics 5031 "Non-terminating comment at end of file" and "Missing `#endif' at 5032 end of file." Removing the lines with solitary backslashes solves 5033 the problem. 5034 5035Don't compile several files at once if output matters to you 5036 Some compilers, such as HP's, report names of files being compiled 5037 when given more than one file operand. For instance: 5038 5039 $ cc a.c b.c 5040 a.c: 5041 b.c: 5042 5043 This can cause problems if you observe the output of the compiler 5044 to detect failures. Invoking `cc -c a.c && cc -c b.c && cc -o c 5045 a.o b.o' solves the issue. 5046 5047Don't rely on `#error' failing 5048 The IRIX C compiler does not fail when #error is preprocessed; it 5049 simply emits a diagnostic and continues, exiting successfully. So, 5050 instead of an error directive like `#error "Unsupported word size"' 5051 it is more portable to use an invalid directive like `#Unsupported 5052 word size' in Autoconf tests. In ordinary source code, `#error' is 5053 OK, since installers with inadequate compilers like IRIX can simply 5054 examine these compilers' diagnostic output. 5055 5056Don't rely on correct `#line' support 5057 On Solaris, `c89' (at least Sun C 5.3 through 5.8) diagnoses 5058 `#line' directives whose line numbers are greater than 32767. 5059 Nothing in Posix makes this invalid. That is why Autoconf stopped 5060 issuing `#line' directives. 5061 5062 -- Macro: AC_PROG_CC ([COMPILER-SEARCH-LIST]) 5063 Determine a C compiler to use. If `CC' is not already set in the 5064 environment, check for `gcc' and `cc', then for other C compilers. 5065 Set output variable `CC' to the name of the compiler found. 5066 5067 This macro may, however, be invoked with an optional first argument 5068 which, if specified, must be a blank-separated list of C compilers 5069 to search for. This just gives the user an opportunity to specify 5070 an alternative search list for the C compiler. For example, if 5071 you didn't like the default order, then you could invoke 5072 `AC_PROG_CC' like this: 5073 5074 AC_PROG_CC([gcc cl cc]) 5075 5076 If the C compiler does not handle function prototypes correctly by 5077 default, try to add an option to output variable `CC' to make it 5078 so. This macro tries various options that select 5079 standard-conformance modes on various systems. 5080 5081 After calling this macro you can check whether the C compiler has 5082 been set to accept ANSI C89 (ISO C90); if not, the shell variable 5083 `ac_cv_prog_cc_c89' is set to `no'. See also `AC_C_PROTOTYPES' 5084 below. 5085 5086 If using the GNU C compiler, set shell variable `GCC' to `yes'. 5087 If output variable `CFLAGS' was not already set, set it to `-g 5088 -O2' for the GNU C compiler (`-O2' on systems where GCC does not 5089 accept `-g'), or `-g' for other compilers. 5090 5091 -- Macro: AC_PROG_CC_C_O 5092 If the C compiler does not accept the `-c' and `-o' options 5093 simultaneously, define `NO_MINUS_C_MINUS_O'. This macro actually 5094 tests both the compiler found by `AC_PROG_CC', and, if different, 5095 the first `cc' in the path. The test fails if one fails. This 5096 macro was created for GNU Make to choose the default C compilation 5097 rule. 5098 5099 -- Macro: AC_PROG_CPP 5100 Set output variable `CPP' to a command that runs the C 5101 preprocessor. If `$CC -E' doesn't work, `/lib/cpp' is used. It 5102 is only portable to run `CPP' on files with a `.c' extension. 5103 5104 Some preprocessors don't indicate missing include files by the 5105 error status. For such preprocessors an internal variable is set 5106 that causes other macros to check the standard error from the 5107 preprocessor and consider the test failed if any warnings have 5108 been reported. For most preprocessors, though, warnings do not 5109 cause include-file tests to fail unless `AC_PROG_CPP_WERROR' is 5110 also specified. 5111 5112 -- Macro: AC_PROG_CPP_WERROR 5113 This acts like `AC_PROG_CPP', except it treats warnings from the 5114 preprocessor as errors even if the preprocessor exit status 5115 indicates success. This is useful for avoiding headers that 5116 generate mandatory warnings, such as deprecation notices. 5117 5118 The following macros check for C compiler or machine architecture 5119features. To check for characteristics not listed here, use 5120`AC_COMPILE_IFELSE' (*note Running the Compiler::) or `AC_RUN_IFELSE' 5121(*note Runtime::). 5122 5123 -- Macro: AC_PROG_CC_STDC 5124 If the C compiler cannot compile ISO Standard C (currently C99), 5125 try to add an option to output variable `CC' to make it work. If 5126 the compiler does not support C99, fall back to supporting ANSI 5127 C89 (ISO C90). 5128 5129 After calling this macro you can check whether the C compiler has 5130 been set to accept Standard C; if not, the shell variable 5131 `ac_cv_prog_cc_stdc' is set to `no'. 5132 5133 -- Macro: AC_PROG_CC_C89 5134 If the C compiler is not in ANSI C89 (ISO C90) mode by default, 5135 try to add an option to output variable `CC' to make it so. This 5136 macro tries various options that select ANSI C89 on some system or 5137 another. It considers the compiler to be in ANSI C89 mode if it 5138 handles function prototypes correctly. 5139 5140 After calling this macro you can check whether the C compiler has 5141 been set to accept ANSI C89; if not, the shell variable 5142 `ac_cv_prog_cc_c89' is set to `no'. 5143 5144 This macro is called automatically by `AC_PROG_CC'. 5145 5146 -- Macro: AC_PROG_CC_C99 5147 If the C compiler is not in C99 mode by default, try to add an 5148 option to output variable `CC' to make it so. This macro tries 5149 various options that select C99 on some system or another. It 5150 considers the compiler to be in C99 mode if it handles `_Bool', 5151 `//' comments, flexible array members, `inline', `long long int', 5152 mixed code and declarations, named initialization of structs, 5153 `restrict', `va_copy', varargs macros, variable declarations in 5154 `for' loops, and variable length arrays. 5155 5156 After calling this macro you can check whether the C compiler has 5157 been set to accept C99; if not, the shell variable 5158 `ac_cv_prog_cc_c99' is set to `no'. 5159 5160 -- Macro: AC_C_BACKSLASH_A 5161 Define `HAVE_C_BACKSLASH_A' to 1 if the C compiler understands 5162 `\a'. 5163 5164 This macro is obsolescent, as current C compilers understand `\a'. 5165 New programs need not use this macro. 5166 5167 -- Macro: AC_C_BIGENDIAN ([ACTION-IF-TRUE], [ACTION-IF-FALSE], 5168 [ACTION-IF-UNKNOWN]) 5169 If words are stored with the most significant byte first (like 5170 Motorola and SPARC CPUs), execute ACTION-IF-TRUE. If words are 5171 stored with the least significant byte first (like Intel and VAX 5172 CPUs), execute ACTION-IF-FALSE. 5173 5174 This macro runs a test-case if endianness cannot be determined 5175 from the system header files. When cross-compiling, the test-case 5176 is not run but grep'ed for some magic values. ACTION-IF-UNKNOWN 5177 is executed if the latter case fails to determine the byte sex of 5178 the host system. 5179 5180 The default for ACTION-IF-TRUE is to define `WORDS_BIGENDIAN'. 5181 The default for ACTION-IF-FALSE is to do nothing. And finally, 5182 the default for ACTION-IF-UNKNOWN is to abort configure and tell 5183 the installer which variable he should preset to bypass this test. 5184 5185 -- Macro: AC_C_CONST 5186 If the C compiler does not fully support the `const' keyword, 5187 define `const' to be empty. Some C compilers that do not define 5188 `__STDC__' do support `const'; some compilers that define 5189 `__STDC__' do not completely support `const'. Programs can simply 5190 use `const' as if every C compiler supported it; for those that 5191 don't, the makefile or configuration header file defines it as 5192 empty. 5193 5194 Occasionally installers use a C++ compiler to compile C code, 5195 typically because they lack a C compiler. This causes problems 5196 with `const', because C and C++ treat `const' differently. For 5197 example: 5198 5199 const int foo; 5200 5201 is valid in C but not in C++. These differences unfortunately 5202 cannot be papered over by defining `const' to be empty. 5203 5204 If `autoconf' detects this situation, it leaves `const' alone, as 5205 this generally yields better results in practice. However, using a 5206 C++ compiler to compile C code is not recommended or supported, and 5207 installers who run into trouble in this area should get a C 5208 compiler like GCC to compile their C code. 5209 5210 This macro is obsolescent, as current C compilers support `const'. 5211 New programs need not use this macro. 5212 5213 -- Macro: AC_C_RESTRICT 5214 If the C compiler recognizes the `restrict' keyword, don't do 5215 anything. If it recognizes only a variant spelling (`__restrict', 5216 `__restrict__', or `_Restrict'), then define `restrict' to that. 5217 Otherwise, define `restrict' to be empty. Thus, programs may 5218 simply use `restrict' as if every C compiler supported it; for 5219 those that do not, the makefile or configuration header defines it 5220 away. 5221 5222 Although support in C++ for the `restrict' keyword is not 5223 required, several C++ compilers do accept the keyword. This macro 5224 works for them, too. 5225 5226 -- Macro: AC_C_VOLATILE 5227 If the C compiler does not understand the keyword `volatile', 5228 define `volatile' to be empty. Programs can simply use `volatile' 5229 as if every C compiler supported it; for those that do not, the 5230 makefile or configuration header defines it as empty. 5231 5232 If the correctness of your program depends on the semantics of 5233 `volatile', simply defining it to be empty does, in a sense, break 5234 your code. However, given that the compiler does not support 5235 `volatile', you are at its mercy anyway. At least your program 5236 compiles, when it wouldn't before. *Note Volatile Objects::, for 5237 more about `volatile'. 5238 5239 In general, the `volatile' keyword is a standard C feature, so you 5240 might expect that `volatile' is available only when `__STDC__' is 5241 defined. However, Ultrix 4.3's native compiler does support 5242 volatile, but does not define `__STDC__'. 5243 5244 This macro is obsolescent, as current C compilers support 5245 `volatile'. New programs need not use this macro. 5246 5247 -- Macro: AC_C_INLINE 5248 If the C compiler supports the keyword `inline', do nothing. 5249 Otherwise define `inline' to `__inline__' or `__inline' if it 5250 accepts one of those, otherwise define `inline' to be empty. 5251 5252 -- Macro: AC_C_CHAR_UNSIGNED 5253 If the C type `char' is unsigned, define `__CHAR_UNSIGNED__', 5254 unless the C compiler predefines it. 5255 5256 -- Macro: AC_C_STRINGIZE 5257 If the C preprocessor supports the stringizing operator, define 5258 `HAVE_STRINGIZE'. The stringizing operator is `#' and is found in 5259 macros such as this: 5260 5261 #define x(y) #y 5262 5263 This macro is obsolescent, as current C compilers support the 5264 stringizing operator. New programs need not use this macro. 5265 5266 -- Macro: AC_C_FLEXIBLE_ARRAY_MEMBER 5267 If the C compiler supports flexible array members, define 5268 `FLEXIBLE_ARRAY_MEMBER' to nothing; otherwise define it to 1. 5269 That way, a declaration like this: 5270 5271 struct s 5272 { 5273 size_t n_vals; 5274 double val[FLEXIBLE_ARRAY_MEMBER]; 5275 }; 5276 5277 will let applications use the "struct hack" even with compilers 5278 that do not support flexible array members. To allocate and use 5279 such an object, you can use code like this: 5280 5281 size_t i; 5282 size_t n = compute_value_count (); 5283 struct s *p = 5284 malloc (offsetof (struct s, val) 5285 + n * sizeof (double)); 5286 p->n_vals = n; 5287 for (i = 0; i < n; i++) 5288 p->val[i] = compute_value (i); 5289 5290 -- Macro: AC_C_VARARRAYS 5291 If the C compiler supports variable-length arrays, define 5292 `HAVE_C_VARRAYS'. A variable-length array is an array of automatic 5293 storage duration whose length is determined at run time, when the 5294 array is declared. 5295 5296 -- Macro: AC_C_TYPEOF 5297 If the C compiler supports GCC's `typeof' syntax either directly or 5298 through a different spelling of the keyword (e.g., `__typeof__'), 5299 define `HAVE_TYPEOF'. If the support is available only through a 5300 different spelling, define `typeof' to that spelling. 5301 5302 -- Macro: AC_C_PROTOTYPES 5303 If function prototypes are understood by the compiler (as 5304 determined by `AC_PROG_CC'), define `PROTOTYPES' and 5305 `__PROTOTYPES'. Defining `__PROTOTYPES' is for the benefit of 5306 header files that cannot use macros that infringe on user name 5307 space. 5308 5309 This macro is obsolescent, as current C compilers support 5310 prototypes. New programs need not use this macro. 5311 5312 -- Macro: AC_PROG_GCC_TRADITIONAL 5313 Add `-traditional' to output variable `CC' if using the GNU C 5314 compiler and `ioctl' does not work properly without 5315 `-traditional'. That usually happens when the fixed header files 5316 have not been installed on an old system. 5317 5318 This macro is obsolescent, since current versions of the GNU C 5319 compiler fix the header files automatically when installed. 5320 5321 5322File: autoconf.info, Node: C++ Compiler, Next: Objective C Compiler, Prev: C Compiler, Up: Compilers and Preprocessors 5323 53245.10.4 C++ Compiler Characteristics 5325----------------------------------- 5326 5327 -- Macro: AC_PROG_CXX ([COMPILER-SEARCH-LIST]) 5328 Determine a C++ compiler to use. Check whether the environment 5329 variable `CXX' or `CCC' (in that order) is set; if so, then set 5330 output variable `CXX' to its value. 5331 5332 Otherwise, if the macro is invoked without an argument, then 5333 search for a C++ compiler under the likely names (first `g++' and 5334 `c++' then other names). If none of those checks succeed, then as 5335 a last resort set `CXX' to `g++'. 5336 5337 This macro may, however, be invoked with an optional first argument 5338 which, if specified, must be a blank-separated list of C++ 5339 compilers to search for. This just gives the user an opportunity 5340 to specify an alternative search list for the C++ compiler. For 5341 example, if you didn't like the default order, then you could 5342 invoke `AC_PROG_CXX' like this: 5343 5344 AC_PROG_CXX([gcc cl KCC CC cxx cc++ xlC aCC c++ g++]) 5345 5346 If using the GNU C++ compiler, set shell variable `GXX' to `yes'. 5347 If output variable `CXXFLAGS' was not already set, set it to `-g 5348 -O2' for the GNU C++ compiler (`-O2' on systems where G++ does not 5349 accept `-g'), or `-g' for other compilers. 5350 5351 -- Macro: AC_PROG_CXXCPP 5352 Set output variable `CXXCPP' to a command that runs the C++ 5353 preprocessor. If `$CXX -E' doesn't work, `/lib/cpp' is used. It 5354 is portable to run `CXXCPP' only on files with a `.c', `.C', 5355 `.cc', or `.cpp' extension. 5356 5357 Some preprocessors don't indicate missing include files by the 5358 error status. For such preprocessors an internal variable is set 5359 that causes other macros to check the standard error from the 5360 preprocessor and consider the test failed if any warnings have 5361 been reported. However, it is not known whether such broken 5362 preprocessors exist for C++. 5363 5364 -- Macro: AC_PROG_CXX_C_O 5365 Test whether the C++ compiler accepts the options `-c' and `-o' 5366 simultaneously, and define `CXX_NO_MINUS_C_MINUS_O', if it does 5367 not. 5368 5369 5370File: autoconf.info, Node: Objective C Compiler, Next: Erlang Compiler and Interpreter, Prev: C++ Compiler, Up: Compilers and Preprocessors 5371 53725.10.5 Objective C Compiler Characteristics 5373------------------------------------------- 5374 5375 -- Macro: AC_PROG_OBJC ([COMPILER-SEARCH-LIST]) 5376 Determine an Objective C compiler to use. If `OBJC' is not already 5377 set in the environment, check for Objective C compilers. Set 5378 output variable `OBJC' to the name of the compiler found. 5379 5380 This macro may, however, be invoked with an optional first argument 5381 which, if specified, must be a blank-separated list of Objective C 5382 compilers to search for. This just gives the user an opportunity 5383 to specify an alternative search list for the Objective C 5384 compiler. For example, if you didn't like the default order, then 5385 you could invoke `AC_PROG_OBJC' like this: 5386 5387 AC_PROG_OBJC([gcc objcc objc]) 5388 5389 If using the GNU Objective C compiler, set shell variable `GOBJC' 5390 to `yes'. If output variable `OBJCFLAGS' was not already set, set 5391 it to `-g -O2' for the GNU Objective C compiler (`-O2' on systems 5392 where `gcc' does not accept `-g'), or `-g' for other compilers. 5393 5394 -- Macro: AC_PROG_OBJCCPP 5395 Set output variable `OBJCCPP' to a command that runs the Objective 5396 C preprocessor. If `$OBJC -E' doesn't work, `/lib/cpp' is used. 5397 5398 5399File: autoconf.info, Node: Erlang Compiler and Interpreter, Next: Fortran Compiler, Prev: Objective C Compiler, Up: Compilers and Preprocessors 5400 54015.10.6 Erlang Compiler and Interpreter Characteristics 5402------------------------------------------------------ 5403 5404Autoconf defines the following macros for determining paths to the 5405essential Erlang/OTP programs: 5406 5407 -- Macro: AC_ERLANG_PATH_ERLC ([VALUE-IF-NOT-FOUND], [PATH]) 5408 Determine an Erlang compiler to use. If `ERLC' is not already set 5409 in the environment, check for `erlc'. Set output variable `ERLC' 5410 to the complete path of the compiler command found. In addition, 5411 if `ERLCFLAGS' is not set in the environment, set it to an empty 5412 value. 5413 5414 The two optional arguments have the same meaning as the two last 5415 arguments of macro `AC_PROG_PATH' for looking for the `erlc' 5416 program. For example, to look for `erlc' only in the 5417 `/usr/lib/erlang/bin' directory: 5418 5419 AC_ERLANG_PATH_ERLC([not found], [/usr/lib/erlang/bin]) 5420 5421 -- Macro: AC_ERLANG_NEED_ERLC ([PATH]) 5422 A simplified variant of the `AC_ERLANG_PATH_ERLC' macro, that 5423 prints an error message and exits the `configure' script if the 5424 `erlc' program is not found. 5425 5426 -- Macro: AC_ERLANG_PATH_ERL ([VALUE-IF-NOT-FOUND], [PATH]) 5427 Determine an Erlang interpreter to use. If `ERL' is not already 5428 set in the environment, check for `erl'. Set output variable 5429 `ERL' to the complete path of the interpreter command found. 5430 5431 The two optional arguments have the same meaning as the two last 5432 arguments of macro `AC_PROG_PATH' for looking for the `erl' 5433 program. For example, to look for `erl' only in the 5434 `/usr/lib/erlang/bin' directory: 5435 5436 AC_ERLANG_PATH_ERL([not found], [/usr/lib/erlang/bin]) 5437 5438 -- Macro: AC_ERLANG_NEED_ERL ([PATH]) 5439 A simplified variant of the `AC_ERLANG_PATH_ERL' macro, that 5440 prints an error message and exits the `configure' script if the 5441 `erl' program is not found. 5442 5443 5444File: autoconf.info, Node: Fortran Compiler, Prev: Erlang Compiler and Interpreter, Up: Compilers and Preprocessors 5445 54465.10.7 Fortran Compiler Characteristics 5447--------------------------------------- 5448 5449The Autoconf Fortran support is divided into two categories: legacy 5450Fortran 77 macros (`F77'), and modern Fortran macros (`FC'). The 5451former are intended for traditional Fortran 77 code, and have output 5452variables like `F77', `FFLAGS', and `FLIBS'. The latter are for newer 5453programs that can (or must) compile under the newer Fortran standards, 5454and have output variables like `FC', `FCFLAGS', and `FCLIBS'. 5455 5456 Except for two new macros `AC_FC_SRCEXT' and `AC_FC_FREEFORM' (see 5457below), the `FC' and `F77' macros behave almost identically, and so 5458they are documented together in this section. 5459 5460 -- Macro: AC_PROG_F77 ([COMPILER-SEARCH-LIST]) 5461 Determine a Fortran 77 compiler to use. If `F77' is not already 5462 set in the environment, then check for `g77' and `f77', and then 5463 some other names. Set the output variable `F77' to the name of 5464 the compiler found. 5465 5466 This macro may, however, be invoked with an optional first argument 5467 which, if specified, must be a blank-separated list of Fortran 77 5468 compilers to search for. This just gives the user an opportunity 5469 to specify an alternative search list for the Fortran 77 compiler. 5470 For example, if you didn't like the default order, then you could 5471 invoke `AC_PROG_F77' like this: 5472 5473 AC_PROG_F77([fl32 f77 fort77 xlf g77 f90 xlf90]) 5474 5475 If using `g77' (the GNU Fortran 77 compiler), then set the shell 5476 variable `G77' to `yes'. If the output variable `FFLAGS' was not 5477 already set in the environment, then set it to `-g -02' for `g77' 5478 (or `-O2' where `g77' does not accept `-g'). Otherwise, set 5479 `FFLAGS' to `-g' for all other Fortran 77 compilers. 5480 5481 -- Macro: AC_PROG_FC ([COMPILER-SEARCH-LIST], [DIALECT]) 5482 Determine a Fortran compiler to use. If `FC' is not already set in 5483 the environment, then `dialect' is a hint to indicate what Fortran 5484 dialect to search for; the default is to search for the newest 5485 available dialect. Set the output variable `FC' to the name of 5486 the compiler found. 5487 5488 By default, newer dialects are preferred over older dialects, but 5489 if `dialect' is specified then older dialects are preferred 5490 starting with the specified dialect. `dialect' can currently be 5491 one of Fortran 77, Fortran 90, or Fortran 95. However, this is 5492 only a hint of which compiler _name_ to prefer (e.g., `f90' or 5493 `f95'), and no attempt is made to guarantee that a particular 5494 language standard is actually supported. Thus, it is preferable 5495 that you avoid the `dialect' option, and use AC_PROG_FC only for 5496 code compatible with the latest Fortran standard. 5497 5498 This macro may, alternatively, be invoked with an optional first 5499 argument which, if specified, must be a blank-separated list of 5500 Fortran compilers to search for, just as in `AC_PROG_F77'. 5501 5502 If the output variable `FCFLAGS' was not already set in the 5503 environment, then set it to `-g -02' for GNU `g77' (or `-O2' where 5504 `g77' does not accept `-g'). Otherwise, set `FCFLAGS' to `-g' for 5505 all other Fortran compilers. 5506 5507 -- Macro: AC_PROG_F77_C_O 5508 -- Macro: AC_PROG_FC_C_O 5509 Test whether the Fortran compiler accepts the options `-c' and 5510 `-o' simultaneously, and define `F77_NO_MINUS_C_MINUS_O' or 5511 `FC_NO_MINUS_C_MINUS_O', respectively, if it does not. 5512 5513 The following macros check for Fortran compiler characteristics. To 5514check for characteristics not listed here, use `AC_COMPILE_IFELSE' 5515(*note Running the Compiler::) or `AC_RUN_IFELSE' (*note Runtime::), 5516making sure to first set the current language to Fortran 77 or Fortran 5517via `AC_LANG([Fortran 77])' or `AC_LANG(Fortran)' (*note Language 5518Choice::). 5519 5520 -- Macro: AC_F77_LIBRARY_LDFLAGS 5521 -- Macro: AC_FC_LIBRARY_LDFLAGS 5522 Determine the linker flags (e.g., `-L' and `-l') for the "Fortran 5523 intrinsic and runtime libraries" that are required to successfully 5524 link a Fortran program or shared library. The output variable 5525 `FLIBS' or `FCLIBS' is set to these flags (which should be 5526 included after `LIBS' when linking). 5527 5528 This macro is intended to be used in those situations when it is 5529 necessary to mix, e.g., C++ and Fortran source code in a single 5530 program or shared library (*note Mixing Fortran 77 With C and C++: 5531 (automake)Mixing Fortran 77 With C and C++.). 5532 5533 For example, if object files from a C++ and Fortran compiler must 5534 be linked together, then the C++ compiler/linker must be used for 5535 linking (since special C++-ish things need to happen at link time 5536 like calling global constructors, instantiating templates, 5537 enabling exception support, etc.). 5538 5539 However, the Fortran intrinsic and runtime libraries must be 5540 linked in as well, but the C++ compiler/linker doesn't know by 5541 default how to add these Fortran 77 libraries. Hence, this macro 5542 was created to determine these Fortran libraries. 5543 5544 The macros `AC_F77_DUMMY_MAIN' and `AC_FC_DUMMY_MAIN' or 5545 `AC_F77_MAIN' and `AC_FC_MAIN' are probably also necessary to link 5546 C/C++ with Fortran; see below. 5547 5548 -- Macro: AC_F77_DUMMY_MAIN ([ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND]) 5549 -- Macro: AC_FC_DUMMY_MAIN ([ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND]) 5550 With many compilers, the Fortran libraries detected by 5551 `AC_F77_LIBRARY_LDFLAGS' or `AC_FC_LIBRARY_LDFLAGS' provide their 5552 own `main' entry function that initializes things like Fortran 5553 I/O, and which then calls a user-provided entry function named 5554 (say) `MAIN__' to run the user's program. The `AC_F77_DUMMY_MAIN' 5555 and `AC_FC_DUMMY_MAIN' or `AC_F77_MAIN' and `AC_FC_MAIN' macros 5556 figure out how to deal with this interaction. 5557 5558 When using Fortran for purely numerical functions (no I/O, etc.) 5559 often one prefers to provide one's own `main' and skip the Fortran 5560 library initializations. In this case, however, one may still 5561 need to provide a dummy `MAIN__' routine in order to prevent 5562 linking errors on some systems. `AC_F77_DUMMY_MAIN' or 5563 `AC_FC_DUMMY_MAIN' detects whether any such routine is _required_ 5564 for linking, and what its name is; the shell variable 5565 `F77_DUMMY_MAIN' or `FC_DUMMY_MAIN' holds this name, `unknown' 5566 when no solution was found, and `none' when no such dummy main is 5567 needed. 5568 5569 By default, ACTION-IF-FOUND defines `F77_DUMMY_MAIN' or 5570 `FC_DUMMY_MAIN' to the name of this routine (e.g., `MAIN__') _if_ 5571 it is required. ACTION-IF-NOT-FOUND defaults to exiting with an 5572 error. 5573 5574 In order to link with Fortran routines, the user's C/C++ program 5575 should then include the following code to define the dummy main if 5576 it is needed: 5577 5578 #ifdef F77_DUMMY_MAIN 5579 # ifdef __cplusplus 5580 extern "C" 5581 # endif 5582 int F77_DUMMY_MAIN() { return 1; } 5583 #endif 5584 5585 (Replace `F77' with `FC' for Fortran instead of Fortran 77.) 5586 5587 Note that this macro is called automatically from `AC_F77_WRAPPERS' 5588 or `AC_FC_WRAPPERS'; there is generally no need to call it 5589 explicitly unless one wants to change the default actions. 5590 5591 -- Macro: AC_F77_MAIN 5592 -- Macro: AC_FC_MAIN 5593 As discussed above, many Fortran libraries allow you to provide an 5594 entry point called (say) `MAIN__' instead of the usual `main', 5595 which is then called by a `main' function in the Fortran libraries 5596 that initializes things like Fortran I/O. The `AC_F77_MAIN' and 5597 `AC_FC_MAIN' macros detect whether it is _possible_ to utilize 5598 such an alternate main function, and defines `F77_MAIN' and 5599 `FC_MAIN' to the name of the function. (If no alternate main 5600 function name is found, `F77_MAIN' and `FC_MAIN' are simply 5601 defined to `main'.) 5602 5603 Thus, when calling Fortran routines from C that perform things 5604 like I/O, one should use this macro and name the "main" function 5605 `F77_MAIN' or `FC_MAIN' instead of `main'. 5606 5607 -- Macro: AC_F77_WRAPPERS 5608 -- Macro: AC_FC_WRAPPERS 5609 Defines C macros `F77_FUNC (name, NAME)', `FC_FUNC (name, NAME)', 5610 `F77_FUNC_(name, NAME)', and `FC_FUNC_(name, NAME)' to properly 5611 mangle the names of C/C++ identifiers, and identifiers with 5612 underscores, respectively, so that they match the name-mangling 5613 scheme used by the Fortran compiler. 5614 5615 Fortran is case-insensitive, and in order to achieve this the 5616 Fortran compiler converts all identifiers into a canonical case 5617 and format. To call a Fortran subroutine from C or to write a C 5618 function that is callable from Fortran, the C program must 5619 explicitly use identifiers in the format expected by the Fortran 5620 compiler. In order to do this, one simply wraps all C identifiers 5621 in one of the macros provided by `AC_F77_WRAPPERS' or 5622 `AC_FC_WRAPPERS'. For example, suppose you have the following 5623 Fortran 77 subroutine: 5624 5625 subroutine foobar (x, y) 5626 double precision x, y 5627 y = 3.14159 * x 5628 return 5629 end 5630 5631 You would then declare its prototype in C or C++ as: 5632 5633 #define FOOBAR_F77 F77_FUNC (foobar, FOOBAR) 5634 #ifdef __cplusplus 5635 extern "C" /* prevent C++ name mangling */ 5636 #endif 5637 void FOOBAR_F77(double *x, double *y); 5638 5639 Note that we pass both the lowercase and uppercase versions of the 5640 function name to `F77_FUNC' so that it can select the right one. 5641 Note also that all parameters to Fortran 77 routines are passed as 5642 pointers (*note Mixing Fortran 77 With C and C++: (automake)Mixing 5643 Fortran 77 With C and C++.). 5644 5645 (Replace `F77' with `FC' for Fortran instead of Fortran 77.) 5646 5647 Although Autoconf tries to be intelligent about detecting the 5648 name-mangling scheme of the Fortran compiler, there may be Fortran 5649 compilers that it doesn't support yet. In this case, the above 5650 code generates a compile-time error, but some other behavior 5651 (e.g., disabling Fortran-related features) can be induced by 5652 checking whether `F77_FUNC' or `FC_FUNC' is defined. 5653 5654 Now, to call that routine from a C program, we would do something 5655 like: 5656 5657 { 5658 double x = 2.7183, y; 5659 FOOBAR_F77 (&x, &y); 5660 } 5661 5662 If the Fortran identifier contains an underscore (e.g., `foo_bar'), 5663 you should use `F77_FUNC_' or `FC_FUNC_' instead of `F77_FUNC' or 5664 `FC_FUNC' (with the same arguments). This is because some Fortran 5665 compilers mangle names differently if they contain an underscore. 5666 5667 -- Macro: AC_F77_FUNC (NAME, [SHELLVAR]) 5668 -- Macro: AC_FC_FUNC (NAME, [SHELLVAR]) 5669 Given an identifier NAME, set the shell variable SHELLVAR to hold 5670 the mangled version NAME according to the rules of the Fortran 5671 linker (see also `AC_F77_WRAPPERS' or `AC_FC_WRAPPERS'). SHELLVAR 5672 is optional; if it is not supplied, the shell variable is simply 5673 NAME. The purpose of this macro is to give the caller a way to 5674 access the name-mangling information other than through the C 5675 preprocessor as above, for example, to call Fortran routines from 5676 some language other than C/C++. 5677 5678 -- Macro: AC_FC_SRCEXT (EXT, [ACTION-IF-SUCCESS], [ACTION-IF-FAILURE]) 5679 By default, the `FC' macros perform their tests using a `.f' 5680 extension for source-code files. Some compilers, however, only 5681 enable newer language features for appropriately named files, 5682 e.g., Fortran 90 features only for `.f90' files. On the other 5683 hand, some other compilers expect all source files to end in `.f' 5684 and require special flags to support other file name extensions. 5685 The `AC_FC_SRCEXT' macro deals with both of these issues. 5686 5687 The `AC_FC_SRCEXT' tries to get the `FC' compiler to accept files 5688 ending with the extension .EXT (i.e., EXT does _not_ contain the 5689 dot). If any special compiler flags are needed for this, it 5690 stores them in the output variable `FCFLAGS_'EXT. This extension 5691 and these flags are then used for all subsequent `FC' tests (until 5692 `AC_FC_SRCEXT' is called again). 5693 5694 For example, you would use `AC_FC_SRCEXT(f90)' to employ the 5695 `.f90' extension in future tests, and it would set a `FCFLAGS_f90' 5696 output variable with any extra flags that are needed to compile 5697 such files. 5698 5699 The `FCFLAGS_'EXT can _not_ be simply absorbed into `FCFLAGS', for 5700 two reasons based on the limitations of some compilers. First, 5701 only one `FCFLAGS_'EXT can be used at a time, so files with 5702 different extensions must be compiled separately. Second, 5703 `FCFLAGS_'EXT must appear _immediately_ before the source-code 5704 file name when compiling. So, continuing the example above, you 5705 might compile a `foo.f90' file in your makefile with the command: 5706 5707 foo.o: foo.f90 5708 $(FC) -c $(FCFLAGS) $(FCFLAGS_f90) '$(srcdir)/foo.f90' 5709 5710 If `AC_FC_SRCEXT' succeeds in compiling files with the EXT 5711 extension, it calls ACTION-IF-SUCCESS (defaults to nothing). If 5712 it fails, and cannot find a way to make the `FC' compiler accept 5713 such files, it calls ACTION-IF-FAILURE (defaults to exiting with an 5714 error message). 5715 5716 5717 -- Macro: AC_FC_FREEFORM ([ACTION-IF-SUCCESS], [ACTION-IF-FAILURE]) 5718 The `AC_FC_FREEFORM' tries to ensure that the Fortran compiler 5719 (`$FC') allows free-format source code (as opposed to the older 5720 fixed-format style from Fortran 77). If necessary, it may add some 5721 additional flags to `FCFLAGS'. 5722 5723 This macro is most important if you are using the default `.f' 5724 extension, since many compilers interpret this extension as 5725 indicating fixed-format source unless an additional flag is 5726 supplied. If you specify a different extension with 5727 `AC_FC_SRCEXT', such as `.f90' or `.f95', then `AC_FC_FREEFORM' 5728 ordinarily succeeds without modifying `FCFLAGS'. 5729 5730 If `AC_FC_FREEFORM' succeeds in compiling free-form source, it 5731 calls ACTION-IF-SUCCESS (defaults to nothing). If it fails, it 5732 calls ACTION-IF-FAILURE (defaults to exiting with an error 5733 message). 5734 5735 5736File: autoconf.info, Node: System Services, Next: Posix Variants, Prev: Compilers and Preprocessors, Up: Existing Tests 5737 57385.11 System Services 5739==================== 5740 5741The following macros check for operating system services or 5742capabilities. 5743 5744 -- Macro: AC_PATH_X 5745 Try to locate the X Window System include files and libraries. If 5746 the user gave the command line options `--x-includes=DIR' and 5747 `--x-libraries=DIR', use those directories. 5748 5749 If either or both were not given, get the missing values by running 5750 `xmkmf' (or an executable pointed to by the `XMKMF' environment 5751 variable) on a trivial `Imakefile' and examining the makefile that 5752 it produces. Setting `XMKMF' to `false' disables this method. 5753 5754 If this method fails to find the X Window System, `configure' 5755 looks for the files in several directories where they often reside. 5756 If either method is successful, set the shell variables 5757 `x_includes' and `x_libraries' to their locations, unless they are 5758 in directories the compiler searches by default. 5759 5760 If both methods fail, or the user gave the command line option 5761 `--without-x', set the shell variable `no_x' to `yes'; otherwise 5762 set it to the empty string. 5763 5764 -- Macro: AC_PATH_XTRA 5765 An enhanced version of `AC_PATH_X'. It adds the C compiler flags 5766 that X needs to output variable `X_CFLAGS', and the X linker flags 5767 to `X_LIBS'. Define `X_DISPLAY_MISSING' if X is not available. 5768 5769 This macro also checks for special libraries that some systems 5770 need in order to compile X programs. It adds any that the system 5771 needs to output variable `X_EXTRA_LIBS'. And it checks for 5772 special X11R6 libraries that need to be linked with before 5773 `-lX11', and adds any found to the output variable `X_PRE_LIBS'. 5774 5775 5776 -- Macro: AC_SYS_INTERPRETER 5777 Check whether the system supports starting scripts with a line of 5778 the form `#!/bin/sh' to select the interpreter to use for the 5779 script. After running this macro, shell code in `configure.ac' 5780 can check the shell variable `interpval'; it is set to `yes' if 5781 the system supports `#!', `no' if not. 5782 5783 -- Macro: AC_SYS_LARGEFILE 5784 Arrange for large-file support 5785 (http://www.unix-systems.org/version2/whatsnew/lfs20mar.html). On 5786 some hosts, one must use special compiler options to build 5787 programs that can access large files. Append any such options to 5788 the output variable `CC'. Define `_FILE_OFFSET_BITS' and 5789 `_LARGE_FILES' if necessary. 5790 5791 Large-file support can be disabled by configuring with the 5792 `--disable-largefile' option. 5793 5794 If you use this macro, check that your program works even when 5795 `off_t' is wider than `long int', since this is common when 5796 large-file support is enabled. For example, it is not correct to 5797 print an arbitrary `off_t' value `X' with `printf ("%ld", (long 5798 int) X)'. 5799 5800 The LFS introduced the `fseeko' and `ftello' functions to replace 5801 their C counterparts `fseek' and `ftell' that do not use `off_t'. 5802 Take care to use `AC_FUNC_FSEEKO' to make their prototypes 5803 available when using them and large-file support is enabled. 5804 5805 -- Macro: AC_SYS_LONG_FILE_NAMES 5806 If the system supports file names longer than 14 characters, define 5807 `HAVE_LONG_FILE_NAMES'. 5808 5809 -- Macro: AC_SYS_POSIX_TERMIOS 5810 Check to see if the Posix termios headers and functions are 5811 available on the system. If so, set the shell variable 5812 `ac_cv_sys_posix_termios' to `yes'. If not, set the variable to 5813 `no'. 5814 5815 5816File: autoconf.info, Node: Posix Variants, Next: Erlang Libraries, Prev: System Services, Up: Existing Tests 5817 58185.12 Posix Variants 5819=================== 5820 5821The following macros check for certain operating systems that need 5822special treatment for some programs, due to exceptional oddities in 5823their header files or libraries. These macros are warts; they will be 5824replaced by a more systematic approach, based on the functions they make 5825available or the environments they provide. 5826 5827 -- Macro: AC_AIX 5828 If on AIX, define `_ALL_SOURCE'. Allows the use of some BSD 5829 functions. Should be called before any macros that run the C 5830 compiler. 5831 5832 -- Macro: AC_GNU_SOURCE 5833 If using the GNU C library, define `_GNU_SOURCE'. Allows the use 5834 of some GNU functions. Should be called before any macros that 5835 run the C compiler. 5836 5837 -- Macro: AC_ISC_POSIX 5838 For INTERACTIVE Systems Corporation Unix, add `-lcposix' to output 5839 variable `LIBS' if necessary for Posix facilities. Call this 5840 after `AC_PROG_CC' and before any other macros that use Posix 5841 interfaces. 5842 5843 This macro is obsolescent, as INTERACTIVE Unix is obsolete, and Sun 5844 dropped support for it on 2006-07-23. New programs need not use 5845 this macro. 5846 5847 -- Macro: AC_MINIX 5848 If on Minix, define `_MINIX' and `_POSIX_SOURCE' and define 5849 `_POSIX_1_SOURCE' to be 2. This allows the use of Posix 5850 facilities. Should be called before any macros that run the C 5851 compiler. 5852 5853 -- Macro: AC_USE_SYSTEM_EXTENSIONS 5854 If possible, enable extensions to Posix on hosts that normally 5855 disable the extensions, typically due to standards-conformance 5856 namespace issues. This may involve defining `__EXTENSIONS__' and 5857 `_POSIX_PTHREAD_SEMANTICS', which are macros used by Solaris. It 5858 also defines `_TANDEM_SOURCE' for the HP NonStop platform. This 5859 macro also has the combined effects of `AC_GNU_SOURCE', `AC_AIX', 5860 and `AC_MINIX'. 5861 5862 5863File: autoconf.info, Node: Erlang Libraries, Prev: Posix Variants, Up: Existing Tests 5864 58655.13 Erlang Libraries 5866===================== 5867 5868The following macros check for an installation of Erlang/OTP, and for 5869the presence of certain Erlang libraries. All those macros require the 5870configuration of an Erlang interpreter and an Erlang compiler (*note 5871Erlang Compiler and Interpreter::). 5872 5873 -- Macro: AC_ERLANG_SUBST_ROOT_DIR 5874 Set the output variable `ERLANG_ROOT_DIR' to the path to the base 5875 directory in which Erlang/OTP is installed (as returned by 5876 Erlang's `code:root_dir/0' function). The result of this test is 5877 cached if caching is enabled when running `configure'. 5878 5879 -- Macro: AC_ERLANG_SUBST_LIB_DIR 5880 Set the output variable `ERLANG_LIB_DIR' to the path of the library 5881 directory of Erlang/OTP (as returned by Erlang's `code:lib_dir/0' 5882 function), which subdirectories each contain an installed 5883 Erlang/OTP library. The result of this test is cached if caching 5884 is enabled when running `configure'. 5885 5886 -- Macro: AC_ERLANG_CHECK_LIB (LIBRARY, [ACTION-IF-FOUND], 5887 [ACTION-IF-NOT-FOUND]) 5888 Test whether the Erlang/OTP library LIBRARY is installed by 5889 calling Erlang's `code:lib_dir/1' function. The result of this 5890 test is cached if caching is enabled when running `configure'. 5891 ACTION-IF-FOUND is a list of shell commands to run if the library 5892 is installed; ACTION-IF-NOT-FOUND is a list of shell commands to 5893 run if it is not. Additionally, if the library is installed, the 5894 output variable `ERLANG_LIB_DIR_LIBRARY' is set to the path to the 5895 library installation directory, and the output variable 5896 `ERLANG_LIB_VER_LIBRARY' is set to the version number that is part 5897 of the subdirectory name, if it is in the standard form 5898 (`LIBRARY-VERSION'). If the directory name does not have a 5899 version part, `ERLANG_LIB_VER_LIBRARY' is set to the empty string. 5900 If the library is not installed, `ERLANG_LIB_DIR_LIBRARY' and 5901 `ERLANG_LIB_VER_LIBRARY' are set to `"not found"'. For example, 5902 to check if library `stdlib' is installed: 5903 5904 AC_ERLANG_CHECK_LIB([stdlib], 5905 [echo "stdlib version \"$ERLANG_LIB_VER_stdlib\"" 5906 echo "is installed in \"$ERLANG_LIB_DIR_stdlib\""], 5907 [AC_MSG_ERROR([stdlib was not found!])]) 5908 5909 In addition to the above macros, which test installed Erlang 5910libraries, the following macros determine the paths to the directories 5911into which newly built Erlang libraries are to be installed: 5912 5913 -- Macro: AC_ERLANG_SUBST_INSTALL_LIB_DIR 5914 Set the `ERLANG_INSTALL_LIB_DIR' output variable to the directory 5915 into which every built Erlang library should be installed in a 5916 separate subdirectory. If this variable is not set in the 5917 environment when `configure' runs, its default value is 5918 `$ERLANG_LIB_DIR', which value is set by the 5919 `AC_ERLANG_SUBST_LIB_DIR' macro. 5920 5921 -- Macro: AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR (LIBRARY, VERSION) 5922 Set the `ERLANG_INSTALL_LIB_DIR_LIBRARY' output variable to the 5923 directory into which the built Erlang library LIBRARY version 5924 VERSION should be installed. If this variable is not set in the 5925 environment when `configure' runs, its default value is 5926 `$ERLANG_INSTALL_LIB_DIR/LIBRARY-VERSION', the value of the 5927 `ERLANG_INSTALL_LIB_DIR' variable being set by the 5928 `AC_ERLANG_SUBST_INSTALL_LIB_DIR' macro. 5929 5930 5931File: autoconf.info, Node: Writing Tests, Next: Results, Prev: Existing Tests, Up: Top 5932 59336 Writing Tests 5934*************** 5935 5936If the existing feature tests don't do something you need, you have to 5937write new ones. These macros are the building blocks. They provide 5938ways for other macros to check whether various kinds of features are 5939available and report the results. 5940 5941 This chapter contains some suggestions and some of the reasons why 5942the existing tests are written the way they are. You can also learn a 5943lot about how to write Autoconf tests by looking at the existing ones. 5944If something goes wrong in one or more of the Autoconf tests, this 5945information can help you understand the assumptions behind them, which 5946might help you figure out how to best solve the problem. 5947 5948 These macros check the output of the compiler system of the current 5949language (*note Language Choice::). They do not cache the results of 5950their tests for future use (*note Caching Results::), because they don't 5951know enough about the information they are checking for to generate a 5952cache variable name. They also do not print any messages, for the same 5953reason. The checks for particular kinds of features call these macros 5954and do cache their results and print messages about what they're 5955checking for. 5956 5957 When you write a feature test that could be applicable to more than 5958one software package, the best thing to do is encapsulate it in a new 5959macro. *Note Writing Autoconf Macros::, for how to do that. 5960 5961* Menu: 5962 5963* Language Choice:: Selecting which language to use for testing 5964* Writing Test Programs:: Forging source files for compilers 5965* Running the Preprocessor:: Detecting preprocessor symbols 5966* Running the Compiler:: Detecting language or header features 5967* Running the Linker:: Detecting library features 5968* Runtime:: Testing for runtime features 5969* Systemology:: A zoology of operating systems 5970* Multiple Cases:: Tests for several possible values 5971 5972 5973File: autoconf.info, Node: Language Choice, Next: Writing Test Programs, Up: Writing Tests 5974 59756.1 Language Choice 5976=================== 5977 5978Autoconf-generated `configure' scripts check for the C compiler and its 5979features by default. Packages that use other programming languages 5980(maybe more than one, e.g., C and C++) need to test features of the 5981compilers for the respective languages. The following macros determine 5982which programming language is used in the subsequent tests in 5983`configure.ac'. 5984 5985 -- Macro: AC_LANG (LANGUAGE) 5986 Do compilation tests using the compiler, preprocessor, and file 5987 extensions for the specified LANGUAGE. 5988 5989 Supported languages are: 5990 5991 `C' 5992 Do compilation tests using `CC' and `CPP' and use extension 5993 `.c' for test programs. Use compilation flags: `CPPFLAGS' 5994 with `CPP', and both `CPPFLAGS' and `CFLAGS' with `CC'. 5995 5996 `C++' 5997 Do compilation tests using `CXX' and `CXXCPP' and use 5998 extension `.C' for test programs. Use compilation flags: 5999 `CPPFLAGS' with `CXXPP', and both `CPPFLAGS' and `CXXFLAGS' 6000 with `CXX'. 6001 6002 `Fortran 77' 6003 Do compilation tests using `F77' and use extension `.f' for 6004 test programs. Use compilation flags: `FFLAGS'. 6005 6006 `Fortran' 6007 Do compilation tests using `FC' and use extension `.f' (or 6008 whatever has been set by `AC_FC_SRCEXT') for test programs. 6009 Use compilation flags: `FCFLAGS'. 6010 6011 `Erlang' 6012 Compile and execute tests using `ERLC' and `ERL' and use 6013 extension `.erl' for test Erlang modules. Use compilation 6014 flags: `ERLCFLAGS'. 6015 6016 `Objective C' 6017 Do compilation tests using `OBJC' and `OBJCCPP' and use 6018 extension `.m' for test programs. Use compilation flags: 6019 `CPPFLAGS' with `OBJCPP', and both `CPPFLAGS' and `OBJCFLAGS' 6020 with `OBJC'. 6021 6022 -- Macro: AC_LANG_PUSH (LANGUAGE) 6023 Remember the current language (as set by `AC_LANG') on a stack, and 6024 then select the LANGUAGE. Use this macro and `AC_LANG_POP' in 6025 macros that need to temporarily switch to a particular language. 6026 6027 -- Macro: AC_LANG_POP ([LANGUAGE]) 6028 Select the language that is saved on the top of the stack, as set 6029 by `AC_LANG_PUSH', and remove it from the stack. 6030 6031 If given, LANGUAGE specifies the language we just _quit_. It is a 6032 good idea to specify it when it's known (which should be the 6033 case...), since Autoconf detects inconsistencies. 6034 6035 AC_LANG_PUSH([Fortran 77]) 6036 # Perform some tests on Fortran 77. 6037 # ... 6038 AC_LANG_POP([Fortran 77]) 6039 6040 -- Macro: AC_LANG_ASSERT (LANGUAGE) 6041 Check statically that the current language is LANGUAGE. You 6042 should use this in your language specific macros to avoid that 6043 they be called with an inappropriate language. 6044 6045 This macro runs only at `autoconf' time, and incurs no cost at 6046 `configure' time. Sadly enough and because Autoconf is a two 6047 layer language (1), the macros `AC_LANG_PUSH' and `AC_LANG_POP' 6048 cannot be "optimizing", therefore as much as possible you ought to 6049 avoid using them to wrap your code, rather, require from the user 6050 to run the macro with a correct current language, and check it 6051 with `AC_LANG_ASSERT'. And anyway, that may help the user 6052 understand she is running a Fortran macro while expecting a result 6053 about her Fortran 77 compiler... 6054 6055 -- Macro: AC_REQUIRE_CPP 6056 Ensure that whichever preprocessor would currently be used for 6057 tests has been found. Calls `AC_REQUIRE' (*note Prerequisite 6058 Macros::) with an argument of either `AC_PROG_CPP' or 6059 `AC_PROG_CXXCPP', depending on which language is current. 6060 6061 ---------- Footnotes ---------- 6062 6063 (1) Because M4 is not aware of Sh code, especially conditionals, 6064some optimizations that look nice statically may produce incorrect 6065results at runtime. 6066 6067 6068File: autoconf.info, Node: Writing Test Programs, Next: Running the Preprocessor, Prev: Language Choice, Up: Writing Tests 6069 60706.2 Writing Test Programs 6071========================= 6072 6073Autoconf tests follow a common scheme: feed some program with some 6074input, and most of the time, feed a compiler with some source file. 6075This section is dedicated to these source samples. 6076 6077* Menu: 6078 6079* Guidelines:: General rules for writing test programs 6080* Test Functions:: Avoiding pitfalls in test programs 6081* Generating Sources:: Source program boilerplate 6082 6083 6084File: autoconf.info, Node: Guidelines, Next: Test Functions, Up: Writing Test Programs 6085 60866.2.1 Guidelines for Test Programs 6087---------------------------------- 6088 6089The most important rule to follow when writing testing samples is: 6090 6091 _Look for realism._ 6092 6093 This motto means that testing samples must be written with the same 6094strictness as real programs are written. In particular, you should 6095avoid "shortcuts" and simplifications. 6096 6097 Don't just play with the preprocessor if you want to prepare a 6098compilation. For instance, using `cpp' to check whether a header is 6099functional might let your `configure' accept a header which causes some 6100_compiler_ error. Do not hesitate to check a header with other headers 6101included before, especially required headers. 6102 6103 Make sure the symbols you use are properly defined, i.e., refrain for 6104simply declaring a function yourself instead of including the proper 6105header. 6106 6107 Test programs should not write to standard output. They should exit 6108with status 0 if the test succeeds, and with status 1 otherwise, so 6109that success can be distinguished easily from a core dump or other 6110failure; segmentation violations and other failures produce a nonzero 6111exit status. Unless you arrange for `exit' to be declared, test 6112programs should `return', not `exit', from `main', because on many 6113systems `exit' is not declared by default. 6114 6115 Test programs can use `#if' or `#ifdef' to check the values of 6116preprocessor macros defined by tests that have already run. For 6117example, if you call `AC_HEADER_STDBOOL', then later on in 6118`configure.ac' you can have a test program that includes `stdbool.h' 6119conditionally: 6120 6121 #ifdef HAVE_STDBOOL_H 6122 # include <stdbool.h> 6123 #endif 6124 6125 Both `#if HAVE_STDBOOL_H' and `#ifdef HAVE_STDBOOL_H' will work with 6126any standard C compiler. Some developers prefer `#if' because it is 6127easier to read, while others prefer `#ifdef' because it avoids 6128diagnostics with picky compilers like GCC with the `-Wundef' option. 6129 6130 If a test program needs to use or create a data file, give it a name 6131that starts with `conftest', such as `conftest.data'. The `configure' 6132script cleans up by running `rm -f -r conftest*' after running test 6133programs and if the script is interrupted. 6134 6135 6136File: autoconf.info, Node: Test Functions, Next: Generating Sources, Prev: Guidelines, Up: Writing Test Programs 6137 61386.2.2 Test Functions 6139-------------------- 6140 6141These days it's safe to assume support for function prototypes 6142(introduced in C89). 6143 6144 Functions that test programs declare should also be conditionalized 6145for C++, which requires `extern "C"' prototypes. Make sure to not 6146include any header files containing clashing prototypes. 6147 6148 #ifdef __cplusplus 6149 extern "C" 6150 #endif 6151 void *valloc (size_t); 6152 6153 If a test program calls a function with invalid parameters (just to 6154see whether it exists), organize the program to ensure that it never 6155invokes that function. You can do this by calling it in another 6156function that is never invoked. You can't do it by putting it after a 6157call to `exit', because GCC version 2 knows that `exit' never returns 6158and optimizes out any code that follows it in the same block. 6159 6160 If you include any header files, be sure to call the functions 6161relevant to them with the correct number of arguments, even if they are 6162just 0, to avoid compilation errors due to prototypes. GCC version 2 6163has internal prototypes for several functions that it automatically 6164inlines; for example, `memcpy'. To avoid errors when checking for 6165them, either pass them the correct number of arguments or redeclare them 6166with a different return type (such as `char'). 6167 6168 6169File: autoconf.info, Node: Generating Sources, Prev: Test Functions, Up: Writing Test Programs 6170 61716.2.3 Generating Sources 6172------------------------ 6173 6174Autoconf provides a set of macros that can be used to generate test 6175source files. They are written to be language generic, i.e., they 6176actually depend on the current language (*note Language Choice::) to 6177"format" the output properly. 6178 6179 -- Macro: AC_LANG_CONFTEST (SOURCE) 6180 Save the SOURCE text in the current test source file: 6181 `conftest.EXTENSION' where the EXTENSION depends on the current 6182 language. 6183 6184 Note that the SOURCE is evaluated exactly once, like regular 6185 Autoconf macro arguments, and therefore (i) you may pass a macro 6186 invocation, (ii) if not, be sure to double quote if needed. 6187 6188 -- Macro: AC_LANG_SOURCE (SOURCE) 6189 Expands into the SOURCE, with the definition of all the 6190 `AC_DEFINE' performed so far. 6191 6192 For instance executing (observe the double quotation!): 6193 6194 AC_INIT([Hello], [1.0], [bug-hello@example.org]) 6195 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"], 6196 [Greetings string.]) 6197 AC_LANG(C) 6198 AC_LANG_CONFTEST( 6199 [AC_LANG_SOURCE([[const char hw[] = "Hello, World\n";]])]) 6200 gcc -E -dD -o - conftest.c 6201 6202results in: 6203 6204 ... 6205 # 1 "conftest.c" 6206 6207 #define PACKAGE_NAME "Hello" 6208 #define PACKAGE_TARNAME "hello" 6209 #define PACKAGE_VERSION "1.0" 6210 #define PACKAGE_STRING "Hello 1.0" 6211 #define PACKAGE_BUGREPORT "bug-hello@example.org" 6212 #define HELLO_WORLD "Hello, World\n" 6213 6214 const char hw[] = "Hello, World\n"; 6215 6216 When the test language is Fortran or Erlang, the `AC_DEFINE' 6217definitions are not automatically translated into constants in the 6218source code by this macro. 6219 6220 -- Macro: AC_LANG_PROGRAM (PROLOGUE, BODY) 6221 Expands into a source file which consists of the PROLOGUE, and 6222 then BODY as body of the main function (e.g., `main' in C). Since 6223 it uses `AC_LANG_SOURCE', the features of the latter are available. 6224 6225 For instance: 6226 6227 AC_INIT([Hello], [1.0], [bug-hello@example.org]) 6228 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"], 6229 [Greetings string.]) 6230 AC_LANG_CONFTEST( 6231 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]], 6232 [[fputs (hw, stdout);]])]) 6233 gcc -E -dD -o - conftest.c 6234 6235results in: 6236 6237 ... 6238 # 1 "conftest.c" 6239 6240 #define PACKAGE_NAME "Hello" 6241 #define PACKAGE_TARNAME "hello" 6242 #define PACKAGE_VERSION "1.0" 6243 #define PACKAGE_STRING "Hello 1.0" 6244 #define PACKAGE_BUGREPORT "bug-hello@example.org" 6245 #define HELLO_WORLD "Hello, World\n" 6246 6247 const char hw[] = "Hello, World\n"; 6248 int 6249 main () 6250 { 6251 fputs (hw, stdout); 6252 ; 6253 return 0; 6254 } 6255 6256 In Erlang tests, the created source file is that of an Erlang module 6257called `conftest' (`conftest.erl'). This module defines and exports at 6258least one `start/0' function, which is called to perform the test. The 6259PROLOGUE is optional code that is inserted between the module header and 6260the `start/0' function definition. BODY is the body of the `start/0' 6261function without the final period (*note Runtime::, about constraints 6262on this function's behavior). 6263 6264 For instance: 6265 6266 AC_INIT([Hello], [1.0], [bug-hello@example.org]) 6267 AC_LANG(Erlang) 6268 AC_LANG_CONFTEST( 6269 [AC_LANG_PROGRAM([[-define(HELLO_WORLD, "Hello, world!").]], 6270 [[io:format("~s~n", [?HELLO_WORLD])]])]) 6271 cat conftest.erl 6272 6273results in: 6274 6275 -module(conftest). 6276 -export([start/0]). 6277 -define(HELLO_WORLD, "Hello, world!"). 6278 start() -> 6279 io:format("~s~n", [?HELLO_WORLD]) 6280 . 6281 6282 -- Macro: AC_LANG_CALL (PROLOGUE, FUNCTION) 6283 Expands into a source file which consists of the PROLOGUE, and 6284 then a call to the FUNCTION as body of the main function (e.g., 6285 `main' in C). Since it uses `AC_LANG_PROGRAM', the feature of the 6286 latter are available. 6287 6288 This function will probably be replaced in the future by a version 6289 which would enable specifying the arguments. The use of this 6290 macro is not encouraged, as it violates strongly the typing system. 6291 6292 This macro cannot be used for Erlang tests. 6293 6294 -- Macro: AC_LANG_FUNC_LINK_TRY (FUNCTION) 6295 Expands into a source file which uses the FUNCTION in the body of 6296 the main function (e.g., `main' in C). Since it uses 6297 `AC_LANG_PROGRAM', the features of the latter are available. 6298 6299 As `AC_LANG_CALL', this macro is documented only for completeness. 6300 It is considered to be severely broken, and in the future will be 6301 removed in favor of actual function calls (with properly typed 6302 arguments). 6303 6304 This macro cannot be used for Erlang tests. 6305 6306 6307File: autoconf.info, Node: Running the Preprocessor, Next: Running the Compiler, Prev: Writing Test Programs, Up: Writing Tests 6308 63096.3 Running the Preprocessor 6310============================ 6311 6312Sometimes one might need to run the preprocessor on some source file. 6313_Usually it is a bad idea_, as you typically need to _compile_ your 6314project, not merely run the preprocessor on it; therefore you certainly 6315want to run the compiler, not the preprocessor. Resist the temptation 6316of following the easiest path. 6317 6318 Nevertheless, if you need to run the preprocessor, then use 6319`AC_PREPROC_IFELSE'. 6320 6321 The macros described in this section cannot be used for tests in 6322Erlang or Fortran, since those languages require no preprocessor. 6323 6324 -- Macro: AC_PREPROC_IFELSE (INPUT, [ACTION-IF-TRUE], 6325 [ACTION-IF-FALSE]) 6326 Run the preprocessor of the current language (*note Language 6327 Choice::) on the INPUT, run the shell commands ACTION-IF-TRUE on 6328 success, ACTION-IF-FALSE otherwise. The INPUT can be made by 6329 `AC_LANG_PROGRAM' and friends. 6330 6331 This macro uses `CPPFLAGS', but not `CFLAGS', because `-g', `-O', 6332 etc. are not valid options to many C preprocessors. 6333 6334 It is customary to report unexpected failures with 6335 `AC_MSG_FAILURE'. 6336 6337 For instance: 6338 6339 AC_INIT([Hello], [1.0], [bug-hello@example.org]) 6340 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"], 6341 [Greetings string.]) 6342 AC_PREPROC_IFELSE( 6343 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]], 6344 [[fputs (hw, stdout);]])], 6345 [AC_MSG_RESULT([OK])], 6346 [AC_MSG_FAILURE([unexpected preprocessor failure])]) 6347 6348results in: 6349 6350 checking for gcc... gcc 6351 checking for C compiler default output file name... a.out 6352 checking whether the C compiler works... yes 6353 checking whether we are cross compiling... no 6354 checking for suffix of executables... 6355 checking for suffix of object files... o 6356 checking whether we are using the GNU C compiler... yes 6357 checking whether gcc accepts -g... yes 6358 checking for gcc option to accept ISO C89... none needed 6359 checking how to run the C preprocessor... gcc -E 6360 OK 6361 6362 6363 The macro `AC_TRY_CPP' (*note Obsolete Macros::) used to play the 6364role of `AC_PREPROC_IFELSE', but double quotes its argument, making it 6365impossible to use it to elaborate sources. You are encouraged to get 6366rid of your old use of the macro `AC_TRY_CPP' in favor of 6367`AC_PREPROC_IFELSE', but, in the first place, are you sure you need to 6368run the _preprocessor_ and not the compiler? 6369 6370 -- Macro: AC_EGREP_HEADER (PATTERN, HEADER-FILE, ACTION-IF-FOUND, 6371 [ACTION-IF-NOT-FOUND]) 6372 If the output of running the preprocessor on the system header file 6373 HEADER-FILE matches the extended regular expression PATTERN, 6374 execute shell commands ACTION-IF-FOUND, otherwise execute 6375 ACTION-IF-NOT-FOUND. 6376 6377 -- Macro: AC_EGREP_CPP (PATTERN, PROGRAM, [ACTION-IF-FOUND], 6378 [ACTION-IF-NOT-FOUND]) 6379 PROGRAM is the text of a C or C++ program, on which shell 6380 variable, back quote, and backslash substitutions are performed. 6381 If the output of running the preprocessor on PROGRAM matches the 6382 extended regular expression PATTERN, execute shell commands 6383 ACTION-IF-FOUND, otherwise execute ACTION-IF-NOT-FOUND. 6384 6385 6386File: autoconf.info, Node: Running the Compiler, Next: Running the Linker, Prev: Running the Preprocessor, Up: Writing Tests 6387 63886.4 Running the Compiler 6389======================== 6390 6391To check for a syntax feature of the current language's (*note Language 6392Choice::) compiler, such as whether it recognizes a certain keyword, or 6393simply to try some library feature, use `AC_COMPILE_IFELSE' to try to 6394compile a small program that uses that feature. 6395 6396 -- Macro: AC_COMPILE_IFELSE (INPUT, [ACTION-IF-TRUE], 6397 [ACTION-IF-FALSE]) 6398 Run the compiler and compilation flags of the current language 6399 (*note Language Choice::) on the INPUT, run the shell commands 6400 ACTION-IF-TRUE on success, ACTION-IF-FALSE otherwise. The INPUT 6401 can be made by `AC_LANG_PROGRAM' and friends. 6402 6403 It is customary to report unexpected failures with 6404 `AC_MSG_FAILURE'. This macro does not try to link; use 6405 `AC_LINK_IFELSE' if you need to do that (*note Running the 6406 Linker::). 6407 6408 For tests in Erlang, the INPUT must be the source code of a module 6409named `conftest'. `AC_COMPILE_IFELSE' generates a `conftest.beam' file 6410that can be interpreted by the Erlang virtual machine (`ERL'). It is 6411recommended to use `AC_LANG_PROGRAM' to specify the test program, to 6412ensure that the Erlang module has the right name. 6413 6414 6415File: autoconf.info, Node: Running the Linker, Next: Runtime, Prev: Running the Compiler, Up: Writing Tests 6416 64176.5 Running the Linker 6418====================== 6419 6420To check for a library, a function, or a global variable, Autoconf 6421`configure' scripts try to compile and link a small program that uses 6422it. This is unlike Metaconfig, which by default uses `nm' or `ar' on 6423the C library to try to figure out which functions are available. 6424Trying to link with the function is usually a more reliable approach 6425because it avoids dealing with the variations in the options and output 6426formats of `nm' and `ar' and in the location of the standard libraries. 6427It also allows configuring for cross-compilation or checking a 6428function's runtime behavior if needed. On the other hand, it can be 6429slower than scanning the libraries once, but accuracy is more important 6430than speed. 6431 6432 `AC_LINK_IFELSE' is used to compile test programs to test for 6433functions and global variables. It is also used by `AC_CHECK_LIB' to 6434check for libraries (*note Libraries::), by adding the library being 6435checked for to `LIBS' temporarily and trying to link a small program. 6436 6437 -- Macro: AC_LINK_IFELSE (INPUT, [ACTION-IF-TRUE], [ACTION-IF-FALSE]) 6438 Run the compiler (and compilation flags) and the linker of the 6439 current language (*note Language Choice::) on the INPUT, run the 6440 shell commands ACTION-IF-TRUE on success, ACTION-IF-FALSE 6441 otherwise. The INPUT can be made by `AC_LANG_PROGRAM' and friends. 6442 6443 `LDFLAGS' and `LIBS' are used for linking, in addition to the 6444 current compilation flags. 6445 6446 It is customary to report unexpected failures with 6447 `AC_MSG_FAILURE'. This macro does not try to execute the program; 6448 use `AC_RUN_IFELSE' if you need to do that (*note Runtime::). 6449 6450 The `AC_LINK_IFELSE' macro cannot be used for Erlang tests, since 6451Erlang programs are interpreted and do not require linking. 6452 6453 6454File: autoconf.info, Node: Runtime, Next: Systemology, Prev: Running the Linker, Up: Writing Tests 6455 64566.6 Checking Runtime Behavior 6457============================= 6458 6459Sometimes you need to find out how a system performs at runtime, such 6460as whether a given function has a certain capability or bug. If you 6461can, make such checks when your program runs instead of when it is 6462configured. You can check for things like the machine's endianness when 6463your program initializes itself. 6464 6465 If you really need to test for a runtime behavior while configuring, 6466you can write a test program to determine the result, and compile and 6467run it using `AC_RUN_IFELSE'. Avoid running test programs if possible, 6468because this prevents people from configuring your package for 6469cross-compiling. 6470 6471 -- Macro: AC_RUN_IFELSE (INPUT, [ACTION-IF-TRUE], [ACTION-IF-FALSE], 6472 [ACTION-IF-CROSS-COMPILING]) 6473 If PROGRAM compiles and links successfully and returns an exit 6474 status of 0 when executed, run shell commands ACTION-IF-TRUE. 6475 Otherwise, run shell commands ACTION-IF-FALSE. 6476 6477 The INPUT can be made by `AC_LANG_PROGRAM' and friends. `LDFLAGS' 6478 and `LIBS' are used for linking, in addition to the compilation 6479 flags of the current language (*note Language Choice::). 6480 6481 If the compiler being used does not produce executables that run 6482 on the system where `configure' is being run, then the test 6483 program is not run. If the optional shell commands 6484 ACTION-IF-CROSS-COMPILING are given, they are run instead. 6485 Otherwise, `configure' prints an error message and exits. 6486 6487 In the ACTION-IF-FALSE section, the failing exit status is 6488 available in the shell variable `$?'. This exit status might be 6489 that of a failed compilation, or it might be that of a failed 6490 program execution. 6491 6492 It is customary to report unexpected failures with 6493 `AC_MSG_FAILURE'. 6494 6495 Try to provide a pessimistic default value to use when 6496cross-compiling makes runtime tests impossible. You do this by passing 6497the optional last argument to `AC_RUN_IFELSE'. `autoconf' prints a 6498warning message when creating `configure' each time it encounters a 6499call to `AC_RUN_IFELSE' with no ACTION-IF-CROSS-COMPILING argument 6500given. You may ignore the warning, though users cannot configure your 6501package for cross-compiling. A few of the macros distributed with 6502Autoconf produce this warning message. 6503 6504 To configure for cross-compiling you can also choose a value for 6505those parameters based on the canonical system name (*note Manual 6506Configuration::). Alternatively, set up a test results cache file with 6507the correct values for the host system (*note Caching Results::). 6508 6509 To provide a default for calls of `AC_RUN_IFELSE' that are embedded 6510in other macros, including a few of the ones that come with Autoconf, 6511you can test whether the shell variable `cross_compiling' is set to 6512`yes', and then use an alternate method to get the results instead of 6513calling the macros. 6514 6515 A C or C++ runtime test should be portable. *Note Portable C and 6516C++::. 6517 6518 Erlang tests must exit themselves the Erlang VM by calling the 6519`halt/1' function: the given status code is used to determine the 6520success of the test (status is `0') or its failure (status is different 6521than `0'), as explained above. It must be noted that data output 6522through the standard output (e.g., using `io:format/2') may be 6523truncated when halting the VM. Therefore, if a test must output 6524configuration information, it is recommended to create and to output 6525data into the temporary file named `conftest.out', using the functions 6526of module `file'. The `conftest.out' file is automatically deleted by 6527the `AC_RUN_IFELSE' macro. For instance, a simplified implementation 6528of Autoconf's `AC_ERLANG_SUBST_LIB_DIR' macro is: 6529 6530 AC_INIT([LibdirTest], [1.0], [bug-libdirtest@example.org]) 6531 AC_ERLANG_NEED_ERL 6532 AC_LANG(Erlang) 6533 AC_RUN_IFELSE( 6534 [AC_LANG_PROGRAM([], [dnl 6535 file:write_file("conftest.out", code:lib_dir()), 6536 halt(0)])], 6537 [echo "code:lib_dir() returned: `cat conftest.out`"], 6538 [AC_MSG_FAILURE([test Erlang program execution failed])]) 6539 6540 6541File: autoconf.info, Node: Systemology, Next: Multiple Cases, Prev: Runtime, Up: Writing Tests 6542 65436.7 Systemology 6544=============== 6545 6546This section aims at presenting some systems and pointers to 6547documentation. It may help you addressing particular problems reported 6548by users. 6549 6550 Posix-conforming systems (http://www.opengroup.org/susv3) are 6551derived from the Unix operating system 6552(http://www.bell-labs.com/history/unix/). 6553 6554 The Rosetta Stone for Unix (http://bhami.com/rosetta.html) contains 6555a table correlating the features of various Posix-conforming systems. 6556Unix History (http://www.levenez.com/unix/) is a simplified diagram of 6557how many Unix systems were derived from each other. 6558 6559 The Heirloom Project (http://heirloom.sourceforge.net/) provides 6560some variants of traditional implementations of Unix utilities. 6561 6562Darwin 6563 Darwin is also known as Mac OS X. Beware that the file system 6564 _can_ be case-preserving, but case insensitive. This can cause 6565 nasty problems, since for instance the installation attempt for a 6566 package having an `INSTALL' file can result in `make install' 6567 report that nothing was to be done! 6568 6569 That's all dependent on whether the file system is a UFS (case 6570 sensitive) or HFS+ (case preserving). By default Apple wants you 6571 to install the OS on HFS+. Unfortunately, there are some pieces of 6572 software which really need to be built on UFS. We may want to 6573 rebuild Darwin to have both UFS and HFS+ available (and put the 6574 /local/build tree on the UFS). 6575 6576QNX 4.25 6577 QNX is a realtime operating system running on Intel architecture 6578 meant to be scalable from the small embedded systems to the hundred 6579 processor super-computer. It claims to be Posix certified. More 6580 information is available on the QNX home page 6581 (http://www.qnx.com/). 6582 6583Tru64 6584 Documentation of several versions of Tru64 6585 (http://h30097.www3.hp.com/docs/) is available in different 6586 formats. 6587 6588Unix version 7 6589 Officially this was called the "Seventh Edition" of "the UNIX 6590 time-sharing system" but we use the more-common name "Unix version 6591 7". Documentation is available in the Unix Seventh Edition Manual 6592 (http://plan9.bell-labs.com/7thEdMan/). Previous versions of Unix 6593 are called "Unix version 6", etc., but they were not as widely 6594 used. 6595 6596 6597File: autoconf.info, Node: Multiple Cases, Prev: Systemology, Up: Writing Tests 6598 65996.8 Multiple Cases 6600================== 6601 6602Some operations are accomplished in several possible ways, depending on 6603the OS variant. Checking for them essentially requires a "case 6604statement". Autoconf does not directly provide one; however, it is 6605easy to simulate by using a shell variable to keep track of whether a 6606way to perform the operation has been found yet. 6607 6608 Here is an example that uses the shell variable `fstype' to keep 6609track of whether the remaining cases need to be checked. 6610 6611 AC_MSG_CHECKING([how to get file system type]) 6612 fstype=no 6613 # The order of these tests is important. 6614 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statvfs.h> 6615 #include <sys/fstyp.h>]])], 6616 [AC_DEFINE([FSTYPE_STATVFS], [1], 6617 [Define if statvfs exists.]) 6618 fstype=SVR4]) 6619 if test $fstype = no; then 6620 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h> 6621 #include <sys/fstyp.h>]])], 6622 [AC_DEFINE([FSTYPE_USG_STATFS], [1], 6623 [Define if USG statfs.]) 6624 fstype=SVR3]) 6625 fi 6626 if test $fstype = no; then 6627 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h> 6628 #include <sys/vmount.h>]])]), 6629 [AC_DEFINE([FSTYPE_AIX_STATFS], [1], 6630 [Define if AIX statfs.]) 6631 fstype=AIX]) 6632 fi 6633 # (more cases omitted here) 6634 AC_MSG_RESULT([$fstype]) 6635 6636 6637File: autoconf.info, Node: Results, Next: Programming in M4, Prev: Writing Tests, Up: Top 6638 66397 Results of Tests 6640****************** 6641 6642Once `configure' has determined whether a feature exists, what can it 6643do to record that information? There are four sorts of things it can 6644do: define a C preprocessor symbol, set a variable in the output files, 6645save the result in a cache file for future `configure' runs, and print 6646a message letting the user know the result of the test. 6647 6648* Menu: 6649 6650* Defining Symbols:: Defining C preprocessor symbols 6651* Setting Output Variables:: Replacing variables in output files 6652* Special Chars in Variables:: Characters to beware of in variables 6653* Caching Results:: Speeding up subsequent `configure' runs 6654* Printing Messages:: Notifying `configure' users 6655 6656 6657File: autoconf.info, Node: Defining Symbols, Next: Setting Output Variables, Up: Results 6658 66597.1 Defining C Preprocessor Symbols 6660=================================== 6661 6662A common action to take in response to a feature test is to define a C 6663preprocessor symbol indicating the results of the test. That is done by 6664calling `AC_DEFINE' or `AC_DEFINE_UNQUOTED'. 6665 6666 By default, `AC_OUTPUT' places the symbols defined by these macros 6667into the output variable `DEFS', which contains an option 6668`-DSYMBOL=VALUE' for each symbol defined. Unlike in Autoconf version 66691, there is no variable `DEFS' defined while `configure' is running. 6670To check whether Autoconf macros have already defined a certain C 6671preprocessor symbol, test the value of the appropriate cache variable, 6672as in this example: 6673 6674 AC_CHECK_FUNC([vprintf], [AC_DEFINE([HAVE_VPRINTF], [1], 6675 [Define if vprintf exists.])]) 6676 if test "$ac_cv_func_vprintf" != yes; then 6677 AC_CHECK_FUNC([_doprnt], [AC_DEFINE([HAVE_DOPRNT], [1], 6678 [Define if _doprnt exists.])]) 6679 fi 6680 6681 If `AC_CONFIG_HEADERS' has been called, then instead of creating 6682`DEFS', `AC_OUTPUT' creates a header file by substituting the correct 6683values into `#define' statements in a template file. *Note 6684Configuration Headers::, for more information about this kind of output. 6685 6686 -- Macro: AC_DEFINE (VARIABLE, VALUE, [DESCRIPTION]) 6687 -- Macro: AC_DEFINE (VARIABLE) 6688 Define the C preprocessor variable VARIABLE to VALUE (verbatim). 6689 VALUE should not contain literal newlines, and if you are not 6690 using `AC_CONFIG_HEADERS' it should not contain any `#' 6691 characters, as `make' tends to eat them. To use a shell variable, 6692 use `AC_DEFINE_UNQUOTED' instead. DESCRIPTION is only useful if 6693 you are using `AC_CONFIG_HEADERS'. In this case, DESCRIPTION is 6694 put into the generated `config.h.in' as the comment before the 6695 macro define. The following example defines the C preprocessor 6696 variable `EQUATION' to be the string constant `"$a > $b"': 6697 6698 AC_DEFINE([EQUATION], ["$a > $b"], 6699 [Equation string.]) 6700 6701 If neither VALUE nor DESCRIPTION are given, then VALUE defaults to 6702 1 instead of to the empty string. This is for backwards 6703 compatibility with older versions of Autoconf, but this usage is 6704 obsolescent and may be withdrawn in future versions of Autoconf. 6705 6706 If the VARIABLE is a literal string, it is passed to 6707 `m4_pattern_allow' (*note Forbidden Patterns::). 6708 6709 -- Macro: AC_DEFINE_UNQUOTED (VARIABLE, VALUE, [DESCRIPTION]) 6710 -- Macro: AC_DEFINE_UNQUOTED (VARIABLE) 6711 Like `AC_DEFINE', but three shell expansions are 6712 performed--once--on VARIABLE and VALUE: variable expansion (`$'), 6713 command substitution (``'), and backslash escaping (`\'). Single 6714 and double quote characters in the value have no special meaning. 6715 Use this macro instead of `AC_DEFINE' when VARIABLE or VALUE is a 6716 shell variable. Examples: 6717 6718 AC_DEFINE_UNQUOTED([config_machfile], ["$machfile"], 6719 [Configuration machine file.]) 6720 AC_DEFINE_UNQUOTED([GETGROUPS_T], [$ac_cv_type_getgroups], 6721 [getgroups return type.]) 6722 AC_DEFINE_UNQUOTED([$ac_tr_hdr], [1], 6723 [Translated header name.]) 6724 6725 Due to a syntactical bizarreness of the Bourne shell, do not use 6726semicolons to separate `AC_DEFINE' or `AC_DEFINE_UNQUOTED' calls from 6727other macro calls or shell code; that can cause syntax errors in the 6728resulting `configure' script. Use either blanks or newlines. That is, 6729do this: 6730 6731 AC_CHECK_HEADER([elf.h], 6732 [AC_DEFINE([SVR4], [1], [System V Release 4]) LIBS="-lelf $LIBS"]) 6733 6734or this: 6735 6736 AC_CHECK_HEADER([elf.h], 6737 [AC_DEFINE([SVR4], [1], [System V Release 4]) 6738 LIBS="-lelf $LIBS"]) 6739 6740instead of this: 6741 6742 AC_CHECK_HEADER([elf.h], 6743 [AC_DEFINE([SVR4], [1], [System V Release 4]); LIBS="-lelf $LIBS"]) 6744 6745 6746File: autoconf.info, Node: Setting Output Variables, Next: Special Chars in Variables, Prev: Defining Symbols, Up: Results 6747 67487.2 Setting Output Variables 6749============================ 6750 6751Another way to record the results of tests is to set "output 6752variables", which are shell variables whose values are substituted into 6753files that `configure' outputs. The two macros below create new output 6754variables. *Note Preset Output Variables::, for a list of output 6755variables that are always available. 6756 6757 -- Macro: AC_SUBST (VARIABLE, [VALUE]) 6758 Create an output variable from a shell variable. Make `AC_OUTPUT' 6759 substitute the variable VARIABLE into output files (typically one 6760 or more makefiles). This means that `AC_OUTPUT' replaces 6761 instances of `@VARIABLE@' in input files with the value that the 6762 shell variable VARIABLE has when `AC_OUTPUT' is called. The value 6763 can contain newlines. The substituted value is not rescanned for 6764 more output variables; occurrences of `@VARIABLE@' in the value 6765 are inserted literally into the output file. (The algorithm uses 6766 the special marker `|#_!!_#|' internally, so the substituted value 6767 cannot contain `|#_!!_#|'.) 6768 6769 If VALUE is given, in addition assign it to VARIABLE. 6770 6771 The string VARIABLE is passed to `m4_pattern_allow' (*note 6772 Forbidden Patterns::). 6773 6774 -- Macro: AC_SUBST_FILE (VARIABLE) 6775 Another way to create an output variable from a shell variable. 6776 Make `AC_OUTPUT' insert (without substitutions) the contents of 6777 the file named by shell variable VARIABLE into output files. This 6778 means that `AC_OUTPUT' replaces instances of `@VARIABLE@' in 6779 output files (such as `Makefile.in') with the contents of the file 6780 that the shell variable VARIABLE names when `AC_OUTPUT' is called. 6781 Set the variable to `/dev/null' for cases that do not have a file 6782 to insert. This substitution occurs only when the `@VARIABLE@' is 6783 on a line by itself, optionally surrounded by spaces and tabs. The 6784 substitution replaces the whole line, including the spaces, tabs, 6785 and the terminating newline. 6786 6787 This macro is useful for inserting makefile fragments containing 6788 special dependencies or other `make' directives for particular host 6789 or target types into makefiles. For example, `configure.ac' could 6790 contain: 6791 6792 AC_SUBST_FILE([host_frag]) 6793 host_frag=$srcdir/conf/sun4.mh 6794 6795 and then a `Makefile.in' could contain: 6796 6797 @host_frag@ 6798 6799 The string VARIABLE is passed to `m4_pattern_allow' (*note 6800 Forbidden Patterns::). 6801 6802 Running `configure' in varying environments can be extremely 6803dangerous. If for instance the user runs `CC=bizarre-cc ./configure', 6804then the cache, `config.h', and many other output files depend upon 6805`bizarre-cc' being the C compiler. If for some reason the user runs 6806`./configure' again, or if it is run via `./config.status --recheck', 6807(*Note Automatic Remaking::, and *note config.status Invocation::), 6808then the configuration can be inconsistent, composed of results 6809depending upon two different compilers. 6810 6811 Environment variables that affect this situation, such as `CC' 6812above, are called "precious variables", and can be declared as such by 6813`AC_ARG_VAR'. 6814 6815 -- Macro: AC_ARG_VAR (VARIABLE, DESCRIPTION) 6816 Declare VARIABLE is a precious variable, and include its 6817 DESCRIPTION in the variable section of `./configure --help'. 6818 6819 Being precious means that 6820 - VARIABLE is substituted via `AC_SUBST'. 6821 6822 - The value of VARIABLE when `configure' was launched is saved 6823 in the cache, including if it was not specified on the command 6824 line but via the environment. Indeed, while `configure' can 6825 notice the definition of `CC' in `./configure CC=bizarre-cc', 6826 it is impossible to notice it in `CC=bizarre-cc ./configure', 6827 which, unfortunately, is what most users do. 6828 6829 We emphasize that it is the _initial_ value of VARIABLE which 6830 is saved, not that found during the execution of `configure'. 6831 Indeed, specifying `./configure FOO=foo' and letting 6832 `./configure' guess that `FOO' is `foo' can be two different 6833 things. 6834 6835 - VARIABLE is checked for consistency between two `configure' 6836 runs. For instance: 6837 6838 $ ./configure --silent --config-cache 6839 $ CC=cc ./configure --silent --config-cache 6840 configure: error: `CC' was not set in the previous run 6841 configure: error: changes in the environment can compromise \ 6842 the build 6843 configure: error: run `make distclean' and/or \ 6844 `rm config.cache' and start over 6845 6846 and similarly if the variable is unset, or if its content is 6847 changed. 6848 6849 - VARIABLE is kept during automatic reconfiguration (*note 6850 config.status Invocation::) as if it had been passed as a 6851 command line argument, including when no cache is used: 6852 6853 $ CC=/usr/bin/cc ./configure undeclared_var=raboof --silent 6854 $ ./config.status --recheck 6855 running CONFIG_SHELL=/bin/sh /bin/sh ./configure undeclared_var=raboof \ 6856 CC=/usr/bin/cc --no-create --no-recursion 6857 6858 6859File: autoconf.info, Node: Special Chars in Variables, Next: Caching Results, Prev: Setting Output Variables, Up: Results 6860 68617.3 Special Characters in Output Variables 6862========================================== 6863 6864Many output variables are intended to be evaluated both by `make' and 6865by the shell. Some characters are expanded differently in these two 6866contexts, so to avoid confusion these variables' values should not 6867contain any of the following characters: 6868 6869 " # $ & ' ( ) * ; < > ? [ \ ^ ` | 6870 6871 Also, these variables' values should neither contain newlines, nor 6872start with `~', nor contain white space or `:' immediately followed by 6873`~'. The values can contain nonempty sequences of white space 6874characters like tabs and spaces, but each such sequence might 6875arbitrarily be replaced by a single space during substitution. 6876 6877 These restrictions apply both to the values that `configure' 6878computes, and to the values set directly by the user. For example, the 6879following invocations of `configure' are problematic, since they 6880attempt to use special characters within `CPPFLAGS' and white space 6881within `$(srcdir)': 6882 6883 CPPFLAGS='-DOUCH="&\"#$*?"' '../My Source/ouch-1.0/configure' 6884 6885 '../My Source/ouch-1.0/configure' CPPFLAGS='-DOUCH="&\"#$*?"' 6886 6887 6888File: autoconf.info, Node: Caching Results, Next: Printing Messages, Prev: Special Chars in Variables, Up: Results 6889 68907.4 Caching Results 6891=================== 6892 6893To avoid checking for the same features repeatedly in various 6894`configure' scripts (or in repeated runs of one script), `configure' 6895can optionally save the results of many checks in a "cache file" (*note 6896Cache Files::). If a `configure' script runs with caching enabled and 6897finds a cache file, it reads the results of previous runs from the 6898cache and avoids rerunning those checks. As a result, `configure' can 6899then run much faster than if it had to perform all of the checks every 6900time. 6901 6902 -- Macro: AC_CACHE_VAL (CACHE-ID, COMMANDS-TO-SET-IT) 6903 Ensure that the results of the check identified by CACHE-ID are 6904 available. If the results of the check were in the cache file 6905 that was read, and `configure' was not given the `--quiet' or 6906 `--silent' option, print a message saying that the result was 6907 cached; otherwise, run the shell commands COMMANDS-TO-SET-IT. If 6908 the shell commands are run to determine the value, the value is 6909 saved in the cache file just before `configure' creates its output 6910 files. *Note Cache Variable Names::, for how to choose the name 6911 of the CACHE-ID variable. 6912 6913 The COMMANDS-TO-SET-IT _must have no side effects_ except for 6914 setting the variable CACHE-ID, see below. 6915 6916 -- Macro: AC_CACHE_CHECK (MESSAGE, CACHE-ID, COMMANDS-TO-SET-IT) 6917 A wrapper for `AC_CACHE_VAL' that takes care of printing the 6918 messages. This macro provides a convenient shorthand for the most 6919 common way to use these macros. It calls `AC_MSG_CHECKING' for 6920 MESSAGE, then `AC_CACHE_VAL' with the CACHE-ID and COMMANDS 6921 arguments, and `AC_MSG_RESULT' with CACHE-ID. 6922 6923 The COMMANDS-TO-SET-IT _must have no side effects_ except for 6924 setting the variable CACHE-ID, see below. 6925 6926 It is common to find buggy macros using `AC_CACHE_VAL' or 6927`AC_CACHE_CHECK', because people are tempted to call `AC_DEFINE' in the 6928COMMANDS-TO-SET-IT. Instead, the code that _follows_ the call to 6929`AC_CACHE_VAL' should call `AC_DEFINE', by examining the value of the 6930cache variable. For instance, the following macro is broken: 6931 6932 AC_DEFUN([AC_SHELL_TRUE], 6933 [AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works], 6934 [ac_cv_shell_true_works=no 6935 (true) 2>/dev/null && ac_cv_shell_true_works=yes 6936 if test "$ac_cv_shell_true_works" = yes; then 6937 AC_DEFINE([TRUE_WORKS], [1], 6938 [Define if `true(1)' works properly.]) 6939 fi]) 6940 ]) 6941 6942This fails if the cache is enabled: the second time this macro is run, 6943`TRUE_WORKS' _will not be defined_. The proper implementation is: 6944 6945 AC_DEFUN([AC_SHELL_TRUE], 6946 [AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works], 6947 [ac_cv_shell_true_works=no 6948 (true) 2>/dev/null && ac_cv_shell_true_works=yes]) 6949 if test "$ac_cv_shell_true_works" = yes; then 6950 AC_DEFINE([TRUE_WORKS], [1], 6951 [Define if `true(1)' works properly.]) 6952 fi 6953 ]) 6954 6955 Also, COMMANDS-TO-SET-IT should not print any messages, for example 6956with `AC_MSG_CHECKING'; do that before calling `AC_CACHE_VAL', so the 6957messages are printed regardless of whether the results of the check are 6958retrieved from the cache or determined by running the shell commands. 6959 6960* Menu: 6961 6962* Cache Variable Names:: Shell variables used in caches 6963* Cache Files:: Files `configure' uses for caching 6964* Cache Checkpointing:: Loading and saving the cache file 6965 6966 6967File: autoconf.info, Node: Cache Variable Names, Next: Cache Files, Up: Caching Results 6968 69697.4.1 Cache Variable Names 6970-------------------------- 6971 6972The names of cache variables should have the following format: 6973 6974 PACKAGE-PREFIX_cv_VALUE-TYPE_SPECIFIC-VALUE_[ADDITIONAL-OPTIONS] 6975 6976for example, `ac_cv_header_stat_broken' or 6977`ac_cv_prog_gcc_traditional'. The parts of the variable name are: 6978 6979PACKAGE-PREFIX 6980 An abbreviation for your package or organization; the same prefix 6981 you begin local Autoconf macros with, except lowercase by 6982 convention. For cache values used by the distributed Autoconf 6983 macros, this value is `ac'. 6984 6985`_cv_' 6986 Indicates that this shell variable is a cache value. This string 6987 _must_ be present in the variable name, including the leading 6988 underscore. 6989 6990VALUE-TYPE 6991 A convention for classifying cache values, to produce a rational 6992 naming system. The values used in Autoconf are listed in *Note 6993 Macro Names::. 6994 6995SPECIFIC-VALUE 6996 Which member of the class of cache values this test applies to. 6997 For example, which function (`alloca'), program (`gcc'), or output 6998 variable (`INSTALL'). 6999 7000ADDITIONAL-OPTIONS 7001 Any particular behavior of the specific member that this test 7002 applies to. For example, `broken' or `set'. This part of the 7003 name may be omitted if it does not apply. 7004 7005 The values assigned to cache variables may not contain newlines. 7006Usually, their values are Boolean (`yes' or `no') or the names of files 7007or functions; so this is not an important restriction. 7008 7009 7010File: autoconf.info, Node: Cache Files, Next: Cache Checkpointing, Prev: Cache Variable Names, Up: Caching Results 7011 70127.4.2 Cache Files 7013----------------- 7014 7015A cache file is a shell script that caches the results of configure 7016tests run on one system so they can be shared between configure scripts 7017and configure runs. It is not useful on other systems. If its contents 7018are invalid for some reason, the user may delete or edit it. 7019 7020 By default, `configure' uses no cache file, to avoid problems caused 7021by accidental use of stale cache files. 7022 7023 To enable caching, `configure' accepts `--config-cache' (or `-C') to 7024cache results in the file `config.cache'. Alternatively, 7025`--cache-file=FILE' specifies that FILE be the cache file. The cache 7026file is created if it does not exist already. When `configure' calls 7027`configure' scripts in subdirectories, it uses the `--cache-file' 7028argument so that they share the same cache. *Note Subdirectories::, 7029for information on configuring subdirectories with the 7030`AC_CONFIG_SUBDIRS' macro. 7031 7032 `config.status' only pays attention to the cache file if it is given 7033the `--recheck' option, which makes it rerun `configure'. 7034 7035 It is wrong to try to distribute cache files for particular system 7036types. There is too much room for error in doing that, and too much 7037administrative overhead in maintaining them. For any features that 7038can't be guessed automatically, use the standard method of the canonical 7039system type and linking files (*note Manual Configuration::). 7040 7041 The site initialization script can specify a site-wide cache file to 7042use, instead of the usual per-program cache. In this case, the cache 7043file gradually accumulates information whenever someone runs a new 7044`configure' script. (Running `configure' merges the new cache results 7045with the existing cache file.) This may cause problems, however, if 7046the system configuration (e.g., the installed libraries or compilers) 7047changes and the stale cache file is not deleted. 7048 7049 7050File: autoconf.info, Node: Cache Checkpointing, Prev: Cache Files, Up: Caching Results 7051 70527.4.3 Cache Checkpointing 7053------------------------- 7054 7055If your configure script, or a macro called from `configure.ac', happens 7056to abort the configure process, it may be useful to checkpoint the cache 7057a few times at key points using `AC_CACHE_SAVE'. Doing so reduces the 7058amount of time it takes to rerun the configure script with (hopefully) 7059the error that caused the previous abort corrected. 7060 7061 -- Macro: AC_CACHE_LOAD 7062 Loads values from existing cache file, or creates a new cache file 7063 if a cache file is not found. Called automatically from `AC_INIT'. 7064 7065 -- Macro: AC_CACHE_SAVE 7066 Flushes all cached values to the cache file. Called automatically 7067 from `AC_OUTPUT', but it can be quite useful to call 7068 `AC_CACHE_SAVE' at key points in `configure.ac'. 7069 7070 For instance: 7071 7072 ... AC_INIT, etc. ... 7073 # Checks for programs. 7074 AC_PROG_CC 7075 AC_PROG_AWK 7076 ... more program checks ... 7077 AC_CACHE_SAVE 7078 7079 # Checks for libraries. 7080 AC_CHECK_LIB([nsl], [gethostbyname]) 7081 AC_CHECK_LIB([socket], [connect]) 7082 ... more lib checks ... 7083 AC_CACHE_SAVE 7084 7085 # Might abort... 7086 AM_PATH_GTK([1.0.2], [], [AC_MSG_ERROR([GTK not in path])]) 7087 AM_PATH_GTKMM([0.9.5], [], [AC_MSG_ERROR([GTK not in path])]) 7088 ... AC_OUTPUT, etc. ... 7089 7090 7091File: autoconf.info, Node: Printing Messages, Prev: Caching Results, Up: Results 7092 70937.5 Printing Messages 7094===================== 7095 7096`configure' scripts need to give users running them several kinds of 7097information. The following macros print messages in ways appropriate 7098for each kind. The arguments to all of them get enclosed in shell 7099double quotes, so the shell performs variable and back-quote 7100substitution on them. 7101 7102 These macros are all wrappers around the `echo' shell command. They 7103direct output to the appropriate file descriptor (*note File Descriptor 7104Macros::). `configure' scripts should rarely need to run `echo' 7105directly to print messages for the user. Using these macros makes it 7106easy to change how and when each kind of message is printed; such 7107changes need only be made to the macro definitions and all the callers 7108change automatically. 7109 7110 To diagnose static issues, i.e., when `autoconf' is run, see *Note 7111Reporting Messages::. 7112 7113 -- Macro: AC_MSG_CHECKING (FEATURE-DESCRIPTION) 7114 Notify the user that `configure' is checking for a particular 7115 feature. This macro prints a message that starts with `checking ' 7116 and ends with `...' and no newline. It must be followed by a call 7117 to `AC_MSG_RESULT' to print the result of the check and the 7118 newline. The FEATURE-DESCRIPTION should be something like 7119 `whether the Fortran compiler accepts C++ comments' or `for c89'. 7120 7121 This macro prints nothing if `configure' is run with the `--quiet' 7122 or `--silent' option. 7123 7124 -- Macro: AC_MSG_RESULT (RESULT-DESCRIPTION) 7125 Notify the user of the results of a check. RESULT-DESCRIPTION is 7126 almost always the value of the cache variable for the check, 7127 typically `yes', `no', or a file name. This macro should follow a 7128 call to `AC_MSG_CHECKING', and the RESULT-DESCRIPTION should be 7129 the completion of the message printed by the call to 7130 `AC_MSG_CHECKING'. 7131 7132 This macro prints nothing if `configure' is run with the `--quiet' 7133 or `--silent' option. 7134 7135 -- Macro: AC_MSG_NOTICE (MESSAGE) 7136 Deliver the MESSAGE to the user. It is useful mainly to print a 7137 general description of the overall purpose of a group of feature 7138 checks, e.g., 7139 7140 AC_MSG_NOTICE([checking if stack overflow is detectable]) 7141 7142 This macro prints nothing if `configure' is run with the `--quiet' 7143 or `--silent' option. 7144 7145 -- Macro: AC_MSG_ERROR (ERROR-DESCRIPTION, [EXIT-STATUS]) 7146 Notify the user of an error that prevents `configure' from 7147 completing. This macro prints an error message to the standard 7148 error output and exits `configure' with EXIT-STATUS (1 by default). 7149 ERROR-DESCRIPTION should be something like `invalid value $HOME 7150 for \$HOME'. 7151 7152 The ERROR-DESCRIPTION should start with a lower-case letter, and 7153 "cannot" is preferred to "can't". 7154 7155 -- Macro: AC_MSG_FAILURE (ERROR-DESCRIPTION, [EXIT-STATUS]) 7156 This `AC_MSG_ERROR' wrapper notifies the user of an error that 7157 prevents `configure' from completing _and_ that additional details 7158 are provided in `config.log'. This is typically used when 7159 abnormal results are found during a compilation. 7160 7161 -- Macro: AC_MSG_WARN (PROBLEM-DESCRIPTION) 7162 Notify the `configure' user of a possible problem. This macro 7163 prints the message to the standard error output; `configure' 7164 continues running afterward, so macros that call `AC_MSG_WARN' 7165 should provide a default (back-up) behavior for the situations 7166 they warn about. PROBLEM-DESCRIPTION should be something like `ln 7167 -s seems to make hard links'. 7168 7169 7170File: autoconf.info, Node: Programming in M4, Next: Writing Autoconf Macros, Prev: Results, Up: Top 7171 71728 Programming in M4 7173******************* 7174 7175Autoconf is written on top of two layers: "M4sugar", which provides 7176convenient macros for pure M4 programming, and "M4sh", which provides 7177macros dedicated to shell script generation. 7178 7179 As of this version of Autoconf, these two layers are still 7180experimental, and their interface might change in the future. As a 7181matter of fact, _anything that is not documented must not be used_. 7182 7183* Menu: 7184 7185* M4 Quotation:: Protecting macros from unwanted expansion 7186* Using autom4te:: The Autoconf executables backbone 7187* Programming in M4sugar:: Convenient pure M4 macros 7188* Programming in M4sh:: Common shell Constructs 7189* File Descriptor Macros:: File descriptor macros for input and output 7190 7191 7192File: autoconf.info, Node: M4 Quotation, Next: Using autom4te, Up: Programming in M4 7193 71948.1 M4 Quotation 7195================ 7196 7197The most common problem with existing macros is an improper quotation. 7198This section, which users of Autoconf can skip, but which macro writers 7199_must_ read, first justifies the quotation scheme that was chosen for 7200Autoconf and then ends with a rule of thumb. Understanding the former 7201helps one to follow the latter. 7202 7203* Menu: 7204 7205* Active Characters:: Characters that change the behavior of M4 7206* One Macro Call:: Quotation and one macro call 7207* Quotation and Nested Macros:: Macros calling macros 7208* Changequote is Evil:: Worse than INTERCAL: M4 + changequote 7209* Quadrigraphs:: Another way to escape special characters 7210* Quotation Rule Of Thumb:: One parenthesis, one quote 7211 7212 7213File: autoconf.info, Node: Active Characters, Next: One Macro Call, Up: M4 Quotation 7214 72158.1.1 Active Characters 7216----------------------- 7217 7218To fully understand where proper quotation is important, you first need 7219to know what the special characters are in Autoconf: `#' introduces a 7220comment inside which no macro expansion is performed, `,' separates 7221arguments, `[' and `]' are the quotes themselves, and finally `(' and 7222`)' (which M4 tries to match by pairs). 7223 7224 In order to understand the delicate case of macro calls, we first 7225have to present some obvious failures. Below they are "obvious-ified", 7226but when you find them in real life, they are usually in disguise. 7227 7228 Comments, introduced by a hash and running up to the newline, are 7229opaque tokens to the top level: active characters are turned off, and 7230there is no macro expansion: 7231 7232 # define([def], ine) 7233 =># define([def], ine) 7234 7235 Each time there can be a macro expansion, there is a quotation 7236expansion, i.e., one level of quotes is stripped: 7237 7238 int tab[10]; 7239 =>int tab10; 7240 [int tab[10];] 7241 =>int tab[10]; 7242 7243 Without this in mind, the reader might try hopelessly to use her 7244macro `array': 7245 7246 define([array], [int tab[10];]) 7247 array 7248 =>int tab10; 7249 [array] 7250 =>array 7251 7252How can you correctly output the intended results(1)? 7253 7254 ---------- Footnotes ---------- 7255 7256 (1) Using `defn'. 7257 7258 7259File: autoconf.info, Node: One Macro Call, Next: Quotation and Nested Macros, Prev: Active Characters, Up: M4 Quotation 7260 72618.1.2 One Macro Call 7262-------------------- 7263 7264Let's proceed on the interaction between active characters and macros 7265with this small macro, which just returns its first argument: 7266 7267 define([car], [$1]) 7268 7269The two pairs of quotes above are not part of the arguments of 7270`define'; rather, they are understood by the top level when it tries to 7271find the arguments of `define'. Therefore, assuming `car' is not 7272already defined, it is equivalent to write: 7273 7274 define(car, $1) 7275 7276But, while it is acceptable for a `configure.ac' to avoid unnecessary 7277quotes, it is bad practice for Autoconf macros which must both be more 7278robust and also advocate perfect style. 7279 7280 At the top level, there are only two possibilities: either you quote 7281or you don't: 7282 7283 car(foo, bar, baz) 7284 =>foo 7285 [car(foo, bar, baz)] 7286 =>car(foo, bar, baz) 7287 7288 Let's pay attention to the special characters: 7289 7290 car(#) 7291 error-->EOF in argument list 7292 7293 The closing parenthesis is hidden in the comment; with a hypothetical 7294quoting, the top level understood it this way: 7295 7296 car([#)] 7297 7298Proper quotation, of course, fixes the problem: 7299 7300 car([#]) 7301 =># 7302 7303 Here are more examples: 7304 7305 car(foo, bar) 7306 =>foo 7307 car([foo, bar]) 7308 =>foo, bar 7309 car((foo, bar)) 7310 =>(foo, bar) 7311 car([(foo], [bar)]) 7312 =>(foo 7313 define([a], [b]) 7314 => 7315 car(a) 7316 =>b 7317 car([a]) 7318 =>b 7319 car([[a]]) 7320 =>a 7321 car([[[a]]]) 7322 =>[a] 7323 7324 With this in mind, we can explore the cases where macros invoke 7325macros.... 7326 7327 7328File: autoconf.info, Node: Quotation and Nested Macros, Next: Changequote is Evil, Prev: One Macro Call, Up: M4 Quotation 7329 73308.1.3 Quotation and Nested Macros 7331--------------------------------- 7332 7333The examples below use the following macros: 7334 7335 define([car], [$1]) 7336 define([active], [ACT, IVE]) 7337 define([array], [int tab[10]]) 7338 7339 Each additional embedded macro call introduces other possible 7340interesting quotations: 7341 7342 car(active) 7343 =>ACT 7344 car([active]) 7345 =>ACT, IVE 7346 car([[active]]) 7347 =>active 7348 7349 In the first case, the top level looks for the arguments of `car', 7350and finds `active'. Because M4 evaluates its arguments before applying 7351the macro, `active' is expanded, which results in: 7352 7353 car(ACT, IVE) 7354 =>ACT 7355 7356In the second case, the top level gives `active' as first and only 7357argument of `car', which results in: 7358 7359 active 7360 =>ACT, IVE 7361 7362i.e., the argument is evaluated _after_ the macro that invokes it. In 7363the third case, `car' receives `[active]', which results in: 7364 7365 [active] 7366 =>active 7367 7368exactly as we already saw above. 7369 7370 The example above, applied to a more realistic example, gives: 7371 7372 car(int tab[10];) 7373 =>int tab10; 7374 car([int tab[10];]) 7375 =>int tab10; 7376 car([[int tab[10];]]) 7377 =>int tab[10]; 7378 7379Huh? The first case is easily understood, but why is the second wrong, 7380and the third right? To understand that, you must know that after M4 7381expands a macro, the resulting text is immediately subjected to macro 7382expansion and quote removal. This means that the quote removal occurs 7383twice--first before the argument is passed to the `car' macro, and 7384second after the `car' macro expands to the first argument. 7385 7386 As the author of the Autoconf macro `car', you then consider it to 7387be incorrect that your users have to double-quote the arguments of 7388`car', so you "fix" your macro. Let's call it `qar' for quoted car: 7389 7390 define([qar], [[$1]]) 7391 7392and check that `qar' is properly fixed: 7393 7394 qar([int tab[10];]) 7395 =>int tab[10]; 7396 7397Ahhh! That's much better. 7398 7399 But note what you've done: now that the arguments are literal 7400strings, if the user wants to use the results of expansions as 7401arguments, she has to use an _unquoted_ macro call: 7402 7403 qar(active) 7404 =>ACT 7405 7406where she wanted to reproduce what she used to do with `car': 7407 7408 car([active]) 7409 =>ACT, IVE 7410 7411Worse yet: she wants to use a macro that produces a set of `cpp' macros: 7412 7413 define([my_includes], [#include <stdio.h>]) 7414 car([my_includes]) 7415 =>#include <stdio.h> 7416 qar(my_includes) 7417 error-->EOF in argument list 7418 7419 This macro, `qar', because it double quotes its arguments, forces 7420its users to leave their macro calls unquoted, which is dangerous. 7421Commas and other active symbols are interpreted by M4 before they are 7422given to the macro, often not in the way the users expect. Also, 7423because `qar' behaves differently from the other macros, it's an 7424exception that should be avoided in Autoconf. 7425 7426 7427File: autoconf.info, Node: Changequote is Evil, Next: Quadrigraphs, Prev: Quotation and Nested Macros, Up: M4 Quotation 7428 74298.1.4 `changequote' is Evil 7430--------------------------- 7431 7432The temptation is often high to bypass proper quotation, in particular 7433when it's late at night. Then, many experienced Autoconf hackers 7434finally surrender to the dark side of the force and use the ultimate 7435weapon: `changequote'. 7436 7437 The M4 builtin `changequote' belongs to a set of primitives that 7438allow one to adjust the syntax of the language to adjust it to one's 7439needs. For instance, by default M4 uses ``' and `'' as quotes, but in 7440the context of shell programming (and actually of most programming 7441languages), that's about the worst choice one can make: because of 7442strings and back-quoted expressions in shell code (such as `'this'' and 7443``that`'), because of literal characters in usual programming languages 7444(as in `'0''), there are many unbalanced ``' and `''. Proper M4 7445quotation then becomes a nightmare, if not impossible. In order to 7446make M4 useful in such a context, its designers have equipped it with 7447`changequote', which makes it possible to choose another pair of 7448quotes. M4sugar, M4sh, Autoconf, and Autotest all have chosen to use 7449`[' and `]'. Not especially because they are unlikely characters, but 7450_because they are characters unlikely to be unbalanced_. 7451 7452 There are other magic primitives, such as `changecom' to specify 7453what syntactic forms are comments (it is common to see `changecom(<!--, 7454-->)' when M4 is used to produce HTML pages), `changeword' and 7455`changesyntax' to change other syntactic details (such as the character 7456to denote the Nth argument, `$' by default, the parenthesis around 7457arguments, etc.). 7458 7459 These primitives are really meant to make M4 more useful for specific 7460domains: they should be considered like command line options: 7461`--quotes', `--comments', `--words', and `--syntax'. Nevertheless, 7462they are implemented as M4 builtins, as it makes M4 libraries self 7463contained (no need for additional options). 7464 7465 There lies the problem.... 7466 7467 7468 The problem is that it is then tempting to use them in the middle of 7469an M4 script, as opposed to its initialization. This, if not carefully 7470thought out, can lead to disastrous effects: _you are changing the 7471language in the middle of the execution_. Changing and restoring the 7472syntax is often not enough: if you happened to invoke macros in between, 7473these macros are lost, as the current syntax is probably not the one 7474they were implemented with. 7475 7476 7477File: autoconf.info, Node: Quadrigraphs, Next: Quotation Rule Of Thumb, Prev: Changequote is Evil, Up: M4 Quotation 7478 74798.1.5 Quadrigraphs 7480------------------ 7481 7482When writing an Autoconf macro you may occasionally need to generate 7483special characters that are difficult to express with the standard 7484Autoconf quoting rules. For example, you may need to output the regular 7485expression `[^[]', which matches any character other than `['. This 7486expression contains unbalanced brackets so it cannot be put easily into 7487an M4 macro. 7488 7489 You can work around this problem by using one of the following 7490"quadrigraphs": 7491 7492`@<:@' 7493 `[' 7494 7495`@:>@' 7496 `]' 7497 7498`@S|@' 7499 `$' 7500 7501`@%:@' 7502 `#' 7503 7504`@&t@' 7505 Expands to nothing. 7506 7507 Quadrigraphs are replaced at a late stage of the translation process, 7508after `m4' is run, so they do not get in the way of M4 quoting. For 7509example, the string `^@<:@', independently of its quotation, appears as 7510`^[' in the output. 7511 7512 The empty quadrigraph can be used: 7513 7514 - to mark trailing spaces explicitly 7515 7516 Trailing spaces are smashed by `autom4te'. This is a feature. 7517 7518 - to produce other quadrigraphs 7519 7520 For instance `@<@&t@:@' produces `@<:@'. 7521 7522 - to escape _occurrences_ of forbidden patterns 7523 7524 For instance you might want to mention `AC_FOO' in a comment, while 7525 still being sure that `autom4te' still catches unexpanded `AC_*'. 7526 Then write `AC@&t@_FOO'. 7527 7528 The name `@&t@' was suggested by Paul Eggert: 7529 7530 I should give some credit to the `@&t@' pun. The `&' is my own 7531 invention, but the `t' came from the source code of the ALGOL68C 7532 compiler, written by Steve Bourne (of Bourne shell fame), and 7533 which used `mt' to denote the empty string. In C, it would have 7534 looked like something like: 7535 7536 char const mt[] = ""; 7537 7538 but of course the source code was written in Algol 68. 7539 7540 I don't know where he got `mt' from: it could have been his own 7541 invention, and I suppose it could have been a common pun around the 7542 Cambridge University computer lab at the time. 7543 7544 7545File: autoconf.info, Node: Quotation Rule Of Thumb, Prev: Quadrigraphs, Up: M4 Quotation 7546 75478.1.6 Quotation Rule Of Thumb 7548----------------------------- 7549 7550To conclude, the quotation rule of thumb is: 7551 7552 _One pair of quotes per pair of parentheses._ 7553 7554 Never over-quote, never under-quote, in particular in the definition 7555of macros. In the few places where the macros need to use brackets 7556(usually in C program text or regular expressions), properly quote _the 7557arguments_! 7558 7559 It is common to read Autoconf programs with snippets like: 7560 7561 AC_TRY_LINK( 7562 changequote(<<, >>)dnl 7563 <<#include <time.h> 7564 #ifndef tzname /* For SGI. */ 7565 extern char *tzname[]; /* RS6000 and others reject char **tzname. */ 7566 #endif>>, 7567 changequote([, ])dnl 7568 [atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no) 7569 7570which is incredibly useless since `AC_TRY_LINK' is _already_ double 7571quoting, so you just need: 7572 7573 AC_TRY_LINK( 7574 [#include <time.h> 7575 #ifndef tzname /* For SGI. */ 7576 extern char *tzname[]; /* RS6000 and others reject char **tzname. */ 7577 #endif], 7578 [atoi (*tzname);], 7579 [ac_cv_var_tzname=yes], 7580 [ac_cv_var_tzname=no]) 7581 7582The M4-fluent reader might note that these two examples are rigorously 7583equivalent, since M4 swallows both the `changequote(<<, >>)' and `<<' 7584`>>' when it "collects" the arguments: these quotes are not part of the 7585arguments! 7586 7587 Simplified, the example above is just doing this: 7588 7589 changequote(<<, >>)dnl 7590 <<[]>> 7591 changequote([, ])dnl 7592 7593instead of simply: 7594 7595 [[]] 7596 7597 With macros that do not double quote their arguments (which is the 7598rule), double-quote the (risky) literals: 7599 7600 AC_LINK_IFELSE([AC_LANG_PROGRAM( 7601 [[#include <time.h> 7602 #ifndef tzname /* For SGI. */ 7603 extern char *tzname[]; /* RS6000 and others reject char **tzname. */ 7604 #endif]], 7605 [atoi (*tzname);])], 7606 [ac_cv_var_tzname=yes], 7607 [ac_cv_var_tzname=no]) 7608 7609 Please note that the macro `AC_TRY_LINK' is obsolete, so you really 7610should be using `AC_LINK_IFELSE' instead. 7611 7612 *Note Quadrigraphs::, for what to do if you run into a hopeless case 7613where quoting does not suffice. 7614 7615 When you create a `configure' script using newly written macros, 7616examine it carefully to check whether you need to add more quotes in 7617your macros. If one or more words have disappeared in the M4 output, 7618you need more quotes. When in doubt, quote. 7619 7620 However, it's also possible to put on too many layers of quotes. If 7621this happens, the resulting `configure' script may contain unexpanded 7622macros. The `autoconf' program checks for this problem by looking for 7623the string `AC_' in `configure'. However, this heuristic does not work 7624in general: for example, it does not catch overquoting in `AC_DEFINE' 7625descriptions. 7626 7627 7628File: autoconf.info, Node: Using autom4te, Next: Programming in M4sugar, Prev: M4 Quotation, Up: Programming in M4 7629 76308.2 Using `autom4te' 7631==================== 7632 7633The Autoconf suite, including M4sugar, M4sh, and Autotest, in addition 7634to Autoconf per se, heavily rely on M4. All these different uses 7635revealed common needs factored into a layer over M4: `autom4te'(1). 7636 7637 `autom4te' is a preprocessor that is like `m4'. It supports M4 7638extensions designed for use in tools like Autoconf. 7639 7640* Menu: 7641 7642* autom4te Invocation:: A GNU M4 wrapper 7643* Customizing autom4te:: Customizing the Autoconf package 7644 7645 ---------- Footnotes ---------- 7646 7647 (1) Yet another great name from Lars J. Aas. 7648 7649 7650File: autoconf.info, Node: autom4te Invocation, Next: Customizing autom4te, Up: Using autom4te 7651 76528.2.1 Invoking `autom4te' 7653------------------------- 7654 7655The command line arguments are modeled after M4's: 7656 7657 autom4te OPTIONS FILES 7658 7659where the FILES are directly passed to `m4'. By default, GNU M4 is 7660found during configuration, but the environment variable `M4' can be 7661set to tell `autom4te' where to look. In addition to the regular 7662expansion, it handles the replacement of the quadrigraphs (*note 7663Quadrigraphs::), and of `__oline__', the current line in the output. 7664It supports an extended syntax for the FILES: 7665 7666`FILE.m4f' 7667 This file is an M4 frozen file. Note that _all the previous files 7668 are ignored_. See the option `--melt' for the rationale. 7669 7670`FILE?' 7671 If found in the library path, the FILE is included for expansion, 7672 otherwise it is ignored instead of triggering a failure. 7673 7674 7675 Of course, it supports the Autoconf common subset of options: 7676 7677`--help' 7678`-h' 7679 Print a summary of the command line options and exit. 7680 7681`--version' 7682`-V' 7683 Print the version number of Autoconf and exit. 7684 7685`--verbose' 7686`-v' 7687 Report processing steps. 7688 7689`--debug' 7690`-d' 7691 Don't remove the temporary files and be even more verbose. 7692 7693`--include=DIR' 7694`-I DIR' 7695 Also look for input files in DIR. Multiple invocations accumulate. 7696 7697`--output=FILE' 7698`-o FILE' 7699 Save output (script or trace) to FILE. The file `-' stands for 7700 the standard output. 7701 7702 7703 As an extension of `m4', it includes the following options: 7704 7705`--warnings=CATEGORY' 7706`-W CATEGORY' 7707 Report the warnings related to CATEGORY (which can actually be a 7708 comma separated list). *Note Reporting Messages::, macro 7709 `AC_DIAGNOSE', for a comprehensive list of categories. Special 7710 values include: 7711 7712 `all' 7713 report all the warnings 7714 7715 `none' 7716 report none 7717 7718 `error' 7719 treats warnings as errors 7720 7721 `no-CATEGORY' 7722 disable warnings falling into CATEGORY 7723 7724 Warnings about `syntax' are enabled by default, and the environment 7725 variable `WARNINGS', a comma separated list of categories, is 7726 honored. `autom4te -W CATEGORY' actually behaves as if you had 7727 run: 7728 7729 autom4te --warnings=syntax,$WARNINGS,CATEGORY 7730 7731 For example, if you want to disable defaults and `WARNINGS' of 7732 `autom4te', but enable the warnings about obsolete constructs, you 7733 would use `-W none,obsolete'. 7734 7735 `autom4te' displays a back trace for errors, but not for warnings; 7736 if you want them, just pass `-W error'. 7737 7738`--melt' 7739`-M' 7740 Do not use frozen files. Any argument `FILE.m4f' is replaced by 7741 `FILE.m4'. This helps tracing the macros which are executed only 7742 when the files are frozen, typically `m4_define'. For instance, 7743 running: 7744 7745 autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4 7746 7747 is roughly equivalent to running: 7748 7749 m4 1.m4 2.m4 3.m4 4.m4 input.m4 7750 7751 while 7752 7753 autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4 7754 7755 is equivalent to: 7756 7757 m4 --reload-state=4.m4f input.m4 7758 7759`--freeze' 7760`-f' 7761 Produce a frozen state file. `autom4te' freezing is stricter than 7762 M4's: it must produce no warnings, and no output other than empty 7763 lines (a line with white space is _not_ empty) and comments 7764 (starting with `#'). Unlike `m4''s similarly-named option, this 7765 option takes no argument: 7766 7767 autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f 7768 7769 corresponds to 7770 7771 m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f 7772 7773`--mode=OCTAL-MODE' 7774`-m OCTAL-MODE' 7775 Set the mode of the non-traces output to OCTAL-MODE; by default 7776 `0666'. 7777 7778 7779 As another additional feature over `m4', `autom4te' caches its 7780results. GNU M4 is able to produce a regular output and traces at the 7781same time. Traces are heavily used in the GNU Build System: 7782`autoheader' uses them to build `config.h.in', `autoreconf' to 7783determine what GNU Build System components are used, `automake' to 7784"parse" `configure.ac' etc. To avoid recomputation, traces are cached 7785while performing regular expansion, and conversely. This cache is 7786(actually, the caches are) stored in the directory `autom4te.cache'. 7787_It can safely be removed_ at any moment (especially if for some reason 7788`autom4te' considers it is trashed). 7789 7790`--cache=DIRECTORY' 7791`-C DIRECTORY' 7792 Specify the name of the directory where the result should be 7793 cached. Passing an empty value disables caching. Be sure to pass 7794 a relative file name, as for the time being, global caches are not 7795 supported. 7796 7797`--no-cache' 7798 Don't cache the results. 7799 7800`--force' 7801`-f' 7802 If a cache is used, consider it obsolete (but update it anyway). 7803 7804 7805 Because traces are so important to the GNU Build System, `autom4te' 7806provides high level tracing features as compared to M4, and helps 7807exploiting the cache: 7808 7809`--trace=MACRO[:FORMAT]' 7810`-t MACRO[:FORMAT]' 7811 Trace the invocations of MACRO according to the FORMAT. Multiple 7812 `--trace' arguments can be used to list several macros. Multiple 7813 `--trace' arguments for a single macro are not cumulative; 7814 instead, you should just make FORMAT as long as needed. 7815 7816 The FORMAT is a regular string, with newlines if desired, and 7817 several special escape codes. It defaults to `$f:$l:$n:$%'. It 7818 can use the following special escapes: 7819 7820 `$$' 7821 The character `$'. 7822 7823 `$f' 7824 The file name from which MACRO is called. 7825 7826 `$l' 7827 The line number from which MACRO is called. 7828 7829 `$d' 7830 The depth of the MACRO call. This is an M4 technical detail 7831 that you probably don't want to know about. 7832 7833 `$n' 7834 The name of the MACRO. 7835 7836 `$NUM' 7837 The NUMth argument of the call to MACRO. 7838 7839 `$@' 7840 `$SEP@' 7841 `${SEPARATOR}@' 7842 All the arguments passed to MACRO, separated by the character 7843 SEP or the string SEPARATOR (`,' by default). Each argument 7844 is quoted, i.e., enclosed in a pair of square brackets. 7845 7846 `$*' 7847 `$SEP*' 7848 `${SEPARATOR}*' 7849 As above, but the arguments are not quoted. 7850 7851 `$%' 7852 `$SEP%' 7853 `${SEPARATOR}%' 7854 As above, but the arguments are not quoted, all new line 7855 characters in the arguments are smashed, and the default 7856 separator is `:'. 7857 7858 The escape `$%' produces single-line trace outputs (unless 7859 you put newlines in the `separator'), while `$@' and `$*' do 7860 not. 7861 7862 *Note autoconf Invocation::, for examples of trace uses. 7863 7864`--preselect=MACRO' 7865`-p MACRO' 7866 Cache the traces of MACRO, but do not enable traces. This is 7867 especially important to save CPU cycles in the future. For 7868 instance, when invoked, `autoconf' preselects all the macros that 7869 `autoheader', `automake', `autoreconf', etc., trace, so that 7870 running `m4' is not needed to trace them: the cache suffices. 7871 This results in a huge speed-up. 7872 7873 7874 Finally, `autom4te' introduces the concept of "Autom4te libraries". 7875They consists in a powerful yet extremely simple feature: sets of 7876combined command line arguments: 7877 7878`--language=LANGUAGE' 7879`-l LANGUAGE' 7880 Use the LANGUAGE Autom4te library. Current languages include: 7881 7882 `M4sugar' 7883 create M4sugar output. 7884 7885 `M4sh' 7886 create M4sh executable shell scripts. 7887 7888 `Autotest' 7889 create Autotest executable test suites. 7890 7891 `Autoconf-without-aclocal-m4' 7892 create Autoconf executable configure scripts without reading 7893 `aclocal.m4'. 7894 7895 `Autoconf' 7896 create Autoconf executable configure scripts. This language 7897 inherits all the characteristics of 7898 `Autoconf-without-aclocal-m4' and additionally reads 7899 `aclocal.m4'. 7900 7901`--prepend-include=DIR' 7902 7903`-B DIR' 7904 Prepend directory DIR to the search path. This is used to include 7905 the language-specific files before any third-party macros. 7906 7907 7908 As an example, if Autoconf is installed in its default location, 7909`/usr/local', the command `autom4te -l m4sugar foo.m4' is strictly 7910equivalent to the command: 7911 7912 autom4te --prepend-include /usr/local/share/autoconf \ 7913 m4sugar/m4sugar.m4f --warnings syntax foo.m4 7914 7915Recursive expansion applies here: the command `autom4te -l m4sh foo.m4' 7916is the same as `autom4te --language M4sugar m4sugar/m4sh.m4f foo.m4', 7917i.e.: 7918 7919 autom4te --prepend-include /usr/local/share/autoconf \ 7920 m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4 7921 7922The definition of the languages is stored in `autom4te.cfg'. 7923 7924 7925File: autoconf.info, Node: Customizing autom4te, Prev: autom4te Invocation, Up: Using autom4te 7926 79278.2.2 Customizing `autom4te' 7928---------------------------- 7929 7930One can customize `autom4te' via `~/.autom4te.cfg' (i.e., as found in 7931the user home directory), and `./.autom4te.cfg' (i.e., as found in the 7932directory from which `autom4te' is run). The order is first reading 7933`autom4te.cfg', then `~/.autom4te.cfg', then `./.autom4te.cfg', and 7934finally the command line arguments. 7935 7936 In these text files, comments are introduced with `#', and empty 7937lines are ignored. Customization is performed on a per-language basis, 7938wrapped in between a `begin-language: "LANGUAGE"', `end-language: 7939"LANGUAGE"' pair. 7940 7941 Customizing a language stands for appending options (*note autom4te 7942Invocation::) to the current definition of the language. Options, and 7943more generally arguments, are introduced by `args: ARGUMENTS'. You may 7944use the traditional shell syntax to quote the ARGUMENTS. 7945 7946 As an example, to disable Autoconf caches (`autom4te.cache') 7947globally, include the following lines in `~/.autom4te.cfg': 7948 7949 7950## ------------------ ## 7951## User Preferences. ## 7952## ------------------ ## 7953 7954begin-language: "Autoconf-without-aclocal-m4" 7955args: --no-cache 7956end-language: "Autoconf-without-aclocal-m4" 7957 7958 7959File: autoconf.info, Node: Programming in M4sugar, Next: Programming in M4sh, Prev: Using autom4te, Up: Programming in M4 7960 79618.3 Programming in M4sugar 7962========================== 7963 7964M4 by itself provides only a small, but sufficient, set of all-purpose 7965macros. M4sugar introduces additional generic macros. Its name was 7966coined by Lars J. Aas: "Readability And Greater Understanding Stands 4 7967M4sugar". 7968 7969* Menu: 7970 7971* Redefined M4 Macros:: M4 builtins changed in M4sugar 7972* Looping constructs:: Iteration in M4 7973* Evaluation Macros:: More quotation and evaluation control 7974* Text processing Macros:: String manipulation in M4 7975* Forbidden Patterns:: Catching unexpanded macros 7976 7977 7978File: autoconf.info, Node: Redefined M4 Macros, Next: Looping constructs, Up: Programming in M4sugar 7979 79808.3.1 Redefined M4 Macros 7981------------------------- 7982 7983With a few exceptions, all the M4 native macros are moved in the `m4_' 7984pseudo-namespace, e.g., M4sugar renames `define' as `m4_define' etc. 7985 7986 Some M4 macros are redefined, and are slightly incompatible with 7987their native equivalent. 7988 7989 -- Macro: dnl 7990 This macro kept its original name: no `m4_dnl' is defined. 7991 7992 -- Macro: m4_defn (MACRO) 7993 Unlike the M4 builtin, this macro fails if MACRO is not defined. 7994 See `m4_undefine'. 7995 7996 -- Macro: m4_exit (EXIT-STATUS) 7997 This macro corresponds to `m4exit'. 7998 7999 -- Macro: m4_if (COMMENT) 8000 -- Macro: m4_if (STRING-1, STRING-2, EQUAL, [NOT-EQUAL]) 8001 -- Macro: m4_if (STRING-1, STRING-2, EQUAL, ...) 8002 This macro corresponds to `ifelse'. 8003 8004 -- Macro: m4_include (FILE) 8005 -- Macro: m4_sinclude (FILE) 8006 Like the M4 builtins, but warn against multiple inclusions of FILE. 8007 8008 -- Macro: m4_bpatsubst (STRING, REGEXP, [REPLACEMENT]) 8009 This macro corresponds to `patsubst'. The name `m4_patsubst' is 8010 kept for future versions of M4sh, on top of GNU M4 which will 8011 provide extended regular expression syntax via `epatsubst'. 8012 8013 -- Macro: m4_popdef (MACRO) 8014 Unlike the M4 builtin, this macro fails if MACRO is not defined. 8015 See `m4_undefine'. 8016 8017 -- Macro: m4_bregexp (STRING, REGEXP, [REPLACEMENT]) 8018 This macro corresponds to `regexp'. The name `m4_regexp' is kept 8019 for future versions of M4sh, on top of GNU M4 which will provide 8020 extended regular expression syntax via `eregexp'. 8021 8022 -- Macro: m4_wrap (TEXT) 8023 This macro corresponds to `m4wrap'. 8024 8025 Posix requires arguments of multiple `m4wrap' calls to be 8026 reprocessed at EOF in the same order as the original calls. GNU 8027 M4 versions through 1.4.x, however, reprocess them in reverse 8028 order. Your code should not depend on the order. 8029 8030 Also, Posix requires `m4wrap' to ignore its second and succeeding 8031 arguments, but GNU M4 versions through 1.4.x concatenate the 8032 arguments with intervening spaces. Your code should not pass more 8033 than one argument. 8034 8035 You are encouraged to end TEXT with `[]', to avoid unexpected 8036 token pasting between consecutive invocations of `m4_wrap', as in: 8037 8038 m4_define([foo], [bar]) 8039 m4_define([foofoo], [OUCH]) 8040 m4_wrap([foo]) 8041 m4_wrap([foo]) 8042 =>OUCH 8043 8044 -- Macro: m4_undefine (MACRO) 8045 Unlike the M4 builtin, this macro fails if MACRO is not defined. 8046 Use 8047 8048 m4_ifdef([MACRO], [m4_undefine([MACRO])]) 8049 8050 to recover the behavior of the builtin. 8051 8052 -- Macro: m4_maketemp (TEMPLATE) 8053 -- Macro: m4_mkstemp (TEMPLATE) 8054 Posix requires `maketemp' to replace the trailing `X' characters 8055 in TEMPLATE with the process id, without regards to the existence 8056 of a file by that name, but this a security hole. When this was 8057 pointed out to the Posix folks, they agreed to invent a new macro 8058 `mkstemp' that always creates a uniquely named file, but not all 8059 versions of GNU M4 support the new macro. In M4sugar, 8060 `m4_maketemp' and `m4_mkstemp' are synonyms for each other, and 8061 both have the secure semantics regardless of which macro the 8062 underlying M4 provides. 8063 8064 8065File: autoconf.info, Node: Looping constructs, Next: Evaluation Macros, Prev: Redefined M4 Macros, Up: Programming in M4sugar 8066 80678.3.2 Looping constructs 8068------------------------ 8069 8070The following macros implement loops in M4. 8071 8072 -- Macro: m4_for (VAR, FIRST, LAST, [STEP], EXPRESSION) 8073 Loop over the numeric values between FIRST and LAST including 8074 bounds by increments of STEP. For each iteration, expand 8075 EXPRESSION with the numeric value assigned to VAR. If STEP is 8076 omitted, it defaults to `1' or `-1' depending on the order of the 8077 limits. If given, STEP has to match this order. 8078 8079 -- Macro: m4_foreach (VAR, LIST, EXPRESSION) 8080 Loop over the comma-separated M4 list LIST, assigning each value 8081 to VAR, and expand EXPRESSION. The following example outputs two 8082 lines: 8083 8084 m4_foreach([myvar], [[foo], [bar, baz]], 8085 [echo myvar 8086 ]) 8087 8088 -- Macro: m4_foreach_w (VAR, LIST, EXPRESSION) 8089 Loop over the white-space-separated list LIST, assigning each value 8090 to VAR, and expand EXPRESSION. 8091 8092 The deprecated macro `AC_FOREACH' is an alias of `m4_foreach_w'. 8093 8094 8095File: autoconf.info, Node: Evaluation Macros, Next: Text processing Macros, Prev: Looping constructs, Up: Programming in M4sugar 8096 80978.3.3 Evaluation Macros 8098----------------------- 8099 8100The following macros give some control over the order of the evaluation 8101by adding or removing levels of quotes. They are meant for hard-core M4 8102programmers. 8103 8104 -- Macro: m4_dquote (ARG1, ...) 8105 Return the arguments as a quoted list of quoted arguments. 8106 8107 -- Macro: m4_quote (ARG1, ...) 8108 Return the arguments as a single entity, i.e., wrap them into a 8109 pair of quotes. 8110 8111 The following example aims at emphasizing the difference between 8112(i), not using these macros, (ii), using `m4_quote', and (iii), using 8113`m4_dquote'. 8114 8115 $ cat example.m4 8116 # Overquote, so that quotes are visible. 8117 m4_define([show], [$[]1 = [$1], $[]@ = [$@]]) 8118 m4_define([mkargs], [1, 2, 3]) 8119 m4_define([arg1], [[$1]]) 8120 m4_divert(0)dnl 8121 show(a, b) 8122 show(m4_quote(a, b)) 8123 show(m4_dquote(a, b)) 8124 arg1(mkargs) 8125 arg1([mkargs]) 8126 arg1(m4_defn([mkargs])) 8127 arg1(m4_quote(mkargs)) 8128 arg1(m4_dquote(mkargs)) 8129 $ autom4te -l m4sugar example.m4 8130 $1 = a, $@ = [a],[b] 8131 $1 = a,b, $@ = [a,b] 8132 $1 = [a],[b], $@ = [[a],[b]] 8133 1 8134 mkargs 8135 1, 2, 3 8136 1,2,3 8137 [1],[2],[3] 8138 8139 8140File: autoconf.info, Node: Text processing Macros, Next: Forbidden Patterns, Prev: Evaluation Macros, Up: Programming in M4sugar 8141 81428.3.4 Text processing Macros 8143---------------------------- 8144 8145The following macros may be used to manipulate strings in M4. They are 8146not intended for casual use. 8147 8148 -- Macro: m4_re_escape (STRING) 8149 Backslash-escape all characters in STRING that are active in 8150 regexps. 8151 8152 -- Macro: m4_tolower (STRING) 8153 -- Macro: m4_toupper (STRING) 8154 Return STRING with letters converted to upper or lower case, 8155 respectively. 8156 8157 -- Macro: m4_split (STRING, [REGEXP]) 8158 Split STRING into an M4 list of elements quoted by `[' and `]', 8159 while keeping white space at the beginning and at the end. If 8160 REGEXP is given, use it instead of `[\t ]+' for splitting. If 8161 STRING is empty, the result is an empty list. 8162 8163 -- Macro: m4_normalize (STRING) 8164 Remove leading and trailing spaces and tabs, sequences of 8165 backslash-then-newline, and replace multiple spaces and tabs with a 8166 single space. 8167 8168 -- Macro: m4_append (MACRO-NAME, STRING, [SEPARATOR]) 8169 -- Macro: m4_append_uniq (MACRO-NAME, STRING, [SEPARATOR]) 8170 Redefine MACRO-NAME to its former contents with SEPARATOR and 8171 STRING added at the end. If MACRO-NAME was undefined before (but 8172 not if it was defined but empty), then no SEPARATOR is added. 8173 `m4_append' can be used to grow strings, and `m4_append_uniq' to 8174 grow strings without duplicating substrings. 8175 8176 8177File: autoconf.info, Node: Forbidden Patterns, Prev: Text processing Macros, Up: Programming in M4sugar 8178 81798.3.5 Forbidden Patterns 8180------------------------ 8181 8182M4sugar provides a means to define suspicious patterns, patterns 8183describing tokens which should not be found in the output. For 8184instance, if an Autoconf `configure' script includes tokens such as 8185`AC_DEFINE', or `dnl', then most probably something went wrong 8186(typically a macro was not evaluated because of overquotation). 8187 8188 M4sugar forbids all the tokens matching `^m4_' and `^dnl$'. 8189 8190 -- Macro: m4_pattern_forbid (PATTERN) 8191 Declare that no token matching PATTERN must be found in the output. 8192 Comments are not checked; this can be a problem if, for instance, 8193 you have some macro left unexpanded after an `#include'. No 8194 consensus is currently found in the Autoconf community, as some 8195 people consider it should be valid to name macros in comments 8196 (which doesn't make sense to the author of this documentation, as 8197 `#'-comments should document the output, not the input, documented 8198 by `dnl' comments). 8199 8200 Of course, you might encounter exceptions to these generic rules, for 8201instance you might have to refer to `$m4_flags'. 8202 8203 -- Macro: m4_pattern_allow (PATTERN) 8204 Any token matching PATTERN is allowed, including if it matches an 8205 `m4_pattern_forbid' pattern. 8206 8207 8208File: autoconf.info, Node: Programming in M4sh, Next: File Descriptor Macros, Prev: Programming in M4sugar, Up: Programming in M4 8209 82108.4 Programming in M4sh 8211======================= 8212 8213M4sh, pronounced "mash", is aiming at producing portable Bourne shell 8214scripts. This name was coined by Lars J. Aas, who notes that, 8215according to the Webster's Revised Unabridged Dictionary (1913): 8216 8217 Mash \Mash\, n. [Akin to G. meisch, maisch, meische, maische, 8218 mash, wash, and prob. to AS. miscian to mix. See "Mix".] 8219 8220 1. A mass of mixed ingredients reduced to a soft pulpy state by 8221 beating or pressure.... 8222 8223 2. A mixture of meal or bran and water fed to animals. 8224 8225 3. A mess; trouble. [Obs.] -Beau. & Fl. 8226 8227 For the time being, it is not mature enough to be widely used. 8228 8229 M4sh provides portable alternatives for some common shell constructs 8230that unfortunately are not portable in practice. 8231 8232 -- Macro: AS_BOURNE_COMPATIBLE 8233 Set up the shell to be more compatible with the Bourne shell as 8234 standardized by Posix, if possible. This may involve setting 8235 environment variables, or setting options, or similar 8236 implementation-specific actions. 8237 8238 -- Macro: AS_CASE (WORD, [PATTERN1], [IF-MATCHED1], ..., [DEFAULT]) 8239 Expand into a shell `case' statement, where WORD is matched 8240 against one or more patterns. IF-MATCHED is run if the 8241 corresponding pattern matched WORD, else DEFAULT is run. 8242 8243 -- Macro: AS_DIRNAME (FILE-NAME) 8244 Output the directory portion of FILE-NAME. For example, if 8245 `$file' is `/one/two/three', the command 8246 `dir=`AS_DIRNAME(["$file"])`' sets `dir' to `/one/two'. 8247 8248 -- Macro: AS_IF (TEST1, [RUN-IF-TRUE1], ..., [RUN-IF-FALSE]) 8249 Run shell code TEST1. If TEST1 exits with a zero status then run 8250 shell code RUN-IF-TRUE1, else examine further tests. If no test 8251 exits with a zero status, run shell code RUN-IF-FALSE, with 8252 simplifications if either RUN-IF-TRUE1 or RUN-IF-FALSE1 is empty. 8253 For example, 8254 8255 AS_IF([test "$foo" = yes], [HANDLE_FOO([yes])], 8256 [test "$foo" != no], [HANDLE_FOO([maybe])], 8257 [echo foo not specified]) 8258 8259 ensures any required macros of `HANDLE_FOO' are expanded before 8260 the first test. 8261 8262 -- Macro: AS_MKDIR_P (FILE-NAME) 8263 Make the directory FILE-NAME, including intervening directories as 8264 necessary. This is equivalent to `mkdir -p FILE-NAME', except 8265 that it is portable to older versions of `mkdir' that lack support 8266 for the `-p' option. Also, `AS_MKDIR_P' succeeds if FILE-NAME is 8267 a symbolic link to an existing directory, even though Posix is 8268 unclear whether `mkdir -p' should succeed in that case. If 8269 creation of FILE-NAME fails, exit the script. 8270 8271 Also see the `AC_PROG_MKDIR_P' macro (*note Particular Programs::). 8272 8273 -- Macro: AS_SHELL_SANITIZE 8274 Initialize the shell suitably for `configure' scripts. This has 8275 the effect of `AS_BOURNE_COMPATIBLE', and sets some other 8276 environment variables for predictable results from configuration 8277 tests. For example, it sets `LC_ALL' to change to the default C 8278 locale. *Note Special Shell Variables::. 8279 8280 -- Macro: AS_TR_CPP (EXPRESSION) 8281 Transform EXPRESSION into a valid right-hand side for a C 8282 `#define'. For example: 8283 8284 # This outputs "#define HAVE_CHAR_P 1". 8285 type="char *" 8286 echo "#define AS_TR_CPP([HAVE_$type]) 1" 8287 8288 -- Macro: AS_TR_SH (EXPRESSION) 8289 Transform EXPRESSION into a valid shell variable name. For 8290 example: 8291 8292 # This outputs "Have it!". 8293 header="sys/some file.h" 8294 AS_TR_SH([HAVE_$header])=yes 8295 if test "$HAVE_sys_some_file_h" = yes; then echo "Have it!"; fi 8296 8297 -- Macro: AS_SET_CATFILE (VAR, DIR, FILE) 8298 Set the shell variable VAR to DIR/FILE, but optimizing the common 8299 cases (DIR or FILE is `.', FILE is absolute, etc.). 8300 8301 8302File: autoconf.info, Node: File Descriptor Macros, Prev: Programming in M4sh, Up: Programming in M4 8303 83048.5 File Descriptor Macros 8305========================== 8306 8307The following macros define file descriptors used to output messages 8308(or input values) from `configure' scripts. For example: 8309 8310 echo "$wombats found" >&AS_MESSAGE_LOG_FD 8311 echo 'Enter desired kangaroo count:' >&AS_MESSAGE_FD 8312 read kangaroos <&AS_ORIGINAL_STDIN_FD` 8313 8314However doing so is seldom needed, because Autoconf provides higher 8315level macros as described below. 8316 8317 -- Macro: AS_MESSAGE_FD 8318 The file descriptor for `checking for...' messages and results. 8319 Normally this directs messages to the standard output, however when 8320 `configure' is run with the `-q' option, messages sent to 8321 `AS_MESSAGE_FD' are discarded. 8322 8323 If you want to display some messages, consider using one of the 8324 printing macros (*note Printing Messages::) instead. Copies of 8325 messages output via these macros are also recorded in `config.log'. 8326 8327 -- Macro: AS_MESSAGE_LOG_FD 8328 The file descriptor for messages logged to `config.log'. Macros 8329 that run tools, like `AC_COMPILE_IFELSE' (*note Running the 8330 Compiler::), redirect all output to this descriptor. You may want 8331 to do so if you develop such a low-level macro. 8332 8333 -- Macro: AS_ORIGINAL_STDIN_FD 8334 The file descriptor for the original standard input. 8335 8336 When `configure' runs, it may accidentally execute an interactive 8337 command that has the same name as the non-interactive meant to be 8338 used or checked. If the standard input was the terminal, such 8339 interactive programs would cause `configure' to stop, pending some 8340 user input. Therefore `configure' redirects its standard input 8341 from `/dev/null' during its initialization. This is not normally 8342 a problem, since `configure' normally does not need user input. 8343 8344 In the extreme case where your `configure' script really needs to 8345 obtain some values from the original standard input, you can read 8346 them explicitly from `AS_ORIGINAL_STDIN_FD'. 8347 8348 8349File: autoconf.info, Node: Writing Autoconf Macros, Next: Portable Shell, Prev: Programming in M4, Up: Top 8350 83519 Writing Autoconf Macros 8352************************* 8353 8354When you write a feature test that could be applicable to more than one 8355software package, the best thing to do is encapsulate it in a new macro. 8356Here are some instructions and guidelines for writing Autoconf macros. 8357 8358* Menu: 8359 8360* Macro Definitions:: Basic format of an Autoconf macro 8361* Macro Names:: What to call your new macros 8362* Reporting Messages:: Notifying `autoconf' users 8363* Dependencies Between Macros:: What to do when macros depend on other macros 8364* Obsoleting Macros:: Warning about old ways of doing things 8365* Coding Style:: Writing Autoconf macros a` la Autoconf 8366 8367 8368File: autoconf.info, Node: Macro Definitions, Next: Macro Names, Up: Writing Autoconf Macros 8369 83709.1 Macro Definitions 8371===================== 8372 8373Autoconf macros are defined using the `AC_DEFUN' macro, which is 8374similar to the M4 builtin `m4_define' macro. In addition to defining a 8375macro, `AC_DEFUN' adds to it some code that is used to constrain the 8376order in which macros are called (*note Prerequisite Macros::). 8377 8378 An Autoconf macro definition looks like this: 8379 8380 AC_DEFUN(MACRO-NAME, MACRO-BODY) 8381 8382 You can refer to any arguments passed to the macro as `$1', `$2', 8383etc. *Note How to define new macros: (m4.info)Definitions, for more 8384complete information on writing M4 macros. 8385 8386 Be sure to properly quote both the MACRO-BODY _and_ the MACRO-NAME 8387to avoid any problems if the macro happens to have been previously 8388defined. 8389 8390 Each macro should have a header comment that gives its prototype, 8391and a brief description. When arguments have default values, display 8392them in the prototype. For example: 8393 8394 # AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1]) 8395 # -------------------------------------- 8396 m4_define([AC_MSG_ERROR], 8397 [{ AS_MESSAGE([error: $1], [2]) 8398 exit m4_default([$2], [1]); }]) 8399 8400 Comments about the macro should be left in the header comment. Most 8401other comments make their way into `configure', so just keep using `#' 8402to introduce comments. 8403 8404 If you have some special comments about pure M4 code, comments that 8405make no sense in `configure' and in the header comment, then use the 8406builtin `dnl': it causes M4 to discard the text through the next 8407newline. 8408 8409 Keep in mind that `dnl' is rarely needed to introduce comments; 8410`dnl' is more useful to get rid of the newlines following macros that 8411produce no output, such as `AC_REQUIRE'. 8412 8413 8414File: autoconf.info, Node: Macro Names, Next: Reporting Messages, Prev: Macro Definitions, Up: Writing Autoconf Macros 8415 84169.2 Macro Names 8417=============== 8418 8419All of the Autoconf macros have all-uppercase names starting with `AC_' 8420to prevent them from accidentally conflicting with other text. All 8421shell variables that they use for internal purposes have 8422mostly-lowercase names starting with `ac_'. To ensure that your macros 8423don't conflict with present or future Autoconf macros, you should 8424prefix your own macro names and any shell variables they use with some 8425other sequence. Possibilities include your initials, or an abbreviation 8426for the name of your organization or software package. 8427 8428 Most of the Autoconf macros' names follow a structured naming 8429convention that indicates the kind of feature check by the name. The 8430macro names consist of several words, separated by underscores, going 8431from most general to most specific. The names of their cache variables 8432use the same convention (*note Cache Variable Names::, for more 8433information on them). 8434 8435 The first word of the name after `AC_' usually tells the category of 8436the feature being tested. Here are the categories used in Autoconf for 8437specific test macros, the kind of macro that you are more likely to 8438write. They are also used for cache variables, in all-lowercase. Use 8439them where applicable; where they're not, invent your own categories. 8440 8441`C' 8442 C language builtin features. 8443 8444`DECL' 8445 Declarations of C variables in header files. 8446 8447`FUNC' 8448 Functions in libraries. 8449 8450`GROUP' 8451 Posix group owners of files. 8452 8453`HEADER' 8454 Header files. 8455 8456`LIB' 8457 C libraries. 8458 8459`PATH' 8460 Absolute names of files, including programs. 8461 8462`PROG' 8463 The base names of programs. 8464 8465`MEMBER' 8466 Members of aggregates. 8467 8468`SYS' 8469 Operating system features. 8470 8471`TYPE' 8472 C builtin or declared types. 8473 8474`VAR' 8475 C variables in libraries. 8476 8477 After the category comes the name of the particular feature being 8478tested. Any further words in the macro name indicate particular aspects 8479of the feature. For example, `AC_PROG_CC_STDC' checks whether the C 8480compiler supports ISO Standard C. 8481 8482 An internal macro should have a name that starts with an underscore; 8483Autoconf internals should therefore start with `_AC_'. Additionally, a 8484macro that is an internal subroutine of another macro should have a 8485name that starts with an underscore and the name of that other macro, 8486followed by one or more words saying what the internal macro does. For 8487example, `AC_PATH_X' has internal macros `_AC_PATH_X_XMKMF' and 8488`_AC_PATH_X_DIRECT'. 8489 8490 8491File: autoconf.info, Node: Reporting Messages, Next: Dependencies Between Macros, Prev: Macro Names, Up: Writing Autoconf Macros 8492 84939.3 Reporting Messages 8494====================== 8495 8496When macros statically diagnose abnormal situations, benign or fatal, 8497they should report them using these macros. For dynamic issues, i.e., 8498when `configure' is run, see *Note Printing Messages::. 8499 8500 -- Macro: AC_DIAGNOSE (CATEGORY, MESSAGE) 8501 Report MESSAGE as a warning (or as an error if requested by the 8502 user) if warnings of the CATEGORY are turned on. You are 8503 encouraged to use standard categories, which currently include: 8504 8505 `all' 8506 messages that don't fall into one of the following 8507 categories. Use of an empty CATEGORY is equivalent. 8508 8509 `cross' 8510 related to cross compilation issues. 8511 8512 `obsolete' 8513 use of an obsolete construct. 8514 8515 `syntax' 8516 dubious syntactic constructs, incorrectly ordered macro calls. 8517 8518 -- Macro: AC_WARNING (MESSAGE) 8519 Equivalent to `AC_DIAGNOSE([syntax], MESSAGE)', but you are 8520 strongly encouraged to use a finer grained category. 8521 8522 -- Macro: AC_FATAL (MESSAGE) 8523 Report a severe error MESSAGE, and have `autoconf' die. 8524 8525 When the user runs `autoconf -W error', warnings from `AC_DIAGNOSE' 8526and `AC_WARNING' are reported as error, see *Note autoconf Invocation::. 8527 8528 8529File: autoconf.info, Node: Dependencies Between Macros, Next: Obsoleting Macros, Prev: Reporting Messages, Up: Writing Autoconf Macros 8530 85319.4 Dependencies Between Macros 8532=============================== 8533 8534Some Autoconf macros depend on other macros having been called first in 8535order to work correctly. Autoconf provides a way to ensure that certain 8536macros are called if needed and a way to warn the user if macros are 8537called in an order that might cause incorrect operation. 8538 8539* Menu: 8540 8541* Prerequisite Macros:: Ensuring required information 8542* Suggested Ordering:: Warning about possible ordering problems 8543* One-Shot Macros:: Ensuring a macro is called only once 8544 8545 8546File: autoconf.info, Node: Prerequisite Macros, Next: Suggested Ordering, Up: Dependencies Between Macros 8547 85489.4.1 Prerequisite Macros 8549------------------------- 8550 8551A macro that you write might need to use values that have previously 8552been computed by other macros. For example, `AC_DECL_YYTEXT' examines 8553the output of `flex' or `lex', so it depends on `AC_PROG_LEX' having 8554been called first to set the shell variable `LEX'. 8555 8556 Rather than forcing the user of the macros to keep track of the 8557dependencies between them, you can use the `AC_REQUIRE' macro to do it 8558automatically. `AC_REQUIRE' can ensure that a macro is only called if 8559it is needed, and only called once. 8560 8561 -- Macro: AC_REQUIRE (MACRO-NAME) 8562 If the M4 macro MACRO-NAME has not already been called, call it 8563 (without any arguments). Make sure to quote MACRO-NAME with 8564 square brackets. MACRO-NAME must have been defined using 8565 `AC_DEFUN' or else contain a call to `AC_PROVIDE' to indicate that 8566 it has been called. 8567 8568 `AC_REQUIRE' must be used inside a macro defined by `AC_DEFUN'; it 8569 must not be called from the top level. 8570 8571 `AC_REQUIRE' is often misunderstood. It really implements 8572dependencies between macros in the sense that if one macro depends upon 8573another, the latter is expanded _before_ the body of the former. To be 8574more precise, the required macro is expanded before the outermost 8575defined macro in the current expansion stack. In particular, 8576`AC_REQUIRE([FOO])' is not replaced with the body of `FOO'. For 8577instance, this definition of macros: 8578 8579 AC_DEFUN([TRAVOLTA], 8580 [test "$body_temperature_in_celsius" -gt "38" && 8581 dance_floor=occupied]) 8582 AC_DEFUN([NEWTON_JOHN], 8583 [test "$hair_style" = "curly" && 8584 dance_floor=occupied]) 8585 8586 AC_DEFUN([RESERVE_DANCE_FLOOR], 8587 [if date | grep '^Sat.*pm' >/dev/null 2>&1; then 8588 AC_REQUIRE([TRAVOLTA]) 8589 AC_REQUIRE([NEWTON_JOHN]) 8590 fi]) 8591 8592with this `configure.ac' 8593 8594 AC_INIT([Dance Manager], [1.0], [bug-dance@example.org]) 8595 RESERVE_DANCE_FLOOR 8596 if test "$dance_floor" = occupied; then 8597 AC_MSG_ERROR([cannot pick up here, let's move]) 8598 fi 8599 8600does not leave you with a better chance to meet a kindred soul at other 8601times than Saturday night since it expands into: 8602 8603 test "$body_temperature_in_Celsius" -gt "38" && 8604 dance_floor=occupied 8605 test "$hair_style" = "curly" && 8606 dance_floor=occupied 8607 fi 8608 if date | grep '^Sat.*pm' >/dev/null 2>&1; then 8609 8610 8611 fi 8612 8613 This behavior was chosen on purpose: (i) it prevents messages in 8614required macros from interrupting the messages in the requiring macros; 8615(ii) it avoids bad surprises when shell conditionals are used, as in: 8616 8617 if ...; then 8618 AC_REQUIRE([SOME_CHECK]) 8619 fi 8620 ... 8621 SOME_CHECK 8622 8623 The helper macros `AS_IF' and `AS_CASE' may be used to enforce 8624expansion of required macros outside of shell conditional constructs. 8625You are furthermore encouraged to put all `AC_REQUIRE' calls at the 8626beginning of a macro. You can use `dnl' to avoid the empty lines they 8627leave. 8628 8629 8630File: autoconf.info, Node: Suggested Ordering, Next: One-Shot Macros, Prev: Prerequisite Macros, Up: Dependencies Between Macros 8631 86329.4.2 Suggested Ordering 8633------------------------ 8634 8635Some macros should be run before another macro if both are called, but 8636neither _requires_ that the other be called. For example, a macro that 8637changes the behavior of the C compiler should be called before any 8638macros that run the C compiler. Many of these dependencies are noted in 8639the documentation. 8640 8641 Autoconf provides the `AC_BEFORE' macro to warn users when macros 8642with this kind of dependency appear out of order in a `configure.ac' 8643file. The warning occurs when creating `configure' from 8644`configure.ac', not when running `configure'. 8645 8646 For example, `AC_PROG_CPP' checks whether the C compiler can run the 8647C preprocessor when given the `-E' option. It should therefore be 8648called after any macros that change which C compiler is being used, 8649such as `AC_PROG_CC'. So `AC_PROG_CC' contains: 8650 8651 AC_BEFORE([$0], [AC_PROG_CPP])dnl 8652 8653This warns the user if a call to `AC_PROG_CPP' has already occurred 8654when `AC_PROG_CC' is called. 8655 8656 -- Macro: AC_BEFORE (THIS-MACRO-NAME, CALLED-MACRO-NAME) 8657 Make M4 print a warning message to the standard error output if 8658 CALLED-MACRO-NAME has already been called. THIS-MACRO-NAME should 8659 be the name of the macro that is calling `AC_BEFORE'. The macro 8660 CALLED-MACRO-NAME must have been defined using `AC_DEFUN' or else 8661 contain a call to `AC_PROVIDE' to indicate that it has been called. 8662 8663 8664File: autoconf.info, Node: One-Shot Macros, Prev: Suggested Ordering, Up: Dependencies Between Macros 8665 86669.4.3 One-Shot Macros 8667--------------------- 8668 8669Some macros should be called only once, either because calling them 8670multiple time is unsafe, or because it is bad style. For instance 8671Autoconf ensures that `AC_CANONICAL_BUILD' and cousins (*note 8672Canonicalizing::) are evaluated only once, because it makes no sense to 8673run these expensive checks more than once. Such one-shot macros can be 8674defined using `AC_DEFUN_ONCE'. 8675 8676 -- Macro: AC_DEFUN_ONCE (MACRO-NAME, MACRO-BODY) 8677 Declare macro MACRO-NAME like `AC_DEFUN' would (*note Macro 8678 Definitions::), and emit a warning any time the macro is called 8679 more than once. 8680 8681 Obviously it is not sensible to evaluate a macro defined by 8682`AC_DEFUN_ONCE' in a macro defined by `AC_DEFUN'. Most of the time you 8683want to use `AC_REQUIRE' (*note Prerequisite Macros::). 8684 8685 8686File: autoconf.info, Node: Obsoleting Macros, Next: Coding Style, Prev: Dependencies Between Macros, Up: Writing Autoconf Macros 8687 86889.5 Obsoleting Macros 8689===================== 8690 8691Configuration and portability technology has evolved over the years. 8692Often better ways of solving a particular problem are developed, or 8693ad-hoc approaches are systematized. This process has occurred in many 8694parts of Autoconf. One result is that some of the macros are now 8695considered "obsolete"; they still work, but are no longer considered 8696the best thing to do, hence they should be replaced with more modern 8697macros. Ideally, `autoupdate' should replace the old macro calls with 8698their modern implementation. 8699 8700 Autoconf provides a simple means to obsolete a macro. 8701 8702 -- Macro: AU_DEFUN (OLD-MACRO, IMPLEMENTATION, [MESSAGE]) 8703 Define OLD-MACRO as IMPLEMENTATION. The only difference with 8704 `AC_DEFUN' is that the user is warned that OLD-MACRO is now 8705 obsolete. 8706 8707 If she then uses `autoupdate', the call to OLD-MACRO is replaced 8708 by the modern IMPLEMENTATION. MESSAGE should include information 8709 on what to do after running `autoupdate'; `autoupdate' prints it 8710 as a warning, and includes it in the updated `configure.ac' file. 8711 8712 The details of this macro are hairy: if `autoconf' encounters an 8713 `AU_DEFUN'ed macro, all macros inside its second argument are 8714 expanded as usual. However, when `autoupdate' is run, only M4 and 8715 M4sugar macros are expanded here, while all other macros are 8716 disabled and appear literally in the updated `configure.ac'. 8717 8718 -- Macro: AU_ALIAS (OLD-NAME, NEW-NAME) 8719 Used if the OLD-NAME is to be replaced by a call to NEW-MACRO with 8720 the same parameters. This happens for example if the macro was 8721 renamed. 8722 8723 8724File: autoconf.info, Node: Coding Style, Prev: Obsoleting Macros, Up: Writing Autoconf Macros 8725 87269.6 Coding Style 8727================ 8728 8729The Autoconf macros follow a strict coding style. You are encouraged to 8730follow this style, especially if you intend to distribute your macro, 8731either by contributing it to Autoconf itself, or via other means. 8732 8733 The first requirement is to pay great attention to the quotation. 8734For more details, see *Note Autoconf Language::, and *Note M4 8735Quotation::. 8736 8737 Do not try to invent new interfaces. It is likely that there is a 8738macro in Autoconf that resembles the macro you are defining: try to 8739stick to this existing interface (order of arguments, default values, 8740etc.). We _are_ conscious that some of these interfaces are not 8741perfect; nevertheless, when harmless, homogeneity should be preferred 8742over creativity. 8743 8744 Be careful about clashes both between M4 symbols and between shell 8745variables. 8746 8747 If you stick to the suggested M4 naming scheme (*note Macro Names::), 8748you are unlikely to generate conflicts. Nevertheless, when you need to 8749set a special value, _avoid using a regular macro name_; rather, use an 8750"impossible" name. For instance, up to version 2.13, the macro 8751`AC_SUBST' used to remember what SYMBOL macros were already defined by 8752setting `AC_SUBST_SYMBOL', which is a regular macro name. But since 8753there is a macro named `AC_SUBST_FILE', it was just impossible to 8754`AC_SUBST(FILE)'! In this case, `AC_SUBST(SYMBOL)' or 8755`_AC_SUBST(SYMBOL)' should have been used (yes, with the parentheses). 8756 8757 No Autoconf macro should ever enter the user-variable name space; 8758i.e., except for the variables that are the actual result of running the 8759macro, all shell variables should start with `ac_'. In addition, small 8760macros or any macro that is likely to be embedded in other macros 8761should be careful not to use obvious names. 8762 8763 Do not use `dnl' to introduce comments: most of the comments you are 8764likely to write are either header comments which are not output anyway, 8765or comments that should make their way into `configure'. There are 8766exceptional cases where you do want to comment special M4 constructs, 8767in which case `dnl' is right, but keep in mind that it is unlikely. 8768 8769 M4 ignores the leading blanks and newlines before each argument. 8770Use this feature to indent in such a way that arguments are (more or 8771less) aligned with the opening parenthesis of the macro being called. 8772For instance, instead of 8773 8774 AC_CACHE_CHECK(for EMX OS/2 environment, 8775 ac_cv_emxos2, 8776 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])], 8777 [ac_cv_emxos2=yes], [ac_cv_emxos2=no])]) 8778 8779write 8780 8781 AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2], 8782 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])], 8783 [ac_cv_emxos2=yes], 8784 [ac_cv_emxos2=no])]) 8785 8786or even 8787 8788 AC_CACHE_CHECK([for EMX OS/2 environment], 8789 [ac_cv_emxos2], 8790 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], 8791 [return __EMX__;])], 8792 [ac_cv_emxos2=yes], 8793 [ac_cv_emxos2=no])]) 8794 8795 When using `AC_RUN_IFELSE' or any macro that cannot work when 8796cross-compiling, provide a pessimistic value (typically `no'). 8797 8798 Feel free to use various tricks to prevent auxiliary tools, such as 8799syntax-highlighting editors, from behaving improperly. For instance, 8800instead of: 8801 8802 m4_bpatsubst([$1], [$"]) 8803 8804use 8805 8806 m4_bpatsubst([$1], [$""]) 8807 8808so that Emacsen do not open an endless "string" at the first quote. 8809For the same reasons, avoid: 8810 8811 test $[#] != 0 8812 8813and use: 8814 8815 test $[@%:@] != 0 8816 8817Otherwise, the closing bracket would be hidden inside a `#'-comment, 8818breaking the bracket-matching highlighting from Emacsen. Note the 8819preferred style to escape from M4: `$[1]', `$[@]', etc. Do not escape 8820when it is unnecessary. Common examples of useless quotation are 8821`[$]$1' (write `$$1'), `[$]var' (use `$var'), etc. If you add 8822portability issues to the picture, you'll prefer `${1+"$[@]"}' to 8823`"[$]@"', and you'll prefer do something better than hacking Autoconf 8824`:-)'. 8825 8826 When using `sed', don't use `-e' except for indenting purposes. 8827With the `s' and `y' commands, the preferred separator is `/' unless 8828`/' itself might appear in the pattern or replacement, in which case 8829you should use `|', or optionally `,' if you know the pattern and 8830replacement cannot contain a file name. If none of these characters 8831will do, choose a printable character that cannot appear in the pattern 8832or replacement. Characters from the set `"#$&'()*;<=>?`|~' are good 8833choices if the pattern or replacement might contain a file name, since 8834they have special meaning to the shell and are less likely to occur in 8835file names. 8836 8837 *Note Macro Definitions::, for details on how to define a macro. If 8838a macro doesn't use `AC_REQUIRE', is expected to never be the object of 8839an `AC_REQUIRE' directive, and macros required by other macros inside 8840arguments do not need to be expanded before this macro, then use 8841`m4_define'. In case of doubt, use `AC_DEFUN'. All the `AC_REQUIRE' 8842statements should be at the beginning of the macro, and each statement 8843should be followed by `dnl'. 8844 8845 You should not rely on the number of arguments: instead of checking 8846whether an argument is missing, test that it is not empty. It provides 8847both a simpler and a more predictable interface to the user, and saves 8848room for further arguments. 8849 8850 Unless the macro is short, try to leave the closing `])' at the 8851beginning of a line, followed by a comment that repeats the name of the 8852macro being defined. This introduces an additional newline in 8853`configure'; normally, that is not a problem, but if you want to remove 8854it you can use `[]dnl' on the last line. You can similarly use `[]dnl' 8855after a macro call to remove its newline. `[]dnl' is recommended 8856instead of `dnl' to ensure that M4 does not interpret the `dnl' as 8857being attached to the preceding text or macro output. For example, 8858instead of: 8859 8860 AC_DEFUN([AC_PATH_X], 8861 [AC_MSG_CHECKING([for X]) 8862 AC_REQUIRE_CPP() 8863 # ...omitted... 8864 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes]) 8865 fi]) 8866 8867you would write: 8868 8869 AC_DEFUN([AC_PATH_X], 8870 [AC_REQUIRE_CPP()[]dnl 8871 AC_MSG_CHECKING([for X]) 8872 # ...omitted... 8873 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes]) 8874 fi[]dnl 8875 ])# AC_PATH_X 8876 8877 If the macro is long, try to split it into logical chunks. 8878Typically, macros that check for a bug in a function and prepare its 8879`AC_LIBOBJ' replacement should have an auxiliary macro to perform this 8880setup. Do not hesitate to introduce auxiliary macros to factor your 8881code. 8882 8883 In order to highlight the recommended coding style, here is a macro 8884written the old way: 8885 8886 dnl Check for EMX on OS/2. 8887 dnl _AC_EMXOS2 8888 AC_DEFUN(_AC_EMXOS2, 8889 [AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2, 8890 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)], 8891 ac_cv_emxos2=yes, ac_cv_emxos2=no)]) 8892 test "$ac_cv_emxos2" = yes && EMXOS2=yes]) 8893 8894and the new way: 8895 8896 # _AC_EMXOS2 8897 # ---------- 8898 # Check for EMX on OS/2. 8899 m4_define([_AC_EMXOS2], 8900 [AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2], 8901 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])], 8902 [ac_cv_emxos2=yes], 8903 [ac_cv_emxos2=no])]) 8904 test "$ac_cv_emxos2" = yes && EMXOS2=yes[]dnl 8905 ])# _AC_EMXOS2 8906 8907 8908File: autoconf.info, Node: Portable Shell, Next: Portable Make, Prev: Writing Autoconf Macros, Up: Top 8909 891010 Portable Shell Programming 8911***************************** 8912 8913When writing your own checks, there are some shell-script programming 8914techniques you should avoid in order to make your code portable. The 8915Bourne shell and upward-compatible shells like the Korn shell and Bash 8916have evolved over the years, but to prevent trouble, do not take 8917advantage of features that were added after Unix version 7, circa 1977 8918(*note Systemology::). 8919 8920 You should not use shell functions, aliases, negated character 8921classes, or other features that are not found in all Bourne-compatible 8922shells; restrict yourself to the lowest common denominator. Even 8923`unset' is not supported by all shells! 8924 8925 Some ancient systems have quite small limits on the length of the 8926`#!' line; for instance, 32 bytes (not including the newline) on SunOS 89274. A few ancient 4.2BSD based systems (such as Dynix circa 1984) 8928required a single space between the `#!' and the `/'. However, these 8929ancient systems are no longer of practical concern. 8930 8931 The set of external programs you should run in a `configure' script 8932is fairly small. *Note Utilities in Makefiles: (standards)Utilities in 8933Makefiles, for the list. This restriction allows users to start out 8934with a fairly small set of programs and build the rest, avoiding too 8935many interdependencies between packages. 8936 8937 Some of these external utilities have a portable subset of features; 8938see *Note Limitations of Usual Tools::. 8939 8940 There are other sources of documentation about shells. The 8941specification for the Posix Shell Command Language 8942(http://www.opengroup.org/susv3/utilities/xcu_chap02.html), though more 8943generous than the restrictive shell subset described above, is fairly 8944portable nowadays. Also please see the Shell FAQs 8945(http://www.faqs.org/faqs/unix-faq/shell/). 8946 8947* Menu: 8948 8949* Shellology:: A zoology of shells 8950* Here-Documents:: Quirks and tricks 8951* File Descriptors:: FDs and redirections 8952* File System Conventions:: File names 8953* Shell Substitutions:: Variable and command expansions 8954* Assignments:: Varying side effects of assignments 8955* Parentheses:: Parentheses in shell scripts 8956* Slashes:: Slashes in shell scripts 8957* Special Shell Variables:: Variables you should not change 8958* Limitations of Builtins:: Portable use of not so portable /bin/sh 8959* Limitations of Usual Tools:: Portable use of portable tools 8960 8961 8962File: autoconf.info, Node: Shellology, Next: Here-Documents, Up: Portable Shell 8963 896410.1 Shellology 8965=============== 8966 8967There are several families of shells, most prominently the Bourne family 8968and the C shell family which are deeply incompatible. If you want to 8969write portable shell scripts, avoid members of the C shell family. The 8970the Shell difference FAQ 8971(http://www.faqs.org/faqs/unix-faq/shell/shell-differences/) includes a 8972small history of Posix shells, and a comparison between several of them. 8973 8974 Below we describe some of the members of the Bourne shell family. 8975 8976Ash 8977 Ash is often used on GNU/Linux and BSD systems as a light-weight 8978 Bourne-compatible shell. Ash 0.2 has some bugs that are fixed in 8979 the 0.3.x series, but portable shell scripts should work around 8980 them, since version 0.2 is still shipped with many GNU/Linux 8981 distributions. 8982 8983 To be compatible with Ash 0.2: 8984 8985 - don't use `$?' after expanding empty or unset variables, or 8986 at the start of an `eval': 8987 8988 foo= 8989 false 8990 $foo 8991 echo "Do not use it: $?" 8992 false 8993 eval 'echo "Do not use it: $?"' 8994 8995 - don't use command substitution within variable expansion: 8996 8997 cat ${FOO=`bar`} 8998 8999 - beware that single builtin substitutions are not performed by 9000 a subshell, hence their effect applies to the current shell! 9001 *Note Shell Substitutions::, item "Command Substitution". 9002 9003Bash 9004 To detect whether you are running Bash, test whether 9005 `BASH_VERSION' is set. To require Posix compatibility, run `set 9006 -o posix'. *Note Bash Posix Mode: (bash)Bash POSIX Mode, for 9007 details. 9008 9009Bash 2.05 and later 9010 Versions 2.05 and later of Bash use a different format for the 9011 output of the `set' builtin, designed to make evaluating its 9012 output easier. However, this output is not compatible with earlier 9013 versions of Bash (or with many other shells, probably). So if you 9014 use Bash 2.05 or higher to execute `configure', you'll need to use 9015 Bash 2.05 for all other build tasks as well. 9016 9017Ksh 9018 The Korn shell is compatible with the Bourne family and it mostly 9019 conforms to Posix. It has two major variants commonly called 9020 `ksh88' and `ksh93', named after the years of initial release. It 9021 is usually called `ksh', but is called `sh' on some hosts if you 9022 set your path appropriately. 9023 9024 Solaris systems have three variants: `/usr/bin/ksh' is `ksh88'; it 9025 is standard on Solaris 2.0 and later. `/usr/xpg4/bin/sh' is a 9026 Posix-compliant variant of `ksh88'; it is standard on Solaris 9 9027 and later. `/usr/dt/bin/dtksh' is `ksh93'. Variants that are not 9028 standard may be parts of optional packages. There is no extra 9029 charge for these packages, but they are not part of a minimal OS 9030 install and therefore some installations may not have it. 9031 9032 Starting with Tru64 Version 4.0, the Korn shell `/usr/bin/ksh' is 9033 also available as `/usr/bin/posix/sh'. If the environment 9034 variable `BIN_SH' is set to `xpg4', subsidiary invocations of the 9035 standard shell conform to Posix. 9036 9037Pdksh 9038 A public-domain clone of the Korn shell called `pdksh' is widely 9039 available: it has most of the `ksh88' features along with a few of 9040 its own. It usually sets `KSH_VERSION', except if invoked as 9041 `/bin/sh' on OpenBSD, and similarly to Bash you can require Posix 9042 compatibility by running `set -o posix'. Unfortunately, with 9043 `pdksh' 5.2.14 (the latest stable version as of February 2006) 9044 Posix mode is buggy and causes `pdksh' to depart from Posix in at 9045 least one respect: 9046 9047 $ echo "`echo \"hello\"`" 9048 hello 9049 $ set -o posix 9050 $ echo "`echo \"hello\"`" 9051 "hello" 9052 9053 The last line of output contains spurious quotes. This is yet 9054 another reason why portable shell code should not contain 9055 `"`...\"...\"...`"' constructs (*note Shell Substitutions::). 9056 9057Zsh 9058 To detect whether you are running `zsh', test whether 9059 `ZSH_VERSION' is set. By default `zsh' is _not_ compatible with 9060 the Bourne shell: you must execute `emulate sh', and for `zsh' 9061 versions before 3.1.6-dev-18 you must also set `NULLCMD' to `:'. 9062 *Note Compatibility: (zsh)Compatibility, for details. 9063 9064 The default Mac OS X `sh' was originally Zsh; it was changed to 9065 Bash in Mac OS X 10.2. 9066 9067 The following discussion between Russ Allbery and Robert Lipe is 9068worth reading: 9069 9070Russ Allbery: 9071 9072 The GNU assumption that `/bin/sh' is the one and only shell leads 9073 to a permanent deadlock. Vendors don't want to break users' 9074 existing shell scripts, and there are some corner cases in the 9075 Bourne shell that are not completely compatible with a Posix 9076 shell. Thus, vendors who have taken this route will _never_ 9077 (OK..."never say never") replace the Bourne shell (as `/bin/sh') 9078 with a Posix shell. 9079 9080Robert Lipe: 9081 9082 This is exactly the problem. While most (at least most System 9083 V's) do have a Bourne shell that accepts shell functions most 9084 vendor `/bin/sh' programs are not the Posix shell. 9085 9086 So while most modern systems do have a shell _somewhere_ that 9087 meets the Posix standard, the challenge is to find it. 9088 9089 9090File: autoconf.info, Node: Here-Documents, Next: File Descriptors, Prev: Shellology, Up: Portable Shell 9091 909210.2 Here-Documents 9093=================== 9094 9095Don't rely on `\' being preserved just because it has no special 9096meaning together with the next symbol. In the native `sh' on OpenBSD 90972.7 `\"' expands to `"' in here-documents with unquoted delimiter. As 9098a general rule, if `\\' expands to `\' use `\\' to get `\'. 9099 9100 With OpenBSD 2.7's `sh' 9101 9102 $ cat <<EOF 9103 > \" \\ 9104 > EOF 9105 " \ 9106 9107and with Bash: 9108 9109 bash-2.04$ cat <<EOF 9110 > \" \\ 9111 > EOF 9112 \" \ 9113 9114 Some shells mishandle large here-documents: for example, Solaris 10 9115`dtksh' and the UnixWare 7.1.1 Posix shell, which are derived from Korn 9116shell version M-12/28/93d, mishandle braced variable expansion that 9117crosses a 1024- or 4096-byte buffer boundary within a here-document. 9118Only the part of the variable name after the boundary is used. For 9119example, `${variable}' could be replaced by the expansion of `${ble}'. 9120If the end of the variable name is aligned with the block boundary, the 9121shell reports an error, as if you used `${}'. Instead of 9122`${variable-default}', the shell may expand `${riable-default}', or 9123even `${fault}'. This bug can often be worked around by omitting the 9124braces: `$variable'. The bug was fixed in `ksh93g' (1998-04-30) but as 9125of 2006 many operating systems were still shipping older versions with 9126the bug. 9127 9128 Many older shells (including the Bourne shell) implement 9129here-documents inefficiently. In particular, some shells can be 9130extremely inefficient when a single statement contains many 9131here-documents. For instance if your `configure.ac' includes something 9132like: 9133 9134 if <cross_compiling>; then 9135 assume this and that 9136 else 9137 check this 9138 check that 9139 check something else 9140 ... 9141 on and on forever 9142 ... 9143 fi 9144 9145 A shell parses the whole `if'/`fi' construct, creating temporary 9146files for each here-document in it. Some shells create links for such 9147here-documents on every `fork', so that the clean-up code they had 9148installed correctly removes them. It is creating the links that can 9149take the shell forever. 9150 9151 Moving the tests out of the `if'/`fi', or creating multiple 9152`if'/`fi' constructs, would improve the performance significantly. 9153Anyway, this kind of construct is not exactly the typical use of 9154Autoconf. In fact, it's even not recommended, because M4 macros can't 9155look into shell conditionals, so we may fail to expand a macro when it 9156was expanded before in a conditional path, and the condition turned out 9157to be false at runtime, and we end up not executing the macro at all. 9158 9159 9160File: autoconf.info, Node: File Descriptors, Next: File System Conventions, Prev: Here-Documents, Up: Portable Shell 9161 916210.3 File Descriptors 9163===================== 9164 9165Most shells, if not all (including Bash, Zsh, Ash), output traces on 9166stderr, even for subshells. This might result in undesirable content 9167if you meant to capture the standard-error output of the inner command: 9168 9169 $ ash -x -c '(eval "echo foo >&2") 2>stderr' 9170 $ cat stderr 9171 + eval echo foo >&2 9172 + echo foo 9173 foo 9174 $ bash -x -c '(eval "echo foo >&2") 2>stderr' 9175 $ cat stderr 9176 + eval 'echo foo >&2' 9177 ++ echo foo 9178 foo 9179 $ zsh -x -c '(eval "echo foo >&2") 2>stderr' 9180 # Traces on startup files deleted here. 9181 $ cat stderr 9182 +zsh:1> eval echo foo >&2 9183 +zsh:1> echo foo 9184 foo 9185 9186One workaround is to grep out uninteresting lines, hoping not to remove 9187good ones. 9188 9189 If you intend to redirect both standard error and standard output, 9190redirect standard output first. This works better with HP-UX, since 9191its shell mishandles tracing if standard error is redirected first: 9192 9193 $ sh -x -c ': 2>err >out' 9194 + : 9195 + 2> err $ cat err 9196 1> out 9197 9198 Don't try to redirect the standard error of a command substitution. 9199It must be done _inside_ the command substitution. When running `: `cd 9200/zorglub` 2>/dev/null' expect the error message to escape, while `: `cd 9201/zorglub 2>/dev/null`' works properly. 9202 9203 It is worth noting that Zsh (but not Ash nor Bash) makes it possible 9204in assignments though: `foo=`cd /zorglub` 2>/dev/null'. 9205 9206 Don't redirect the same file descriptor several times, as you are 9207doomed to failure under Ultrix. 9208 9209 ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995 9210 UWS V4.4 (Rev. 11) 9211 $ eval 'echo matter >fullness' >void 9212 illegal io 9213 $ eval '(echo matter >fullness)' >void 9214 illegal io 9215 $ (eval '(echo matter >fullness)') >void 9216 Ambiguous output redirect. 9217 9218In each case the expected result is of course `fullness' containing 9219`matter' and `void' being empty. 9220 9221 Don't rely on file descriptors 0, 1, and 2 remaining closed in a 9222subsidiary program. If any of these descriptors is closed, the 9223operating system may open an unspecified file for the descriptor in the 9224new process image. Posix says this may be done only if the subsidiary 9225program is set-user-ID or set-group-ID, but HP-UX 11.23 does it even for 9226ordinary programs. 9227 9228 Don't rely on open file descriptors being open in child processes. 9229In `ksh', file descriptors above 2 which are opened using `exec N>file' 9230are closed by a subsequent `exec' (such as that involved in the 9231fork-and-exec which runs a program or script). Thus, using `sh', we 9232have: 9233 9234 $ cat ./descrips 9235 #!/bin/sh - 9236 echo hello >&5 9237 $ exec 5>t 9238 $ ./descrips 9239 $ cat t 9240 $ 9241 hello 9242 9243But using ksh: 9244 9245 $ exec 5>t 9246 $ ./descrips 9247 hello 9248 $ cat t 9249 $ 9250 9251Within the process which runs the `descrips' script, file descriptor 5 9252is closed. 9253 9254 DOS variants cannot rename or remove open files, such as in `mv foo 9255bar >foo' or `rm foo >foo', even though this is perfectly portable 9256among Posix hosts. 9257 9258 A few ancient systems reserved some file descriptors. By convention, 9259file descriptor 3 was opened to `/dev/tty' when you logged into Eighth 9260Edition (1985) through Tenth Edition Unix (1989). File descriptor 4 9261had a special use on the Stardent/Kubota Titan (circa 1990), though we 9262don't now remember what it was. Both these systems are obsolete, so 9263it's now safe to treat file descriptors 3 and 4 like any other file 9264descriptors. 9265 9266 9267File: autoconf.info, Node: File System Conventions, Next: Shell Substitutions, Prev: File Descriptors, Up: Portable Shell 9268 926910.4 File System Conventions 9270============================ 9271 9272Autoconf uses shell-script processing extensively, so the file names 9273that it processes should not contain characters that are special to the 9274shell. Special characters include space, tab, newline, NUL, and the 9275following: 9276 9277 " # $ & ' ( ) * ; < = > ? [ \ ` | 9278 9279 Also, file names should not begin with `~' or `-', and should 9280contain neither `-' immediately after `/' nor `~' immediately after 9281`:'. On Posix-like platforms, directory names should not contain `:', 9282as this runs afoul of `:' used as the path separator. 9283 9284 These restrictions apply not only to the files that you distribute, 9285but also to the absolute file names of your source, build, and 9286destination directories. 9287 9288 On some Posix-like platforms, `!' and `^' are special too, so they 9289should be avoided. 9290 9291 Posix lets implementations treat leading `//' specially, but 9292requires leading `///' and beyond to be equivalent to `/'. Most Unix 9293variants treat `//' like `/'. However, some treat `//' as a 9294"super-root" that can provide access to files that are not otherwise 9295reachable from `/'. The super-root tradition began with Apollo 9296Domain/OS, which died out long ago, but unfortunately Cygwin has 9297revived it. 9298 9299 While `autoconf' and friends are usually run on some Posix variety, 9300they can be used on other systems, most notably DOS variants. This 9301impacts several assumptions regarding file names. 9302 9303For example, the following code: 9304 9305 case $foo_dir in 9306 /*) # Absolute 9307 ;; 9308 *) 9309 foo_dir=$dots$foo_dir ;; 9310 esac 9311 9312fails to properly detect absolute file names on those systems, because 9313they can use a drivespec, and usually use a backslash as directory 9314separator. If you want to be portable to DOS variants (at the price of 9315rejecting valid but oddball Posix file names like `a:\b'), you can 9316check for absolute file names like this: 9317 9318 case $foo_dir in 9319 [\\/]* | ?:[\\/]* ) # Absolute 9320 ;; 9321 *) 9322 foo_dir=$dots$foo_dir ;; 9323 esac 9324 9325Make sure you quote the brackets if appropriate and keep the backslash 9326as first character (*note Limitations of Builtins::). 9327 9328 Also, because the colon is used as part of a drivespec, these 9329systems don't use it as path separator. When creating or accessing 9330paths, you can use the `PATH_SEPARATOR' output variable instead. 9331`configure' sets this to the appropriate value (`:' or `;') when it 9332starts up. 9333 9334 File names need extra care as well. While DOS variants that are 9335Posixy enough to run `autoconf' (such as DJGPP) are usually able to 9336handle long file names properly, there are still limitations that can 9337seriously break packages. Several of these issues can be easily 9338detected by the doschk 9339(ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz) package. 9340 9341 A short overview follows; problems are marked with SFN/LFN to 9342indicate where they apply: SFN means the issues are only relevant to 9343plain DOS, not to DOS under Microsoft Windows variants, while LFN 9344identifies problems that exist even under Microsoft Windows variants. 9345 9346No multiple dots (SFN) 9347 DOS cannot handle multiple dots in file names. This is an 9348 especially important thing to remember when building a portable 9349 configure script, as `autoconf' uses a .in suffix for template 9350 files. 9351 9352 This is perfectly OK on Posix variants: 9353 9354 AC_CONFIG_HEADERS([config.h]) 9355 AC_CONFIG_FILES([source.c foo.bar]) 9356 AC_OUTPUT 9357 9358 but it causes problems on DOS, as it requires `config.h.in', 9359 `source.c.in' and `foo.bar.in'. To make your package more portable 9360 to DOS-based environments, you should use this instead: 9361 9362 AC_CONFIG_HEADERS([config.h:config.hin]) 9363 AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in]) 9364 AC_OUTPUT 9365 9366No leading dot (SFN) 9367 DOS cannot handle file names that start with a dot. This is 9368 usually not important for `autoconf'. 9369 9370Case insensitivity (LFN) 9371 DOS is case insensitive, so you cannot, for example, have both a 9372 file called `INSTALL' and a directory called `install'. This also 9373 affects `make'; if there's a file called `INSTALL' in the 9374 directory, `make install' does nothing (unless the `install' 9375 target is marked as PHONY). 9376 9377The 8+3 limit (SFN) 9378 Because the DOS file system only stores the first 8 characters of 9379 the file name and the first 3 of the extension, those must be 9380 unique. That means that `foobar-part1.c', `foobar-part2.c' and 9381 `foobar-prettybird.c' all resolve to the same file name 9382 (`FOOBAR-P.C'). The same goes for `foo.bar' and `foo.bartender'. 9383 9384 The 8+3 limit is not usually a problem under Microsoft Windows, as 9385 it uses numeric tails in the short version of file names to make 9386 them unique. However, a registry setting can turn this behavior 9387 off. While this makes it possible to share file trees containing 9388 long file names between SFN and LFN environments, it also means 9389 the above problem applies there as well. 9390 9391Invalid characters (LFN) 9392 Some characters are invalid in DOS file names, and should therefore 9393 be avoided. In a LFN environment, these are `/', `\', `?', `*', 9394 `:', `<', `>', `|' and `"'. In a SFN environment, other 9395 characters are also invalid. These include `+', `,', `[' and `]'. 9396 9397Invalid names (LFN) 9398 Some DOS file names are reserved, and cause problems if you try to 9399 use files with those names. These names include `CON', `AUX', 9400 `COM1', `COM2', `COM3', `COM4', `LPT1', `LPT2', `LPT3', `NUL', and 9401 `PRN'. File names are case insensitive, so even names like 9402 `aux/config.guess' are disallowed. 9403 9404 9405 9406File: autoconf.info, Node: Shell Substitutions, Next: Assignments, Prev: File System Conventions, Up: Portable Shell 9407 940810.5 Shell Substitutions 9409======================== 9410 9411Contrary to a persistent urban legend, the Bourne shell does not 9412systematically split variables and back-quoted expressions, in 9413particular on the right-hand side of assignments and in the argument of 9414`case'. For instance, the following code: 9415 9416 case "$given_srcdir" in 9417 .) top_srcdir="`echo "$dots" | sed 's,/$,,'`" ;; 9418 *) top_srcdir="$dots$given_srcdir" ;; 9419 esac 9420 9421is more readable when written as: 9422 9423 case $given_srcdir in 9424 .) top_srcdir=`echo "$dots" | sed 's,/$,,'` ;; 9425 *) top_srcdir=$dots$given_srcdir ;; 9426 esac 9427 9428and in fact it is even _more_ portable: in the first case of the first 9429attempt, the computation of `top_srcdir' is not portable, since not all 9430shells properly understand `"`..."..."...`"'. Worse yet, not all 9431shells understand `"`...\"...\"...`"' the same way. There is just no 9432portable way to use double-quoted strings inside double-quoted 9433back-quoted expressions (pfew!). 9434 9435`$@' 9436 One of the most famous shell-portability issues is related to 9437 `"$@"'. When there are no positional arguments, Posix says that 9438 `"$@"' is supposed to be equivalent to nothing, but the original 9439 Unix version 7 Bourne shell treated it as equivalent to `""' 9440 instead, and this behavior survives in later implementations like 9441 Digital Unix 5.0. 9442 9443 The traditional way to work around this portability problem is to 9444 use `${1+"$@"}'. Unfortunately this method does not work with Zsh 9445 (3.x and 4.x), which is used on Mac OS X. When emulating the 9446 Bourne shell, Zsh performs word splitting on `${1+"$@"}': 9447 9448 zsh $ emulate sh 9449 zsh $ for i in "$@"; do echo $i; done 9450 Hello World 9451 ! 9452 zsh $ for i in ${1+"$@"}; do echo $i; done 9453 Hello 9454 World 9455 ! 9456 9457 Zsh handles plain `"$@"' properly, but we can't use plain `"$@"' 9458 because of the portability problems mentioned above. One 9459 workaround relies on Zsh's "global aliases" to convert `${1+"$@"}' 9460 into `"$@"' by itself: 9461 9462 test "${ZSH_VERSION+set}" = set && alias -g '${1+"$@"}'='"$@"' 9463 9464 A more conservative workaround is to avoid `"$@"' if it is 9465 possible that there may be no positional arguments. For example, 9466 instead of: 9467 9468 cat conftest.c "$@" 9469 9470 you can use this instead: 9471 9472 case $# in 9473 0) cat conftest.c;; 9474 *) cat conftest.c "$@";; 9475 esac 9476 9477 Autoconf macros often use the `set' command to update `$@', so if 9478 you are writing shell code intended for `configure' you should not 9479 assume that the value of `$@' persists for any length of time. 9480 9481`${10}' 9482 The 10th, 11th, ... positional parameters can be accessed only 9483 after a `shift'. The 7th Edition shell reported an error if given 9484 `${10}', and Solaris 10 `/bin/sh' still acts that way: 9485 9486 $ set 1 2 3 4 5 6 7 8 9 10 9487 $ echo ${10} 9488 bad substitution 9489 9490`${VAR:-VALUE}' 9491 Old BSD shells, including the Ultrix `sh', don't accept the colon 9492 for any shell substitution, and complain and die. 9493 9494`${VAR=LITERAL}' 9495 Be sure to quote: 9496 9497 : ${var='Some words'} 9498 9499 otherwise some shells, such as on Digital Unix V 5.0, die because 9500 of a "bad substitution". 9501 9502 9503 Solaris `/bin/sh' has a frightening bug in its interpretation of 9504 this. Imagine you need set a variable to a string containing `}'. 9505 This `}' character confuses Solaris `/bin/sh' when the affected 9506 variable was already set. This bug can be exercised by running: 9507 9508 $ unset foo 9509 $ foo=${foo='}'} 9510 $ echo $foo 9511 } 9512 $ foo=${foo='}' # no error; this hints to what the bug is 9513 $ echo $foo 9514 } 9515 $ foo=${foo='}'} 9516 $ echo $foo 9517 }} 9518 ^ ugh! 9519 9520 It seems that `}' is interpreted as matching `${', even though it 9521 is enclosed in single quotes. The problem doesn't happen using 9522 double quotes. 9523 9524`${VAR=EXPANDED-VALUE}' 9525 On Ultrix, running 9526 9527 default="yu,yaa" 9528 : ${var="$default"} 9529 9530 sets VAR to `M-yM-uM-,M-yM-aM-a', i.e., the 8th bit of each char 9531 is set. You don't observe the phenomenon using a simple `echo 9532 $var' since apparently the shell resets the 8th bit when it 9533 expands $var. Here are two means to make this shell confess its 9534 sins: 9535 9536 $ cat -v <<EOF 9537 $var 9538 EOF 9539 9540 and 9541 9542 $ set | grep '^var=' | cat -v 9543 9544 One classic incarnation of this bug is: 9545 9546 default="a b c" 9547 : ${list="$default"} 9548 for c in $list; do 9549 echo $c 9550 done 9551 9552 You'll get `a b c' on a single line. Why? Because there are no 9553 spaces in `$list': there are `M- ', i.e., spaces with the 8th bit 9554 set, hence no IFS splitting is performed!!! 9555 9556 One piece of good news is that Ultrix works fine with `: 9557 ${list=$default}'; i.e., if you _don't_ quote. The bad news is 9558 then that QNX 4.25 then sets LIST to the _last_ item of DEFAULT! 9559 9560 The portable way out consists in using a double assignment, to 9561 switch the 8th bit twice on Ultrix: 9562 9563 list=${list="$default"} 9564 9565 ...but beware of the `}' bug from Solaris (see above). For safety, 9566 use: 9567 9568 test "${var+set}" = set || var={VALUE} 9569 9570``COMMANDS`' 9571 Posix requires shells to trim all trailing newlines from command 9572 output before substituting it, so assignments like `dir=`echo 9573 "$file" | tr a A`' do not work as expected if `$file' ends in a 9574 newline. 9575 9576 While in general it makes no sense, do not substitute a single 9577 builtin with side effects, because Ash 0.2, trying to optimize, 9578 does not fork a subshell to perform the command. 9579 9580 For instance, if you wanted to check that `cd' is silent, do not 9581 use `test -z "`cd /`"' because the following can happen: 9582 9583 $ pwd 9584 /tmp 9585 $ test -z "`cd /`" && pwd 9586 / 9587 9588 The result of `foo=`exit 1`' is left as an exercise to the reader. 9589 9590 The MSYS shell leaves a stray byte in the expansion of a 9591 double-quoted command substitution of a native program, if the end 9592 of the substution is not aligned with the end of the double quote. 9593 This may be worked around by inserting another pair of quotes: 9594 9595 $ echo "`printf 'foo\r\n'` bar" > broken 9596 $ echo "`printf 'foo\r\n'`"" bar" | cmp - broken 9597 - broken differ: char 4, line 1 9598 9599`$(COMMANDS)' 9600 This construct is meant to replace ``COMMANDS`', and it has most 9601 of the problems listed under ``COMMANDS`'. 9602 9603 This construct can be nested while this is impossible to do 9604 portably with back quotes. Unfortunately it is not yet 9605 universally supported. Most notably, even recent releases of 9606 Solaris don't support it: 9607 9608 $ showrev -c /bin/sh | grep version 9609 Command version: SunOS 5.10 Generic 121004-01 Oct 2005 9610 $ echo $(echo blah) 9611 syntax error: `(' unexpected 9612 9613 nor does IRIX 6.5's Bourne shell: 9614 $ uname -a 9615 IRIX firebird-image 6.5 07151432 IP22 9616 $ echo $(echo blah) 9617 $(echo blah) 9618 9619 If you do use `$(COMMANDS)', make sure that the commands do not 9620 start with a parenthesis, as that would cause confusion with a 9621 different notation `$((EXPRESSION))' that in modern shells is an 9622 arithmetic expression not a command. To avoid the confusion, 9623 insert a space between the two opening parentheses. 9624 9625 Avoid COMMANDS that contain unbalanced parentheses in 9626 here-documents, comments, or case statement patterns, as many 9627 shells mishandle them. For example, Bash 3.1, `ksh88', `pdksh' 9628 5.2.14, and Zsh 4.2.6 all mishandle the following valid command: 9629 9630 echo $(case x in x) echo hello;; esac) 9631 9632`^' 9633 Always quote `^', otherwise traditional shells such as `/bin/sh' 9634 on Solaris 10 treat this like `|'. 9635 9636 9637 9638File: autoconf.info, Node: Assignments, Next: Parentheses, Prev: Shell Substitutions, Up: Portable Shell 9639 964010.6 Assignments 9641================ 9642 9643When setting several variables in a row, be aware that the order of the 9644evaluation is undefined. For instance `foo=1 foo=2; echo $foo' gives 9645`1' with Solaris `/bin/sh', but `2' with Bash. You must use `;' to 9646enforce the order: `foo=1; foo=2; echo $foo'. 9647 9648 Don't rely on the following to find `subdir/program': 9649 9650 PATH=subdir$PATH_SEPARATOR$PATH program 9651 9652as this does not work with Zsh 3.0.6. Use something like this instead: 9653 9654 (PATH=subdir$PATH_SEPARATOR$PATH; export PATH; exec program) 9655 9656 Don't rely on the exit status of an assignment: Ash 0.2 does not 9657change the status and propagates that of the last statement: 9658 9659 $ false || foo=bar; echo $? 9660 1 9661 $ false || foo=`:`; echo $? 9662 0 9663 9664and to make things even worse, QNX 4.25 just sets the exit status to 0 9665in any case: 9666 9667 $ foo=`exit 1`; echo $? 9668 0 9669 9670 To assign default values, follow this algorithm: 9671 9672 1. If the default value is a literal and does not contain any closing 9673 brace, use: 9674 9675 : ${var='my literal'} 9676 9677 2. If the default value contains no closing brace, has to be 9678 expanded, and the variable being initialized is not intended to be 9679 IFS-split (i.e., it's not a list), then use: 9680 9681 : ${var="$default"} 9682 9683 3. If the default value contains no closing brace, has to be 9684 expanded, and the variable being initialized is intended to be 9685 IFS-split (i.e., it's a list), then use: 9686 9687 var=${var="$default"} 9688 9689 4. If the default value contains a closing brace, then use: 9690 9691 test "${var+set}" = set || var="has a '}'" 9692 9693 In most cases `var=${var="$default"}' is fine, but in case of doubt, 9694just use the last form. *Note Shell Substitutions::, items 9695`${VAR:-VALUE}' and `${VAR=VALUE}' for the rationale. 9696 9697 9698File: autoconf.info, Node: Parentheses, Next: Slashes, Prev: Assignments, Up: Portable Shell 9699 970010.7 Parentheses in Shell Scripts 9701================================= 9702 9703Beware of two opening parentheses in a row, as some shell 9704implementations mishandle them. For example, `pdksh' 5.2.14 misparses 9705the following code: 9706 9707 if ((true) || false); then 9708 echo ok 9709 fi 9710 9711To work around this problem, insert a space between the two opening 9712parentheses. There is a similar problem and workaround with `$(('; see 9713*Note Shell Substitutions::. 9714 9715 Posix requires support for `case' patterns with opening parentheses 9716like this: 9717 9718 case $file_name in 9719 (*.c) echo "C source code";; 9720 esac 9721 9722but the `(' in this example is not portable to many older Bourne shell 9723implementations. It can be omitted safely. 9724 9725 9726File: autoconf.info, Node: Slashes, Next: Special Shell Variables, Prev: Parentheses, Up: Portable Shell 9727 972810.8 Slashes in Shell Scripts 9729============================= 9730 9731Unpatched Tru64 5.1 `sh' omits the last slash of command-line arguments 9732that contain two trailing slashes: 9733 9734 $ echo / // /// //// .// //. 9735 / / // /// ./ //. 9736 $ x=// 9737 $ eval "echo \$x" 9738 / 9739 $ set -x 9740 $ echo abc | tr -t ab // 9741 + echo abc 9742 + tr -t ab / 9743 /bc 9744 9745 Unpatched Tru64 4.0 `sh' adds a slash after `"$var"' if the variable 9746is empty and the second double-quote is followed by a word that begins 9747and ends with slash: 9748 9749 $ sh -xc 'p=; echo "$p"/ouch/' 9750 p= 9751 + echo //ouch/ 9752 //ouch/ 9753 9754 However, our understanding is that patches are available, so perhaps 9755it's not worth worrying about working around these horrendous bugs. 9756 9757 9758File: autoconf.info, Node: Special Shell Variables, Next: Limitations of Builtins, Prev: Slashes, Up: Portable Shell 9759 976010.9 Special Shell Variables 9761============================ 9762 9763Some shell variables should not be used, since they can have a deep 9764influence on the behavior of the shell. In order to recover a sane 9765behavior from the shell, some variables should be unset, but `unset' is 9766not portable (*note Limitations of Builtins::) and a fallback value is 9767needed. 9768 9769 As a general rule, shell variable names containing a lower-case 9770letter are safe; you can define and use these variables without 9771worrying about their effect on the underlying system, and without 9772worrying about whether the shell changes them unexpectedly. (The 9773exception is the shell variable `status', as described below.) 9774 9775 Here is a list of names that are known to cause trouble. This list 9776is not exhaustive, but you should be safe if you avoid the name 9777`status' and names containing only upper-case letters and underscores. 9778 9779`_' 9780 Many shells reserve `$_' for various purposes, e.g., the name of 9781 the last command executed. 9782 9783`BIN_SH' 9784 In Tru64, if `BIN_SH' is set to `xpg4', subsidiary invocations of 9785 the standard shell conform to Posix. 9786 9787`CDPATH' 9788 When this variable is set it specifies a list of directories to 9789 search when invoking `cd' with a relative file name that did not 9790 start with `./' or `../'. Posix 1003.1-2001 says that if a 9791 nonempty directory name from `CDPATH' is used successfully, `cd' 9792 prints the resulting absolute file name. Unfortunately this 9793 output can break idioms like `abs=`cd src && pwd`' because `abs' 9794 receives the name twice. Also, many shells do not conform to this 9795 part of Posix; for example, `zsh' prints the result only if a 9796 directory name other than `.' was chosen from `CDPATH'. 9797 9798 In practice the shells that have this problem also support 9799 `unset', so you can work around the problem as follows: 9800 9801 (unset CDPATH) >/dev/null 2>&1 && unset CDPATH 9802 9803 You can also avoid output by ensuring that your directory name is 9804 absolute or anchored at `./', as in `abs=`cd ./src && pwd`'. 9805 9806 Autoconf-generated scripts automatically unset `CDPATH' if 9807 possible, so you need not worry about this problem in those 9808 scripts. 9809 9810`DUALCASE' 9811 In the MKS shell, case statements and file name generation are 9812 case-insensitive unless `DUALCASE' is nonzero. Autoconf-generated 9813 scripts export this variable when they start up. 9814 9815`ENV' 9816`MAIL' 9817`MAILPATH' 9818`PS1' 9819`PS2' 9820`PS4' 9821 These variables should not matter for shell scripts, since they are 9822 supposed to affect only interactive shells. However, at least one 9823 shell (the pre-3.0 UWIN Korn shell) gets confused about whether it 9824 is interactive, which means that (for example) a `PS1' with a side 9825 effect can unexpectedly modify `$?'. To work around this bug, 9826 Autoconf-generated scripts do something like this: 9827 9828 (unset ENV) >/dev/null 2>&1 && unset ENV MAIL MAILPATH 9829 PS1='$ ' 9830 PS2='> ' 9831 PS4='+ ' 9832 9833`IFS' 9834 Long ago, shell scripts inherited `IFS' from the environment, but 9835 this caused many problems so modern shells ignore any environment 9836 settings for `IFS'. 9837 9838 Don't set the first character of `IFS' to backslash. Indeed, 9839 Bourne shells use the first character (backslash) when joining the 9840 components in `"$@"' and some shells then reinterpret (!) the 9841 backslash escapes, so you can end up with backspace and other 9842 strange characters. 9843 9844 The proper value for `IFS' (in regular code, not when performing 9845 splits) is `<SPC><TAB><RET>'. The first character is especially 9846 important, as it is used to join the arguments in `$*'; however, 9847 note that traditional shells, but also bash-2.04, fail to adhere 9848 to this and join with a space anyway. 9849 9850`LANG' 9851`LC_ALL' 9852`LC_COLLATE' 9853`LC_CTYPE' 9854`LC_MESSAGES' 9855`LC_MONETARY' 9856`LC_NUMERIC' 9857`LC_TIME' 9858 Autoconf-generated scripts normally set all these variables to `C' 9859 because so much configuration code assumes the C locale and Posix 9860 requires that locale environment variables be set to `C' if the C 9861 locale is desired. However, some older, nonstandard systems 9862 (notably SCO) break if locale environment variables are set to 9863 `C', so when running on these systems Autoconf-generated scripts 9864 unset the variables instead. 9865 9866`LANGUAGE' 9867 `LANGUAGE' is not specified by Posix, but it is a GNU extension 9868 that overrides `LC_ALL' in some cases, so Autoconf-generated 9869 scripts set it too. 9870 9871`LC_ADDRESS' 9872`LC_IDENTIFICATION' 9873`LC_MEASUREMENT' 9874`LC_NAME' 9875`LC_PAPER' 9876`LC_TELEPHONE' 9877 These locale environment variables are GNU extensions. They are 9878 treated like their Posix brethren (`LC_COLLATE', etc.) as 9879 described above. 9880 9881`LINENO' 9882 Most modern shells provide the current line number in `LINENO'. 9883 Its value is the line number of the beginning of the current 9884 command. Autoconf attempts to execute `configure' with a shell 9885 that supports `LINENO'. If no such shell is available, it 9886 attempts to implement `LINENO' with a Sed prepass that replaces 9887 each instance of the string `$LINENO' (not followed by an 9888 alphanumeric character) with the line's number. 9889 9890 You should not rely on `LINENO' within `eval', as the behavior 9891 differs in practice. Also, the possibility of the Sed prepass 9892 means that you should not rely on `$LINENO' when quoted, when in 9893 here-documents, or when in long commands that cross line 9894 boundaries. Subshells should be OK, though. In the following 9895 example, lines 1, 6, and 9 are portable, but the other instances of 9896 `LINENO' are not: 9897 9898 $ cat lineno 9899 echo 1. $LINENO 9900 cat <<EOF 9901 3. $LINENO 9902 4. $LINENO 9903 EOF 9904 ( echo 6. $LINENO ) 9905 eval 'echo 7. $LINENO' 9906 echo 8. '$LINENO' 9907 echo 9. $LINENO ' 9908 10.' $LINENO 9909 $ bash-2.05 lineno 9910 1. 1 9911 3. 2 9912 4. 2 9913 6. 6 9914 7. 1 9915 8. $LINENO 9916 9. 9 9917 10. 9 9918 $ zsh-3.0.6 lineno 9919 1. 1 9920 3. 2 9921 4. 2 9922 6. 6 9923 7. 7 9924 8. $LINENO 9925 9. 9 9926 10. 9 9927 $ pdksh-5.2.14 lineno 9928 1. 1 9929 3. 2 9930 4. 2 9931 6. 6 9932 7. 0 9933 8. $LINENO 9934 9. 9 9935 10. 9 9936 $ sed '=' <lineno | 9937 > sed ' 9938 > N 9939 > s,$,-, 9940 > t loop 9941 > :loop 9942 > s,^\([0-9]*\)\(.*\)[$]LINENO\([^a-zA-Z0-9_]\),\1\2\1\3, 9943 > t loop 9944 > s,-$,, 9945 > s,^[0-9]*\n,, 9946 > ' | 9947 > sh 9948 1. 1 9949 3. 3 9950 4. 4 9951 6. 6 9952 7. 7 9953 8. 8 9954 9. 9 9955 10. 10 9956 9957`NULLCMD' 9958 When executing the command `>foo', `zsh' executes `$NULLCMD >foo' 9959 unless it is operating in Bourne shell compatibility mode and the 9960 `zsh' version is newer than 3.1.6-dev-18. If you are using an 9961 older `zsh' and forget to set `NULLCMD', your script might be 9962 suspended waiting for data on its standard input. 9963 9964`PATH_SEPARATOR' 9965 On DJGPP systems, the `PATH_SEPARATOR' environment variable can be 9966 set to either `:' or `;' to control the path separator Bash uses 9967 to set up certain environment variables (such as `PATH'). You can 9968 set this variable to `;' if you want `configure' to use `;' as a 9969 separator; this might be useful if you plan to use non-Posix 9970 shells to execute files. *Note File System Conventions::, for 9971 more information about `PATH_SEPARATOR'. 9972 9973`PWD' 9974 Posix 1003.1-2001 requires that `cd' and `pwd' must update the 9975 `PWD' environment variable to point to the logical name of the 9976 current directory, but traditional shells do not support this. 9977 This can cause confusion if one shell instance maintains `PWD' but 9978 a subsidiary and different shell does not know about `PWD' and 9979 executes `cd'; in this case `PWD' points to the wrong directory. 9980 Use ``pwd`' rather than `$PWD'. 9981 9982`RANDOM' 9983 Many shells provide `RANDOM', a variable that returns a different 9984 integer each time it is used. Most of the time, its value does not 9985 change when it is not used, but on IRIX 6.5 the value changes all 9986 the time. This can be observed by using `set'. It is common 9987 practice to use `$RANDOM' as part of a file name, but code 9988 shouldn't rely on `$RANDOM' expanding to a nonempty string. 9989 9990`status' 9991 This variable is an alias to `$?' for `zsh' (at least 3.1.6), 9992 hence read-only. Do not use it. 9993 9994 9995File: autoconf.info, Node: Limitations of Builtins, Next: Limitations of Usual Tools, Prev: Special Shell Variables, Up: Portable Shell 9996 999710.10 Limitations of Shell Builtins 9998=================================== 9999 10000No, no, we are serious: some shells do have limitations! :) 10001 10002 You should always keep in mind that any builtin or command may 10003support options, and therefore differ in behavior with arguments 10004starting with a dash. For instance, the innocent `echo "$word"' can 10005give unexpected results when `word' starts with a dash. It is often 10006possible to avoid this problem using `echo "x$word"', taking the `x' 10007into account later in the pipe. 10008 10009`.' 10010 Use `.' only with regular files (use `test -f'). Bash 2.03, for 10011 instance, chokes on `. /dev/null'. Also, remember that `.' uses 10012 `PATH' if its argument contains no slashes, so if you want to use 10013 `.' on a file `foo' in the current directory, you must use `. 10014 ./foo'. 10015 10016`!' 10017 The Unix version 7 shell did not support negating the exit status 10018 of commands with `!', and this feature is still absent from some 10019 shells (e.g., Solaris `/bin/sh'). Shell code like this: 10020 10021 if ! cmp file1 file2 >/dev/null 2>&1; then 10022 echo files differ or trouble 10023 fi 10024 10025 is therefore not portable in practice. Typically it is easy to 10026 rewrite such code, e.g.: 10027 10028 cmp file1 file2 >/dev/null 2>&1 || 10029 echo files differ or trouble 10030 10031 More generally, one can always rewrite `! COMMAND' as: 10032 10033 if COMMAND; then (exit 1); else :; fi 10034 10035`break' 10036 The use of `break 2' etc. is safe. 10037 10038`case' 10039 You don't need to quote the argument; no splitting is performed. 10040 10041 You don't need the final `;;', but you should use it. 10042 10043 Because of a bug in its `fnmatch', Bash fails to properly handle 10044 backslashes in character classes: 10045 10046 bash-2.02$ case /tmp in [/\\]*) echo OK;; esac 10047 bash-2.02$ 10048 10049 This is extremely unfortunate, since you are likely to use this 10050 code to handle Posix or MS-DOS absolute file names. To work 10051 around this bug, always put the backslash first: 10052 10053 bash-2.02$ case '\TMP' in [\\/]*) echo OK;; esac 10054 OK 10055 bash-2.02$ case /tmp in [\\/]*) echo OK;; esac 10056 OK 10057 10058 Many Bourne shells cannot handle closing brackets in character 10059 classes correctly. 10060 10061 Some shells also have problems with backslash escaping in case you 10062 do not want to match the backslash: both a backslash and the 10063 escaped character match this pattern. To work around this, 10064 specify the character class in a variable, so that quote removal 10065 does not apply afterwards, and the special characters don't have 10066 to be backslash-escaped: 10067 10068 $ case '\' in [\<]) echo OK;; esac 10069 OK 10070 $ scanset='[<]'; case '\' in $scanset) echo OK;; esac 10071 $ 10072 10073 Even with this, Solaris `ksh' matches a backslash if the set 10074 contains any of the characters `|', `&', `(', or `)'. 10075 10076 Conversely, Tru64 `ksh' (circa 2003) erroneously always matches a 10077 closing parenthesis if not specified in a character class: 10078 10079 $ case foo in *\)*) echo fail ;; esac 10080 fail 10081 $ case foo in *')'*) echo fail ;; esac 10082 fail 10083 10084 Some shells, such as Ash 0.3.8, are confused by an empty 10085 `case'/`esac': 10086 10087 ash-0.3.8 $ case foo in esac; 10088 error-->Syntax error: ";" unexpected (expecting ")") 10089 10090 Many shells still do not support parenthesized cases, which is a 10091 pity for those of us using tools that rely on balanced 10092 parentheses. For instance, Solaris `/bin/sh': 10093 10094 $ case foo in (foo) echo foo;; esac 10095 error-->syntax error: `(' unexpected 10096 10097`cd' 10098 Posix 1003.1-2001 requires that `cd' must support the `-L' 10099 ("logical") and `-P' ("physical") options, with `-L' being the 10100 default. However, traditional shells do not support these 10101 options, and their `cd' command has the `-P' behavior. 10102 10103 Portable scripts should assume neither option is supported, and 10104 should assume neither behavior is the default. This can be a bit 10105 tricky, since the Posix default behavior means that, for example, 10106 `ls ..' and `cd ..' may refer to different directories if the 10107 current logical directory is a symbolic link. It is safe to use 10108 `cd DIR' if DIR contains no `..' components. Also, 10109 Autoconf-generated scripts check for this problem when computing 10110 variables like `ac_top_srcdir' (*note Configuration Actions::), so 10111 it is safe to `cd' to these variables. 10112 10113 See *Note Special Shell Variables::, for portability problems 10114 involving `cd' and the `CDPATH' environment variable. Also please 10115 see the discussion of the `pwd' command. 10116 10117`echo' 10118 The simple `echo' is probably the most surprising source of 10119 portability troubles. It is not possible to use `echo' portably 10120 unless both options and escape sequences are omitted. New 10121 applications which are not aiming at portability should use 10122 `printf' instead of `echo'. 10123 10124 Don't expect any option. *Note Preset Output Variables::, `ECHO_N' 10125 etc. for a means to simulate `-n'. 10126 10127 Do not use backslashes in the arguments, as there is no consensus 10128 on their handling. For `echo '\n' | wc -l', the `sh' of Solaris 10129 outputs 2, but Bash and Zsh (in `sh' emulation mode) output 1. 10130 The problem is truly `echo': all the shells understand `'\n'' as 10131 the string composed of a backslash and an `n'. 10132 10133 Because of these problems, do not pass a string containing 10134 arbitrary characters to `echo'. For example, `echo "$foo"' is safe 10135 if you know that FOO's value cannot contain backslashes and cannot 10136 start with `-', but otherwise you should use a here-document like 10137 this: 10138 10139 cat <<EOF 10140 $foo 10141 EOF 10142 10143`eval' 10144 The `eval' command is useful in limited circumstances, e.g., using 10145 commands like `eval table_$key=\$value' and `eval 10146 value=table_$key' to simulate a hash table when the key is known 10147 to be alphanumeric. However, `eval' is tricky to use on arbitrary 10148 arguments, even when it is implemented correctly. 10149 10150 It is obviously unwise to use `eval $cmd' if the string value of 10151 `cmd' was derived from an untrustworthy source. But even if the 10152 string value is valid, `eval $cmd' might not work as intended, 10153 since it causes field splitting and file name expansion to occur 10154 twice, once for the `eval' and once for the command itself. It is 10155 therefore safer to use `eval "$cmd"'. For example, if CMD has the 10156 value `cat test?.c', `eval $cmd' might expand to the equivalent of 10157 `cat test;.c' if there happens to be a file named `test;.c' in the 10158 current directory; and this in turn mistakenly attempts to invoke 10159 `cat' on the file `test' and then execute the command `.c'. To 10160 avoid this problem, use `eval "$cmd"' rather than `eval $cmd'. 10161 10162 However, suppose that you want to output the text of the evaluated 10163 command just before executing it. Assuming the previous example, 10164 `echo "Executing: $cmd"' outputs `Executing: cat test?.c', but 10165 this output doesn't show the user that `test;.c' is the actual name 10166 of the copied file. Conversely, `eval "echo Executing: $cmd"' 10167 works on this example, but it fails with `cmd='cat foo >bar'', 10168 since it mistakenly replaces the contents of `bar' by the string 10169 `cat foo'. No simple, general, and portable solution to this 10170 problem is known. 10171 10172 You should also be wary of common bugs in `eval' implementations. 10173 In some shell implementations (e.g., older `ash', OpenBSD 3.8 10174 `sh', `pdksh' v5.2.14 99/07/13.2, and `zsh' 4.2.5), the arguments 10175 of `eval' are evaluated in a context where `$?' is 0, so they 10176 exhibit behavior like this: 10177 10178 $ false; eval 'echo $?' 10179 0 10180 10181 The correct behavior here is to output a nonzero value, but 10182 portable scripts should not rely on this. 10183 10184 You should not rely on `LINENO' within `eval'. *Note Special 10185 Shell Variables::. 10186 10187`exit' 10188 The default value of `exit' is supposed to be `$?'; unfortunately, 10189 some shells, such as the DJGPP port of Bash 2.04, just perform 10190 `exit 0'. 10191 10192 bash-2.04$ foo=`exit 1` || echo fail 10193 fail 10194 bash-2.04$ foo=`(exit 1)` || echo fail 10195 fail 10196 bash-2.04$ foo=`(exit 1); exit` || echo fail 10197 bash-2.04$ 10198 10199 Using `exit $?' restores the expected behavior. 10200 10201 Some shell scripts, such as those generated by `autoconf', use a 10202 trap to clean up before exiting. If the last shell command exited 10203 with nonzero status, the trap also exits with nonzero status so 10204 that the invoker can tell that an error occurred. 10205 10206 Unfortunately, in some shells, such as Solaris `/bin/sh', an exit 10207 trap ignores the `exit' command's argument. In these shells, a 10208 trap cannot determine whether it was invoked by plain `exit' or by 10209 `exit 1'. Instead of calling `exit' directly, use the 10210 `AC_MSG_ERROR' macro that has a workaround for this problem. 10211 10212`export' 10213 The builtin `export' dubs a shell variable "environment variable". 10214 Each update of exported variables corresponds to an update of the 10215 environment variables. Conversely, each environment variable 10216 received by the shell when it is launched should be imported as a 10217 shell variable marked as exported. 10218 10219 Alas, many shells, such as Solaris `/bin/sh', IRIX 6.3, IRIX 5.2, 10220 AIX 4.1.5, and Digital Unix 4.0, forget to `export' the 10221 environment variables they receive. As a result, two variables 10222 coexist: the environment variable and the shell variable. The 10223 following code demonstrates this failure: 10224 10225 #!/bin/sh 10226 echo $FOO 10227 FOO=bar 10228 echo $FOO 10229 exec /bin/sh $0 10230 10231 when run with `FOO=foo' in the environment, these shells print 10232 alternately `foo' and `bar', although they should print only `foo' 10233 and then a sequence of `bar's. 10234 10235 Therefore you should `export' again each environment variable that 10236 you update. 10237 10238`false' 10239 Don't expect `false' to exit with status 1: in native Solaris 10240 `/bin/false' exits with status 255. 10241 10242`for' 10243 To loop over positional arguments, use: 10244 10245 for arg 10246 do 10247 echo "$arg" 10248 done 10249 10250 You may _not_ leave the `do' on the same line as `for', since some 10251 shells improperly grok: 10252 10253 for arg; do 10254 echo "$arg" 10255 done 10256 10257 If you want to explicitly refer to the positional arguments, given 10258 the `$@' bug (*note Shell Substitutions::), use: 10259 10260 for arg in ${1+"$@"}; do 10261 echo "$arg" 10262 done 10263 10264 But keep in mind that Zsh, even in Bourne shell emulation mode, 10265 performs word splitting on `${1+"$@"}'; see *Note Shell 10266 Substitutions::, item `$@', for more. 10267 10268`if' 10269 Using `!' is not portable. Instead of: 10270 10271 if ! cmp -s file file.new; then 10272 mv file.new file 10273 fi 10274 10275 use: 10276 10277 if cmp -s file file.new; then :; else 10278 mv file.new file 10279 fi 10280 10281 There are shells that do not reset the exit status from an `if': 10282 10283 $ if (exit 42); then true; fi; echo $? 10284 42 10285 10286 whereas a proper shell should have printed `0'. This is especially 10287 bad in makefiles since it produces false failures. This is why 10288 properly written makefiles, such as Automake's, have such hairy 10289 constructs: 10290 10291 if test -f "$file"; then 10292 install "$file" "$dest" 10293 else 10294 : 10295 fi 10296 10297`printf' 10298 A format string starting with a `-' can cause problems. Bash 10299 (e.g., 2.05b) interprets it as an options argument and gives an 10300 error. And `--' to mark the end of options is not good in the 10301 NetBSD Almquist shell (e.g., 0.4.6) which takes that literally as 10302 the format string. Putting the `-' in a `%c' or `%s' is probably 10303 the easiest way to avoid doubt, 10304 10305 printf %s -foo 10306 10307`read' 10308 Not all shells support `-r' (Solaris `/bin/sh' for example). 10309 10310`pwd' 10311 With modern shells, plain `pwd' outputs a "logical" directory 10312 name, some of whose components may be symbolic links. These 10313 directory names are in contrast to "physical" directory names, 10314 whose components are all directories. 10315 10316 Posix 1003.1-2001 requires that `pwd' must support the `-L' 10317 ("logical") and `-P' ("physical") options, with `-L' being the 10318 default. However, traditional shells do not support these 10319 options, and their `pwd' command has the `-P' behavior. 10320 10321 Portable scripts should assume neither option is supported, and 10322 should assume neither behavior is the default. Also, on many hosts 10323 `/bin/pwd' is equivalent to `pwd -P', but Posix does not require 10324 this behavior and portable scripts should not rely on it. 10325 10326 Typically it's best to use plain `pwd'. On modern hosts this 10327 outputs logical directory names, which have the following 10328 advantages: 10329 10330 * Logical names are what the user specified. 10331 10332 * Physical names may not be portable from one installation host 10333 to another due to network file system gymnastics. 10334 10335 * On modern hosts `pwd -P' may fail due to lack of permissions 10336 to some parent directory, but plain `pwd' cannot fail for this 10337 reason. 10338 10339 Also please see the discussion of the `cd' command. 10340 10341`set' 10342 With the FreeBSD 6.0 shell, the `set' command (without any 10343 options) does not sort its output. 10344 10345 The `set' builtin faces the usual problem with arguments starting 10346 with a dash. Modern shells such as Bash or Zsh understand `--' to 10347 specify the end of the options (any argument after `--' is a 10348 parameter, even `-x' for instance), but many traditional shells 10349 (e.g., Solaris 10 `/bin/sh') simply stop option processing as soon 10350 as a non-option argument is found. Therefore, use `dummy' or 10351 simply `x' to end the option processing, and use `shift' to pop it 10352 out: 10353 10354 set x $my_list; shift 10355 10356 Avoid `set -', e.g., `set - $my_list'. Posix no longer requires 10357 support for this command, and in traditional shells `set - 10358 $my_list' resets the `-v' and `-x' options, which makes scripts 10359 harder to debug. 10360 10361 Some nonstandard shells do not recognize more than one option 10362 (e.g., `set -e -x' assigns `-x' to the command line). It is 10363 better to combine them: 10364 10365 set -ex 10366 10367 The BSD shell has had several problems with the `-e' option, 10368 partly because BSD `make' traditionally used `-e' even though this 10369 was incompatible with Posix (*note Failure in Make Rules::). 10370 Older versions of the BSD shell (circa 1990) mishandled `&&', 10371 `||', `if', and `case' when `-e' was in effect, causing the shell 10372 to exit unexpectedly in some cases. This was particularly a 10373 problem with makefiles, and led to circumlocutions like `sh -c 10374 'test -f file || touch file'', where the seemingly-unnecessary `sh 10375 -c '...'' wrapper works around the bug. 10376 10377 Even relatively-recent versions of the BSD shell (e.g., OpenBSD 10378 3.4) wrongly exit with `-e' if a command within `&&' fails inside 10379 a compound statement. For example: 10380 10381 #! /bin/sh 10382 set -e 10383 foo='' 10384 test -n "$foo" && exit 1 10385 echo one 10386 if :; then 10387 test -n "$foo" && exit 1 10388 fi 10389 echo two 10390 10391 does not print `two'. One workaround is to use `if test -n 10392 "$foo"; then exit 1; fi' rather than `test -n "$foo" && exit 1'. 10393 Another possibility is to warn BSD users not to use `sh -e'. 10394 10395`shift' 10396 Not only is `shift'ing a bad idea when there is nothing left to 10397 shift, but in addition it is not portable: the shell of MIPS 10398 RISC/OS 4.52 refuses to do it. 10399 10400 Don't use `shift 2' etc.; it was not in the 7th Edition Bourne 10401 shell, and it is also absent in many pre-Posix shells. 10402 10403`source' 10404 This command is not portable, as Posix does not require it; use 10405 `.' instead. 10406 10407`test' 10408 The `test' program is the way to perform many file and string 10409 tests. It is often invoked by the alternate name `[', but using 10410 that name in Autoconf code is asking for trouble since it is an M4 10411 quote character. 10412 10413 If you need to make multiple checks using `test', combine them with 10414 the shell operators `&&' and `||' instead of using the `test' 10415 operators `-a' and `-o'. On System V, the precedence of `-a' and 10416 `-o' is wrong relative to the unary operators; consequently, Posix 10417 does not specify them, so using them is nonportable. If you 10418 combine `&&' and `||' in the same statement, keep in mind that 10419 they have equal precedence. 10420 10421 It is safe to use `!' as a `test' operator. For example, `if test 10422 ! -d foo; ...' is portable even though `if ! test -d foo; ...' is 10423 not. 10424 10425`test' (files) 10426 To enable `configure' scripts to support cross-compilation, they 10427 shouldn't do anything that tests features of the build system 10428 instead of the host system. But occasionally you may find it 10429 necessary to check whether some arbitrary file exists. To do so, 10430 use `test -f' or `test -r'. Do not use `test -x', because 4.3BSD 10431 does not have it. Do not use `test -e' either, because Solaris 10432 `/bin/sh' lacks it. To test for symbolic links on systems that 10433 have them, use `test -h' rather than `test -L'; either form 10434 conforms to Posix 1003.1-2001, but older shells like Solaris 8 10435 `/bin/sh' support only `-h'. 10436 10437`test' (strings) 10438 Avoid `test "STRING"', in particular if STRING might start with a 10439 dash, since `test' might interpret its argument as an option 10440 (e.g., `STRING = "-n"'). 10441 10442 Contrary to a common belief, `test -n STRING' and `test -z STRING' 10443 *are* portable. Nevertheless many shells (such as Solaris, AIX 10444 3.2, UNICOS 10.0.0.6, Digital Unix 4, etc.) have bizarre 10445 precedence and may be confused if STRING looks like an operator: 10446 10447 $ test -n = 10448 test: argument expected 10449 10450 If there are risks, use `test "xSTRING" = x' or `test "xSTRING" != 10451 x' instead. 10452 10453 It is common to find variations of the following idiom: 10454 10455 test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" && 10456 ACTION 10457 10458 to take an action when a token matches a given pattern. Such 10459 constructs should always be avoided by using: 10460 10461 echo "$ac_feature" | grep '[^-a-zA-Z0-9_]' >/dev/null 2>&1 && 10462 ACTION 10463 10464 Use `case' where possible since it is faster, being a shell 10465 builtin: 10466 10467 case $ac_feature in 10468 *[!-a-zA-Z0-9_]*) ACTION;; 10469 esac 10470 10471 Alas, negated character classes are probably not portable, 10472 although no shell is known to not support the Posix syntax `[!...]' 10473 (when in interactive mode, `zsh' is confused by the `[!...]' 10474 syntax and looks for an event in its history because of `!'). 10475 Many shells do not support the alternative syntax `[^...]' 10476 (Solaris, Digital Unix, etc.). 10477 10478 One solution can be: 10479 10480 expr "$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null && 10481 ACTION 10482 10483 or better yet 10484 10485 expr "X$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null && 10486 ACTION 10487 10488 `expr "XFOO" : "XBAR"' is more robust than `echo "XFOO" | grep 10489 "^XBAR"', because it avoids problems when `FOO' contains 10490 backslashes. 10491 10492`trap' 10493 It is safe to trap at least the signals 1, 2, 13, and 15. You can 10494 also trap 0, i.e., have the `trap' run when the script ends 10495 (either via an explicit `exit', or the end of the script). The 10496 trap for 0 should be installed outside of a shell function, or AIX 10497 5.3 `/bin/sh' will invoke the trap at the end of this function. 10498 10499 Posix says that `trap - 1 2 13 15' resets the traps for the 10500 specified signals to their default values, but many common shells 10501 (e.g., Solaris `/bin/sh') misinterpret this and attempt to execute 10502 a "command" named `-' when the specified conditions arise. There 10503 is no portable workaround, except for `trap - 0', for which `trap 10504 '' 0' is a portable substitute. 10505 10506 Although Posix is not absolutely clear on this point, it is widely 10507 admitted that when entering the trap `$?' should be set to the exit 10508 status of the last command run before the trap. The ambiguity can 10509 be summarized as: "when the trap is launched by an `exit', what is 10510 the _last_ command run: that before `exit', or `exit' itself?" 10511 10512 Bash considers `exit' to be the last command, while Zsh and 10513 Solaris `/bin/sh' consider that when the trap is run it is _still_ 10514 in the `exit', hence it is the previous exit status that the trap 10515 receives: 10516 10517 $ cat trap.sh 10518 trap 'echo $?' 0 10519 (exit 42); exit 0 10520 $ zsh trap.sh 10521 42 10522 $ bash trap.sh 10523 0 10524 10525 The portable solution is then simple: when you want to `exit 42', 10526 run `(exit 42); exit 42', the first `exit' being used to set the 10527 exit status to 42 for Zsh, and the second to trigger the trap and 10528 pass 42 as exit status for Bash. 10529 10530 The shell in FreeBSD 4.0 has the following bug: `$?' is reset to 0 10531 by empty lines if the code is inside `trap'. 10532 10533 $ trap 'false 10534 10535 echo $?' 0 10536 $ exit 10537 0 10538 10539 Fortunately, this bug only affects `trap'. 10540 10541`true' 10542 Don't worry: as far as we know `true' is portable. Nevertheless, 10543 it's not always a builtin (e.g., Bash 1.x), and the portable shell 10544 community tends to prefer using `:'. This has a funny side 10545 effect: when asked whether `false' is more portable than `true' 10546 Alexandre Oliva answered: 10547 10548 In a sense, yes, because if it doesn't exist, the shell will 10549 produce an exit status of failure, which is correct for 10550 `false', but not for `true'. 10551 10552`unset' 10553 In some nonconforming shells (e.g., Bash 2.05a), `unset FOO' fails 10554 when `FOO' is not set. Also, Bash 2.01 mishandles `unset MAIL' in 10555 some cases and dumps core. 10556 10557 A few ancient shells lack `unset' entirely. Nevertheless, because 10558 it is extremely useful to disable embarrassing variables such as 10559 `PS1', you can test for its existence and use it _provided_ you 10560 give a neutralizing value when `unset' is not supported: 10561 10562 # "|| exit" suppresses any "Segmentation fault" message. 10563 if ( (MAIL=60; unset MAIL) || exit) >/dev/null 2>&1; then 10564 unset=unset 10565 else 10566 unset=false 10567 fi 10568 $unset PS1 || PS1='$ ' 10569 10570 *Note Special Shell Variables::, for some neutralizing values. 10571 Also, see *Note Limitations of Builtins::, documentation of 10572 `export', for the case of environment variables. 10573 10574 10575File: autoconf.info, Node: Limitations of Usual Tools, Prev: Limitations of Builtins, Up: Portable Shell 10576 1057710.11 Limitations of Usual Tools 10578================================ 10579 10580The small set of tools you can expect to find on any machine can still 10581include some limitations you should be aware of. 10582 10583Awk 10584 Don't leave white space before the opening parenthesis in a user 10585 function call. Posix does not allow this and GNU Awk rejects it: 10586 10587 $ gawk 'function die () { print "Aaaaarg!" } 10588 BEGIN { die () }' 10589 gawk: cmd. line:2: BEGIN { die () } 10590 gawk: cmd. line:2: ^ parse error 10591 $ gawk 'function die () { print "Aaaaarg!" } 10592 BEGIN { die() }' 10593 Aaaaarg! 10594 10595 If you want your program to be deterministic, don't depend on `for' 10596 on arrays: 10597 10598 $ cat for.awk 10599 END { 10600 arr["foo"] = 1 10601 arr["bar"] = 1 10602 for (i in arr) 10603 print i 10604 } 10605 $ gawk -f for.awk </dev/null 10606 foo 10607 bar 10608 $ nawk -f for.awk </dev/null 10609 bar 10610 foo 10611 10612 Some Awk implementations, such as HP-UX 11.0's native one, 10613 mishandle anchors: 10614 10615 $ echo xfoo | $AWK '/foo|^bar/ { print }' 10616 $ echo bar | $AWK '/foo|^bar/ { print }' 10617 bar 10618 $ echo xfoo | $AWK '/^bar|foo/ { print }' 10619 xfoo 10620 $ echo bar | $AWK '/^bar|foo/ { print }' 10621 bar 10622 10623 Either do not depend on such patterns (i.e., use `/^(.*foo|bar)/', 10624 or use a simple test to reject such implementations. 10625 10626 AIX version 5.2 has an arbitrary limit of 399 on the length of 10627 regular expressions and literal strings in an Awk program. 10628 10629 Traditional Awk implementations derived from Unix version 7, such 10630 as Solaris `/bin/awk', have many limitations and do not conform to 10631 Posix. Nowadays `AC_PROG_AWK' (*note Particular Programs::) finds 10632 you an Awk that doesn't have these problems, but if for some 10633 reason you prefer not to use `AC_PROG_AWK' you may need to address 10634 them. 10635 10636 Traditional Awk does not support multidimensional arrays or 10637 user-defined functions. 10638 10639 Traditional Awk does not support the `-v' option. You can use 10640 assignments after the program instead, e.g., `$AWK '{print v $1}' 10641 v=x'; however, don't forget that such assignments are not 10642 evaluated until they are encountered (e.g., after any `BEGIN' 10643 action). 10644 10645 Traditional Awk does not support the keywords `delete' or `do'. 10646 10647 Traditional Awk does not support the expressions `A?B:C', `!A', 10648 `A^B', or `A^=B'. 10649 10650 Traditional Awk does not support the predefined `CONVFMT' variable. 10651 10652 Traditional Awk supports only the predefined functions `exp', 10653 `int', `length', `log', `split', `sprintf', `sqrt', and `substr'. 10654 10655 Traditional Awk `getline' is not at all compatible with Posix; 10656 avoid it. 10657 10658 Traditional Awk `split' supports only two arguments. 10659 10660 Traditional Awk has a limit of 99 fields in a record. You may be 10661 able to circumvent this problem by using `split'. 10662 10663`basename' 10664 Not all hosts have a working `basename'. You can use `expr' 10665 instead. 10666 10667`cat' 10668 Don't rely on any option. 10669 10670`cc' 10671 The command `cc -c foo.c' traditionally produces an object file 10672 named `foo.o'. Most compilers allow `-c' to be combined with `-o' 10673 to specify a different object file name, but Posix does not 10674 require this combination and a few compilers lack support for it. 10675 *Note C Compiler::, for how GNU Make tests for this feature with 10676 `AC_PROG_CC_C_O'. 10677 10678 When a compilation such as `cc -o foo foo.c' fails, some compilers 10679 (such as CDS on Reliant Unix) leave a `foo.o'. 10680 10681 HP-UX `cc' doesn't accept `.S' files to preprocess and assemble. 10682 `cc -c foo.S' appears to succeed, but in fact does nothing. 10683 10684 The default executable, produced by `cc foo.c', can be 10685 10686 * `a.out' -- usual Posix convention. 10687 10688 * `b.out' -- i960 compilers (including `gcc'). 10689 10690 * `a.exe' -- DJGPP port of `gcc'. 10691 10692 * `a_out.exe' -- GNV `cc' wrapper for DEC C on OpenVMS. 10693 10694 * `foo.exe' -- various MS-DOS compilers. 10695 10696 The C compiler's traditional name is `cc', but other names like 10697 `gcc' are common. Posix 1003.1-2001 specifies the name `c99', but 10698 older Posix editions specified `c89' and anyway these standard 10699 names are rarely used in practice. Typically the C compiler is 10700 invoked from makefiles that use `$(CC)', so the value of the `CC' 10701 make variable selects the compiler name. 10702 10703`chmod' 10704 Avoid usages like `chmod -w file'; use `chmod a-w file' instead, 10705 for two reasons. First, plain `-w' does not necessarily make the 10706 file unwritable, since it does not affect mode bits that 10707 correspond to bits in the file mode creation mask. Second, Posix 10708 says that the `-w' might be interpreted as an 10709 implementation-specific option, not as a mode; Posix suggests 10710 using `chmod -- -w file' to avoid this confusion, but unfortunately 10711 `--' does not work on some older hosts. 10712 10713`cmp' 10714 `cmp' performs a raw data comparison of two files, while `diff' 10715 compares two text files. Therefore, if you might compare DOS 10716 files, even if only checking whether two files are different, use 10717 `diff' to avoid spurious differences due to differences of newline 10718 encoding. 10719 10720`cp' 10721 Avoid the `-r' option, since Posix 1003.1-2004 marks it as 10722 obsolescent and its behavior on special files is 10723 implementation-defined. Use `-R' instead. On GNU hosts the two 10724 options are equivalent, but on Solaris hosts (for example) `cp -r' 10725 reads from pipes instead of replicating them. 10726 10727 Some `cp' implementations (e.g., BSD/OS 4.2) do not allow trailing 10728 slashes at the end of nonexistent destination directories. To 10729 avoid this problem, omit the trailing slashes. For example, use 10730 `cp -R source /tmp/newdir' rather than `cp -R source /tmp/newdir/' 10731 if `/tmp/newdir' does not exist. 10732 10733 The ancient SunOS 4 `cp' does not support `-f', although its `mv' 10734 does. 10735 10736 Traditionally, file timestamps had 1-second resolution, and `cp 10737 -p' copied the timestamps exactly. However, many modern file 10738 systems have timestamps with 1-nanosecond resolution. 10739 Unfortunately, `cp -p' implementations truncate timestamps when 10740 copying files, so this can result in the destination file 10741 appearing to be older than the source. The exact amount of 10742 truncation depends on the resolution of the system calls that `cp' 10743 uses; traditionally this was `utime', which has 1-second 10744 resolution, but some newer `cp' implementations use `utimes', 10745 which has 1-microsecond resolution. These newer implementations 10746 include GNU Core Utilities 5.0.91 or later, and Solaris 8 (sparc) 10747 patch 109933-02 or later. Unfortunately as of January 2006 there 10748 is still no system call to set timestamps to the full nanosecond 10749 resolution. 10750 10751 Bob Proulx notes that `cp -p' always _tries_ to copy ownerships. 10752 But whether it actually does copy ownerships or not is a system 10753 dependent policy decision implemented by the kernel. If the 10754 kernel allows it then it happens. If the kernel does not allow it 10755 then it does not happen. It is not something `cp' itself has 10756 control over. 10757 10758 In Unix System V any user can chown files to any other user, and 10759 System V also has a non-sticky `/tmp'. That probably derives from 10760 the heritage of System V in a business environment without hostile 10761 users. BSD changed this to be a more secure model where only root 10762 can `chown' files and a sticky `/tmp' is used. That undoubtedly 10763 derives from the heritage of BSD in a campus environment. 10764 10765 GNU/Linux and Solaris by default follow BSD, but can be configured 10766 to allow a System V style `chown'. On the other hand, HP-UX 10767 follows System V, but can be configured to use the modern security 10768 model and disallow `chown'. Since it is an 10769 administrator-configurable parameter you can't use the name of the 10770 kernel as an indicator of the behavior. 10771 10772`date' 10773 Some versions of `date' do not recognize special `%' directives, 10774 and unfortunately, instead of complaining, they just pass them 10775 through, and exit with success: 10776 10777 $ uname -a 10778 OSF1 medusa.sis.pasteur.fr V5.1 732 alpha 10779 $ date "+%s" 10780 %s 10781 10782`diff' 10783 Option `-u' is nonportable. 10784 10785 Some implementations, such as Tru64's, fail when comparing to 10786 `/dev/null'. Use an empty file instead. 10787 10788`dirname' 10789 Not all hosts have a working `dirname', and you should instead use 10790 `AS_DIRNAME' (*note Programming in M4sh::). For example: 10791 10792 dir=`dirname "$file"` # This is not portable. 10793 dir=`AS_DIRNAME(["$file"])` # This is more portable. 10794 10795`egrep' 10796 Posix 1003.1-2001 no longer requires `egrep', but many older hosts 10797 do not yet support the Posix replacement `grep -E'. Also, some 10798 traditional implementations do not work on long input lines. To 10799 work around these problems, invoke `AC_PROG_EGREP' and then use 10800 `$EGREP'. 10801 10802 Portable extended regular expressions should use `\' only to escape 10803 characters in the string `$()*+.?[\^{|'. For example, `\}' is not 10804 portable, even though it typically matches `}'. 10805 10806 The empty alternative is not portable. Use `?' instead. For 10807 instance with Digital Unix v5.0: 10808 10809 > printf "foo\n|foo\n" | $EGREP '^(|foo|bar)$' 10810 |foo 10811 > printf "bar\nbar|\n" | $EGREP '^(foo|bar|)$' 10812 bar| 10813 > printf "foo\nfoo|\n|bar\nbar\n" | $EGREP '^(foo||bar)$' 10814 foo 10815 |bar 10816 10817 `$EGREP' also suffers the limitations of `grep'. 10818 10819`expr' 10820 No `expr' keyword starts with `X', so use `expr X"WORD" : 10821 'XREGEX'' to keep `expr' from misinterpreting WORD. 10822 10823 Don't use `length', `substr', `match' and `index'. 10824 10825`expr' (`|') 10826 You can use `|'. Although Posix does require that `expr ''' 10827 return the empty string, it does not specify the result when you 10828 `|' together the empty string (or zero) with the empty string. For 10829 example: 10830 10831 expr '' \| '' 10832 10833 Posix 1003.2-1992 returns the empty string for this case, but 10834 traditional Unix returns `0' (Solaris is one such example). In 10835 Posix 1003.1-2001, the specification was changed to match 10836 traditional Unix's behavior (which is bizarre, but it's too late 10837 to fix this). Please note that the same problem does arise when 10838 the empty string results from a computation, as in: 10839 10840 expr bar : foo \| foo : bar 10841 10842 Avoid this portability problem by avoiding the empty string. 10843 10844`expr' (`:') 10845 Portable `expr' regular expressions should use `\' to escape only 10846 characters in the string `$()*.0123456789[\^n{}'. For example, 10847 alternation, `\|', is common but Posix does not require its 10848 support, so it should be avoided in portable scripts. Similarly, 10849 `\+' and `\?' should be avoided. 10850 10851 Portable `expr' regular expressions should not begin with `^'. 10852 Patterns are automatically anchored so leading `^' is not needed 10853 anyway. 10854 10855 The Posix standard is ambiguous as to whether `expr 'a' : '\(b\)'' 10856 outputs `0' or the empty string. In practice, it outputs the 10857 empty string on most platforms, but portable scripts should not 10858 assume this. For instance, the QNX 4.25 native `expr' returns `0'. 10859 10860 One might think that a way to get a uniform behavior would be to 10861 use the empty string as a default value: 10862 10863 expr a : '\(b\)' \| '' 10864 10865 Unfortunately this behaves exactly as the original expression; see 10866 the `expr' (`|') entry for more information. 10867 10868 Ancient `expr' implementations (e.g., SunOS 4 `expr' and Solaris 8 10869 `/usr/ucb/expr') have a silly length limit that causes `expr' to 10870 fail if the matched substring is longer than 120 bytes. In this 10871 case, you might want to fall back on `echo|sed' if `expr' fails. 10872 Nowadays this is of practical importance only for the rare 10873 installer who mistakenly puts `/usr/ucb' before `/usr/bin' in 10874 `PATH'. 10875 10876 On Mac OS X 10.4, `expr' mishandles the pattern `[^-]' in some 10877 cases. For example, the command 10878 expr Xpowerpc-apple-darwin8.1.0 : 'X[^-]*-[^-]*-\(.*\)' 10879 10880 outputs `apple-darwin8.1.0' rather than the correct `darwin8.1.0'. 10881 This particular case can be worked around by substituting `[^--]' 10882 for `[^-]'. 10883 10884 Don't leave, there is some more! 10885 10886 The QNX 4.25 `expr', in addition of preferring `0' to the empty 10887 string, has a funny behavior in its exit status: it's always 1 10888 when parentheses are used! 10889 10890 $ val=`expr 'a' : 'a'`; echo "$?: $val" 10891 0: 1 10892 $ val=`expr 'a' : 'b'`; echo "$?: $val" 10893 1: 0 10894 10895 $ val=`expr 'a' : '\(a\)'`; echo "?: $val" 10896 1: a 10897 $ val=`expr 'a' : '\(b\)'`; echo "?: $val" 10898 1: 0 10899 10900 In practice this can be a big problem if you are ready to catch 10901 failures of `expr' programs with some other method (such as using 10902 `sed'), since you may get twice the result. For instance 10903 10904 $ expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/' 10905 10906 outputs `a' on most hosts, but `aa' on QNX 4.25. A simple 10907 workaround consists of testing `expr' and using a variable set to 10908 `expr' or to `false' according to the result. 10909 10910 Tru64 `expr' incorrectly treats the result as a number, if it can 10911 be interpreted that way: 10912 10913 $ expr 00001 : '.*\(...\)' 10914 1 10915 10916`fgrep' 10917 Posix 1003.1-2001 no longer requires `fgrep', but many older hosts 10918 do not yet support the Posix replacement `grep -F'. Also, some 10919 traditional implementations do not work on long input lines. To 10920 work around these problems, invoke `AC_PROG_FGREP' and then use 10921 `$FGREP'. 10922 10923`find' 10924 The option `-maxdepth' seems to be GNU specific. Tru64 v5.1, 10925 NetBSD 1.5 and Solaris `find' commands do not understand it. 10926 10927 The replacement of `{}' is guaranteed only if the argument is 10928 exactly _{}_, not if it's only a part of an argument. For 10929 instance on DU, and HP-UX 10.20 and HP-UX 11: 10930 10931 $ touch foo 10932 $ find . -name foo -exec echo "{}-{}" \; 10933 {}-{} 10934 10935 while GNU `find' reports `./foo-./foo'. 10936 10937`grep' 10938 Portable scripts can rely on the `grep' options `-c', `-l', `-n', 10939 and `-v', but should avoid other options. For example, don't use 10940 `-w', as Posix does not require it and Irix 6.5.16m's `grep' does 10941 not support it. Also, portable scripts should not combine `-c' 10942 with `-l', as Posix does not allow this. 10943 10944 Some of the options required by Posix are not portable in practice. 10945 Don't use `grep -q' to suppress output, because many `grep' 10946 implementations (e.g., Solaris) do not support `-q'. Don't use 10947 `grep -s' to suppress output either, because Posix says `-s' does 10948 not suppress output, only some error messages; also, the `-s' 10949 option of traditional `grep' behaved like `-q' does in most modern 10950 implementations. Instead, redirect the standard output and 10951 standard error (in case the file doesn't exist) of `grep' to 10952 `/dev/null'. Check the exit status of `grep' to determine whether 10953 it found a match. 10954 10955 Some traditional `grep' implementations do not work on long input 10956 lines. On AIX the default `grep' silently truncates long lines on 10957 the input before matching. 10958 10959 Also, many implementations do not support multiple regexps with 10960 `-e': they either reject `-e' entirely (e.g., Solaris) or honor 10961 only the last pattern (e.g., IRIX 6.5 and NeXT). To work around 10962 these problems, invoke `AC_PROG_GREP' and then use `$GREP'. 10963 10964 Another possible workaround for the multiple `-e' problem is to 10965 separate the patterns by newlines, for example: 10966 10967 grep 'foo 10968 bar' in.txt 10969 10970 except that this fails with traditional `grep' implementations and 10971 with OpenBSD 3.8 `grep'. 10972 10973 Traditional `grep' implementations (e.g., Solaris) do not support 10974 the `-E' or `-F' options. To work around these problems, invoke 10975 `AC_PROG_EGREP' and then use `$EGREP', and similarly for 10976 `AC_PROG_FGREP' and `$FGREP'. Even if you are willing to require 10977 support for Posix `grep', your script should not use both `-E' and 10978 `-F', since Posix does not allow this combination. 10979 10980 Portable `grep' regular expressions should use `\' only to escape 10981 characters in the string `$()*.0123456789[\^{}'. For example, 10982 alternation, `\|', is common but Posix does not require its 10983 support in basic regular expressions, so it should be avoided in 10984 portable scripts. Solaris `grep' does not support it. Similarly, 10985 `\+' and `\?' should be avoided. 10986 10987`join' 10988 Solaris 8 `join' has bugs when the second operand is standard 10989 input, and when standard input is a pipe. For example, the 10990 following shell script causes Solaris 8 `join' to loop forever: 10991 10992 cat >file <<'EOF' 10993 1 x 10994 2 y 10995 EOF 10996 cat file | join file - 10997 10998 Use `join - file' instead. 10999 11000`ln' 11001 Don't rely on `ln' having a `-f' option. Symbolic links are not 11002 available on old systems; use `$(LN_S)' as a portable substitute. 11003 11004 For versions of the DJGPP before 2.04, `ln' emulates symbolic links 11005 to executables by generating a stub that in turn calls the real 11006 program. This feature also works with nonexistent files like in 11007 the Posix spec. So `ln -s file link' generates `link.exe', which 11008 attempts to call `file.exe' if run. But this feature only works 11009 for executables, so `cp -p' is used instead for these systems. 11010 DJGPP versions 2.04 and later have full support for symbolic links. 11011 11012`ls' 11013 The portable options are `-acdilrtu'. Current practice is for 11014 `-l' to output both owner and group, even though ancient versions 11015 of `ls' omitted the group. 11016 11017 On ancient hosts, `ls foo' sent the diagnostic `foo not found' to 11018 standard output if `foo' did not exist. Hence a shell command 11019 like `sources=`ls *.c 2>/dev/null`' did not always work, since it 11020 was equivalent to `sources='*.c not found'' in the absence of `.c' 11021 files. This is no longer a practical problem, since current `ls' 11022 implementations send diagnostics to standard error. 11023 11024`mkdir' 11025 No `mkdir' option is portable to older systems. Instead of `mkdir 11026 -p FILE-NAME', you should use `AS_MKDIR_P(FILE-NAME)' (*note 11027 Programming in M4sh::) or `AC_PROG_MKDIR_P' (*note Particular 11028 Programs::). 11029 11030 Combining the `-m' and `-p' options, as in `mkdir -m go-w -p DIR', 11031 often leads to trouble. FreeBSD `mkdir' incorrectly attempts to 11032 change the permissions of DIR even if it already exists. HP-UX 11033 11.23 and IRIX 6.5 `mkdir' often assign the wrong permissions to 11034 any newly-created parents of DIR. 11035 11036 Posix does not clearly specify whether `mkdir -p foo' should 11037 succeed when `foo' is a symbolic link to an already-existing 11038 directory. The GNU Core Utilities 5.1.0 `mkdir' succeeds, but 11039 Solaris `mkdir' fails. 11040 11041 Traditional `mkdir -p' implementations suffer from race conditions. 11042 For example, if you invoke `mkdir -p a/b' and `mkdir -p a/c' at 11043 the same time, both processes might detect that `a' is missing, 11044 one might create `a', then the other might try to create `a' and 11045 fail with a `File exists' diagnostic. The GNU Core Utilities 11046 (`fileutils' version 4.1), FreeBSD 5.0, NetBSD 2.0.2, and OpenBSD 11047 2.4 are known to be race-free when two processes invoke `mkdir -p' 11048 simultaneously, but earlier versions are vulnerable. Solaris 11049 `mkdir' is still vulnerable as of Solaris 10, and other 11050 traditional Unix systems are probably vulnerable too. This 11051 possible race is harmful in parallel builds when several Make 11052 rules call `mkdir -p' to construct directories. You may use 11053 `install-sh -d' as a safe replacement, provided this script is 11054 recent enough; the copy shipped with Autoconf 2.60 and Automake 11055 1.10 is OK, but copies from older versions are vulnerable. 11056 11057`mktemp' 11058 Shell scripts can use temporary files safely with `mktemp', but it 11059 does not exist on all systems. A portable way to create a safe 11060 temporary file name is to create a temporary directory with mode 11061 700 and use a file inside this directory. Both methods prevent 11062 attackers from gaining control, though `mktemp' is far less likely 11063 to fail gratuitously under attack. 11064 11065 Here is sample code to create a new temporary directory safely: 11066 11067 # Create a temporary directory $tmp in $TMPDIR (default /tmp). 11068 # Use mktemp if possible; otherwise fall back on mkdir, 11069 # with $RANDOM to make collisions less likely. 11070 : ${TMPDIR=/tmp} 11071 { 11072 tmp=` 11073 (umask 077 && mktemp -d "$TMPDIR/fooXXXXXX") 2>/dev/null 11074 ` && 11075 test -n "$tmp" && test -d "$tmp" 11076 } || { 11077 tmp=$TMPDIR/foo$$-$RANDOM 11078 (umask 077 && mkdir "$tmp") 11079 } || exit $? 11080 11081`mv' 11082 The only portable options are `-f' and `-i'. 11083 11084 Moving individual files between file systems is portable (it was 11085 in Unix version 6), but it is not always atomic: when doing `mv 11086 new existing', there's a critical section where neither the old 11087 nor the new version of `existing' actually exists. 11088 11089 On some systems moving files from `/tmp' can sometimes cause 11090 undesirable (but perfectly valid) warnings, even if you created 11091 these files. This is because `/tmp' belongs to a group that 11092 ordinary users are not members of, and files created in `/tmp' 11093 inherit the group of `/tmp'. When the file is copied, `mv' issues 11094 a diagnostic without failing: 11095 11096 $ touch /tmp/foo 11097 $ mv /tmp/foo . 11098 error-->mv: ./foo: set owner/group (was: 100/0): Operation not permitted 11099 $ echo $? 11100 0 11101 $ ls foo 11102 foo 11103 11104 This annoying behavior conforms to Posix, unfortunately. 11105 11106 Moving directories across mount points is not portable, use `cp' 11107 and `rm'. 11108 11109 DOS variants cannot rename or remove open files, and do not 11110 support commands like `mv foo bar >foo', even though this is 11111 perfectly portable among Posix hosts. 11112 11113`od' 11114 In Mac OS X 10.3, `od' does not support the standard Posix options 11115 `-A', `-j', `-N', or `-t', or the XSI option `-s'. The only 11116 supported Posix option is `-v', and the only supported XSI options 11117 are those in `-bcdox'. The BSD `hexdump' program can be used 11118 instead. 11119 11120 This problem no longer exists in Mac OS X 10.4.3. 11121 11122`rm' 11123 The `-f' and `-r' options are portable. 11124 11125 It is not portable to invoke `rm' without operands. For example, 11126 on many systems `rm -f -r' (with no other arguments) silently 11127 succeeds without doing anything, but it fails with a diagnostic on 11128 NetBSD 2.0.2. 11129 11130 A file might not be removed even if its parent directory is 11131 writable and searchable. Many Posix hosts cannot remove a mount 11132 point, a named stream, a working directory, or a last link to a 11133 file that is being executed. 11134 11135 DOS variants cannot rename or remove open files, and do not 11136 support commands like `rm foo >foo', even though this is perfectly 11137 portable among Posix hosts. 11138 11139`sed' 11140 Patterns should not include the separator (unless escaped), even 11141 as part of a character class. In conformance with Posix, the Cray 11142 `sed' rejects `s/[^/]*$//': use `s,[^/]*$,,'. 11143 11144 Avoid empty patterns within parentheses (i.e., `\(\)'). Posix does 11145 not require support for empty patterns, and Unicos 9 `sed' rejects 11146 them. 11147 11148 Unicos 9 `sed' loops endlessly on patterns like `.*\n.*'. 11149 11150 Sed scripts should not use branch labels longer than 8 characters 11151 and should not contain comments. HP-UX sed has a limit of 99 11152 commands (not counting `:' commands) and 48 labels, which can not 11153 be circumvented by using more than one script file. It can 11154 execute up to 19 reads with the `r' command per cycle. Solaris 11155 `/usr/ucb/sed' rejects usages that exceed an limit of about 6000 11156 bytes for the internal representation of commands. 11157 11158 Avoid redundant `;', as some `sed' implementations, such as NetBSD 11159 1.4.2's, incorrectly try to interpret the second `;' as a command: 11160 11161 $ echo a | sed 's/x/x/;;s/x/x/' 11162 sed: 1: "s/x/x/;;s/x/x/": invalid command code ; 11163 11164 Input should not have unreasonably long lines, since some `sed' 11165 implementations have an input buffer limited to 4000 bytes. 11166 11167 Portable `sed' regular expressions should use `\' only to escape 11168 characters in the string `$()*.0123456789[\^n{}'. For example, 11169 alternation, `\|', is common but Posix does not require its 11170 support, so it should be avoided in portable scripts. Solaris 11171 `sed' does not support alternation; e.g., `sed '/a\|b/d'' deletes 11172 only lines that contain the literal string `a|b'. Similarly, `\+' 11173 and `\?' should be avoided. 11174 11175 Anchors (`^' and `$') inside groups are not portable. 11176 11177 Nested parenthesization in patterns (e.g., `\(\(a*\)b*)\)') is 11178 quite portable to current hosts, but was not supported by some 11179 ancient `sed' implementations like SVR3. 11180 11181 Some `sed' implementations, e.g., Solaris, restrict the special 11182 role of the asterisk to one-character regular expressions. This 11183 may lead to unexpected behavior: 11184 11185 $ echo '1*23*4' | /usr/bin/sed 's/\(.\)*/x/g' 11186 x2x4 11187 $ echo '1*23*4' | /usr/xpg4/bin/sed 's/\(.\)*/x/g' 11188 x 11189 11190 The `-e' option is portable, so long as its argument does not 11191 begin with `a', `c', or `i' (as this runs afoul of a Tru64 5.1 11192 bug). Some people prefer to use `-e': 11193 11194 sed -e 'COMMAND-1' \ 11195 -e 'COMMAND-2' 11196 11197 as opposed to the equivalent: 11198 11199 sed ' 11200 COMMAND-1 11201 COMMAND-2 11202 ' 11203 11204 The following usage is sometimes equivalent: 11205 11206 sed 'COMMAND-1;COMMAND-2' 11207 11208 but Posix says that this use of a semicolon has undefined effect if 11209 COMMAND-1's verb is `{', `a', `b', `c', `i', `r', `t', `w', `:', 11210 or `#', so you should use semicolon only with simple scripts that 11211 do not use these verbs. 11212 11213 Commands inside { } brackets are further restricted. Posix says 11214 that they cannot be preceded by addresses, `!', or `;', and that 11215 each command must be followed immediately by a newline, without any 11216 intervening blanks or semicolons. The closing bracket must be 11217 alone on a line, other than white space preceding or following it. 11218 11219 Contrary to yet another urban legend, you may portably use `&' in 11220 the replacement part of the `s' command to mean "what was 11221 matched". All descendants of Unix version 7 `sed' (at least; we 11222 don't have first hand experience with older `sed' implementations) 11223 have supported it. 11224 11225 Posix requires that you must not have any white space between `!' 11226 and the following command. It is OK to have blanks between the 11227 address and the `!'. For instance, on Solaris: 11228 11229 $ echo "foo" | sed -n '/bar/ ! p' 11230 error-->Unrecognized command: /bar/ ! p 11231 $ echo "foo" | sed -n '/bar/! p' 11232 error-->Unrecognized command: /bar/! p 11233 $ echo "foo" | sed -n '/bar/ !p' 11234 foo 11235 11236 Posix also says that you should not combine `!' and `;'. If you 11237 use `!', it is best to put it on a command that is delimited by 11238 newlines rather than `;'. 11239 11240 Also note that Posix requires that the `b', `t', `r', and `w' 11241 commands be followed by exactly one space before their argument. 11242 On the other hand, no white space is allowed between `:' and the 11243 subsequent label name. 11244 11245 If a sed script is specified on the command line and ends in an 11246 `a', `c', or `i' command, the last line of inserted text should be 11247 followed by a newline. Otherwise some `sed' implementations 11248 (e.g., OpenBSD 3.9) do not append a newline to the inserted text. 11249 11250 Many `sed' implementations (e.g., MacOS X 10.4, OpenBSD 3.9, 11251 Solaris 10 `/usr/ucb/sed') strip leading white space from the text 11252 of `a', `c', and `i' commands. Prepend a backslash to work around 11253 this incompatibility with Posix: 11254 11255 $ echo flushleft | sed 'a\ 11256 > indented 11257 > ' 11258 flushleft 11259 indented 11260 $ echo foo | sed 'a\ 11261 > \ indented 11262 > ' 11263 flushleft 11264 indented 11265 11266`sed' (`t') 11267 Some old systems have `sed' that "forget" to reset their `t' flag 11268 when starting a new cycle. For instance on MIPS RISC/OS, and on 11269 IRIX 5.3, if you run the following `sed' script (the line numbers 11270 are not actual part of the texts): 11271 11272 s/keep me/kept/g # a 11273 t end # b 11274 s/.*/deleted/g # c 11275 :end # d 11276 11277 on 11278 11279 delete me # 1 11280 delete me # 2 11281 keep me # 3 11282 delete me # 4 11283 11284 you get 11285 11286 deleted 11287 delete me 11288 kept 11289 deleted 11290 11291 instead of 11292 11293 deleted 11294 deleted 11295 kept 11296 deleted 11297 11298 Why? When processing line 1, (c) matches, therefore sets the `t' 11299 flag, and the output is produced. When processing line 2, the `t' 11300 flag is still set (this is the bug). Command (a) fails to match, 11301 but `sed' is not supposed to clear the `t' flag when a 11302 substitution fails. Command (b) sees that the flag is set, 11303 therefore it clears it, and jumps to (d), hence you get `delete me' 11304 instead of `deleted'. When processing line (3), `t' is clear, (a) 11305 matches, so the flag is set, hence (b) clears the flags and jumps. 11306 Finally, since the flag is clear, line 4 is processed properly. 11307 11308 There are two things one should remember about `t' in `sed'. 11309 Firstly, always remember that `t' jumps if _some_ substitution 11310 succeeded, not only the immediately preceding substitution. 11311 Therefore, always use a fake `t clear' followed by a `:clear' on 11312 the next line, to reset the `t' flag where needed. 11313 11314 Secondly, you cannot rely on `sed' to clear the flag at each new 11315 cycle. 11316 11317 One portable implementation of the script above is: 11318 11319 t clear 11320 :clear 11321 s/keep me/kept/g 11322 t end 11323 s/.*/deleted/g 11324 :end 11325 11326`touch' 11327 If you specify the desired timestamp (e.g., with the `-r' option), 11328 `touch' typically uses the `utime' or `utimes' system call, which 11329 can result in the same kind of timestamp truncation problems that 11330 `cp -p' has. 11331 11332 On ancient BSD systems, `touch' or any command that results in an 11333 empty file does not update the timestamps, so use a command like 11334 `echo' as a workaround. Also, GNU `touch' 3.16r (and presumably 11335 all before that) fails to work on SunOS 4.1.3 when the empty file 11336 is on an NFS-mounted 4.2 volume. However, these problems are no 11337 longer of practical concern. 11338 11339 11340 11341File: autoconf.info, Node: Portable Make, Next: Portable C and C++, Prev: Portable Shell, Up: Top 11342 1134311 Portable Make Programming 11344**************************** 11345 11346Writing portable makefiles is an art. Since a makefile's commands are 11347executed by the shell, you must consider the shell portability issues 11348already mentioned. However, other issues are specific to `make' itself. 11349 11350* Menu: 11351 11352* $< in Ordinary Make Rules:: $< in ordinary rules 11353* Failure in Make Rules:: Failing portably in rules 11354* Special Chars in Names:: Special Characters in Macro Names 11355* Backslash-Newline-Newline:: Empty last lines in macro definitions 11356* Backslash-Newline Comments:: Spanning comments across line boundaries 11357* Long Lines in Makefiles:: Line length limitations 11358* Macros and Submakes:: `make macro=value' and submakes 11359* The Make Macro MAKEFLAGS:: `$(MAKEFLAGS)' portability issues 11360* The Make Macro SHELL:: `$(SHELL)' portability issues 11361* Comments in Make Rules:: Other problems with Make comments 11362* obj/ and Make:: Don't name a subdirectory `obj' 11363* make -k Status:: Exit status of `make -k' 11364* VPATH and Make:: `VPATH' woes 11365* Single Suffix Rules:: Single suffix rules and separated dependencies 11366* Timestamps and Make:: Subsecond timestamp resolution 11367 11368 11369File: autoconf.info, Node: $< in Ordinary Make Rules, Next: Failure in Make Rules, Up: Portable Make 11370 1137111.1 `$<' in Ordinary Make Rules 11372================================ 11373 11374Posix says that the `$<' construct in makefiles can be used only in 11375inference rules and in the `.DEFAULT' rule; its meaning in ordinary 11376rules is unspecified. Solaris `make' for instance replaces it with the 11377empty string. OpenBSD (3.0 and later) `make' diagnoses these uses and 11378errors out. 11379 11380 11381File: autoconf.info, Node: Failure in Make Rules, Next: Special Chars in Names, Prev: $< in Ordinary Make Rules, Up: Portable Make 11382 1138311.2 Failure in Make Rules 11384========================== 11385 11386Since 1992 Posix has required that `make' must invoke each command with 11387the equivalent of a `sh -c' subshell. However, many `make' 11388implementations, including BSD make through 2004, use `sh -e -c' 11389instead, and the `-e' option causes the subshell to exit immediately if 11390a subsidiary simple-command fails. For example, the command `touch T; 11391rm -f U' always attempts to remove `U' with Posix make, but incompatible 11392`make' implementations skip the `rm' if the `touch' fails. One way to 11393work around this is to reword the affected simple-commands so that they 11394always succeed, e.g., `touch T || :; rm -f U'. However, even this 11395approach can run into common bugs in BSD implementations of the `-e' 11396option of `sh' and `set' (*note Limitations of Builtins::), so if you 11397are worried about porting to buggy BSD shells it may be simpler to 11398migrate complicated `make' actions into separate scripts. 11399 11400 11401File: autoconf.info, Node: Special Chars in Names, Next: Backslash-Newline-Newline, Prev: Failure in Make Rules, Up: Portable Make 11402 1140311.3 Special Characters in Make Macro Names 11404=========================================== 11405 11406Posix limits macro names to nonempty strings containing only ASCII 11407letters and digits, `.', and `_'. Many `make' implementations allow a 11408wider variety of characters, but portable makefiles should avoid them. 11409It is portable to start a name with a special character, e.g., 11410`$(.FOO)'. 11411 11412 Some ancient `make' implementations don't support leading 11413underscores in macro names. An example is NEWS-OS 4.2R. 11414 11415 $ cat Makefile 11416 _am_include = # 11417 _am_quote = 11418 all:; @echo this is test 11419 $ make 11420 Make: Must be a separator on rules line 2. Stop. 11421 $ cat Makefile2 11422 am_include = # 11423 am_quote = 11424 all:; @echo this is test 11425 $ make -f Makefile2 11426 this is test 11427 11428However, this problem is no longer of practical concern. 11429 11430 11431File: autoconf.info, Node: Backslash-Newline-Newline, Next: Backslash-Newline Comments, Prev: Special Chars in Names, Up: Portable Make 11432 1143311.4 Backslash-Newline-Newline in Make Macro Values 11434=================================================== 11435 11436On some versions of HP-UX, `make' reads multiple newlines following a 11437backslash, continuing to the next non-empty line. For example, 11438 11439 FOO = one \ 11440 11441 BAR = two 11442 11443 test: 11444 : FOO is "$(FOO)" 11445 : BAR is "$(BAR)" 11446 11447shows `FOO' equal to `one BAR = two'. Other implementations sensibly 11448let a backslash continue only to the immediately following line. 11449 11450 11451File: autoconf.info, Node: Backslash-Newline Comments, Next: Long Lines in Makefiles, Prev: Backslash-Newline-Newline, Up: Portable Make 11452 1145311.5 Backslash-Newline in Make Comments 11454======================================= 11455 11456According to Posix, Make comments start with `#' and continue until an 11457unescaped newline is reached. 11458 11459 $ cat Makefile 11460 # A = foo \ 11461 bar \ 11462 baz 11463 11464 all: 11465 @echo ok 11466 $ make # GNU make 11467 ok 11468 11469However this is not always the case. Some implementations discard 11470everything from `#' through the end of the line, ignoring any trailing 11471backslash. 11472 11473 $ pmake # BSD make 11474 "Makefile", line 3: Need an operator 11475 Fatal errors encountered -- cannot continue 11476 11477Therefore, if you want to comment out a multi-line definition, prefix 11478each line with `#', not only the first. 11479 11480 # A = foo \ 11481 # bar \ 11482 # baz 11483 11484 11485File: autoconf.info, Node: Long Lines in Makefiles, Next: Macros and Submakes, Prev: Backslash-Newline Comments, Up: Portable Make 11486 1148711.6 Long Lines in Makefiles 11488============================ 11489 11490Tru64 5.1's `make' has been reported to crash when given a makefile 11491with lines longer than around 20 kB. Earlier versions are reported to 11492exit with `Line too long' diagnostics. 11493 11494 11495File: autoconf.info, Node: Macros and Submakes, Next: The Make Macro MAKEFLAGS, Prev: Long Lines in Makefiles, Up: Portable Make 11496 1149711.7 `make macro=value' and Submakes 11498==================================== 11499 11500A command-line variable definition such as `foo=bar' overrides any 11501definition of `foo' in a makefile. Some `make' implementations (such 11502as GNU `make') propagate this override to subsidiary invocations of 11503`make'. Some other implementations do not pass the substitution along 11504to submakes. 11505 11506 $ cat Makefile 11507 foo = foo 11508 one: 11509 @echo $(foo) 11510 $(MAKE) two 11511 two: 11512 @echo $(foo) 11513 $ make foo=bar # GNU make 3.79.1 11514 bar 11515 make two 11516 make[1]: Entering directory `/home/adl' 11517 bar 11518 make[1]: Leaving directory `/home/adl' 11519 $ pmake foo=bar # BSD make 11520 bar 11521 pmake two 11522 foo 11523 11524 You have a few possibilities if you do want the `foo=bar' override 11525to propagate to submakes. One is to use the `-e' option, which causes 11526all environment variables to have precedence over the makefile macro 11527definitions, and declare foo as an environment variable: 11528 11529 $ env foo=bar make -e 11530 11531 The `-e' option is propagated to submakes automatically, and since 11532the environment is inherited between `make' invocations, the `foo' 11533macro is overridden in submakes as expected. 11534 11535 This syntax (`foo=bar make -e') is portable only when used outside 11536of a makefile, for instance from a script or from the command line. 11537When run inside a `make' rule, GNU `make' 3.80 and prior versions 11538forget to propagate the `-e' option to submakes. 11539 11540 Moreover, using `-e' could have unexpected side effects if your 11541environment contains some other macros usually defined by the makefile. 11542(See also the note about `make -e' and `SHELL' below.) 11543 11544 Another way to propagate overrides to submakes is to do it manually, 11545from your makefile: 11546 11547 foo = foo 11548 one: 11549 @echo $(foo) 11550 $(MAKE) foo=$(foo) two 11551 two: 11552 @echo $(foo) 11553 11554 You need to foresee all macros that a user might want to override if 11555you do that. 11556 11557 11558File: autoconf.info, Node: The Make Macro MAKEFLAGS, Next: The Make Macro SHELL, Prev: Macros and Submakes, Up: Portable Make 11559 1156011.8 The Make Macro MAKEFLAGS 11561============================= 11562 11563Posix requires `make' to use `MAKEFLAGS' to affect the current and 11564recursive invocations of make, but allows implementations several 11565formats for the variable. It is tricky to parse `$MAKEFLAGS' to 11566determine whether `-s' for silent execution or `-k' for continued 11567execution are in effect. For example, you cannot assume that the first 11568space-separated word in `$MAKEFLAGS' contains single-letter options, 11569since in the Cygwin version of GNU `make' it is either `--unix' or 11570`--win32' with the second word containing single-letter options. 11571 11572 $ cat Makefile 11573 all: 11574 @echo MAKEFLAGS = $(MAKEFLAGS) 11575 $ make 11576 MAKEFLAGS = --unix 11577 $ make -k 11578 MAKEFLAGS = --unix -k 11579 11580 11581File: autoconf.info, Node: The Make Macro SHELL, Next: Comments in Make Rules, Prev: The Make Macro MAKEFLAGS, Up: Portable Make 11582 1158311.9 The Make Macro `SHELL' 11584=========================== 11585 11586Posix-compliant `make' internally uses the `$(SHELL)' macro to spawn 11587shell processes and execute Make rules. This is a builtin macro 11588supplied by `make', but it can be modified by a makefile or by a 11589command-line argument. 11590 11591 Not all `make' implementations define this `SHELL' macro. Tru64 11592`make' is an example; this implementation always uses `/bin/sh'. So 11593it's a good idea to always define `SHELL' in your makefiles. If you 11594use Autoconf, do 11595 11596 SHELL = @SHELL@ 11597 11598 Do not force `SHELL = /bin/sh' because that is not correct 11599everywhere. For instance DJGPP lacks `/bin/sh', and when its GNU 11600`make' port sees such a setting it enters a special emulation mode 11601where features like pipes and redirections are emulated on top of DOS's 11602`command.com'. Unfortunately this emulation is incomplete; for 11603instance it does not handle command substitutions. On DJGPP `SHELL' 11604should point to Bash. 11605 11606 Posix-compliant `make' should never acquire the value of $(SHELL) 11607from the environment, even when `make -e' is used (otherwise, think 11608about what would happen to your rules if `SHELL=/bin/tcsh'). 11609 11610 However not all `make' implementations have this exception. For 11611instance it's not surprising that Tru64 `make' doesn't protect `SHELL', 11612since it doesn't use it. 11613 11614 $ cat Makefile 11615 SHELL = /bin/sh 11616 FOO = foo 11617 all: 11618 @echo $(SHELL) 11619 @echo $(FOO) 11620 $ env SHELL=/bin/tcsh FOO=bar make -e # Tru64 Make 11621 /bin/tcsh 11622 bar 11623 $ env SHELL=/bin/tcsh FOO=bar gmake -e # GNU make 11624 /bin/sh 11625 bar 11626 11627 11628File: autoconf.info, Node: Comments in Make Rules, Next: obj/ and Make, Prev: The Make Macro SHELL, Up: Portable Make 11629 1163011.10 Comments in Make Rules 11631============================ 11632 11633Never put comments in a rule. 11634 11635 Some `make' treat anything starting with a tab as a command for the 11636current rule, even if the tab is immediately followed by a `#'. The 11637`make' from Tru64 Unix V5.1 is one of them. The following makefile 11638runs `# foo' through the shell. 11639 11640 all: 11641 # foo 11642 11643 11644File: autoconf.info, Node: obj/ and Make, Next: make -k Status, Prev: Comments in Make Rules, Up: Portable Make 11645 1164611.11 The `obj/' Subdirectory and Make 11647====================================== 11648 11649Never name one of your subdirectories `obj/' if you don't like 11650surprises. 11651 11652 If an `obj/' directory exists, BSD `make' enters it before reading 11653the makefile. Hence the makefile in the current directory is not read. 11654 11655 $ cat Makefile 11656 all: 11657 echo Hello 11658 $ cat obj/Makefile 11659 all: 11660 echo World 11661 $ make # GNU make 11662 echo Hello 11663 Hello 11664 $ pmake # BSD make 11665 echo World 11666 World 11667 11668 11669File: autoconf.info, Node: make -k Status, Next: VPATH and Make, Prev: obj/ and Make, Up: Portable Make 11670 1167111.12 Exit Status of `make -k' 11672============================== 11673 11674Do not rely on the exit status of `make -k'. Some implementations 11675reflect whether they encountered an error in their exit status; other 11676implementations always succeed. 11677 11678 $ cat Makefile 11679 all: 11680 false 11681 $ make -k; echo exit status: $? # GNU make 11682 false 11683 make: *** [all] Error 1 11684 exit status: 2 11685 $ pmake -k; echo exit status: $? # BSD make 11686 false 11687 *** Error code 1 (continuing) 11688 exit status: 0 11689 11690 11691File: autoconf.info, Node: VPATH and Make, Next: Single Suffix Rules, Prev: make -k Status, Up: Portable Make 11692 1169311.13 `VPATH' and Make 11694====================== 11695 11696Posix does not specify the semantics of `VPATH'. Typically, `make' 11697supports `VPATH', but its implementation is not consistent. 11698 11699 Autoconf and Automake support makefiles whose usages of `VPATH' are 11700portable to recent-enough popular implementations of `make', but to 11701keep the resulting makefiles portable, a package's makefile prototypes 11702must take the following issues into account. These issues are 11703complicated and are often poorly understood, and installers who use 11704`VPATH' should expect to find many bugs in this area. If you use 11705`VPATH', the simplest way to avoid these portability bugs is to stick 11706with GNU `make', since it is the most commonly-used `make' among 11707Autoconf users. 11708 11709 Here are some known issues with some `VPATH' implementations. 11710 11711* Menu: 11712 11713* VPATH and Double-colon:: Problems with `::' on ancient hosts 11714* $< in Explicit Rules:: `$<' does not work in ordinary rules 11715* Automatic Rule Rewriting:: `VPATH' goes wild on Solaris 11716* Tru64 Directory Magic:: `mkdir' goes wild on Tru64 11717* Make Target Lookup:: More details about `VPATH' lookup 11718 11719 11720File: autoconf.info, Node: VPATH and Double-colon, Next: $< in Explicit Rules, Up: VPATH and Make 11721 1172211.13.1 `VPATH' and Double-colon Rules 11723-------------------------------------- 11724 11725With ancient versions of Sun `make', any assignment to `VPATH' causes 11726`make' to execute only the first set of double-colon rules. However, 11727this problem is no longer of practical concern. 11728 11729 11730File: autoconf.info, Node: $< in Explicit Rules, Next: Automatic Rule Rewriting, Prev: VPATH and Double-colon, Up: VPATH and Make 11731 1173211.13.2 `$<' Not Supported in Explicit Rules 11733-------------------------------------------- 11734 11735Using `$<' in explicit rules is not portable. The prerequisite file 11736must be named explicitly in the rule. If you want to find the 11737prerequisite via a `VPATH' search, you have to code the whole thing 11738manually. *Note Build Directories::. 11739 11740 11741File: autoconf.info, Node: Automatic Rule Rewriting, Next: Tru64 Directory Magic, Prev: $< in Explicit Rules, Up: VPATH and Make 11742 1174311.13.3 Automatic Rule Rewriting 11744-------------------------------- 11745 11746Some `make' implementations, such as Solaris and Tru64, search for 11747prerequisites in `VPATH' and then rewrite each occurrence as a plain 11748word in the rule. For instance: 11749 11750 # This isn't portable to GNU make. 11751 VPATH = ../pkg/src 11752 f.c: if.c 11753 cp if.c f.c 11754 11755executes `cp ../pkg/src/if.c f.c' if `if.c' is found in `../pkg/src'. 11756 11757 However, this rule leads to real problems in practice. For example, 11758if the source directory contains an ordinary file named `test' that is 11759used in a dependency, Solaris `make' rewrites commands like `if test -r 11760foo; ...' to `if ../pkg/src/test -r foo; ...', which is typically 11761undesirable. To avoid this problem, portable makefiles should never 11762mention a source file whose name is that of a shell keyword like 11763`until' or a shell command like `cat' or `gcc' or `test'. 11764 11765 Because of these problems GNU `make' and many other `make' 11766implementations do not rewrite commands, so portable makefiles should 11767search `VPATH' manually. It is tempting to write this: 11768 11769 # This isn't portable to Solaris make. 11770 VPATH = ../pkg/src 11771 f.c: if.c 11772 cp `test -f if.c || echo $(VPATH)/`if.c f.c 11773 11774However, the "prerequisite rewriting" still applies here. So if `if.c' 11775is in `../pkg/src', Solaris and Tru64 `make' execute 11776 11777 cp `test -f ../pkg/src/if.c || echo ../pkg/src/`if.c f.c 11778 11779which reduces to 11780 11781 cp if.c f.c 11782 11783and thus fails. Oops. 11784 11785 A simple workaround, and good practice anyway, is to use `$?' and 11786`$@' when possible: 11787 11788 VPATH = ../pkg/src 11789 f.c: if.c 11790 cp $? $@ 11791 11792but this does not generalize well to commands with multiple 11793prerequisites. A more general workaround is to rewrite the rule so that 11794the prerequisite `if.c' never appears as a plain word. For example, 11795these three rules would be safe, assuming `if.c' is in `../pkg/src' and 11796the other files are in the working directory: 11797 11798 VPATH = ../pkg/src 11799 f.c: if.c f1.c 11800 cat `test -f ./if.c || echo $(VPATH)/`if.c f1.c >$@ 11801 g.c: if.c g1.c 11802 cat `test -f 'if.c' || echo $(VPATH)/`if.c g1.c >$@ 11803 h.c: if.c h1.c 11804 cat `test -f "if.c" || echo $(VPATH)/`if.c h1.c >$@ 11805 11806 Things get worse when your prerequisites are in a macro. 11807 11808 VPATH = ../pkg/src 11809 HEADERS = f.h g.h h.h 11810 install-HEADERS: $(HEADERS) 11811 for i in $(HEADERS); do \ 11812 $(INSTALL) -m 644 \ 11813 `test -f $$i || echo $(VPATH)/`$$i \ 11814 $(DESTDIR)$(includedir)/$$i; \ 11815 done 11816 11817 The above `install-HEADERS' rule is not Solaris-proof because `for i 11818in $(HEADERS);' is expanded to `for i in f.h g.h h.h;' where `f.h' and 11819`g.h' are plain words and are hence subject to `VPATH' adjustments. 11820 11821 If the three files are in `../pkg/src', the rule is run as: 11822 11823 for i in ../pkg/src/f.h ../pkg/src/g.h h.h; do \ 11824 install -m 644 \ 11825 `test -f $i || echo ../pkg/src/`$i \ 11826 /usr/local/include/$i; \ 11827 done 11828 11829 where the two first `install' calls fail. For instance, consider 11830the `f.h' installation: 11831 11832 install -m 644 \ 11833 `test -f ../pkg/src/f.h || \ 11834 echo ../pkg/src/ \ 11835 `../pkg/src/f.h \ 11836 /usr/local/include/../pkg/src/f.h; 11837 11838It reduces to: 11839 11840 install -m 644 \ 11841 ../pkg/src/f.h \ 11842 /usr/local/include/../pkg/src/f.h; 11843 11844 Note that the manual `VPATH' search did not cause any problems here; 11845however this command installs `f.h' in an incorrect directory. 11846 11847 Trying to quote `$(HEADERS)' in some way, as we did for `foo.c' a 11848few makefiles ago, does not help: 11849 11850 install-HEADERS: $(HEADERS) 11851 headers='$(HEADERS)'; \ 11852 for i in $$headers; do \ 11853 $(INSTALL) -m 644 \ 11854 `test -f $$i || echo $(VPATH)/`$$i \ 11855 $(DESTDIR)$(includedir)/$$i; \ 11856 done 11857 11858 Now, `headers='$(HEADERS)'' macroexpands to: 11859 11860 headers='f.h g.h h.h' 11861 11862but `g.h' is still a plain word. (As an aside, the idiom 11863`headers='$(HEADERS)'; for i in $$headers;' is a good idea if 11864`$(HEADERS)' can be empty, because some shells diagnose a syntax error 11865on `for i in;'.) 11866 11867 One workaround is to strip this unwanted `../pkg/src/' prefix 11868manually: 11869 11870 VPATH = ../pkg/src 11871 HEADERS = f.h g.h h.h 11872 install-HEADERS: $(HEADERS) 11873 headers='$(HEADERS)'; \ 11874 for i in $$headers; do \ 11875 i=`expr "$$i" : '$(VPATH)/\(.*\)'`; 11876 $(INSTALL) -m 644 \ 11877 `test -f $$i || echo $(VPATH)/`$$i \ 11878 $(DESTDIR)$(includedir)/$$i; \ 11879 done 11880 11881 Automake does something similar. However the above hack works only 11882if the files listed in `HEADERS' are in the current directory or a 11883subdirectory; they should not be in an enclosing directory. If we had 11884`HEADERS = ../f.h', the above fragment would fail in a VPATH build with 11885Tru64 `make'. The reason is that not only does Tru64 `make' rewrite 11886dependencies, but it also simplifies them. Hence `../f.h' becomes 11887`../pkg/f.h' instead of `../pkg/src/../f.h'. This obviously defeats 11888any attempt to strip a leading `../pkg/src/' component. 11889 11890 The following example makes the behavior of Tru64 `make' more 11891apparent. 11892 11893 $ cat Makefile 11894 VPATH = sub 11895 all: ../foo 11896 echo ../foo 11897 $ ls 11898 Makefile foo 11899 $ make 11900 echo foo 11901 foo 11902 11903Dependency `../foo' was found in `sub/../foo', but Tru64 `make' 11904simplified it as `foo'. (Note that the `sub/' directory does not even 11905exist, this just means that the simplification occurred before the file 11906was checked for.) 11907 11908 For the record here is how SunOS 4 `make' behaves on this example. 11909 11910 $ make 11911 make: Fatal error: Don't know how to make target `../foo' 11912 $ mkdir sub 11913 $ make 11914 echo sub/../foo 11915 sub/../foo 11916 11917 11918File: autoconf.info, Node: Tru64 Directory Magic, Next: Make Target Lookup, Prev: Automatic Rule Rewriting, Up: VPATH and Make 11919 1192011.13.4 Tru64 `make' Creates Prerequisite Directories Magically 11921--------------------------------------------------------------- 11922 11923When a prerequisite is a subdirectory of `VPATH', Tru64 `make' creates 11924it in the current directory. 11925 11926 $ mkdir -p foo/bar build 11927 $ cd build 11928 $ cat >Makefile <<END 11929 VPATH = .. 11930 all: foo/bar 11931 END 11932 $ make 11933 mkdir foo 11934 mkdir foo/bar 11935 11936 This can yield unexpected results if a rule uses a manual `VPATH' 11937search as presented before. 11938 11939 VPATH = .. 11940 all : foo/bar 11941 command `test -d foo/bar || echo ../`foo/bar 11942 11943 The above `command' is run on the empty `foo/bar' directory that was 11944created in the current directory. 11945 11946 11947File: autoconf.info, Node: Make Target Lookup, Prev: Tru64 Directory Magic, Up: VPATH and Make 11948 1194911.13.5 Make Target Lookup 11950-------------------------- 11951 11952GNU `make' uses a complex algorithm to decide when it should use files 11953found via a `VPATH' search. *Note How Directory Searches are 11954Performed: (make)Search Algorithm. 11955 11956 If a target needs to be rebuilt, GNU `make' discards the file name 11957found during the `VPATH' search for this target, and builds the file 11958locally using the file name given in the makefile. If a target does 11959not need to be rebuilt, GNU `make' uses the file name found during the 11960`VPATH' search. 11961 11962 Other `make' implementations, like NetBSD `make', are easier to 11963describe: the file name found during the `VPATH' search is used whether 11964the target needs to be rebuilt or not. Therefore new files are created 11965locally, but existing files are updated at their `VPATH' location. 11966 11967 OpenBSD and FreeBSD `make', however, never perform a `VPATH' search 11968for a dependency that has an explicit rule. This is extremely annoying. 11969 11970 When attempting a `VPATH' build for an autoconfiscated package 11971(e.g., `mkdir build && cd build && ../configure'), this means GNU 11972`make' builds everything locally in the `build' directory, while BSD 11973`make' builds new files locally and updates existing files in the 11974source directory. 11975 11976 $ cat Makefile 11977 VPATH = .. 11978 all: foo.x bar.x 11979 foo.x bar.x: newer.x 11980 @echo Building $@ 11981 $ touch ../bar.x 11982 $ touch ../newer.x 11983 $ make # GNU make 11984 Building foo.x 11985 Building bar.x 11986 $ pmake # NetBSD make 11987 Building foo.x 11988 Building ../bar.x 11989 $ fmake # FreeBSD make, OpenBSD make 11990 Building foo.x 11991 Building bar.x 11992 $ tmake # Tru64 make 11993 Building foo.x 11994 Building bar.x 11995 $ touch ../bar.x 11996 $ make # GNU make 11997 Building foo.x 11998 $ pmake # NetBSD make 11999 Building foo.x 12000 $ fmake # FreeBSD make, OpenBSD make 12001 Building foo.x 12002 Building bar.x 12003 $ tmake # Tru64 make 12004 Building foo.x 12005 Building bar.x 12006 12007 Note how NetBSD `make' updates `../bar.x' in its VPATH location, and 12008how FreeBSD, OpenBSD, and Tru64 `make' always update `bar.x', even when 12009`../bar.x' is up to date. 12010 12011 Another point worth mentioning is that once GNU `make' has decided 12012to ignore a `VPATH' file name (e.g., it ignored `../bar.x' in the above 12013example) it continues to ignore it when the target occurs as a 12014prerequisite of another rule. 12015 12016 The following example shows that GNU `make' does not look up `bar.x' 12017in `VPATH' before performing the `.x.y' rule, because it ignored the 12018`VPATH' result of `bar.x' while running the `bar.x: newer.x' rule. 12019 12020 $ cat Makefile 12021 VPATH = .. 12022 all: bar.y 12023 bar.x: newer.x 12024 @echo Building $@ 12025 .SUFFIXES: .x .y 12026 .x.y: 12027 cp $< $@ 12028 $ touch ../bar.x 12029 $ touch ../newer.x 12030 $ make # GNU make 12031 Building bar.x 12032 cp bar.x bar.y 12033 cp: cannot stat `bar.x': No such file or directory 12034 make: *** [bar.y] Error 1 12035 $ pmake # NetBSD make 12036 Building ../bar.x 12037 cp ../bar.x bar.y 12038 $ rm bar.y 12039 $ fmake # FreeBSD make, OpenBSD make 12040 echo Building bar.x 12041 cp bar.x bar.y 12042 cp: cannot stat `bar.x': No such file or directory 12043 *** Error code 1 12044 $ tmake # Tru64 make 12045 Building bar.x 12046 cp: bar.x: No such file or directory 12047 *** Exit 1 12048 12049 Note that if you drop away the command from the `bar.x: newer.x' 12050rule, GNU `make' magically starts to work: it knows that `bar.x' hasn't 12051been updated, therefore it doesn't discard the result from `VPATH' 12052(`../bar.x') in succeeding uses. Tru64 also works, but FreeBSD and 12053OpenBSD still don't. 12054 12055 $ cat Makefile 12056 VPATH = .. 12057 all: bar.y 12058 bar.x: newer.x 12059 .SUFFIXES: .x .y 12060 .x.y: 12061 cp $< $@ 12062 $ touch ../bar.x 12063 $ touch ../newer.x 12064 $ make # GNU make 12065 cp ../bar.x bar.y 12066 $ rm bar.y 12067 $ pmake # NetBSD make 12068 cp ../bar.x bar.y 12069 $ rm bar.y 12070 $ fmake # FreeBSD make, OpenBSD make 12071 cp bar.x bar.y 12072 cp: cannot stat `bar.x': No such file or directory 12073 *** Error code 1 12074 $ tmake # Tru64 make 12075 cp ../bar.x bar.y 12076 12077 It seems the sole solution that would please every `make' 12078implementation is to never rely on `VPATH' searches for targets. In 12079other words, `VPATH' should be reserved to unbuilt sources. 12080 12081 12082File: autoconf.info, Node: Single Suffix Rules, Next: Timestamps and Make, Prev: VPATH and Make, Up: Portable Make 12083 1208411.14 Single Suffix Rules and Separated Dependencies 12085==================================================== 12086 12087A "Single Suffix Rule" is basically a usual suffix (inference) rule 12088(`.from.to:'), but which _destination_ suffix is empty (`.from:'). 12089 12090 "Separated dependencies" simply refers to listing the prerequisite 12091of a target, without defining a rule. Usually one can list on the one 12092hand side, the rules, and on the other hand side, the dependencies. 12093 12094 Solaris `make' does not support separated dependencies for targets 12095defined by single suffix rules: 12096 12097 $ cat Makefile 12098 .SUFFIXES: .in 12099 foo: foo.in 12100 .in: 12101 cp $< $@ 12102 $ touch foo.in 12103 $ make 12104 $ ls 12105 Makefile foo.in 12106 12107while GNU Make does: 12108 12109 $ gmake 12110 cp foo.in foo 12111 $ ls 12112 Makefile foo foo.in 12113 12114 Note it works without the `foo: foo.in' dependency. 12115 12116 $ cat Makefile 12117 .SUFFIXES: .in 12118 .in: 12119 cp $< $@ 12120 $ make foo 12121 cp foo.in foo 12122 12123and it works with double suffix inference rules: 12124 12125 $ cat Makefile 12126 foo.out: foo.in 12127 .SUFFIXES: .in .out 12128 .in.out: 12129 cp $< $@ 12130 $ make 12131 cp foo.in foo.out 12132 12133 As a result, in such a case, you have to write target rules. 12134 12135 12136File: autoconf.info, Node: Timestamps and Make, Prev: Single Suffix Rules, Up: Portable Make 12137 1213811.15 Timestamp Resolution and Make 12139=================================== 12140 12141Traditionally, file timestamps had 1-second resolution, and `make' used 12142those timestamps to determine whether one file was newer than the 12143other. However, many modern file systems have timestamps with 121441-nanosecond resolution. Some `make' implementations look at the 12145entire timestamp; others ignore the fractional part, which can lead to 12146incorrect results. Normally this is not a problem, but in some extreme 12147cases you may need to use tricks like `sleep 1' to work around 12148timestamp truncation bugs. 12149 12150 Commands like `cp -p' and `touch -r' typically do not copy file 12151timestamps to their full resolutions (*note Limitations of Usual 12152Tools::). Hence you should be wary of rules like this: 12153 12154 dest: src 12155 cp -p src dest 12156 12157 as `dest' often appears to be older than `src' after the timestamp 12158is truncated, and this can cause `make' to do needless rework the next 12159time it is invoked. To work around this problem, you can use a 12160timestamp file, e.g.: 12161 12162 dest-stamp: src 12163 cp -p src dest 12164 date >dest-stamp 12165 12166 12167File: autoconf.info, Node: Portable C and C++, Next: Manual Configuration, Prev: Portable Make, Up: Top 12168 1216912 Portable C and C++ Programming 12170********************************* 12171 12172C and C++ programs often use low-level features of the underlying 12173system, and therefore are often more difficult to make portable to other 12174platforms. 12175 12176 Several standards have been developed to help make your programs more 12177portable. If you write programs with these standards in mind, you can 12178have greater confidence that your programs work on a wide variety of 12179systems. *Note Language Standards Supported by GCC: (gcc)Standards, 12180for a list of C-related standards. Many programs also assume the Posix 12181standard (http://www.opengroup.org/susv3). 12182 12183 Some old code is written to be portable to K&R C, which predates any 12184C standard. K&R C compilers are no longer of practical interest, 12185though, and the rest of section assumes at least C89, the first C 12186standard. 12187 12188 Program portability is a huge topic, and this section can only 12189briefly introduce common pitfalls. *Note Portability between System 12190Types: (standards)System Portability, for more information. 12191 12192* Menu: 12193 12194* Varieties of Unportability:: How to make your programs unportable 12195* Integer Overflow:: When integers get too large 12196* Null Pointers:: Properties of null pointers 12197* Buffer Overruns:: Subscript errors and the like 12198* Volatile Objects:: `volatile' and signals 12199* Floating Point Portability:: Portable floating-point arithmetic 12200* Exiting Portably:: Exiting and the exit status 12201 12202 12203File: autoconf.info, Node: Varieties of Unportability, Next: Integer Overflow, Up: Portable C and C++ 12204 1220512.1 Varieties of Unportability 12206=============================== 12207 12208Autoconf tests and ordinary programs often need to test what is allowed 12209on a system, and therefore they may need to deliberately exceed the 12210boundaries of what the standards allow, if only to see whether an 12211optional feature is present. When you write such a program, you should 12212keep in mind the difference between constraints, unspecified behavior, 12213and undefined behavior. 12214 12215 In C, a "constraint" is a rule that the compiler must enforce. An 12216example constraint is that C programs must not declare a bit-field with 12217negative width. Tests can therefore reliably assume that programs with 12218negative-width bit-fields are rejected by a compiler that conforms to 12219the standard. 12220 12221 "Unspecified behavior" is valid behavior, where the standard allows 12222multiple possibilities. For example, the order of evaluation of 12223function arguments is unspecified. Some unspecified behavior is 12224"implementation-defined", i.e., documented by the implementation, but 12225since Autoconf tests cannot read the documentation they cannot 12226distinguish between implementation-defined and other unspecified 12227behavior. It is common for Autoconf tests to probe implementations to 12228determine otherwise-unspecified behavior. 12229 12230 "Undefined behavior" is invalid behavior, where the standard allows 12231the implementation to do anything it pleases. For example, 12232dereferencing a null pointer leads to undefined behavior. If possible, 12233test programs should avoid undefined behavior, since a program with 12234undefined behavior might succeed on a test that should fail. 12235 12236 The above rules apply to programs that are intended to conform to the 12237standard. However, strictly-conforming programs are quite rare, since 12238the standards are so limiting. A major goal of Autoconf is to support 12239programs that use implementation features not described by the standard, 12240and it is fairly common for test programs to violate the above rules, if 12241the programs work well enough in practice. 12242 12243 12244File: autoconf.info, Node: Integer Overflow, Next: Null Pointers, Prev: Varieties of Unportability, Up: Portable C and C++ 12245 1224612.2 Integer Overflow 12247===================== 12248 12249In C, signed integer overflow leads to undefined behavior. However, 12250many programs and Autoconf tests assume that signed integer overflow 12251after addition, subtraction, or multiplication silently wraps around 12252modulo a power of two, using two's complement arithmetic, so long as 12253you cast the resulting value to an integer type or store it into an 12254integer variable. Such programs are portable to the vast majority of 12255modern platforms. However, signed integer division is not always 12256harmless: for example, on CPUs of the i386 family, dividing `INT_MIN' 12257by `-1' yields a SIGFPE signal which by default terminates the program. 12258Worse, taking the remainder of these two values typically yields the 12259same signal on these CPUs, even though the C standard requires `INT_MIN 12260% -1' to yield zero because the expression does not overflow. 12261 12262 GCC users might consider using the `-ftrapv' option if they are 12263worried about porting their code to the rare platforms where signed 12264integer overflow does not wrap around after addition, subtraction, or 12265multiplication. 12266 12267 Unsigned integer overflow reliably wraps around modulo the word size. 12268This is guaranteed by the C standard and is portable in practice. 12269 12270 12271File: autoconf.info, Node: Null Pointers, Next: Buffer Overruns, Prev: Integer Overflow, Up: Portable C and C++ 12272 1227312.3 Properties of Null Pointers 12274================================ 12275 12276Most modern hosts reliably fail when you attempt to dereference a null 12277pointer. 12278 12279 On almost all modern hosts, null pointers use an all-bits-zero 12280internal representation, so you can reliably use `memset' with 0 to set 12281all the pointers in an array to null values. 12282 12283 If `p' is a null pointer to an object type, the C expression `p + 0' 12284always evaluates to `p' on modern hosts, even though the standard says 12285that it has undefined behavior. 12286 12287 12288File: autoconf.info, Node: Buffer Overruns, Next: Volatile Objects, Prev: Null Pointers, Up: Portable C and C++ 12289 1229012.4 Buffer Overruns and Subscript Errors 12291========================================= 12292 12293Buffer overruns and subscript errors are the most common dangerous 12294errors in C programs. They result in undefined behavior because storing 12295outside an array typically modifies storage that is used by some other 12296object, and most modern systems lack runtime checks to catch these 12297errors. Programs should not rely on buffer overruns being caught. 12298 12299 There is one exception to the usual rule that a portable program 12300cannot address outside an array. In C, it is valid to compute the 12301address just past an object, e.g., `&a[N]' where `a' has `N' elements, 12302so long as you do not dereference the resulting pointer. But it is not 12303valid to compute the address just before an object, e.g., `&a[-1]'; nor 12304is it valid to compute two past the end, e.g., `&a[N+1]'. On most 12305platforms `&a[-1] < &a[0] && &a[N] < &a[N+1]', but this is not reliable 12306in general, and it is usually easy enough to avoid the potential 12307portability problem, e.g., by allocating an extra unused array element 12308at the start or end. 12309 12310 Valgrind (http://valgrind.org/) can catch many overruns. GCC users 12311might also consider using the `-fmudflap' option to catch overruns. 12312 12313 Buffer overruns are usually caused by off-by-one errors, but there 12314are more subtle ways to get them. 12315 12316 Using `int' values to index into an array or compute array sizes 12317causes problems on typical 64-bit hosts where an array index might be 123182^31 or larger. Index values of type `size_t' avoid this problem, but 12319cannot be negative. Index values of type `ptrdiff_t' are signed, and 12320are wide enough in practice. 12321 12322 If you add or multiply two numbers to calculate an array size, e.g., 12323`malloc (x * sizeof y + z)', havoc ensues if the addition or 12324multiplication overflows. 12325 12326 Many implementations of the `alloca' function silently misbehave and 12327can generate buffer overflows if given sizes that are too large. The 12328size limits are implementation dependent, but are at least 4000 bytes 12329on all platforms that we know about. 12330 12331 The standard functions `asctime', `asctime_r', `ctime', `ctime_r', 12332and `gets' are prone to buffer overflows, and portable code should not 12333use them unless the inputs are known to be within certain limits. The 12334time-related functions can overflow their buffers if given timestamps 12335out of range (e.g., a year less than -999 or greater than 9999). 12336Time-related buffer overflows cannot happen with recent-enough versions 12337of the GNU C library, but are possible with other implementations. The 12338`gets' function is the worst, since it almost invariably overflows its 12339buffer when presented with an input line larger than the buffer. 12340 12341 12342File: autoconf.info, Node: Volatile Objects, Next: Floating Point Portability, Prev: Buffer Overruns, Up: Portable C and C++ 12343 1234412.5 Volatile Objects 12345===================== 12346 12347The keyword `volatile' is often misunderstood in portable code. Its 12348use inhibits some memory-access optimizations, but programmers often 12349wish that it had a different meaning than it actually does. 12350 12351 `volatile' was designed for code that accesses special objects like 12352memory-mapped device registers whose contents spontaneously change. 12353Such code is inherently low-level, and it is difficult to specify 12354portably what `volatile' means in these cases. The C standard says, 12355"What constitutes an access to an object that has volatile-qualified 12356type is implementation-defined," so in theory each implementation is 12357supposed to fill in the gap by documenting what `volatile' means for 12358that implementation. In practice, though, this documentation is 12359usually absent or incomplete. 12360 12361 One area of confusion is the distinction between objects defined with 12362volatile types, and volatile lvalues. From the C standard's point of 12363view, an object defined with a volatile type has externally visible 12364behavior. You can think of such objects as having little oscilloscope 12365probes attached to them, so that the user can observe some properties of 12366accesses to them, just as the user can observe data written to output 12367files. However, the standard does not make it clear whether users can 12368observe accesses by volatile lvalues to ordinary objects. For example: 12369 12370 /* Declare and access a volatile object. 12371 Accesses to X are "visible" to users. */ 12372 static int volatile x; 12373 x = 1; 12374 12375 /* Access two ordinary objects via a volatile lvalue. 12376 It's not clear whether accesses to *P are "visible". */ 12377 int y; 12378 int *z = malloc (sizeof (int)); 12379 int volatile *p; 12380 p = &y; 12381 *p = 1; 12382 p = z; 12383 *p = 1; 12384 12385 Programmers often wish that `volatile' meant "Perform the memory 12386access here and now, without merging several memory accesses, without 12387changing the memory word size, and without reordering." But the C 12388standard does not require this. For objects defined with a volatile 12389type, accesses must be done before the next sequence point; but 12390otherwise merging, reordering, and word-size change is allowed. Worse, 12391it is not clear from the standard whether volatile lvalues provide more 12392guarantees in general than nonvolatile lvalues, if the underlying 12393objects are ordinary. 12394 12395 Even when accessing objects defined with a volatile type, the C 12396standard allows only extremely limited signal handlers: the behavior is 12397undefined if a signal handler reads any nonlocal object, or writes to 12398any nonlocal object whose type is not `sig_atomic_t volatile', or calls 12399any standard library function other than `abort', `signal', and (if C99) 12400`_Exit'. Hence C compilers need not worry about a signal handler 12401disturbing ordinary computation, unless the computation accesses a 12402`sig_atomic_t volatile' lvalue that is not a local variable. (There is 12403an obscure exception for accesses via a pointer to a volatile 12404character, since it may point into part of a `sig_atomic_t volatile' 12405object.) Posix adds to the list of library functions callable from a 12406portable signal handler, but otherwise is like the C standard in this 12407area. 12408 12409 Some C implementations allow memory-access optimizations within each 12410translation unit, such that actual behavior agrees with the behavior 12411required by the standard only when calling a function in some other 12412translation unit, and a signal handler acts like it was called from a 12413different translation unit. The C standard hints that in these 12414implementations, objects referred to by signal handlers "would require 12415explicit specification of `volatile' storage, as well as other 12416implementation-defined restrictions." But unfortunately even for this 12417special case these other restrictions are often not documented well. 12418*Note When is a Volatile Object Accessed?: (gcc)Volatiles, for some 12419restrictions imposed by GCC. *Note Defining Signal Handlers: 12420(libc)Defining Handlers, for some restrictions imposed by the GNU C 12421library. Restrictions differ on other platforms. 12422 12423 If possible, it is best to use a signal handler that fits within the 12424limits imposed by the C and Posix standards. 12425 12426 If this is not practical, you can try the following rules of thumb. 12427A signal handler should access only volatile lvalues, preferably lvalues 12428that refer to objects defined with a volatile type, and should not 12429assume that the accessed objects have an internally consistent state if 12430they are larger than a machine word. Furthermore, installers should 12431employ compilers and compiler options that are commonly used for 12432building operating system kernels, because kernels often need more from 12433`volatile' than the C Standard requires, and installers who compile an 12434application in a similar environment can sometimes benefit from the 12435extra constraints imposed by kernels on compilers. Admittedly we are 12436handwaving somewhat here, as there are few guarantees in this area; the 12437rules of thumb may help to fix some bugs but there is a good chance 12438that they will not fix them all. 12439 12440 For `volatile', C++ has the same problems that C does. 12441Multithreaded applications have even more problems with `volatile', but 12442they are beyond the scope of this section. 12443 12444 The bottom line is that using `volatile' typically hurts performance 12445but should not hurt correctness. In some cases its use does help 12446correctness, but these cases are often so poorly understood that all 12447too often adding `volatile' to a data structure merely alleviates some 12448symptoms of a bug while not fixing the bug in general. 12449 12450 12451File: autoconf.info, Node: Floating Point Portability, Next: Exiting Portably, Prev: Volatile Objects, Up: Portable C and C++ 12452 1245312.6 Floating Point Portability 12454=============================== 12455 12456Almost all modern systems use IEEE-754 floating point, and it is safe to 12457assume IEEE-754 in most portable code these days. For more information, 12458please see David Goldberg's classic paper What Every Computer Scientist 12459Should Know About Floating-Point Arithmetic 12460(http://www.validlab.com/goldberg/paper.pdf). 12461 12462 12463File: autoconf.info, Node: Exiting Portably, Prev: Floating Point Portability, Up: Portable C and C++ 12464 1246512.7 Exiting Portably 12466===================== 12467 12468A C or C++ program can exit with status N by returning N from the 12469`main' function. Portable programs are supposed to exit either with 12470status 0 or `EXIT_SUCCESS' to succeed, or with status `EXIT_FAILURE' to 12471fail, but in practice it is portable to fail by exiting with status 1, 12472and test programs that assume Posix can fail by exiting with status 12473values from 1 through 255. Programs on SunOS 2.0 (1985) through 3.5.2 12474(1988) incorrectly exited with zero status when `main' returned 12475nonzero, but ancient systems like these are no longer of practical 12476concern. 12477 12478 A program can also exit with status N by passing N to the `exit' 12479function, and a program can fail by calling the `abort' function. If a 12480program is specialized to just some platforms, it can fail by calling 12481functions specific to those platforms, e.g., `_exit' (Posix) and 12482`_Exit' (C99). However, like other functions, an exit function should 12483be declared, typically by including a header. For example, if a C 12484program calls `exit', it should include `stdlib.h' either directly or 12485via the default includes (*note Default Includes::). 12486 12487 A program can fail due to undefined behavior such as dereferencing a 12488null pointer, but this is not recommended as undefined behavior allows 12489an implementation to do whatever it pleases and this includes exiting 12490successfully. 12491 12492 12493File: autoconf.info, Node: Manual Configuration, Next: Site Configuration, Prev: Portable C and C++, Up: Top 12494 1249513 Manual Configuration 12496*********************** 12497 12498A few kinds of features can't be guessed automatically by running test 12499programs. For example, the details of the object-file format, or 12500special options that need to be passed to the compiler or linker. You 12501can check for such features using ad-hoc means, such as having 12502`configure' check the output of the `uname' program, or looking for 12503libraries that are unique to particular systems. However, Autoconf 12504provides a uniform method for handling unguessable features. 12505 12506* Menu: 12507 12508* Specifying Names:: Specifying the system type 12509* Canonicalizing:: Getting the canonical system type 12510* Using System Type:: What to do with the system type 12511 12512 12513File: autoconf.info, Node: Specifying Names, Next: Canonicalizing, Up: Manual Configuration 12514 1251513.1 Specifying the System Type 12516=============================== 12517 12518Like other GNU `configure' scripts, Autoconf-generated `configure' 12519scripts can make decisions based on a canonical name for the system 12520type, which has the form: `CPU-VENDOR-OS', where OS can be `SYSTEM' or 12521`KERNEL-SYSTEM' 12522 12523 `configure' can usually guess the canonical name for the type of 12524system it's running on. To do so it runs a script called 12525`config.guess', which infers the name using the `uname' command or 12526symbols predefined by the C preprocessor. 12527 12528 Alternately, the user can specify the system type with command line 12529arguments to `configure'. Doing so is necessary when cross-compiling. 12530In the most complex case of cross-compiling, three system types are 12531involved. The options to specify them are: 12532 12533`--build=BUILD-TYPE' 12534 the type of system on which the package is being configured and 12535 compiled. It defaults to the result of running `config.guess'. 12536 12537`--host=HOST-TYPE' 12538 the type of system on which the package runs. By default it is the 12539 same as the build machine. Specifying it enables the 12540 cross-compilation mode. 12541 12542`--target=TARGET-TYPE' 12543 the type of system for which any compiler tools in the package 12544 produce code (rarely needed). By default, it is the same as host. 12545 12546 If you mean to override the result of `config.guess', use `--build', 12547not `--host', since the latter enables cross-compilation. For 12548historical reasons, passing `--host' also changes the build type. 12549Therefore, whenever you specify `--host', be sure to specify `--build' 12550too; this will be fixed in the future. So, to enter cross-compilation 12551mode, use a command like this 12552 12553 ./configure --build=i686-pc-linux-gnu --host=m68k-coff 12554 12555Note that if you do not specify `--host', `configure' fails if it can't 12556run the code generated by the specified compiler. For example, 12557configuring as follows fails: 12558 12559 ./configure CC=m68k-coff-gcc 12560 12561 In the future, when cross-compiling Autoconf will _not_ accept tools 12562(compilers, linkers, assemblers) whose name is not prefixed with the 12563host type. The only case when this may be useful is when you really 12564are not cross-compiling, but only building for a 12565least-common-denominator architecture: an example is building for 12566`i386-pc-linux-gnu' while running on an `i686-pc-linux-gnu' 12567architecture. In this case, some particular pairs might be similar 12568enough to let you get away with the system compilers, but in general 12569the compiler might make bogus assumptions on the host: if you know what 12570you are doing, please create symbolic links from the host compiler to 12571the build compiler. 12572 12573 `configure' recognizes short aliases for many system types; for 12574example, `decstation' can be used instead of `mips-dec-ultrix4.2'. 12575`configure' runs a script called `config.sub' to canonicalize system 12576type aliases. 12577 12578 This section deliberately omits the description of the obsolete 12579interface; see *Note Hosts and Cross-Compilation::. 12580 12581 12582File: autoconf.info, Node: Canonicalizing, Next: Using System Type, Prev: Specifying Names, Up: Manual Configuration 12583 1258413.2 Getting the Canonical System Type 12585====================================== 12586 12587The following macros make the system type available to `configure' 12588scripts. 12589 12590 The variables `build_alias', `host_alias', and `target_alias' are 12591always exactly the arguments of `--build', `--host', and `--target'; in 12592particular, they are left empty if the user did not use them, even if 12593the corresponding `AC_CANONICAL' macro was run. Any configure script 12594may use these variables anywhere. These are the variables that should 12595be used when in interaction with the user. 12596 12597 If you need to recognize some special environments based on their 12598system type, run the following macros to get canonical system names. 12599These variables are not set before the macro call. 12600 12601 If you use these macros, you must distribute `config.guess' and 12602`config.sub' along with your source code. *Note Output::, for 12603information about the `AC_CONFIG_AUX_DIR' macro which you can use to 12604control in which directory `configure' looks for those scripts. 12605 12606 -- Macro: AC_CANONICAL_BUILD 12607 Compute the canonical build-system type variable, `build', and its 12608 three individual parts `build_cpu', `build_vendor', and `build_os'. 12609 12610 If `--build' was specified, then `build' is the canonicalization 12611 of `build_alias' by `config.sub', otherwise it is determined by 12612 the shell script `config.guess'. 12613 12614 -- Macro: AC_CANONICAL_HOST 12615 Compute the canonical host-system type variable, `host', and its 12616 three individual parts `host_cpu', `host_vendor', and `host_os'. 12617 12618 If `--host' was specified, then `host' is the canonicalization of 12619 `host_alias' by `config.sub', otherwise it defaults to `build'. 12620 12621 -- Macro: AC_CANONICAL_TARGET 12622 Compute the canonical target-system type variable, `target', and 12623 its three individual parts `target_cpu', `target_vendor', and 12624 `target_os'. 12625 12626 If `--target' was specified, then `target' is the canonicalization 12627 of `target_alias' by `config.sub', otherwise it defaults to `host'. 12628 12629 Note that there can be artifacts due to the backward compatibility 12630code. See *Note Hosts and Cross-Compilation::, for more. 12631 12632 12633File: autoconf.info, Node: Using System Type, Prev: Canonicalizing, Up: Manual Configuration 12634 1263513.3 Using the System Type 12636========================== 12637 12638In `configure.ac' the system type is generally used by one or more 12639`case' statements to select system-specifics. Shell wildcards can be 12640used to match a group of system types. 12641 12642 For example, an extra assembler code object file could be chosen, 12643giving access to a CPU cycle counter register. `$(CYCLE_OBJ)' in the 12644following would be used in a makefile to add the object to a program or 12645library. 12646 12647 case $host in 12648 alpha*-*-*) CYCLE_OBJ=rpcc.o ;; 12649 i?86-*-*) CYCLE_OBJ=rdtsc.o ;; 12650 *) CYCLE_OBJ= ;; 12651 esac 12652 AC_SUBST([CYCLE_OBJ]) 12653 12654 `AC_CONFIG_LINKS' (*note Configuration Links::) is another good way 12655to select variant source files, for example optimized code for some 12656CPUs. The configured CPU type doesn't always indicate exact CPU types, 12657so some runtime capability checks may be necessary too. 12658 12659 case $host in 12660 alpha*-*-*) AC_CONFIG_LINKS([dither.c:alpha/dither.c]) ;; 12661 powerpc*-*-*) AC_CONFIG_LINKS([dither.c:powerpc/dither.c]) ;; 12662 *-*-*) AC_CONFIG_LINKS([dither.c:generic/dither.c]) ;; 12663 esac 12664 12665 The host system type can also be used to find cross-compilation tools 12666with `AC_CHECK_TOOL' (*note Generic Programs::). 12667 12668 The above examples all show `$host', since this is where the code is 12669going to run. Only rarely is it necessary to test `$build' (which is 12670where the build is being done). 12671 12672 Whenever you're tempted to use `$host' it's worth considering 12673whether some sort of probe would be better. New system types come along 12674periodically or previously missing features are added. Well-written 12675probes can adapt themselves to such things, but hard-coded lists of 12676names can't. Here are some guidelines, 12677 12678 * Availability of libraries and library functions should always be 12679 checked by probing. 12680 12681 * Variant behavior of system calls is best identified with runtime 12682 tests if possible, but bug workarounds or obscure difficulties 12683 might have to be driven from `$host'. 12684 12685 * Assembler code is inevitably highly CPU-specific and is best 12686 selected according to `$host_cpu'. 12687 12688 * Assembler variations like underscore prefix on globals or ELF 12689 versus COFF type directives are however best determined by 12690 probing, perhaps even examining the compiler output. 12691 12692 `$target' is for use by a package creating a compiler or similar. 12693For ordinary packages it's meaningless and should not be used. It 12694indicates what the created compiler should generate code for, if it can 12695cross-compile. `$target' generally selects various hard-coded CPU and 12696system conventions, since usually the compiler or tools under 12697construction themselves determine how the target works. 12698 12699 12700File: autoconf.info, Node: Site Configuration, Next: Running configure Scripts, Prev: Manual Configuration, Up: Top 12701 1270214 Site Configuration 12703********************* 12704 12705`configure' scripts support several kinds of local configuration 12706decisions. There are ways for users to specify where external software 12707packages are, include or exclude optional features, install programs 12708under modified names, and set default values for `configure' options. 12709 12710* Menu: 12711 12712* Help Formatting:: Customizing `configure --help' 12713* External Software:: Working with other optional software 12714* Package Options:: Selecting optional features 12715* Pretty Help Strings:: Formatting help string 12716* Site Details:: Configuring site details 12717* Transforming Names:: Changing program names when installing 12718* Site Defaults:: Giving `configure' local defaults 12719 12720 12721File: autoconf.info, Node: Help Formatting, Next: External Software, Up: Site Configuration 12722 1272314.1 Controlling Help Output 12724============================ 12725 12726Users consult `configure --help' to learn of configuration decisions 12727specific to your package. By default, `configure' breaks this output 12728into sections for each type of option; within each section, help 12729strings appear in the order `configure.ac' defines them: 12730 12731 Optional Features: 12732 ... 12733 --enable-bar include bar 12734 12735 Optional Packages: 12736 ... 12737 --with-foo use foo 12738 12739 -- Macro: AC_PRESERVE_HELP_ORDER 12740 Request an alternate `--help' format, in which options of all 12741 types appear together, in the order defined. Call this macro 12742 before any `AC_ARG_ENABLE' or `AC_ARG_WITH'. 12743 12744 Optional Features and Packages: 12745 ... 12746 --enable-bar include bar 12747 --with-foo use foo 12748 12749 12750 12751File: autoconf.info, Node: External Software, Next: Package Options, Prev: Help Formatting, Up: Site Configuration 12752 1275314.2 Working With External Software 12754=================================== 12755 12756Some packages require, or can optionally use, other software packages 12757that are already installed. The user can give `configure' command line 12758options to specify which such external software to use. The options 12759have one of these forms: 12760 12761 --with-PACKAGE[=ARG] 12762 --without-PACKAGE 12763 12764 For example, `--with-gnu-ld' means work with the GNU linker instead 12765of some other linker. `--with-x' means work with The X Window System. 12766 12767 The user can give an argument by following the package name with `=' 12768and the argument. Giving an argument of `no' is for packages that are 12769used by default; it says to _not_ use the package. An argument that is 12770neither `yes' nor `no' could include a name or number of a version of 12771the other package, to specify more precisely which other package this 12772program is supposed to work with. If no argument is given, it defaults 12773to `yes'. `--without-PACKAGE' is equivalent to `--with-PACKAGE=no'. 12774 12775 `configure' scripts do not complain about `--with-PACKAGE' options 12776that they do not support. This behavior permits configuring a source 12777tree containing multiple packages with a top-level `configure' script 12778when the packages support different options, without spurious error 12779messages about options that some of the packages support. An 12780unfortunate side effect is that option spelling errors are not 12781diagnosed. No better approach to this problem has been suggested so 12782far. 12783 12784 For each external software package that may be used, `configure.ac' 12785should call `AC_ARG_WITH' to detect whether the `configure' user asked 12786to use it. Whether each package is used or not by default, and which 12787arguments are valid, is up to you. 12788 12789 -- Macro: AC_ARG_WITH (PACKAGE, HELP-STRING, [ACTION-IF-GIVEN], 12790 [ACTION-IF-NOT-GIVEN]) 12791 If the user gave `configure' the option `--with-PACKAGE' or 12792 `--without-PACKAGE', run shell commands ACTION-IF-GIVEN. If 12793 neither option was given, run shell commands ACTION-IF-NOT-GIVEN. 12794 The name PACKAGE indicates another software package that this 12795 program should work with. It should consist only of alphanumeric 12796 characters, dashes, and dots. 12797 12798 The option's argument is available to the shell commands 12799 ACTION-IF-GIVEN in the shell variable `withval', which is actually 12800 just the value of the shell variable `with_PACKAGE', with any 12801 non-alphanumeric characters changed into `_'. You may use that 12802 variable instead, if you wish. 12803 12804 The argument HELP-STRING is a description of the option that looks 12805 like this: 12806 --with-readline support fancy command line editing 12807 12808 HELP-STRING may be more than one line long, if more detail is 12809 needed. Just make sure the columns line up in `configure --help'. 12810 Avoid tabs in the help string. You'll need to enclose the help 12811 string in `[' and `]' in order to produce the leading blanks. 12812 12813 You should format your HELP-STRING with the macro `AS_HELP_STRING' 12814 (*note Pretty Help Strings::). 12815 12816 The following example shows how to use the `AC_ARG_WITH' macro in 12817 a common situation. You want to let the user decide whether to 12818 enable support for an external library (e.g., the readline 12819 library); if the user specified neither `--with-readline' nor 12820 `--without-readline', you want to enable support for readline only 12821 if the library is available on the system. 12822 12823 AC_ARG_WITH([readline], 12824 [AS_HELP_STRING([--with-readline], 12825 [support fancy command line editing @<:@default=check@:>@])], 12826 [], 12827 [with_readline=check]) 12828 12829 LIBREADLINE= 12830 AS_IF([test "x$with_readline" != xno], 12831 [AC_CHECK_LIB([readline], [main], 12832 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"]) 12833 AC_DEFINE([HAVE_LIBREADLINE], [1], 12834 [Define if you have libreadline]) 12835 ], 12836 [if test "x$with_readline" != xcheck; then 12837 AC_MSG_FAILURE( 12838 [--with-readline was given, but test for readline failed]) 12839 fi 12840 ], -lncurses)]) 12841 12842 The next example shows how to use `AC_ARG_WITH' to give the user 12843 the possibility to enable support for the readline library, in 12844 case it is still experimental and not well tested, and is 12845 therefore disabled by default. 12846 12847 AC_ARG_WITH([readline], 12848 [AS_HELP_STRING([--with-readline], 12849 [enable experimental support for readline])], 12850 [], 12851 [with_readline=no]) 12852 12853 LIBREADLINE= 12854 AS_IF([test "x$with_readline" != xno], 12855 [AC_CHECK_LIB([readline], [main], 12856 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"]) 12857 AC_DEFINE([HAVE_LIBREADLINE], [1], 12858 [Define if you have libreadline]) 12859 ], 12860 [AC_MSG_FAILURE( 12861 [--with-readline was given, but test for readline failed])], 12862 [-lncurses])]) 12863 12864 The last example shows how to use `AC_ARG_WITH' to give the user 12865 the possibility to disable support for the readline library, given 12866 that it is an important feature and that it should be enabled by 12867 default. 12868 12869 AC_ARG_WITH([readline], 12870 [AS_HELP_STRING([--without-readline], 12871 [disable support for readline])], 12872 [], 12873 [with_readline=yes]) 12874 12875 LIBREADLINE= 12876 AS_IF([test "x$with_readline" != xno], 12877 [AC_CHECK_LIB([readline], [main], 12878 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"]) 12879 AC_DEFINE([HAVE_LIBREADLINE], [1], 12880 [Define if you have libreadline]) 12881 ], 12882 [AC_MSG_FAILURE( 12883 [readline test failed (--without-readline to disable)])], 12884 [-lncurses])]) 12885 12886 These three examples can be easily adapted to the case where 12887 `AC_ARG_ENABLE' should be preferred to `AC_ARG_WITH' (see *Note 12888 Package Options::). 12889 12890 -- Macro: AC_WITH (PACKAGE, ACTION-IF-GIVEN, [ACTION-IF-NOT-GIVEN]) 12891 This is an obsolete version of `AC_ARG_WITH' that does not support 12892 providing a help string. 12893 12894 12895File: autoconf.info, Node: Package Options, Next: Pretty Help Strings, Prev: External Software, Up: Site Configuration 12896 1289714.3 Choosing Package Options 12898============================= 12899 12900If a software package has optional compile-time features, the user can 12901give `configure' command line options to specify whether to compile 12902them. The options have one of these forms: 12903 12904 --enable-FEATURE[=ARG] 12905 --disable-FEATURE 12906 12907 These options allow users to choose which optional features to build 12908and install. `--enable-FEATURE' options should never make a feature 12909behave differently or cause one feature to replace another. They 12910should only cause parts of the program to be built rather than left out. 12911 12912 The user can give an argument by following the feature name with `=' 12913and the argument. Giving an argument of `no' requests that the feature 12914_not_ be made available. A feature with an argument looks like 12915`--enable-debug=stabs'. If no argument is given, it defaults to `yes'. 12916`--disable-FEATURE' is equivalent to `--enable-FEATURE=no'. 12917 12918 `configure' scripts do not complain about `--enable-FEATURE' options 12919that they do not support. This behavior permits configuring a source 12920tree containing multiple packages with a top-level `configure' script 12921when the packages support different options, without spurious error 12922messages about options that some of the packages support. An 12923unfortunate side effect is that option spelling errors are not 12924diagnosed. No better approach to this problem has been suggested so 12925far. 12926 12927 For each optional feature, `configure.ac' should call 12928`AC_ARG_ENABLE' to detect whether the `configure' user asked to include 12929it. Whether each feature is included or not by default, and which 12930arguments are valid, is up to you. 12931 12932 -- Macro: AC_ARG_ENABLE (FEATURE, HELP-STRING, [ACTION-IF-GIVEN], 12933 [ACTION-IF-NOT-GIVEN]) 12934 If the user gave `configure' the option `--enable-FEATURE' or 12935 `--disable-FEATURE', run shell commands ACTION-IF-GIVEN. If 12936 neither option was given, run shell commands ACTION-IF-NOT-GIVEN. 12937 The name FEATURE indicates an optional user-level facility. It 12938 should consist only of alphanumeric characters, dashes, and dots. 12939 12940 The option's argument is available to the shell commands 12941 ACTION-IF-GIVEN in the shell variable `enableval', which is 12942 actually just the value of the shell variable `enable_FEATURE', 12943 with any non-alphanumeric characters changed into `_'. You may 12944 use that variable instead, if you wish. The HELP-STRING argument 12945 is like that of `AC_ARG_WITH' (*note External Software::). 12946 12947 You should format your HELP-STRING with the macro `AS_HELP_STRING' 12948 (*note Pretty Help Strings::). 12949 12950 See the examples suggested with the definition of `AC_ARG_WITH' 12951 (*note External Software::) to get an idea of possible 12952 applications of `AC_ARG_ENABLE'. 12953 12954 -- Macro: AC_ENABLE (FEATURE, ACTION-IF-GIVEN, [ACTION-IF-NOT-GIVEN]) 12955 This is an obsolete version of `AC_ARG_ENABLE' that does not 12956 support providing a help string. 12957 12958 12959File: autoconf.info, Node: Pretty Help Strings, Next: Site Details, Prev: Package Options, Up: Site Configuration 12960 1296114.4 Making Your Help Strings Look Pretty 12962========================================= 12963 12964Properly formatting the `help strings' which are used in `AC_ARG_WITH' 12965(*note External Software::) and `AC_ARG_ENABLE' (*note Package 12966Options::) can be challenging. Specifically, you want your own `help 12967strings' to line up in the appropriate columns of `configure --help' 12968just like the standard Autoconf `help strings' do. This is the purpose 12969of the `AS_HELP_STRING' macro. 12970 12971 -- Macro: AS_HELP_STRING (LEFT-HAND-SIDE, RIGHT-HAND-SIDE) 12972 Expands into an help string that looks pretty when the user 12973 executes `configure --help'. It is typically used in `AC_ARG_WITH' 12974 (*note External Software::) or `AC_ARG_ENABLE' (*note Package 12975 Options::). The following example makes this clearer. 12976 12977 AC_ARG_WITH([foo], 12978 [AS_HELP_STRING([--with-foo], 12979 [use foo (default is no)])], 12980 [use_foo=$withval], 12981 [use_foo=no]) 12982 12983 The second argument of `AS_HELP_STRING' is not a literal, and 12984 should not be double quoted. *Note Autoconf Language::, for a 12985 more detailed explanation. Then the last few lines of `configure 12986 --help' appear like this: 12987 12988 --enable and --with options recognized: 12989 --with-foo use foo (default is no) 12990 12991 The `AS_HELP_STRING' macro is particularly helpful when the 12992 LEFT-HAND-SIDE and/or RIGHT-HAND-SIDE are composed of macro 12993 arguments, as shown in the following example. 12994 12995 AC_DEFUN([MY_ARG_WITH], 12996 [AC_ARG_WITH([$1], 12997 [AS_HELP_STRING([--with-$1], [use $1 (default is $2)])], 12998 [use_[]$1=$withval], 12999 [use_[]$1=$2])]) 13000 13001 13002File: autoconf.info, Node: Site Details, Next: Transforming Names, Prev: Pretty Help Strings, Up: Site Configuration 13003 1300414.5 Configuring Site Details 13005============================= 13006 13007Some software packages require complex site-specific information. Some 13008examples are host names to use for certain services, company names, and 13009email addresses to contact. Since some configuration scripts generated 13010by Metaconfig ask for such information interactively, people sometimes 13011wonder how to get that information in Autoconf-generated configuration 13012scripts, which aren't interactive. 13013 13014 Such site configuration information should be put in a file that is 13015edited _only by users_, not by programs. The location of the file can 13016either be based on the `prefix' variable, or be a standard location 13017such as the user's home directory. It could even be specified by an 13018environment variable. The programs should examine that file at 13019runtime, rather than at compile time. Runtime configuration is more 13020convenient for users and makes the configuration process simpler than 13021getting the information while configuring. *Note Variables for 13022Installation Directories: (standards)Directory Variables, for more 13023information on where to put data files. 13024 13025 13026File: autoconf.info, Node: Transforming Names, Next: Site Defaults, Prev: Site Details, Up: Site Configuration 13027 1302814.6 Transforming Program Names When Installing 13029=============================================== 13030 13031Autoconf supports changing the names of programs when installing them. 13032In order to use these transformations, `configure.ac' must call the 13033macro `AC_ARG_PROGRAM'. 13034 13035 -- Macro: AC_ARG_PROGRAM 13036 Place in output variable `program_transform_name' a sequence of 13037 `sed' commands for changing the names of installed programs. 13038 13039 If any of the options described below are given to `configure', 13040 program names are transformed accordingly. Otherwise, if 13041 `AC_CANONICAL_TARGET' has been called and a `--target' value is 13042 given, the target type followed by a dash is used as a prefix. 13043 Otherwise, no program name transformation is done. 13044 13045* Menu: 13046 13047* Transformation Options:: `configure' options to transform names 13048* Transformation Examples:: Sample uses of transforming names 13049* Transformation Rules:: Makefile uses of transforming names 13050 13051 13052File: autoconf.info, Node: Transformation Options, Next: Transformation Examples, Up: Transforming Names 13053 1305414.6.1 Transformation Options 13055----------------------------- 13056 13057You can specify name transformations by giving `configure' these 13058command line options: 13059 13060`--program-prefix=PREFIX' 13061 prepend PREFIX to the names; 13062 13063`--program-suffix=SUFFIX' 13064 append SUFFIX to the names; 13065 13066`--program-transform-name=EXPRESSION' 13067 perform `sed' substitution EXPRESSION on the names. 13068 13069 13070File: autoconf.info, Node: Transformation Examples, Next: Transformation Rules, Prev: Transformation Options, Up: Transforming Names 13071 1307214.6.2 Transformation Examples 13073------------------------------ 13074 13075These transformations are useful with programs that can be part of a 13076cross-compilation development environment. For example, a 13077cross-assembler running on a Sun 4 configured with 13078`--target=i960-vxworks' is normally installed as `i960-vxworks-as', 13079rather than `as', which could be confused with a native Sun 4 assembler. 13080 13081 You can force a program name to begin with `g', if you don't want 13082GNU programs installed on your system to shadow other programs with the 13083same name. For example, if you configure GNU `diff' with 13084`--program-prefix=g', then when you run `make install' it is installed 13085as `/usr/local/bin/gdiff'. 13086 13087 As a more sophisticated example, you could use 13088 13089 --program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/' 13090 to prepend `g' to most of the program names in a source tree, 13091excepting those like `gdb' that already have one and those like `less' 13092and `lesskey' that aren't GNU programs. (That is assuming that you 13093have a source tree containing those programs that is set up to use this 13094feature.) 13095 13096 One way to install multiple versions of some programs simultaneously 13097is to append a version number to the name of one or both. For example, 13098if you want to keep Autoconf version 1 around for awhile, you can 13099configure Autoconf version 2 using `--program-suffix=2' to install the 13100programs as `/usr/local/bin/autoconf2', `/usr/local/bin/autoheader2', 13101etc. Nevertheless, pay attention that only the binaries are renamed, 13102therefore you'd have problems with the library files which might 13103overlap. 13104 13105 13106File: autoconf.info, Node: Transformation Rules, Prev: Transformation Examples, Up: Transforming Names 13107 1310814.6.3 Transformation Rules 13109--------------------------- 13110 13111Here is how to use the variable `program_transform_name' in a 13112`Makefile.in': 13113 13114 PROGRAMS = cp ls rm 13115 transform = @program_transform_name@ 13116 install: 13117 for p in $(PROGRAMS); do \ 13118 $(INSTALL_PROGRAM) $$p $(DESTDIR)$(bindir)/`echo $$p | \ 13119 sed '$(transform)'`; \ 13120 done 13121 13122 uninstall: 13123 for p in $(PROGRAMS); do \ 13124 rm -f $(DESTDIR)$(bindir)/`echo $$p | sed '$(transform)'`; \ 13125 done 13126 13127 It is guaranteed that `program_transform_name' is never empty, and 13128that there are no useless separators. Therefore you may safely embed 13129`program_transform_name' within a sed program using `;': 13130 13131 transform = @program_transform_name@ 13132 transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/ 13133 13134 Whether to do the transformations on documentation files (Texinfo or 13135`man') is a tricky question; there seems to be no perfect answer, due 13136to the several reasons for name transforming. Documentation is not 13137usually particular to a specific architecture, and Texinfo files do not 13138conflict with system documentation. But they might conflict with 13139earlier versions of the same files, and `man' pages sometimes do 13140conflict with system documentation. As a compromise, it is probably 13141best to do name transformations on `man' pages but not on Texinfo 13142manuals. 13143 13144 13145File: autoconf.info, Node: Site Defaults, Prev: Transforming Names, Up: Site Configuration 13146 1314714.7 Setting Site Defaults 13148========================== 13149 13150Autoconf-generated `configure' scripts allow your site to provide 13151default values for some configuration values. You do this by creating 13152site- and system-wide initialization files. 13153 13154 If the environment variable `CONFIG_SITE' is set, `configure' uses 13155its value as the name of a shell script to read. Otherwise, it reads 13156the shell script `PREFIX/share/config.site' if it exists, then 13157`PREFIX/etc/config.site' if it exists. Thus, settings in 13158machine-specific files override those in machine-independent ones in 13159case of conflict. 13160 13161 Site files can be arbitrary shell scripts, but only certain kinds of 13162code are really appropriate to be in them. Because `configure' reads 13163any cache file after it has read any site files, a site file can define 13164a default cache file to be shared between all Autoconf-generated 13165`configure' scripts run on that system (*note Cache Files::). If you 13166set a default cache file in a site file, it is a good idea to also set 13167the output variable `CC' in that site file, because the cache file is 13168only valid for a particular compiler, but many systems have several 13169available. 13170 13171 You can examine or override the value set by a command line option to 13172`configure' in a site file; options set shell variables that have the 13173same names as the options, with any dashes turned into underscores. 13174The exceptions are that `--without-' and `--disable-' options are like 13175giving the corresponding `--with-' or `--enable-' option and the value 13176`no'. Thus, `--cache-file=localcache' sets the variable `cache_file' 13177to the value `localcache'; `--enable-warnings=no' or 13178`--disable-warnings' sets the variable `enable_warnings' to the value 13179`no'; `--prefix=/usr' sets the variable `prefix' to the value `/usr'; 13180etc. 13181 13182 Site files are also good places to set default values for other 13183output variables, such as `CFLAGS', if you need to give them non-default 13184values: anything you would normally do, repetitively, on the command 13185line. If you use non-default values for PREFIX or EXEC_PREFIX 13186(wherever you locate the site file), you can set them in the site file 13187if you specify it with the `CONFIG_SITE' environment variable. 13188 13189 You can set some cache values in the site file itself. Doing this is 13190useful if you are cross-compiling, where it is impossible to check 13191features that require running a test program. You could "prime the 13192cache" by setting those values correctly for that system in 13193`PREFIX/etc/config.site'. To find out the names of the cache variables 13194you need to set, look for shell variables with `_cv_' in their names in 13195the affected `configure' scripts, or in the Autoconf M4 source code for 13196those macros. 13197 13198 The cache file is careful to not override any variables set in the 13199site files. Similarly, you should not override command-line options in 13200the site files. Your code should check that variables such as `prefix' 13201and `cache_file' have their default values (as set near the top of 13202`configure') before changing them. 13203 13204 Here is a sample file `/usr/share/local/gnu/share/config.site'. The 13205command `configure --prefix=/usr/share/local/gnu' would read this file 13206(if `CONFIG_SITE' is not set to a different file). 13207 13208 # config.site for configure 13209 # 13210 # Change some defaults. 13211 test "$prefix" = NONE && prefix=/usr/share/local/gnu 13212 test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu 13213 test "$sharedstatedir" = '$prefix/com' && sharedstatedir=/var 13214 test "$localstatedir" = '$prefix/var' && localstatedir=/var 13215 13216 # Give Autoconf 2.x generated configure scripts a shared default 13217 # cache file for feature test results, architecture-specific. 13218 if test "$cache_file" = /dev/null; then 13219 cache_file="$prefix/var/config.cache" 13220 # A cache file is only valid for one C compiler. 13221 CC=gcc 13222 fi 13223 13224 13225File: autoconf.info, Node: Running configure Scripts, Next: config.status Invocation, Prev: Site Configuration, Up: Top 13226 1322715 Running `configure' Scripts 13228****************************** 13229 13230Below are instructions on how to configure a package that uses a 13231`configure' script, suitable for inclusion as an `INSTALL' file in the 13232package. A plain-text version of `INSTALL' which you may use comes 13233with Autoconf. 13234 13235* Menu: 13236 13237* Basic Installation:: Instructions for typical cases 13238* Compilers and Options:: Selecting compilers and optimization 13239* Multiple Architectures:: Compiling for multiple architectures at once 13240* Installation Names:: Installing in different directories 13241* Optional Features:: Selecting optional features 13242* System Type:: Specifying the system type 13243* Sharing Defaults:: Setting site-wide defaults for `configure' 13244* Defining Variables:: Specifying the compiler etc. 13245* configure Invocation:: Changing how `configure' runs 13246 13247 13248File: autoconf.info, Node: Basic Installation, Next: Compilers and Options, Up: Running configure Scripts 13249 1325015.1 Basic Installation 13251======================= 13252 13253Briefly, the shell commands `./configure; make; make install' should 13254configure, build, and install this package. The following 13255more-detailed instructions are generic; see the `README' file for 13256instructions specific to this package. 13257 13258 The `configure' shell script attempts to guess correct values for 13259various system-dependent variables used during compilation. It uses 13260those values to create a `Makefile' in each directory of the package. 13261It may also create one or more `.h' files containing system-dependent 13262definitions. Finally, it creates a shell script `config.status' that 13263you can run in the future to recreate the current configuration, and a 13264file `config.log' containing compiler output (useful mainly for 13265debugging `configure'). 13266 13267 It can also use an optional file (typically called `config.cache' 13268and enabled with `--cache-file=config.cache' or simply `-C') that saves 13269the results of its tests to speed up reconfiguring. Caching is 13270disabled by default to prevent problems with accidental use of stale 13271cache files. 13272 13273 If you need to do unusual things to compile the package, please try 13274to figure out how `configure' could check whether to do them, and mail 13275diffs or instructions to the address given in the `README' so they can 13276be considered for the next release. If you are using the cache, and at 13277some point `config.cache' contains results you don't want to keep, you 13278may remove or edit it. 13279 13280 The file `configure.ac' (or `configure.in') is used to create 13281`configure' by a program called `autoconf'. You need `configure.ac' if 13282you want to change it or regenerate `configure' using a newer version 13283of `autoconf'. 13284 13285The simplest way to compile this package is: 13286 13287 1. `cd' to the directory containing the package's source code and type 13288 `./configure' to configure the package for your system. 13289 13290 Running `configure' might take a while. While running, it prints 13291 some messages telling which features it is checking for. 13292 13293 2. Type `make' to compile the package. 13294 13295 3. Optionally, type `make check' to run any self-tests that come with 13296 the package. 13297 13298 4. Type `make install' to install the programs and any data files and 13299 documentation. 13300 13301 5. You can remove the program binaries and object files from the 13302 source code directory by typing `make clean'. To also remove the 13303 files that `configure' created (so you can compile the package for 13304 a different kind of computer), type `make distclean'. There is 13305 also a `make maintainer-clean' target, but that is intended mainly 13306 for the package's developers. If you use it, you may have to get 13307 all sorts of other programs in order to regenerate files that came 13308 with the distribution. 13309 13310 13311File: autoconf.info, Node: Compilers and Options, Next: Multiple Architectures, Prev: Basic Installation, Up: Running configure Scripts 13312 1331315.2 Compilers and Options 13314========================== 13315 13316Some systems require unusual options for compilation or linking that the 13317`configure' script does not know about. Run `./configure --help' for 13318details on some of the pertinent environment variables. 13319 13320 You can give `configure' initial values for configuration parameters 13321by setting variables in the command line or in the environment. Here 13322is an example: 13323 13324 ./configure CC=c99 CFLAGS=-g LIBS=-lposix 13325 13326 *Note Defining Variables::, for more details. 13327 13328 13329File: autoconf.info, Node: Multiple Architectures, Next: Installation Names, Prev: Compilers and Options, Up: Running configure Scripts 13330 1333115.3 Compiling For Multiple Architectures 13332========================================= 13333 13334You can compile the package for more than one kind of computer at the 13335same time, by placing the object files for each architecture in their 13336own directory. To do this, you can use GNU `make'. `cd' to the 13337directory where you want the object files and executables to go and run 13338the `configure' script. `configure' automatically checks for the 13339source code in the directory that `configure' is in and in `..'. 13340 13341 With a non-GNU `make', it is safer to compile the package for one 13342architecture at a time in the source code directory. After you have 13343installed the package for one architecture, use `make distclean' before 13344reconfiguring for another architecture. 13345 13346 13347File: autoconf.info, Node: Installation Names, Next: Optional Features, Prev: Multiple Architectures, Up: Running configure Scripts 13348 1334915.4 Installation Names 13350======================= 13351 13352By default, `make install' installs the package's commands under 13353`/usr/local/bin', include files under `/usr/local/include', etc. You 13354can specify an installation prefix other than `/usr/local' by giving 13355`configure' the option `--prefix=PREFIX'. 13356 13357 You can specify separate installation prefixes for 13358architecture-specific files and architecture-independent files. If you 13359pass the option `--exec-prefix=PREFIX' to `configure', the package uses 13360PREFIX as the prefix for installing programs and libraries. 13361Documentation and other data files still use the regular prefix. 13362 13363 In addition, if you use an unusual directory layout you can give 13364options like `--bindir=DIR' to specify different values for particular 13365kinds of files. Run `configure --help' for a list of the directories 13366you can set and what kinds of files go in them. 13367 13368 If the package supports it, you can cause programs to be installed 13369with an extra prefix or suffix on their names by giving `configure' the 13370option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'. 13371 13372 13373File: autoconf.info, Node: Optional Features, Next: System Type, Prev: Installation Names, Up: Running configure Scripts 13374 1337515.5 Optional Features 13376====================== 13377 13378Some packages pay attention to `--enable-FEATURE' options to 13379`configure', where FEATURE indicates an optional part of the package. 13380They may also pay attention to `--with-PACKAGE' options, where PACKAGE 13381is something like `gnu-as' or `x' (for the X Window System). The 13382`README' should mention any `--enable-' and `--with-' options that the 13383package recognizes. 13384 13385 For packages that use the X Window System, `configure' can usually 13386find the X include and library files automatically, but if it doesn't, 13387you can use the `configure' options `--x-includes=DIR' and 13388`--x-libraries=DIR' to specify their locations. 13389 13390 13391File: autoconf.info, Node: System Type, Next: Sharing Defaults, Prev: Optional Features, Up: Running configure Scripts 13392 1339315.6 Specifying the System Type 13394=============================== 13395 13396There may be some features `configure' cannot figure out automatically, 13397but needs to determine by the type of machine the package will run on. 13398Usually, assuming the package is built to be run on the _same_ 13399architectures, `configure' can figure that out, but if it prints a 13400message saying it cannot guess the machine type, give it the 13401`--build=TYPE' option. TYPE can either be a short name for the system 13402type, such as `sun4', or a canonical name which has the form: 13403 13404 CPU-COMPANY-SYSTEM 13405 13406where SYSTEM can have one of these forms: 13407 13408 OS KERNEL-OS 13409 13410 See the file `config.sub' for the possible values of each field. If 13411`config.sub' isn't included in this package, then this package doesn't 13412need to know the machine type. 13413 13414 If you are _building_ compiler tools for cross-compiling, you should 13415use the option `--target=TYPE' to select the type of system they will 13416produce code for. 13417 13418 If you want to _use_ a cross compiler, that generates code for a 13419platform different from the build platform, you should specify the 13420"host" platform (i.e., that on which the generated programs will 13421eventually be run) with `--host=TYPE'. 13422 13423 13424File: autoconf.info, Node: Sharing Defaults, Next: Defining Variables, Prev: System Type, Up: Running configure Scripts 13425 1342615.7 Sharing Defaults 13427===================== 13428 13429If you want to set default values for `configure' scripts to share, you 13430can create a site shell script called `config.site' that gives default 13431values for variables like `CC', `cache_file', and `prefix'. 13432`configure' looks for `PREFIX/share/config.site' if it exists, then 13433`PREFIX/etc/config.site' if it exists. Or, you can set the 13434`CONFIG_SITE' environment variable to the location of the site script. 13435A warning: not all `configure' scripts look for a site script. 13436 13437 13438File: autoconf.info, Node: Defining Variables, Next: configure Invocation, Prev: Sharing Defaults, Up: Running configure Scripts 13439 1344015.8 Defining Variables 13441======================= 13442 13443Variables not defined in a site shell script can be set in the 13444environment passed to `configure'. However, some packages may run 13445configure again during the build, and the customized values of these 13446variables may be lost. In order to avoid this problem, you should set 13447them in the `configure' command line, using `VAR=value'. For example: 13448 13449 ./configure CC=/usr/local2/bin/gcc 13450 13451causes the specified `gcc' to be used as the C compiler (unless it is 13452overridden in the site shell script). 13453 13454Unfortunately, this technique does not work for `CONFIG_SHELL' due to 13455an Autoconf bug. Until the bug is fixed you can use this workaround: 13456 13457 CONFIG_SHELL=/bin/bash /bin/bash ./configure CONFIG_SHELL=/bin/bash 13458 13459 13460File: autoconf.info, Node: configure Invocation, Prev: Defining Variables, Up: Running configure Scripts 13461 1346215.9 `configure' Invocation 13463=========================== 13464 13465`configure' recognizes the following options to control how it operates. 13466 13467`--help' 13468`-h' 13469 Print a summary of the options to `configure', and exit. 13470 13471`--version' 13472`-V' 13473 Print the version of Autoconf used to generate the `configure' 13474 script, and exit. 13475 13476`--cache-file=FILE' 13477 Enable the cache: use and save the results of the tests in FILE, 13478 traditionally `config.cache'. FILE defaults to `/dev/null' to 13479 disable caching. 13480 13481`--config-cache' 13482`-C' 13483 Alias for `--cache-file=config.cache'. 13484 13485`--quiet' 13486`--silent' 13487`-q' 13488 Do not print messages saying which checks are being made. To 13489 suppress all normal output, redirect it to `/dev/null' (any error 13490 messages will still be shown). 13491 13492`--srcdir=DIR' 13493 Look for the package's source code in directory DIR. Usually 13494 `configure' can determine that directory automatically. 13495 13496`configure' also accepts some other, not widely useful, options. Run 13497`configure --help' for more details. 13498 13499 13500File: autoconf.info, Node: config.status Invocation, Next: Obsolete Constructs, Prev: Running configure Scripts, Up: Top 13501 1350216 Recreating a Configuration 13503***************************** 13504 13505The `configure' script creates a file named `config.status', which 13506actually configures, "instantiates", the template files. It also 13507records the configuration options that were specified when the package 13508was last configured in case reconfiguring is needed. 13509 13510 Synopsis: 13511 ./config.status OPTION... [FILE...] 13512 13513 It configures the FILES; if none are specified, all the templates 13514are instantiated. The files must be specified without their 13515dependencies, as in 13516 13517 ./config.status foobar 13518 13519not 13520 13521 ./config.status foobar:foo.in:bar.in 13522 13523 The supported options are: 13524 13525`--help' 13526`-h' 13527 Print a summary of the command line options, the list of the 13528 template files, and exit. 13529 13530`--version' 13531`-V' 13532 Print the version number of Autoconf and the configuration 13533 settings, and exit. 13534 13535`--silent' 13536`--quiet' 13537`-q' 13538 Do not print progress messages. 13539 13540`--debug' 13541`-d' 13542 Don't remove the temporary files. 13543 13544`--file=FILE[:TEMPLATE]' 13545 Require that FILE be instantiated as if 13546 `AC_CONFIG_FILES(FILE:TEMPLATE)' was used. Both FILE and TEMPLATE 13547 may be `-' in which case the standard output and/or standard 13548 input, respectively, is used. If a TEMPLATE file name is 13549 relative, it is first looked for in the build tree, and then in 13550 the source tree. *Note Configuration Actions::, for more details. 13551 13552 This option and the following ones provide one way for separately 13553 distributed packages to share the values computed by `configure'. 13554 Doing so can be useful if some of the packages need a superset of 13555 the features that one of them, perhaps a common library, does. 13556 These options allow a `config.status' file to create files other 13557 than the ones that its `configure.ac' specifies, so it can be used 13558 for a different package. 13559 13560`--header=FILE[:TEMPLATE]' 13561 Same as `--file' above, but with `AC_CONFIG_HEADERS'. 13562 13563`--recheck' 13564 Ask `config.status' to update itself and exit (no instantiation). 13565 This option is useful if you change `configure', so that the 13566 results of some tests might be different from the previous run. 13567 The `--recheck' option reruns `configure' with the same arguments 13568 you used before, plus the `--no-create' option, which prevents 13569 `configure' from running `config.status' and creating `Makefile' 13570 and other files, and the `--no-recursion' option, which prevents 13571 `configure' from running other `configure' scripts in 13572 subdirectories. (This is so other Make rules can run 13573 `config.status' when it changes; *note Automatic Remaking::, for 13574 an example). 13575 13576 `config.status' checks several optional environment variables that 13577can alter its behavior: 13578 13579 -- Variable: CONFIG_SHELL 13580 The shell with which to run `configure' for the `--recheck' 13581 option. It must be Bourne-compatible. The default is a shell that 13582 supports `LINENO' if available, and `/bin/sh' otherwise. Invoking 13583 `configure' by hand bypasses this setting, so you may need to use 13584 a command like `CONFIG_SHELL=/bin/bash /bin/bash ./configure' to 13585 insure that the same shell is used everywhere. The absolute name 13586 of the shell should be passed. 13587 13588 -- Variable: CONFIG_STATUS 13589 The file name to use for the shell script that records the 13590 configuration. The default is `./config.status'. This variable is 13591 useful when one package uses parts of another and the `configure' 13592 scripts shouldn't be merged because they are maintained separately. 13593 13594 You can use `./config.status' in your makefiles. For example, in 13595the dependencies given above (*note Automatic Remaking::), 13596`config.status' is run twice when `configure.ac' has changed. If that 13597bothers you, you can make each run only regenerate the files for that 13598rule: 13599 config.h: stamp-h 13600 stamp-h: config.h.in config.status 13601 ./config.status config.h 13602 echo > stamp-h 13603 13604 Makefile: Makefile.in config.status 13605 ./config.status Makefile 13606 13607 The calling convention of `config.status' has changed; see *Note 13608Obsolete config.status Use::, for details. 13609 13610 13611File: autoconf.info, Node: Obsolete Constructs, Next: Using Autotest, Prev: config.status Invocation, Up: Top 13612 1361317 Obsolete Constructs 13614********************** 13615 13616Autoconf changes, and throughout the years some constructs have been 13617obsoleted. Most of the changes involve the macros, but in some cases 13618the tools themselves, or even some concepts, are now considered 13619obsolete. 13620 13621 You may completely skip this chapter if you are new to Autoconf. Its 13622intention is mainly to help maintainers updating their packages by 13623understanding how to move to more modern constructs. 13624 13625* Menu: 13626 13627* Obsolete config.status Use:: Different calling convention 13628* acconfig.h:: Additional entries in `config.h.in' 13629* autoupdate Invocation:: Automatic update of `configure.ac' 13630* Obsolete Macros:: Backward compatibility macros 13631* Autoconf 1:: Tips for upgrading your files 13632* Autoconf 2.13:: Some fresher tips 13633 13634 13635File: autoconf.info, Node: Obsolete config.status Use, Next: acconfig.h, Up: Obsolete Constructs 13636 1363717.1 Obsolete `config.status' Invocation 13638======================================== 13639 13640`config.status' now supports arguments to specify the files to 13641instantiate; see *Note config.status Invocation::, for more details. 13642Before, environment variables had to be used. 13643 13644 -- Variable: CONFIG_COMMANDS 13645 The tags of the commands to execute. The default is the arguments 13646 given to `AC_OUTPUT' and `AC_CONFIG_COMMANDS' in `configure.ac'. 13647 13648 -- Variable: CONFIG_FILES 13649 The files in which to perform `@VARIABLE@' substitutions. The 13650 default is the arguments given to `AC_OUTPUT' and 13651 `AC_CONFIG_FILES' in `configure.ac'. 13652 13653 -- Variable: CONFIG_HEADERS 13654 The files in which to substitute C `#define' statements. The 13655 default is the arguments given to `AC_CONFIG_HEADERS'; if that 13656 macro was not called, `config.status' ignores this variable. 13657 13658 -- Variable: CONFIG_LINKS 13659 The symbolic links to establish. The default is the arguments 13660 given to `AC_CONFIG_LINKS'; if that macro was not called, 13661 `config.status' ignores this variable. 13662 13663 In *Note config.status Invocation::, using this old interface, the 13664example would be: 13665 13666 config.h: stamp-h 13667 stamp-h: config.h.in config.status 13668 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \ 13669 CONFIG_HEADERS=config.h ./config.status 13670 echo > stamp-h 13671 13672 Makefile: Makefile.in config.status 13673 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \ 13674 CONFIG_FILES=Makefile ./config.status 13675 13676(If `configure.ac' does not call `AC_CONFIG_HEADERS', there is no need 13677to set `CONFIG_HEADERS' in the `make' rules. Equally for 13678`CONFIG_COMMANDS', etc.) 13679 13680 13681File: autoconf.info, Node: acconfig.h, Next: autoupdate Invocation, Prev: Obsolete config.status Use, Up: Obsolete Constructs 13682 1368317.2 `acconfig.h' 13684================= 13685 13686In order to produce `config.h.in', `autoheader' needs to build or to 13687find templates for each symbol. Modern releases of Autoconf use 13688`AH_VERBATIM' and `AH_TEMPLATE' (*note Autoheader Macros::), but in 13689older releases a file, `acconfig.h', contained the list of needed 13690templates. `autoheader' copied comments and `#define' and `#undef' 13691statements from `acconfig.h' in the current directory, if present. 13692This file used to be mandatory if you `AC_DEFINE' any additional 13693symbols. 13694 13695 Modern releases of Autoconf also provide `AH_TOP' and `AH_BOTTOM' if 13696you need to prepend/append some information to `config.h.in'. Ancient 13697versions of Autoconf had a similar feature: if `./acconfig.h' contains 13698the string `@TOP@', `autoheader' copies the lines before the line 13699containing `@TOP@' into the top of the file that it generates. 13700Similarly, if `./acconfig.h' contains the string `@BOTTOM@', 13701`autoheader' copies the lines after that line to the end of the file it 13702generates. Either or both of those strings may be omitted. An even 13703older alternate way to produce the same effect in ancient versions of 13704Autoconf is to create the files `FILE.top' (typically `config.h.top') 13705and/or `FILE.bot' in the current directory. If they exist, 13706`autoheader' copies them to the beginning and end, respectively, of its 13707output. 13708 13709 In former versions of Autoconf, the files used in preparing a 13710software package for distribution were: 13711 configure.ac --. .------> autoconf* -----> configure 13712 +---+ 13713 [aclocal.m4] --+ `---. 13714 [acsite.m4] ---' | 13715 +--> [autoheader*] -> [config.h.in] 13716 [acconfig.h] ----. | 13717 +-----' 13718 [config.h.top] --+ 13719 [config.h.bot] --' 13720 13721 Using only the `AH_' macros, `configure.ac' should be 13722self-contained, and should not depend upon `acconfig.h' etc. 13723 13724 13725File: autoconf.info, Node: autoupdate Invocation, Next: Obsolete Macros, Prev: acconfig.h, Up: Obsolete Constructs 13726 1372717.3 Using `autoupdate' to Modernize `configure.ac' 13728=================================================== 13729 13730The `autoupdate' program updates a `configure.ac' file that calls 13731Autoconf macros by their old names to use the current macro names. In 13732version 2 of Autoconf, most of the macros were renamed to use a more 13733uniform and descriptive naming scheme. *Note Macro Names::, for a 13734description of the new scheme. Although the old names still work 13735(*note Obsolete Macros::, for a list of the old macros and the 13736corresponding new names), you can make your `configure.ac' files more 13737readable and make it easier to use the current Autoconf documentation 13738if you update them to use the new macro names. 13739 13740 If given no arguments, `autoupdate' updates `configure.ac', backing 13741up the original version with the suffix `~' (or the value of the 13742environment variable `SIMPLE_BACKUP_SUFFIX', if that is set). If you 13743give `autoupdate' an argument, it reads that file instead of 13744`configure.ac' and writes the updated file to the standard output. 13745 13746`autoupdate' accepts the following options: 13747 13748`--help' 13749`-h' 13750 Print a summary of the command line options and exit. 13751 13752`--version' 13753`-V' 13754 Print the version number of Autoconf and exit. 13755 13756`--verbose' 13757`-v' 13758 Report processing steps. 13759 13760`--debug' 13761`-d' 13762 Don't remove the temporary files. 13763 13764`--force' 13765`-f' 13766 Force the update even if the file has not changed. Disregard the 13767 cache. 13768 13769`--include=DIR' 13770`-I DIR' 13771 Also look for input files in DIR. Multiple invocations accumulate. 13772 Directories are browsed from last to first. 13773 13774 13775File: autoconf.info, Node: Obsolete Macros, Next: Autoconf 1, Prev: autoupdate Invocation, Up: Obsolete Constructs 13776 1377717.4 Obsolete Macros 13778==================== 13779 13780Several macros are obsoleted in Autoconf, for various reasons (typically 13781they failed to quote properly, couldn't be extended for more recent 13782issues, etc.). They are still supported, but deprecated: their use 13783should be avoided. 13784 13785 During the jump from Autoconf version 1 to version 2, most of the 13786macros were renamed to use a more uniform and descriptive naming scheme, 13787but their signature did not change. *Note Macro Names::, for a 13788description of the new naming scheme. Below, if there is just the 13789mapping from old names to new names for these macros, the reader is 13790invited to refer to the definition of the new macro for the signature 13791and the description. 13792 13793 -- Macro: AC_ALLOCA 13794 `AC_FUNC_ALLOCA' 13795 13796 -- Macro: AC_ARG_ARRAY 13797 removed because of limited usefulness 13798 13799 -- Macro: AC_C_CROSS 13800 This macro is obsolete; it does nothing. 13801 13802 -- Macro: AC_C_LONG_DOUBLE 13803 If the C compiler supports a working `long double' type with more 13804 range or precision than the `double' type, define 13805 `HAVE_LONG_DOUBLE'. 13806 13807 You should use `AC_TYPE_LONG_DOUBLE' or 13808 `AC_TYPE_LONG_DOUBLE_WIDER' instead. *Note Particular Types::. 13809 13810 -- Macro: AC_CANONICAL_SYSTEM 13811 Determine the system type and set output variables to the names of 13812 the canonical system types. *Note Canonicalizing::, for details 13813 about the variables this macro sets. 13814 13815 The user is encouraged to use either `AC_CANONICAL_BUILD', or 13816 `AC_CANONICAL_HOST', or `AC_CANONICAL_TARGET', depending on the 13817 needs. Using `AC_CANONICAL_TARGET' is enough to run the two other 13818 macros. 13819 13820 -- Macro: AC_CHAR_UNSIGNED 13821 `AC_C_CHAR_UNSIGNED' 13822 13823 -- Macro: AC_CHECK_TYPE (TYPE, DEFAULT) 13824 Autoconf, up to 2.13, used to provide this version of 13825 `AC_CHECK_TYPE', deprecated because of its flaws. First, although 13826 it is a member of the `CHECK' clan, it does more than just 13827 checking. Secondly, missing types are defined using `#define', 13828 not `typedef', and this can lead to problems in the case of 13829 pointer types. 13830 13831 This use of `AC_CHECK_TYPE' is obsolete and discouraged; see *Note 13832 Generic Types::, for the description of the current macro. 13833 13834 If the type TYPE is not defined, define it to be the C (or C++) 13835 builtin type DEFAULT, e.g., `short int' or `unsigned int'. 13836 13837 This macro is equivalent to: 13838 13839 AC_CHECK_TYPE([TYPE], [], 13840 [AC_DEFINE_UNQUOTED([TYPE], [DEFAULT], 13841 [Define to `DEFAULT' 13842 if <sys/types.h> does not define.])]) 13843 13844 In order to keep backward compatibility, the two versions of 13845 `AC_CHECK_TYPE' are implemented, selected by a simple heuristics: 13846 13847 1. If there are three or four arguments, the modern version is 13848 used. 13849 13850 2. If the second argument appears to be a C or C++ type, then the 13851 obsolete version is used. This happens if the argument is a 13852 C or C++ _builtin_ type or a C identifier ending in `_t', 13853 optionally followed by one of `[(* ' and then by a string of 13854 zero or more characters taken from the set `[]()* _a-zA-Z0-9'. 13855 13856 3. If the second argument is spelled with the alphabet of valid 13857 C and C++ types, the user is warned and the modern version is 13858 used. 13859 13860 4. Otherwise, the modern version is used. 13861 13862 You are encouraged either to use a valid builtin type, or to use 13863 the equivalent modern code (see above), or better yet, to use 13864 `AC_CHECK_TYPES' together with 13865 13866 #ifndef HAVE_LOFF_T 13867 typedef loff_t off_t; 13868 #endif 13869 13870 -- Macro: AC_CHECKING (FEATURE-DESCRIPTION) 13871 Same as `AC_MSG_NOTICE([checking FEATURE-DESCRIPTION...]'. 13872 13873 -- Macro: AC_COMPILE_CHECK (ECHO-TEXT, INCLUDES, FUNCTION-BODY, 13874 ACTION-IF-TRUE, [ACTION-IF-FALSE]) 13875 This is an obsolete version of `AC_TRY_COMPILE' itself replaced by 13876 `AC_COMPILE_IFELSE' (*note Running the Compiler::), with the 13877 addition that it prints `checking for ECHO-TEXT' to the standard 13878 output first, if ECHO-TEXT is non-empty. Use `AC_MSG_CHECKING' 13879 and `AC_MSG_RESULT' instead to print messages (*note Printing 13880 Messages::). 13881 13882 -- Macro: AC_CONST 13883 `AC_C_CONST' 13884 13885 -- Macro: AC_CROSS_CHECK 13886 Same as `AC_C_CROSS', which is obsolete too, and does nothing 13887 `:-)'. 13888 13889 -- Macro: AC_CYGWIN 13890 Check for the Cygwin environment in which case the shell variable 13891 `CYGWIN' is set to `yes'. Don't use this macro, the dignified 13892 means to check the nature of the host is using 13893 `AC_CANONICAL_HOST'. As a matter of fact this macro is defined as: 13894 13895 AC_REQUIRE([AC_CANONICAL_HOST])[]dnl 13896 case $host_os in 13897 *cygwin* ) CYGWIN=yes;; 13898 * ) CYGWIN=no;; 13899 esac 13900 13901 Beware that the variable `CYGWIN' has a special meaning when 13902 running Cygwin, and should not be changed. That's yet another 13903 reason not to use this macro. 13904 13905 -- Macro: AC_DECL_SYS_SIGLIST 13906 Same as: 13907 13908 AC_CHECK_DECLS([sys_siglist], [], [], 13909 [#include <signal.h> 13910 /* NetBSD declares sys_siglist in unistd.h. */ 13911 #ifdef HAVE_UNISTD_H 13912 # include <unistd.h> 13913 #endif 13914 ]) 13915 13916 -- Macro: AC_DECL_YYTEXT 13917 Does nothing, now integrated in `AC_PROG_LEX'. 13918 13919 -- Macro: AC_DIR_HEADER 13920 Like calling `AC_FUNC_CLOSEDIR_VOID' and`AC_HEADER_DIRENT', but 13921 defines a different set of C preprocessor macros to indicate which 13922 header file is found: 13923 13924 Header Old Symbol New Symbol 13925 `dirent.h' `DIRENT' `HAVE_DIRENT_H' 13926 `sys/ndir.h' `SYSNDIR' `HAVE_SYS_NDIR_H' 13927 `sys/dir.h' `SYSDIR' `HAVE_SYS_DIR_H' 13928 `ndir.h' `NDIR' `HAVE_NDIR_H' 13929 13930 -- Macro: AC_DYNIX_SEQ 13931 If on DYNIX/ptx, add `-lseq' to output variable `LIBS'. This 13932 macro used to be defined as 13933 13934 AC_CHECK_LIB([seq], [getmntent], [LIBS="-lseq $LIBS"]) 13935 13936 now it is just `AC_FUNC_GETMNTENT'. 13937 13938 -- Macro: AC_EXEEXT 13939 Defined the output variable `EXEEXT' based on the output of the 13940 compiler, which is now done automatically. Typically set to empty 13941 string if Posix and `.exe' if a DOS variant. 13942 13943 -- Macro: AC_EMXOS2 13944 Similar to `AC_CYGWIN' but checks for the EMX environment on OS/2 13945 and sets `EMXOS2'. 13946 13947 -- Macro: AC_ERROR 13948 `AC_MSG_ERROR' 13949 13950 -- Macro: AC_FIND_X 13951 `AC_PATH_X' 13952 13953 -- Macro: AC_FIND_XTRA 13954 `AC_PATH_XTRA' 13955 13956 -- Macro: AC_FOREACH 13957 `m4_foreach_w' 13958 13959 -- Macro: AC_FUNC_CHECK 13960 `AC_CHECK_FUNC' 13961 13962 -- Macro: AC_FUNC_WAIT3 13963 If `wait3' is found and fills in the contents of its third argument 13964 (a `struct rusage *'), which HP-UX does not do, define 13965 `HAVE_WAIT3'. 13966 13967 These days portable programs should use `waitpid', not `wait3', as 13968 `wait3' has been removed from Posix. 13969 13970 -- Macro: AC_GCC_TRADITIONAL 13971 `AC_PROG_GCC_TRADITIONAL' 13972 13973 -- Macro: AC_GETGROUPS_T 13974 `AC_TYPE_GETGROUPS' 13975 13976 -- Macro: AC_GETLOADAVG 13977 `AC_FUNC_GETLOADAVG' 13978 13979 -- Macro: AC_HAVE_FUNCS 13980 `AC_CHECK_FUNCS' 13981 13982 -- Macro: AC_HAVE_HEADERS 13983 `AC_CHECK_HEADERS' 13984 13985 -- Macro: AC_HAVE_LIBRARY (LIBRARY, [ACTION-IF-FOUND], 13986 [ACTION-IF-NOT-FOUND], [OTHER-LIBRARIES]) 13987 This macro is equivalent to calling `AC_CHECK_LIB' with a FUNCTION 13988 argument of `main'. In addition, LIBRARY can be written as any of 13989 `foo', `-lfoo', or `libfoo.a'. In all of those cases, the 13990 compiler is passed `-lfoo'. However, LIBRARY cannot be a shell 13991 variable; it must be a literal name. 13992 13993 -- Macro: AC_HAVE_POUNDBANG 13994 `AC_SYS_INTERPRETER' (different calling convention) 13995 13996 -- Macro: AC_HEADER_CHECK 13997 `AC_CHECK_HEADER' 13998 13999 -- Macro: AC_HEADER_EGREP 14000 `AC_EGREP_HEADER' 14001 14002 -- Macro: AC_HELP_STRING 14003 `AS_HELP_STRING' 14004 14005 -- Macro: AC_INIT (UNIQUE-FILE-IN-SOURCE-DIR) 14006 Formerly `AC_INIT' used to have a single argument, and was 14007 equivalent to: 14008 14009 AC_INIT 14010 AC_CONFIG_SRCDIR(UNIQUE-FILE-IN-SOURCE-DIR) 14011 14012 -- Macro: AC_INLINE 14013 `AC_C_INLINE' 14014 14015 -- Macro: AC_INT_16_BITS 14016 If the C type `int' is 16 bits wide, define `INT_16_BITS'. Use 14017 `AC_CHECK_SIZEOF(int)' instead. 14018 14019 -- Macro: AC_IRIX_SUN 14020 If on IRIX (Silicon Graphics Unix), add `-lsun' to output `LIBS'. 14021 If you were using it to get `getmntent', use `AC_FUNC_GETMNTENT' 14022 instead. If you used it for the NIS versions of the password and 14023 group functions, use `AC_CHECK_LIB(sun, getpwnam)'. Up to 14024 Autoconf 2.13, it used to be 14025 14026 AC_CHECK_LIB([sun], [getmntent], [LIBS="-lsun $LIBS"]) 14027 14028 now it is defined as 14029 14030 AC_FUNC_GETMNTENT 14031 AC_CHECK_LIB([sun], [getpwnam]) 14032 14033 -- Macro: AC_LANG_C 14034 Same as `AC_LANG([C])'. 14035 14036 -- Macro: AC_LANG_CPLUSPLUS 14037 Same as `AC_LANG([C++])'. 14038 14039 -- Macro: AC_LANG_FORTRAN77 14040 Same as `AC_LANG([Fortran 77])'. 14041 14042 -- Macro: AC_LANG_RESTORE 14043 Select the LANGUAGE that is saved on the top of the stack, as set 14044 by `AC_LANG_SAVE', remove it from the stack, and call 14045 `AC_LANG(LANGUAGE)'. 14046 14047 -- Macro: AC_LANG_SAVE 14048 Remember the current language (as set by `AC_LANG') on a stack. 14049 The current language does not change. `AC_LANG_PUSH' is preferred. 14050 14051 -- Macro: AC_LINK_FILES (SOURCE..., DEST...) 14052 This is an obsolete version of `AC_CONFIG_LINKS'. An updated 14053 version of: 14054 14055 AC_LINK_FILES(config/$machine.h config/$obj_format.h, 14056 host.h object.h) 14057 14058 is: 14059 14060 AC_CONFIG_LINKS([host.h:config/$machine.h 14061 object.h:config/$obj_format.h]) 14062 14063 -- Macro: AC_LN_S 14064 `AC_PROG_LN_S' 14065 14066 -- Macro: AC_LONG_64_BITS 14067 Define `LONG_64_BITS' if the C type `long int' is 64 bits wide. 14068 Use the generic macro `AC_CHECK_SIZEOF([long int])' instead. 14069 14070 -- Macro: AC_LONG_DOUBLE 14071 If the C compiler supports a working `long double' type with more 14072 range or precision than the `double' type, define 14073 `HAVE_LONG_DOUBLE'. 14074 14075 You should use `AC_TYPE_LONG_DOUBLE' or 14076 `AC_TYPE_LONG_DOUBLE_WIDER' instead. *Note Particular Types::. 14077 14078 -- Macro: AC_LONG_FILE_NAMES 14079 `AC_SYS_LONG_FILE_NAMES' 14080 14081 -- Macro: AC_MAJOR_HEADER 14082 `AC_HEADER_MAJOR' 14083 14084 -- Macro: AC_MEMORY_H 14085 Used to define `NEED_MEMORY_H' if the `mem' functions were defined 14086 in `memory.h'. Today it is equivalent to 14087 `AC_CHECK_HEADERS([memory.h])'. Adjust your code to depend upon 14088 `HAVE_MEMORY_H', not `NEED_MEMORY_H'; see *Note Standard Symbols::. 14089 14090 -- Macro: AC_MINGW32 14091 Similar to `AC_CYGWIN' but checks for the MinGW compiler 14092 environment and sets `MINGW32'. 14093 14094 -- Macro: AC_MINUS_C_MINUS_O 14095 `AC_PROG_CC_C_O' 14096 14097 -- Macro: AC_MMAP 14098 `AC_FUNC_MMAP' 14099 14100 -- Macro: AC_MODE_T 14101 `AC_TYPE_MODE_T' 14102 14103 -- Macro: AC_OBJEXT 14104 Defined the output variable `OBJEXT' based on the output of the 14105 compiler, after .c files have been excluded. Typically set to `o' 14106 if Posix, `obj' if a DOS variant. Now the compiler checking 14107 macros handle this automatically. 14108 14109 -- Macro: AC_OBSOLETE (THIS-MACRO-NAME, [SUGGESTION]) 14110 Make M4 print a message to the standard error output warning that 14111 THIS-MACRO-NAME is obsolete, and giving the file and line number 14112 where it was called. THIS-MACRO-NAME should be the name of the 14113 macro that is calling `AC_OBSOLETE'. If SUGGESTION is given, it 14114 is printed at the end of the warning message; for example, it can 14115 be a suggestion for what to use instead of THIS-MACRO-NAME. 14116 14117 For instance 14118 14119 AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl 14120 14121 You are encouraged to use `AU_DEFUN' instead, since it gives better 14122 services to the user. 14123 14124 -- Macro: AC_OFF_T 14125 `AC_TYPE_OFF_T' 14126 14127 -- Macro: AC_OUTPUT ([FILE]..., [EXTRA-CMDS], [INIT-CMDS]) 14128 The use of `AC_OUTPUT' with argument is deprecated. This obsoleted 14129 interface is equivalent to: 14130 14131 AC_CONFIG_FILES(FILE...) 14132 AC_CONFIG_COMMANDS([default], 14133 EXTRA-CMDS, INIT-CMDS) 14134 AC_OUTPUT 14135 14136 -- Macro: AC_OUTPUT_COMMANDS (EXTRA-CMDS, [INIT-CMDS]) 14137 Specify additional shell commands to run at the end of 14138 `config.status', and shell commands to initialize any variables 14139 from `configure'. This macro may be called multiple times. It is 14140 obsolete, replaced by `AC_CONFIG_COMMANDS'. 14141 14142 Here is an unrealistic example: 14143 14144 fubar=27 14145 AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.], 14146 [fubar=$fubar]) 14147 AC_OUTPUT_COMMANDS([echo this is another, extra, bit], 14148 [echo init bit]) 14149 14150 Aside from the fact that `AC_CONFIG_COMMANDS' requires an 14151 additional key, an important difference is that 14152 `AC_OUTPUT_COMMANDS' is quoting its arguments twice, unlike 14153 `AC_CONFIG_COMMANDS'. This means that `AC_CONFIG_COMMANDS' can 14154 safely be given macro calls as arguments: 14155 14156 AC_CONFIG_COMMANDS(foo, [my_FOO()]) 14157 14158 Conversely, where one level of quoting was enough for literal 14159 strings with `AC_OUTPUT_COMMANDS', you need two with 14160 `AC_CONFIG_COMMANDS'. The following lines are equivalent: 14161 14162 AC_OUTPUT_COMMANDS([echo "Square brackets: []"]) 14163 AC_CONFIG_COMMANDS([default], [[echo "Square brackets: []"]]) 14164 14165 -- Macro: AC_PID_T 14166 `AC_TYPE_PID_T' 14167 14168 -- Macro: AC_PREFIX 14169 `AC_PREFIX_PROGRAM' 14170 14171 -- Macro: AC_PROGRAMS_CHECK 14172 `AC_CHECK_PROGS' 14173 14174 -- Macro: AC_PROGRAMS_PATH 14175 `AC_PATH_PROGS' 14176 14177 -- Macro: AC_PROGRAM_CHECK 14178 `AC_CHECK_PROG' 14179 14180 -- Macro: AC_PROGRAM_EGREP 14181 `AC_EGREP_CPP' 14182 14183 -- Macro: AC_PROGRAM_PATH 14184 `AC_PATH_PROG' 14185 14186 -- Macro: AC_REMOTE_TAPE 14187 removed because of limited usefulness 14188 14189 -- Macro: AC_RESTARTABLE_SYSCALLS 14190 `AC_SYS_RESTARTABLE_SYSCALLS' 14191 14192 -- Macro: AC_RETSIGTYPE 14193 `AC_TYPE_SIGNAL' 14194 14195 -- Macro: AC_RSH 14196 removed because of limited usefulness 14197 14198 -- Macro: AC_SCO_INTL 14199 If on SCO Unix, add `-lintl' to output variable `LIBS'. This 14200 macro used to do this: 14201 14202 AC_CHECK_LIB([intl], [strftime], [LIBS="-lintl $LIBS"]) 14203 14204 Now it just calls `AC_FUNC_STRFTIME' instead. 14205 14206 -- Macro: AC_SETVBUF_REVERSED 14207 `AC_FUNC_SETVBUF_REVERSED' 14208 14209 -- Macro: AC_SET_MAKE 14210 `AC_PROG_MAKE_SET' 14211 14212 -- Macro: AC_SIZEOF_TYPE 14213 `AC_CHECK_SIZEOF' 14214 14215 -- Macro: AC_SIZE_T 14216 `AC_TYPE_SIZE_T' 14217 14218 -- Macro: AC_STAT_MACROS_BROKEN 14219 `AC_HEADER_STAT' 14220 14221 -- Macro: AC_STDC_HEADERS 14222 `AC_HEADER_STDC' 14223 14224 -- Macro: AC_STRCOLL 14225 `AC_FUNC_STRCOLL' 14226 14227 -- Macro: AC_ST_BLKSIZE 14228 `AC_CHECK_MEMBERS' 14229 14230 -- Macro: AC_ST_BLOCKS 14231 `AC_STRUCT_ST_BLOCKS' 14232 14233 -- Macro: AC_ST_RDEV 14234 `AC_CHECK_MEMBERS' 14235 14236 -- Macro: AC_SYS_RESTARTABLE_SYSCALLS 14237 If the system automatically restarts a system call that is 14238 interrupted by a signal, define `HAVE_RESTARTABLE_SYSCALLS'. This 14239 macro does not check whether system calls are restarted in 14240 general--it checks whether a signal handler installed with 14241 `signal' (but not `sigaction') causes system calls to be 14242 restarted. It does not check whether system calls can be 14243 restarted when interrupted by signals that have no handler. 14244 14245 These days portable programs should use `sigaction' with 14246 `SA_RESTART' if they want restartable system calls. They should 14247 not rely on `HAVE_RESTARTABLE_SYSCALLS', since nowadays whether a 14248 system call is restartable is a dynamic issue, not a 14249 configuration-time issue. 14250 14251 -- Macro: AC_SYS_SIGLIST_DECLARED 14252 `AC_DECL_SYS_SIGLIST' 14253 14254 -- Macro: AC_TEST_CPP 14255 `AC_TRY_CPP', replaced by `AC_PREPROC_IFELSE'. 14256 14257 -- Macro: AC_TEST_PROGRAM 14258 `AC_TRY_RUN', replaced by `AC_RUN_IFELSE'. 14259 14260 -- Macro: AC_TIMEZONE 14261 `AC_STRUCT_TIMEZONE' 14262 14263 -- Macro: AC_TIME_WITH_SYS_TIME 14264 `AC_HEADER_TIME' 14265 14266 -- Macro: AC_TRY_COMPILE (INCLUDES, FUNCTION-BODY, [ACTION-IF-TRUE], 14267 [ACTION-IF-FALSE]) 14268 Same as: 14269 14270 AC_COMPILE_IFELSE( 14271 [AC_LANG_PROGRAM([[INCLUDES]], 14272 [[FUNCTION-BODY]])], 14273 [ACTION-IF-TRUE], 14274 [ACTION-IF-FALSE]) 14275 14276 *Note Running the Compiler::. 14277 14278 This macro double quotes both INCLUDES and FUNCTION-BODY. 14279 14280 For C and C++, INCLUDES is any `#include' statements needed by the 14281 code in FUNCTION-BODY (INCLUDES is ignored if the currently 14282 selected language is Fortran or Fortran 77). The compiler and 14283 compilation flags are determined by the current language (*note 14284 Language Choice::). 14285 14286 -- Macro: AC_TRY_CPP (INPUT, [ACTION-IF-TRUE], [ACTION-IF-FALSE]) 14287 Same as: 14288 14289 AC_PREPROC_IFELSE( 14290 [AC_LANG_SOURCE([[INPUT]])], 14291 [ACTION-IF-TRUE], 14292 [ACTION-IF-FALSE]) 14293 14294 *Note Running the Preprocessor::. 14295 14296 This macro double quotes the INPUT. 14297 14298 -- Macro: AC_TRY_LINK (INCLUDES, FUNCTION-BODY, [ACTION-IF-TRUE], 14299 [ACTION-IF-FALSE]) 14300 Same as: 14301 14302 AC_LINK_IFELSE( 14303 [AC_LANG_PROGRAM([[INCLUDES]], 14304 [[FUNCTION-BODY]])], 14305 [ACTION-IF-TRUE], 14306 [ACTION-IF-FALSE]) 14307 14308 *Note Running the Compiler::. 14309 14310 This macro double quotes both INCLUDES and FUNCTION-BODY. 14311 14312 Depending on the current language (*note Language Choice::), 14313 create a test program to see whether a function whose body 14314 consists of FUNCTION-BODY can be compiled and linked. If the file 14315 compiles and links successfully, run shell commands 14316 ACTION-IF-FOUND, otherwise run ACTION-IF-NOT-FOUND. 14317 14318 This macro double quotes both INCLUDES and FUNCTION-BODY. 14319 14320 For C and C++, INCLUDES is any `#include' statements needed by the 14321 code in FUNCTION-BODY (INCLUDES is ignored if the currently 14322 selected language is Fortran or Fortran 77). The compiler and 14323 compilation flags are determined by the current language (*note 14324 Language Choice::), and in addition `LDFLAGS' and `LIBS' are used 14325 for linking. 14326 14327 -- Macro: AC_TRY_LINK_FUNC (FUNCTION, [ACTION-IF-FOUND], 14328 [ACTION-IF-NOT-FOUND]) 14329 This macro is equivalent to `AC_LINK_IFELSE([AC_LANG_CALL([], 14330 [FUNCTION])], [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND])'. 14331 14332 -- Macro: AC_TRY_RUN (PROGRAM, [ACTION-IF-TRUE], [ACTION-IF-FALSE], 14333 [ACTION-IF-CROSS-COMPILING]) 14334 Same as: 14335 14336 AC_RUN_IFELSE( 14337 [AC_LANG_SOURCE([[PROGRAM]])], 14338 [ACTION-IF-TRUE], 14339 [ACTION-IF-FALSE], 14340 [ACTION-IF-CROSS-COMPILING]) 14341 14342 *Note Runtime::. 14343 14344 -- Macro: AC_UID_T 14345 `AC_TYPE_UID_T' 14346 14347 -- Macro: AC_UNISTD_H 14348 Same as `AC_CHECK_HEADERS([unistd.h])'. 14349 14350 -- Macro: AC_USG 14351 Define `USG' if the BSD string functions are defined in 14352 `strings.h'. You should no longer depend upon `USG', but on 14353 `HAVE_STRING_H'; see *Note Standard Symbols::. 14354 14355 -- Macro: AC_UTIME_NULL 14356 `AC_FUNC_UTIME_NULL' 14357 14358 -- Macro: AC_VALIDATE_CACHED_SYSTEM_TUPLE ([CMD]) 14359 If the cache file is inconsistent with the current host, target and 14360 build system types, it used to execute CMD or print a default 14361 error message. This is now handled by default. 14362 14363 -- Macro: AC_VERBOSE (RESULT-DESCRIPTION) 14364 `AC_MSG_RESULT'. 14365 14366 -- Macro: AC_VFORK 14367 `AC_FUNC_VFORK' 14368 14369 -- Macro: AC_VPRINTF 14370 `AC_FUNC_VPRINTF' 14371 14372 -- Macro: AC_WAIT3 14373 `AC_FUNC_WAIT3' 14374 14375 -- Macro: AC_WARN 14376 `AC_MSG_WARN' 14377 14378 -- Macro: AC_WORDS_BIGENDIAN 14379 `AC_C_BIGENDIAN' 14380 14381 -- Macro: AC_XENIX_DIR 14382 This macro used to add `-lx' to output variable `LIBS' if on 14383 Xenix. Also, if `dirent.h' is being checked for, added `-ldir' to 14384 `LIBS'. Now it is merely an alias of `AC_HEADER_DIRENT' instead, 14385 plus some code to detect whether running XENIX on which you should 14386 not depend: 14387 14388 AC_MSG_CHECKING([for Xenix]) 14389 AC_EGREP_CPP([yes], 14390 [#if defined M_XENIX && !defined M_UNIX 14391 yes 14392 #endif], 14393 [AC_MSG_RESULT([yes]); XENIX=yes], 14394 [AC_MSG_RESULT([no]); XENIX=]) 14395 14396 -- Macro: AC_YYTEXT_POINTER 14397 `AC_DECL_YYTEXT' 14398 14399 14400File: autoconf.info, Node: Autoconf 1, Next: Autoconf 2.13, Prev: Obsolete Macros, Up: Obsolete Constructs 14401 1440217.5 Upgrading From Version 1 14403============================= 14404 14405Autoconf version 2 is mostly backward compatible with version 1. 14406However, it introduces better ways to do some things, and doesn't 14407support some of the ugly things in version 1. So, depending on how 14408sophisticated your `configure.ac' files are, you might have to do some 14409manual work in order to upgrade to version 2. This chapter points out 14410some problems to watch for when upgrading. Also, perhaps your 14411`configure' scripts could benefit from some of the new features in 14412version 2; the changes are summarized in the file `NEWS' in the 14413Autoconf distribution. 14414 14415* Menu: 14416 14417* Changed File Names:: Files you might rename 14418* Changed Makefiles:: New things to put in `Makefile.in' 14419* Changed Macros:: Macro calls you might replace 14420* Changed Results:: Changes in how to check test results 14421* Changed Macro Writing:: Better ways to write your own macros 14422 14423 14424File: autoconf.info, Node: Changed File Names, Next: Changed Makefiles, Up: Autoconf 1 14425 1442617.5.1 Changed File Names 14427------------------------- 14428 14429If you have an `aclocal.m4' installed with Autoconf (as opposed to in a 14430particular package's source directory), you must rename it to 14431`acsite.m4'. *Note autoconf Invocation::. 14432 14433 If you distribute `install.sh' with your package, rename it to 14434`install-sh' so `make' builtin rules don't inadvertently create a file 14435called `install' from it. `AC_PROG_INSTALL' looks for the script under 14436both names, but it is best to use the new name. 14437 14438 If you were using `config.h.top', `config.h.bot', or `acconfig.h', 14439you still can, but you have less clutter if you use the `AH_' macros. 14440*Note Autoheader Macros::. 14441 14442 14443File: autoconf.info, Node: Changed Makefiles, Next: Changed Macros, Prev: Changed File Names, Up: Autoconf 1 14444 1444517.5.2 Changed Makefiles 14446------------------------ 14447 14448Add `@CFLAGS@', `@CPPFLAGS@', and `@LDFLAGS@' in your `Makefile.in' 14449files, so they can take advantage of the values of those variables in 14450the environment when `configure' is run. Doing this isn't necessary, 14451but it's a convenience for users. 14452 14453 Also add `@configure_input@' in a comment to each input file for 14454`AC_OUTPUT', so that the output files contain a comment saying they 14455were produced by `configure'. Automatically selecting the right 14456comment syntax for all the kinds of files that people call `AC_OUTPUT' 14457on became too much work. 14458 14459 Add `config.log' and `config.cache' to the list of files you remove 14460in `distclean' targets. 14461 14462 If you have the following in `Makefile.in': 14463 14464 prefix = /usr/local 14465 exec_prefix = $(prefix) 14466 14467you must change it to: 14468 14469 prefix = @prefix@ 14470 exec_prefix = @exec_prefix@ 14471 14472The old behavior of replacing those variables without `@' characters 14473around them has been removed. 14474 14475 14476File: autoconf.info, Node: Changed Macros, Next: Changed Results, Prev: Changed Makefiles, Up: Autoconf 1 14477 1447817.5.3 Changed Macros 14479--------------------- 14480 14481Many of the macros were renamed in Autoconf version 2. You can still 14482use the old names, but the new ones are clearer, and it's easier to find 14483the documentation for them. *Note Obsolete Macros::, for a table 14484showing the new names for the old macros. Use the `autoupdate' program 14485to convert your `configure.ac' to using the new macro names. *Note 14486autoupdate Invocation::. 14487 14488 Some macros have been superseded by similar ones that do the job 14489better, but are not call-compatible. If you get warnings about calling 14490obsolete macros while running `autoconf', you may safely ignore them, 14491but your `configure' script generally works better if you follow the 14492advice that is printed about what to replace the obsolete macros with. 14493In particular, the mechanism for reporting the results of tests has 14494changed. If you were using `echo' or `AC_VERBOSE' (perhaps via 14495`AC_COMPILE_CHECK'), your `configure' script's output looks better if 14496you switch to `AC_MSG_CHECKING' and `AC_MSG_RESULT'. *Note Printing 14497Messages::. Those macros work best in conjunction with cache 14498variables. *Note Caching Results::. 14499 14500 14501File: autoconf.info, Node: Changed Results, Next: Changed Macro Writing, Prev: Changed Macros, Up: Autoconf 1 14502 1450317.5.4 Changed Results 14504---------------------- 14505 14506If you were checking the results of previous tests by examining the 14507shell variable `DEFS', you need to switch to checking the values of the 14508cache variables for those tests. `DEFS' no longer exists while 14509`configure' is running; it is only created when generating output 14510files. This difference from version 1 is because properly quoting the 14511contents of that variable turned out to be too cumbersome and 14512inefficient to do every time `AC_DEFINE' is called. *Note Cache 14513Variable Names::. 14514 14515 For example, here is a `configure.ac' fragment written for Autoconf 14516version 1: 14517 14518 AC_HAVE_FUNCS(syslog) 14519 case "$DEFS" in 14520 *-DHAVE_SYSLOG*) ;; 14521 *) # syslog is not in the default libraries. See if it's in some other. 14522 saved_LIBS="$LIBS" 14523 for lib in bsd socket inet; do 14524 AC_CHECKING(for syslog in -l$lib) 14525 LIBS="-l$lib $saved_LIBS" 14526 AC_HAVE_FUNCS(syslog) 14527 case "$DEFS" in 14528 *-DHAVE_SYSLOG*) break ;; 14529 *) ;; 14530 esac 14531 LIBS="$saved_LIBS" 14532 done ;; 14533 esac 14534 14535 Here is a way to write it for version 2: 14536 14537 AC_CHECK_FUNCS([syslog]) 14538 if test $ac_cv_func_syslog = no; then 14539 # syslog is not in the default libraries. See if it's in some other. 14540 for lib in bsd socket inet; do 14541 AC_CHECK_LIB([$lib], [syslog], [AC_DEFINE([HAVE_SYSLOG]) 14542 LIBS="-l$lib $LIBS"; break]) 14543 done 14544 fi 14545 14546 If you were working around bugs in `AC_DEFINE_UNQUOTED' by adding 14547backslashes before quotes, you need to remove them. It now works 14548predictably, and does not treat quotes (except back quotes) specially. 14549*Note Setting Output Variables::. 14550 14551 All of the Boolean shell variables set by Autoconf macros now use 14552`yes' for the true value. Most of them use `no' for false, though for 14553backward compatibility some use the empty string instead. If you were 14554relying on a shell variable being set to something like 1 or `t' for 14555true, you need to change your tests. 14556 14557 14558File: autoconf.info, Node: Changed Macro Writing, Prev: Changed Results, Up: Autoconf 1 14559 1456017.5.5 Changed Macro Writing 14561---------------------------- 14562 14563When defining your own macros, you should now use `AC_DEFUN' instead of 14564`define'. `AC_DEFUN' automatically calls `AC_PROVIDE' and ensures that 14565macros called via `AC_REQUIRE' do not interrupt other macros, to 14566prevent nested `checking...' messages on the screen. There's no actual 14567harm in continuing to use the older way, but it's less convenient and 14568attractive. *Note Macro Definitions::. 14569 14570 You probably looked at the macros that came with Autoconf as a guide 14571for how to do things. It would be a good idea to take a look at the new 14572versions of them, as the style is somewhat improved and they take 14573advantage of some new features. 14574 14575 If you were doing tricky things with undocumented Autoconf internals 14576(macros, variables, diversions), check whether you need to change 14577anything to account for changes that have been made. Perhaps you can 14578even use an officially supported technique in version 2 instead of 14579kludging. Or perhaps not. 14580 14581 To speed up your locally written feature tests, add caching to them. 14582See whether any of your tests are of general enough usefulness to 14583encapsulate them into macros that you can share. 14584 14585 14586File: autoconf.info, Node: Autoconf 2.13, Prev: Autoconf 1, Up: Obsolete Constructs 14587 1458817.6 Upgrading From Version 2.13 14589================================ 14590 14591The introduction of the previous section (*note Autoconf 1::) perfectly 14592suits this section.... 14593 14594 Autoconf version 2.50 is mostly backward compatible with version 14595 2.13. However, it introduces better ways to do some things, and 14596 doesn't support some of the ugly things in version 2.13. So, 14597 depending on how sophisticated your `configure.ac' files are, you 14598 might have to do some manual work in order to upgrade to version 14599 2.50. This chapter points out some problems to watch for when 14600 upgrading. Also, perhaps your `configure' scripts could benefit 14601 from some of the new features in version 2.50; the changes are 14602 summarized in the file `NEWS' in the Autoconf distribution. 14603 14604* Menu: 14605 14606* Changed Quotation:: Broken code which used to work 14607* New Macros:: Interaction with foreign macros 14608* Hosts and Cross-Compilation:: Bugward compatibility kludges 14609* AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token 14610* AC_FOO_IFELSE vs AC_TRY_FOO:: A more generic scheme for testing sources 14611 14612 14613File: autoconf.info, Node: Changed Quotation, Next: New Macros, Up: Autoconf 2.13 14614 1461517.6.1 Changed Quotation 14616------------------------ 14617 14618The most important changes are invisible to you: the implementation of 14619most macros have completely changed. This allowed more factorization of 14620the code, better error messages, a higher uniformity of the user's 14621interface etc. Unfortunately, as a side effect, some construct which 14622used to (miraculously) work might break starting with Autoconf 2.50. 14623The most common culprit is bad quotation. 14624 14625 For instance, in the following example, the message is not properly 14626quoted: 14627 14628 AC_INIT 14629 AC_CHECK_HEADERS(foo.h, , 14630 AC_MSG_ERROR(cannot find foo.h, bailing out)) 14631 AC_OUTPUT 14632 14633Autoconf 2.13 simply ignores it: 14634 14635 $ autoconf-2.13; ./configure --silent 14636 creating cache ./config.cache 14637 configure: error: cannot find foo.h 14638 $ 14639 14640while Autoconf 2.50 produces a broken `configure': 14641 14642 $ autoconf-2.50; ./configure --silent 14643 configure: error: cannot find foo.h 14644 ./configure: exit: bad non-numeric arg `bailing' 14645 ./configure: exit: bad non-numeric arg `bailing' 14646 $ 14647 14648 The message needs to be quoted, and the `AC_MSG_ERROR' invocation 14649too! 14650 14651 AC_INIT([Example], [1.0], [bug-example@example.org]) 14652 AC_CHECK_HEADERS([foo.h], [], 14653 [AC_MSG_ERROR([cannot find foo.h, bailing out])]) 14654 AC_OUTPUT 14655 14656 Many many (and many more) Autoconf macros were lacking proper 14657quotation, including no less than... `AC_DEFUN' itself! 14658 14659 $ cat configure.in 14660 AC_DEFUN([AC_PROG_INSTALL], 14661 [# My own much better version 14662 ]) 14663 AC_INIT 14664 AC_PROG_INSTALL 14665 AC_OUTPUT 14666 $ autoconf-2.13 14667 autoconf: Undefined macros: 14668 ***BUG in Autoconf--please report*** AC_FD_MSG 14669 ***BUG in Autoconf--please report*** AC_EPI 14670 configure.in:1:AC_DEFUN([AC_PROG_INSTALL], 14671 configure.in:5:AC_PROG_INSTALL 14672 $ autoconf-2.50 14673 $ 14674 14675 14676File: autoconf.info, Node: New Macros, Next: Hosts and Cross-Compilation, Prev: Changed Quotation, Up: Autoconf 2.13 14677 1467817.6.2 New Macros 14679----------------- 14680 14681While Autoconf was relatively dormant in the late 1990s, Automake 14682provided Autoconf-like macros for a while. Starting with Autoconf 2.50 14683in 2001, Autoconf provided versions of these macros, integrated in the 14684`AC_' namespace, instead of `AM_'. But in order to ease the upgrading 14685via `autoupdate', bindings to such `AM_' macros are provided. 14686 14687 Unfortunately older versions of Automake (e.g., Automake 1.4) did 14688not quote the names of these macros. Therefore, when `m4' finds 14689something like `AC_DEFUN(AM_TYPE_PTRDIFF_T, ...)' in `aclocal.m4', 14690`AM_TYPE_PTRDIFF_T' is expanded, replaced with its Autoconf definition. 14691 14692 Fortunately Autoconf catches pre-`AC_INIT' expansions, and 14693complains, in its own words: 14694 14695 $ cat configure.ac 14696 AC_INIT([Example], [1.0], [bug-example@example.org]) 14697 AM_TYPE_PTRDIFF_T 14698 $ aclocal-1.4 14699 $ autoconf 14700 aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion 14701 aclocal.m4:17: the top level 14702 autom4te: m4 failed with exit status: 1 14703 $ 14704 14705 Modern versions of Automake no longer define most of these macros, 14706and properly quote the names of the remaining macros. If you must use 14707an old Automake, do not depend upon macros from Automake as it is 14708simply not its job to provide macros (but the one it requires itself): 14709 14710 $ cat configure.ac 14711 AC_INIT([Example], [1.0], [bug-example@example.org]) 14712 AM_TYPE_PTRDIFF_T 14713 $ rm aclocal.m4 14714 $ autoupdate 14715 autoupdate: `configure.ac' is updated 14716 $ cat configure.ac 14717 AC_INIT([Example], [1.0], [bug-example@example.org]) 14718 AC_CHECK_TYPES([ptrdiff_t]) 14719 $ aclocal-1.4 14720 $ autoconf 14721 $ 14722 14723 14724File: autoconf.info, Node: Hosts and Cross-Compilation, Next: AC_LIBOBJ vs LIBOBJS, Prev: New Macros, Up: Autoconf 2.13 14725 1472617.6.3 Hosts and Cross-Compilation 14727---------------------------------- 14728 14729Based on the experience of compiler writers, and after long public 14730debates, many aspects of the cross-compilation chain have changed: 14731 14732 - the relationship between the build, host, and target architecture 14733 types, 14734 14735 - the command line interface for specifying them to `configure', 14736 14737 - the variables defined in `configure', 14738 14739 - the enabling of cross-compilation mode. 14740 14741 14742 The relationship between build, host, and target have been cleaned 14743up: the chain of default is now simply: target defaults to host, host to 14744build, and build to the result of `config.guess'. Nevertheless, in 14745order to ease the transition from 2.13 to 2.50, the following 14746transition scheme is implemented. _Do not rely on it_, as it will be 14747completely disabled in a couple of releases (we cannot keep it, as it 14748proves to cause more problems than it cures). 14749 14750 They all default to the result of running `config.guess', unless you 14751specify either `--build' or `--host'. In this case, the default 14752becomes the system type you specified. If you specify both, and 14753they're different, `configure' enters cross compilation mode, so it 14754doesn't run any tests that require execution. 14755 14756 Hint: if you mean to override the result of `config.guess', prefer 14757`--build' over `--host'. In the future, `--host' will not override the 14758name of the build system type. Whenever you specify `--host', be sure 14759to specify `--build' too. 14760 14761 14762 For backward compatibility, `configure' accepts a system type as an 14763option by itself. Such an option overrides the defaults for build, 14764host, and target system types. The following configure statement 14765configures a cross toolchain that runs on NetBSD/alpha but generates 14766code for GNU Hurd/sparc, which is also the build platform. 14767 14768 ./configure --host=alpha-netbsd sparc-gnu 14769 14770 14771 In Autoconf 2.13 and before, the variables `build', `host', and 14772`target' had a different semantics before and after the invocation of 14773`AC_CANONICAL_BUILD' etc. Now, the argument of `--build' is strictly 14774copied into `build_alias', and is left empty otherwise. After the 14775`AC_CANONICAL_BUILD', `build' is set to the canonicalized build type. 14776To ease the transition, before, its contents is the same as that of 14777`build_alias'. Do _not_ rely on this broken feature. 14778 14779 For consistency with the backward compatibility scheme exposed above, 14780when `--host' is specified but `--build' isn't, the build system is 14781assumed to be the same as `--host', and `build_alias' is set to that 14782value. Eventually, this historically incorrect behavior will go away. 14783 14784 14785 The former scheme to enable cross-compilation proved to cause more 14786harm than good, in particular, it used to be triggered too easily, 14787leaving regular end users puzzled in front of cryptic error messages. 14788`configure' could even enter cross-compilation mode only because the 14789compiler was not functional. This is mainly because `configure' used 14790to try to detect cross-compilation, instead of waiting for an explicit 14791flag from the user. 14792 14793 Now, `configure' enters cross-compilation mode if and only if 14794`--host' is passed. 14795 14796 That's the short documentation. To ease the transition between 2.13 14797and its successors, a more complicated scheme is implemented. _Do not 14798rely on the following_, as it will be removed in the near future. 14799 14800 If you specify `--host', but not `--build', when `configure' 14801performs the first compiler test it tries to run an executable produced 14802by the compiler. If the execution fails, it enters cross-compilation 14803mode. This is fragile. Moreover, by the time the compiler test is 14804performed, it may be too late to modify the build-system type: other 14805tests may have already been performed. Therefore, whenever you specify 14806`--host', be sure to specify `--build' too. 14807 14808 ./configure --build=i686-pc-linux-gnu --host=m68k-coff 14809 14810enters cross-compilation mode. The former interface, which consisted 14811in setting the compiler to a cross-compiler without informing 14812`configure' is obsolete. For instance, `configure' fails if it can't 14813run the code generated by the specified compiler if you configure as 14814follows: 14815 14816 ./configure CC=m68k-coff-gcc 14817 14818 14819File: autoconf.info, Node: AC_LIBOBJ vs LIBOBJS, Next: AC_FOO_IFELSE vs AC_TRY_FOO, Prev: Hosts and Cross-Compilation, Up: Autoconf 2.13 14820 1482117.6.4 `AC_LIBOBJ' vs. `LIBOBJS' 14822-------------------------------- 14823 14824Up to Autoconf 2.13, the replacement of functions was triggered via the 14825variable `LIBOBJS'. Since Autoconf 2.50, the macro `AC_LIBOBJ' should 14826be used instead (*note Generic Functions::). Starting at Autoconf 148272.53, the use of `LIBOBJS' is an error. 14828 14829 This change is mandated by the unification of the GNU Build System 14830components. In particular, the various fragile techniques used to parse 14831a `configure.ac' are all replaced with the use of traces. As a 14832consequence, any action must be traceable, which obsoletes critical 14833variable assignments. Fortunately, `LIBOBJS' was the only problem, and 14834it can even be handled gracefully (read, "without your having to change 14835something"). 14836 14837 There were two typical uses of `LIBOBJS': asking for a replacement 14838function, and adjusting `LIBOBJS' for Automake and/or Libtool. 14839 14840 14841 As for function replacement, the fix is immediate: use `AC_LIBOBJ'. 14842For instance: 14843 14844 LIBOBJS="$LIBOBJS fnmatch.o" 14845 LIBOBJS="$LIBOBJS malloc.$ac_objext" 14846 14847should be replaced with: 14848 14849 AC_LIBOBJ([fnmatch]) 14850 AC_LIBOBJ([malloc]) 14851 14852 14853 When used with Automake 1.10 or newer, a suitable value for 14854`LIBOBJDIR' is set so that the `LIBOBJS' and `LTLIBOBJS' can be 14855referenced from any `Makefile.am'. Even without Automake, arranging 14856for `LIBOBJDIR' to be set correctly enables referencing `LIBOBJS' and 14857`LTLIBOBJS' in another directory. The `LIBOJBDIR' feature is 14858experimental. 14859 14860 14861File: autoconf.info, Node: AC_FOO_IFELSE vs AC_TRY_FOO, Prev: AC_LIBOBJ vs LIBOBJS, Up: Autoconf 2.13 14862 1486317.6.5 `AC_FOO_IFELSE' vs. `AC_TRY_FOO' 14864--------------------------------------- 14865 14866Since Autoconf 2.50, internal codes uses `AC_PREPROC_IFELSE', 14867`AC_COMPILE_IFELSE', `AC_LINK_IFELSE', and `AC_RUN_IFELSE' on one hand 14868and `AC_LANG_SOURCES', and `AC_LANG_PROGRAM' on the other hand instead 14869of the deprecated `AC_TRY_CPP', `AC_TRY_COMPILE', `AC_TRY_LINK', and 14870`AC_TRY_RUN'. The motivations where: 14871 - a more consistent interface: `AC_TRY_COMPILE' etc. were double 14872 quoting their arguments; 14873 14874 - the combinatoric explosion is solved by decomposing on the one 14875 hand the generation of sources, and on the other hand executing 14876 the program; 14877 14878 - this scheme helps supporting more languages than plain C and C++. 14879 14880 In addition to the change of syntax, the philosophy has changed too: 14881while emphasis was put on speed at the expense of accuracy, today's 14882Autoconf promotes accuracy of the testing framework at, ahem..., the 14883expense of speed. 14884 14885 As a perfect example of what is _not_ to be done, here is how to 14886find out whether a header file contains a particular declaration, such 14887as a typedef, a structure, a structure member, or a function. Use 14888`AC_EGREP_HEADER' instead of running `grep' directly on the header 14889file; on some systems the symbol might be defined in another header 14890file that the file you are checking includes. 14891 14892 As a (bad) example, here is how you should not check for C 14893preprocessor symbols, either defined by header files or predefined by 14894the C preprocessor: using `AC_EGREP_CPP': 14895 14896 AC_EGREP_CPP(yes, 14897 [#ifdef _AIX 14898 yes 14899 #endif 14900 ], is_aix=yes, is_aix=no) 14901 14902 The above example, properly written would (i) use `AC_LANG_PROGRAM', 14903and (ii) run the compiler: 14904 14905 AC_COMPILE_IFELSE([AC_LANG_PROGRAM( 14906 [[#ifndef _AIX 14907 error: This isn't AIX! 14908 #endif 14909 ]])], 14910 [is_aix=yes], 14911 [is_aix=no]) 14912 14913 14914File: autoconf.info, Node: Using Autotest, Next: FAQ, Prev: Obsolete Constructs, Up: Top 14915 1491618 Generating Test Suites with Autotest 14917*************************************** 14918 14919 *N.B.: This section describes an experimental feature which will 14920 be part of Autoconf in a forthcoming release. Although we believe 14921 Autotest is stabilizing, this documentation describes an interface which 14922 might change in the future: do not depend upon Autotest without 14923 subscribing to the Autoconf mailing lists.* 14924 14925 It is paradoxical that portable projects depend on nonportable tools 14926to run their test suite. Autoconf by itself is the paragon of this 14927problem: although it aims at perfectly portability, up to 2.13 its test 14928suite was using DejaGNU, a rich and complex testing framework, but 14929which is far from being standard on Posix systems. Worse yet, it was 14930likely to be missing on the most fragile platforms, the very platforms 14931that are most likely to torture Autoconf and exhibit deficiencies. 14932 14933 To circumvent this problem, many package maintainers have developed 14934their own testing framework, based on simple shell scripts whose sole 14935outputs are exit status values describing whether the test succeeded. 14936Most of these tests share common patterns, and this can result in lots 14937of duplicated code and tedious maintenance. 14938 14939 Following exactly the same reasoning that yielded to the inception of 14940Autoconf, Autotest provides a test suite generation framework, based on 14941M4 macros building a portable shell script. The suite itself is 14942equipped with automatic logging and tracing facilities which greatly 14943diminish the interaction with bug reporters, and simple timing reports. 14944 14945 Autoconf itself has been using Autotest for years, and we do attest 14946that it has considerably improved the strength of the test suite and the 14947quality of bug reports. Other projects are known to use some generation 14948of Autotest, such as Bison, Free Recode, Free Wdiff, GNU Tar, each of 14949them with different needs, and this usage has validated Autotest as a 14950general testing framework. 14951 14952 Nonetheless, compared to DejaGNU, Autotest is inadequate for 14953interactive tool testing, which is probably its main limitation. 14954 14955* Menu: 14956 14957* Using an Autotest Test Suite:: Autotest and the user 14958* Writing testsuite.at:: Autotest macros 14959* testsuite Invocation:: Running `testsuite' scripts 14960* Making testsuite Scripts:: Using autom4te to create `testsuite' 14961 14962 14963File: autoconf.info, Node: Using an Autotest Test Suite, Next: Writing testsuite.at, Up: Using Autotest 14964 1496518.1 Using an Autotest Test Suite 14966================================= 14967 14968* Menu: 14969 14970* testsuite Scripts:: The concepts of Autotest 14971* Autotest Logs:: Their contents 14972 14973 14974File: autoconf.info, Node: testsuite Scripts, Next: Autotest Logs, Up: Using an Autotest Test Suite 14975 1497618.1.1 `testsuite' Scripts 14977-------------------------- 14978 14979Generating testing or validation suites using Autotest is rather easy. 14980The whole validation suite is held in a file to be processed through 14981`autom4te', itself using GNU M4 under the scene, to produce a 14982stand-alone Bourne shell script which then gets distributed. Neither 14983`autom4te' nor GNU M4 are needed at the installer's end. 14984 14985 Each test of the validation suite should be part of some test group. 14986A "test group" is a sequence of interwoven tests that ought to be 14987executed together, usually because one test in the group creates data 14988files than a later test in the same group needs to read. Complex test 14989groups make later debugging more tedious. It is much better to keep 14990only a few tests per test group. Ideally there is only one test per 14991test group. 14992 14993 For all but the simplest packages, some file such as `testsuite.at' 14994does not fully hold all test sources, as these are often easier to 14995maintain in separate files. Each of these separate files holds a single 14996test group, or a sequence of test groups all addressing some common 14997functionality in the package. In such cases, `testsuite.at' merely 14998initializes the validation suite, and sometimes does elementary health 14999checking, before listing include statements for all other test files. 15000The special file `package.m4', containing the identification of the 15001package, is automatically included if found. 15002 15003 A convenient alternative consists in moving all the global issues 15004(local Autotest macros, elementary health checking, and `AT_INIT' 15005invocation) into the file `local.at', and making `testsuite.at' be a 15006simple list of `m4_include' of sub test suites. In such case, 15007generating the whole test suite or pieces of it is only a matter of 15008choosing the `autom4te' command line arguments. 15009 15010 The validation scripts that Autotest produces are by convention 15011called `testsuite'. When run, `testsuite' executes each test group in 15012turn, producing only one summary line per test to say if that 15013particular test succeeded or failed. At end of all tests, summarizing 15014counters get printed. One debugging directory is left for each test 15015group which failed, if any: such directories are named 15016`testsuite.dir/NN', where NN is the sequence number of the test group, 15017and they include: 15018 15019 * a debugging script named `run' which reruns the test in "debug 15020 mode" (*note testsuite Invocation::). The automatic generation of 15021 debugging scripts has the purpose of easing the chase for bugs. 15022 15023 * all the files created with `AT_DATA' 15024 15025 * a log of the run, named `testsuite.log' 15026 15027 In the ideal situation, none of the tests fail, and consequently no 15028debugging directory is left behind for validation. 15029 15030 It often happens in practice that individual tests in the validation 15031suite need to get information coming out of the configuration process. 15032Some of this information, common for all validation suites, is provided 15033through the file `atconfig', automatically created by 15034`AC_CONFIG_TESTDIR'. For configuration informations which your testing 15035environment specifically needs, you might prepare an optional file 15036named `atlocal.in', instantiated by `AC_CONFIG_FILES'. The 15037configuration process produces `atconfig' and `atlocal' out of these 15038two input files, and these two produced files are automatically read by 15039the `testsuite' script. 15040 15041 Here is a diagram showing the relationship between files. 15042 15043Files used in preparing a software package for distribution: 15044 15045 [package.m4] -->. 15046 \ 15047 subfile-1.at ->. [local.at] ---->+ 15048 ... \ \ 15049 subfile-i.at ---->-- testsuite.at -->-- autom4te* -->testsuite 15050 ... / 15051 subfile-n.at ->' 15052 15053Files used in configuring a software package: 15054 15055 .--> atconfig 15056 / 15057 [atlocal.in] --> config.status* --< 15058 \ 15059 `--> [atlocal] 15060 15061Files created during the test suite execution: 15062 15063 atconfig -->. .--> testsuite.log 15064 \ / 15065 >-- testsuite* --< 15066 / \ 15067 [atlocal] ->' `--> [testsuite.dir] 15068 15069 15070File: autoconf.info, Node: Autotest Logs, Prev: testsuite Scripts, Up: Using an Autotest Test Suite 15071 1507218.1.2 Autotest Logs 15073-------------------- 15074 15075When run, the test suite creates a log file named after itself, e.g., a 15076test suite named `testsuite' creates `testsuite.log'. It contains a 15077lot of information, usually more than maintainers actually need, but 15078therefore most of the time it contains all that is needed: 15079 15080command line arguments 15081 A bad but unfortunately widespread habit consists of setting 15082 environment variables before the command, such as in 15083 `CC=my-home-grown-cc ./testsuite'. The test suite does not know 15084 this change, hence (i) it cannot report it to you, and (ii) it 15085 cannot preserve the value of `CC' for subsequent runs. Autoconf 15086 faced exactly the same problem, and solved it by asking users to 15087 pass the variable definitions as command line arguments. Autotest 15088 requires this rule, too, but has no means to enforce it; the log 15089 then contains a trace of the variables that were changed by the 15090 user. 15091 15092`ChangeLog' excerpts 15093 The topmost lines of all the `ChangeLog' files found in the source 15094 hierarchy. This is especially useful when bugs are reported 15095 against development versions of the package, since the version 15096 string does not provide sufficient information to know the exact 15097 state of the sources the user compiled. Of course, this relies on 15098 the use of a `ChangeLog'. 15099 15100build machine 15101 Running a test suite in a cross-compile environment is not an easy 15102 task, since it would mean having the test suite run on a machine 15103 BUILD, while running programs on a machine HOST. It is much 15104 simpler to run both the test suite and the programs on HOST, but 15105 then, from the point of view of the test suite, there remains a 15106 single environment, HOST = BUILD. The log contains relevant 15107 information on the state of the build machine, including some 15108 important environment variables. 15109 15110tested programs 15111 The absolute file name and answers to `--version' of the tested 15112 programs (see *Note Writing testsuite.at::, `AT_TESTED'). 15113 15114configuration log 15115 The contents of `config.log', as created by `configure', are 15116 appended. It contains the configuration flags and a detailed 15117 report on the configuration itself. 15118 15119 15120File: autoconf.info, Node: Writing testsuite.at, Next: testsuite Invocation, Prev: Using an Autotest Test Suite, Up: Using Autotest 15121 1512218.2 Writing `testsuite.at' 15123=========================== 15124 15125The `testsuite.at' is a Bourne shell script making use of special 15126Autotest M4 macros. It often contains a call to `AT_INIT' near its 15127beginning followed by one call to `m4_include' per source file for 15128tests. Each such included file, or the remainder of `testsuite.at' if 15129include files are not used, contain a sequence of test groups. Each 15130test group begins with a call to `AT_SETUP', then an arbitrary number 15131of shell commands or calls to `AT_CHECK', and then completes with a 15132call to `AT_CLEANUP'. 15133 15134 -- Macro: AT_INIT ([NAME]) 15135 Initialize Autotest. Giving a NAME to the test suite is 15136 encouraged if your package includes several test suites. In any 15137 case, the test suite always displays the package name and version. 15138 It also inherits the package bug report address. 15139 15140 -- Macro: AT_COPYRIGHT (COPYRIGHT-NOTICE) 15141 State that, in addition to the Free Software Foundation's 15142 copyright on the Autotest macros, parts of your test suite are 15143 covered by COPYRIGHT-NOTICE. 15144 15145 The COPYRIGHT-NOTICE shows up in both the head of `testsuite' and 15146 in `testsuite --version'. 15147 15148 -- Macro: AT_TESTED (EXECUTABLES) 15149 Log the file name and answer to `--version' of each program in 15150 space-separated list EXECUTABLES. Several invocations register 15151 new executables, in other words, don't fear registering one program 15152 several times. 15153 15154 Autotest test suites rely on `PATH' to find the tested program. 15155This avoids the need to generate absolute names of the various tools, 15156and makes it possible to test installed programs. Therefore, knowing 15157which programs are being exercised is crucial to understanding problems 15158in the test suite itself, or its occasional misuses. It is a good idea 15159to also subscribe foreign programs you depend upon, to avoid 15160incompatible diagnostics. 15161 15162 15163 -- Macro: AT_SETUP (TEST-GROUP-NAME) 15164 This macro starts a group of related tests, all to be executed in 15165 the same subshell. It accepts a single argument, which holds a 15166 few words (no more than about 30 or 40 characters) quickly 15167 describing the purpose of the test group being started. 15168 15169 -- Macro: AT_KEYWORDS (KEYWORDS) 15170 Associate the space-separated list of KEYWORDS to the enclosing 15171 test group. This makes it possible to run "slices" of the test 15172 suite. For instance, if some of your test groups exercise some 15173 `foo' feature, then using `AT_KEYWORDS(foo)' lets you run 15174 `./testsuite -k foo' to run exclusively these test groups. The 15175 TITLE of the test group is automatically recorded to `AT_KEYWORDS'. 15176 15177 Several invocations within a test group accumulate new keywords. 15178 In other words, don't fear registering the same keyword several 15179 times in a test group. 15180 15181 -- Macro: AT_CAPTURE_FILE (FILE) 15182 If the current test group fails, log the contents of FILE. 15183 Several identical calls within one test group have no additional 15184 effect. 15185 15186 -- Macro: AT_XFAIL_IF (SHELL-CONDITION) 15187 Determine whether the test is expected to fail because it is a 15188 known bug (for unsupported features, you should skip the test). 15189 SHELL-CONDITION is a shell expression such as a `test' command; 15190 you can instantiate this macro many times from within the same 15191 test group, and one of the conditions is enough to turn the test 15192 into an expected failure. 15193 15194 -- Macro: AT_CLEANUP 15195 End the current test group. 15196 15197 15198 -- Macro: AT_DATA (FILE, CONTENTS) 15199 Initialize an input data FILE with given CONTENTS. Of course, the 15200 CONTENTS have to be properly quoted between square brackets to 15201 protect against included commas or spurious M4 expansion. The 15202 contents ought to end with an end of line. 15203 15204 -- Macro: AT_CHECK (COMMANDS, [STATUS = `0'], [STDOUT = `'], [STDERR = 15205 `'], [RUN-IF-FAIL], [RUN-IF-PASS]) 15206 Execute a test by performing given shell COMMANDS. These commands 15207 should normally exit with STATUS, while producing expected STDOUT 15208 and STDERR contents. If COMMANDS exit with status 77, then the 15209 whole test group is skipped. Otherwise, if this test fails, run 15210 shell commands RUN-IF-FAIL or, if this test passes, run shell 15211 commands RUN-IF-PASS. 15212 15213 The COMMANDS _must not_ redirect the standard output, nor the 15214 standard error. 15215 15216 If STATUS, or STDOUT, or STDERR is `ignore', then the 15217 corresponding value is not checked. 15218 15219 The special value `expout' for STDOUT means the expected output of 15220 the COMMANDS is the content of the file `expout'. If STDOUT is 15221 `stdout', then the standard output of the COMMANDS is available 15222 for further tests in the file `stdout'. Similarly for STDERR with 15223 `experr' and `stderr'. 15224 15225 15226File: autoconf.info, Node: testsuite Invocation, Next: Making testsuite Scripts, Prev: Writing testsuite.at, Up: Using Autotest 15227 1522818.3 Running `testsuite' Scripts 15229================================ 15230 15231Autotest test suites support the following arguments: 15232 15233`--help' 15234`-h' 15235 Display the list of options and exit successfully. 15236 15237`--version' 15238`-V' 15239 Display the version of the test suite and exit successfully. 15240 15241`--clean' 15242`-c' 15243 Remove all the files the test suite might have created and exit. 15244 Meant for `clean' Make targets. 15245 15246`--list' 15247`-l' 15248 List all the tests (or only the selection), including their 15249 possible keywords. 15250 15251 15252 By default all tests are performed (or described with `--list') in 15253the default environment first silently, then verbosely, but the 15254environment, set of tests, and verbosity level can be tuned: 15255 15256`VARIABLE=VALUE' 15257 Set the environment VARIABLE to VALUE. Use this rather than 15258 `FOO=foo ./testsuite' as debugging scripts would then run in a 15259 different environment. 15260 15261 The variable `AUTOTEST_PATH' specifies the testing path to prepend 15262 to `PATH'. Relative directory names (not starting with `/') are 15263 considered to be relative to the top level of the package being 15264 built. All directories are made absolute, first starting from the 15265 top level _build_ tree, then from the _source_ tree. For instance 15266 `./testsuite AUTOTEST_PATH=tests:bin' for a `/src/foo-1.0' source 15267 package built in `/tmp/foo' results in 15268 `/tmp/foo/tests:/tmp/foo/bin' and then 15269 `/src/foo-1.0/tests:/src/foo-1.0/bin' being prepended to `PATH'. 15270 15271`NUMBER' 15272`NUMBER-NUMBER' 15273`NUMBER-' 15274`-NUMBER' 15275 Add the corresponding test groups, with obvious semantics, to the 15276 selection. 15277 15278`--keywords=KEYWORDS' 15279`-k KEYWORDS' 15280 Add to the selection the test groups with title or keywords 15281 (arguments to `AT_SETUP' or `AT_KEYWORDS') that match _all_ 15282 keywords of the comma separated list KEYWORDS, case-insensitively. 15283 Use `!' immediately before the keyword to invert the selection 15284 for this keyword. By default, the keywords match whole words; 15285 enclose them in `.*' to also match parts of words. 15286 15287 For example, running 15288 15289 ./testsuite -k 'autoupdate,.*FUNC.*' 15290 15291 selects all tests tagged `autoupdate' _and_ with tags containing 15292 `FUNC' (as in `AC_CHECK_FUNC', `AC_FUNC_ALLOCA', etc.), while 15293 15294 ./testsuite -k '!autoupdate' -k '.*FUNC.*' 15295 15296 selects all tests not tagged `autoupdate' _or_ with tags 15297 containing `FUNC'. 15298 15299`--errexit' 15300`-e' 15301 If any test fails, immediately abort testing. It implies 15302 `--debug': post test group clean up, and top-level logging are 15303 inhibited. This option is meant for the full test suite, it is 15304 not really useful for generated debugging scripts. 15305 15306`--verbose' 15307`-v' 15308 Force more verbosity in the detailed output of what is being done. 15309 This is the default for debugging scripts. 15310 15311`--debug' 15312`-d' 15313 Do not remove the files after a test group was performed --but 15314 they are still removed _before_, therefore using this option is 15315 sane when running several test groups. Create debugging scripts. 15316 Do not overwrite the top-level log (in order to preserve 15317 supposedly existing full log file). This is the default for 15318 debugging scripts, but it can also be useful to debug the 15319 testsuite itself. 15320 15321`--trace' 15322`-x' 15323 Trigger shell tracing of the test groups. 15324 15325 15326File: autoconf.info, Node: Making testsuite Scripts, Prev: testsuite Invocation, Up: Using Autotest 15327 1532818.4 Making `testsuite' Scripts 15329=============================== 15330 15331For putting Autotest into movement, you need some configuration and 15332makefile machinery. We recommend, at least if your package uses deep or 15333shallow hierarchies, that you use `tests/' as the name of the directory 15334holding all your tests and their makefile. Here is a check list of 15335things to do. 15336 15337 - Make sure to create the file `package.m4', which defines the 15338 identity of the package. It must define `AT_PACKAGE_STRING', the 15339 full signature of the package, and `AT_PACKAGE_BUGREPORT', the 15340 address to which bug reports should be sent. For sake of 15341 completeness, we suggest that you also define `AT_PACKAGE_NAME', 15342 `AT_PACKAGE_TARNAME', and `AT_PACKAGE_VERSION'. *Note 15343 Initializing configure::, for a description of these variables. We 15344 suggest the following makefile excerpt: 15345 15346 $(srcdir)/package.m4: $(top_srcdir)/configure.ac 15347 { \ 15348 echo '# Signature of the current package.'; \ 15349 echo 'm4_define([AT_PACKAGE_NAME], [@PACKAGE_NAME@])'; \ 15350 echo 'm4_define([AT_PACKAGE_TARNAME], [@PACKAGE_TARNAME@])'; \ 15351 echo 'm4_define([AT_PACKAGE_VERSION], [@PACKAGE_VERSION@])'; \ 15352 echo 'm4_define([AT_PACKAGE_STRING], [@PACKAGE_STRING@])'; \ 15353 echo 'm4_define([AT_PACKAGE_BUGREPORT], [@PACKAGE_BUGREPORT@])'; \ 15354 } >'$(srcdir)/package.m4' 15355 15356 Be sure to distribute `package.m4' and to put it into the source 15357 hierarchy: the test suite ought to be shipped! 15358 15359 - Invoke `AC_CONFIG_TESTDIR'. 15360 15361 -- Macro: AC_CONFIG_TESTDIR (DIRECTORY, [TEST-PATH = `directory']) 15362 An Autotest test suite is to be configured in DIRECTORY. This 15363 macro requires the instantiation of `DIRECTORY/atconfig' from 15364 `DIRECTORY/atconfig.in', and sets the default `AUTOTEST_PATH' 15365 to TEST-PATH (*note testsuite Invocation::). 15366 15367 - Still within `configure.ac', as appropriate, ensure that some 15368 `AC_CONFIG_FILES' command includes substitution for 15369 `tests/atlocal'. 15370 15371 - The `tests/Makefile.in' should be modified so the validation in 15372 your package is triggered by `make check'. An example is provided 15373 below. 15374 15375 With Automake, here is a minimal example about how to link `make 15376check' with a validation suite. 15377 15378 EXTRA_DIST = testsuite.at $(TESTSUITE) atlocal.in 15379 TESTSUITE = $(srcdir)/testsuite 15380 15381 check-local: atconfig atlocal $(TESTSUITE) 15382 $(SHELL) '$(TESTSUITE)' $(TESTSUITEFLAGS) 15383 15384 installcheck-local: atconfig atlocal $(TESTSUITE) 15385 $(SHELL) '$(TESTSUITE)' AUTOTEST_PATH='$(bindir)' \ 15386 $(TESTSUITEFLAGS) 15387 15388 clean-local: 15389 test ! -f '$(TESTSUITE)' || \ 15390 $(SHELL) '$(TESTSUITE)' --clean 15391 15392 AUTOTEST = $(AUTOM4TE) --language=autotest 15393 $(TESTSUITE): $(srcdir)/testsuite.at 15394 $(AUTOTEST) -I '$(srcdir)' -o $@.tmp $@.at 15395 mv $@.tmp $@ 15396 15397 You might want to list explicitly the dependencies, i.e., the list of 15398the files `testsuite.at' includes. 15399 15400 With strict Autoconf, you might need to add lines inspired from the 15401following: 15402 15403 subdir = tests 15404 15405 atconfig: $(top_builddir)/config.status 15406 cd $(top_builddir) && \ 15407 $(SHELL) ./config.status $(subdir)/$@ 15408 15409 atlocal: $(srcdir)/atlocal.in $(top_builddir)/config.status 15410 cd $(top_builddir) && \ 15411 $(SHELL) ./config.status $(subdir)/$@ 15412 15413and manage to have `atconfig.in' and `$(EXTRA_DIST)' distributed. 15414 15415 With all this in place, and if you have not initialized 15416`TESTSUITEFLAGS' within your makefile, you can fine-tune test suite 15417execution with this variable, for example: 15418 15419 make check TESTSUITEFLAGS='-v -d -x 75 -k AC_PROG_CC CFLAGS=-g' 15420 15421 15422File: autoconf.info, Node: FAQ, Next: History, Prev: Using Autotest, Up: Top 15423 1542419 Frequent Autoconf Questions, with answers 15425******************************************** 15426 15427Several questions about Autoconf come up occasionally. Here some of 15428them are addressed. 15429 15430* Menu: 15431 15432* Distributing:: Distributing `configure' scripts 15433* Why GNU M4:: Why not use the standard M4? 15434* Bootstrapping:: Autoconf and GNU M4 require each other? 15435* Why Not Imake:: Why GNU uses `configure' instead of Imake 15436* Defining Directories:: Passing `datadir' to program 15437* autom4te.cache:: What is it? Can I remove it? 15438* Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree 15439 15440 15441File: autoconf.info, Node: Distributing, Next: Why GNU M4, Up: FAQ 15442 1544319.1 Distributing `configure' Scripts 15444===================================== 15445 15446 What are the restrictions on distributing `configure' 15447 scripts that Autoconf generates? How does that affect my 15448 programs that use them? 15449 15450 There are no restrictions on how the configuration scripts that 15451Autoconf produces may be distributed or used. In Autoconf version 1, 15452they were covered by the GNU General Public License. We still encourage 15453software authors to distribute their work under terms like those of the 15454GPL, but doing so is not required to use Autoconf. 15455 15456 Of the other files that might be used with `configure', 15457`config.h.in' is under whatever copyright you use for your 15458`configure.ac'. `config.sub' and `config.guess' have an exception to 15459the GPL when they are used with an Autoconf-generated `configure' 15460script, which permits you to distribute them under the same terms as 15461the rest of your package. `install-sh' is from the X Consortium and is 15462not copyrighted. 15463 15464 15465File: autoconf.info, Node: Why GNU M4, Next: Bootstrapping, Prev: Distributing, Up: FAQ 15466 1546719.2 Why Require GNU M4? 15468======================== 15469 15470 Why does Autoconf require GNU M4? 15471 15472 Many M4 implementations have hard-coded limitations on the size and 15473number of macros that Autoconf exceeds. They also lack several builtin 15474macros that it would be difficult to get along without in a 15475sophisticated application like Autoconf, including: 15476 15477 m4_builtin 15478 m4_indir 15479 m4_bpatsubst 15480 __file__ 15481 __line__ 15482 15483 Autoconf requires version 1.4.7 or later of GNU M4. 15484 15485 Since only software maintainers need to use Autoconf, and since GNU 15486M4 is simple to configure and install, it seems reasonable to require 15487GNU M4 to be installed also. Many maintainers of GNU and other free 15488software already have most of the GNU utilities installed, since they 15489prefer them. 15490 15491 15492File: autoconf.info, Node: Bootstrapping, Next: Why Not Imake, Prev: Why GNU M4, Up: FAQ 15493 1549419.3 How Can I Bootstrap? 15495========================= 15496 15497 If Autoconf requires GNU M4 and GNU M4 has an Autoconf 15498 `configure' script, how do I bootstrap? It seems like a chicken 15499 and egg problem! 15500 15501 This is a misunderstanding. Although GNU M4 does come with a 15502`configure' script produced by Autoconf, Autoconf is not required in 15503order to run the script and install GNU M4. Autoconf is only required 15504if you want to change the M4 `configure' script, which few people have 15505to do (mainly its maintainer). 15506 15507 15508File: autoconf.info, Node: Why Not Imake, Next: Defining Directories, Prev: Bootstrapping, Up: FAQ 15509 1551019.4 Why Not Imake? 15511=================== 15512 15513 Why not use Imake instead of `configure' scripts? 15514 15515 Several people have written addressing this question, so I include 15516adaptations of their explanations here. 15517 15518 The following answer is based on one written by Richard Pixley: 15519 15520 Autoconf generated scripts frequently work on machines that it has 15521 never been set up to handle before. That is, it does a good job of 15522 inferring a configuration for a new system. Imake cannot do this. 15523 15524 Imake uses a common database of host specific data. For X11, this 15525 makes sense because the distribution is made as a collection of 15526 tools, by one central authority who has control over the database. 15527 15528 GNU tools are not released this way. Each GNU tool has a 15529 maintainer; these maintainers are scattered across the world. 15530 Using a common database would be a maintenance nightmare. 15531 Autoconf may appear to be this kind of database, but in fact it is 15532 not. Instead of listing host dependencies, it lists program 15533 requirements. 15534 15535 If you view the GNU suite as a collection of native tools, then the 15536 problems are similar. But the GNU development tools can be 15537 configured as cross tools in almost any host+target permutation. 15538 All of these configurations can be installed concurrently. They 15539 can even be configured to share host independent files across 15540 hosts. Imake doesn't address these issues. 15541 15542 Imake templates are a form of standardization. The GNU coding 15543 standards address the same issues without necessarily imposing the 15544 same restrictions. 15545 15546 Here is some further explanation, written by Per Bothner: 15547 15548 One of the advantages of Imake is that it easy to generate large 15549 makefiles using the `#include' and macro mechanisms of `cpp'. 15550 However, `cpp' is not programmable: it has limited conditional 15551 facilities, and no looping. And `cpp' cannot inspect its 15552 environment. 15553 15554 All of these problems are solved by using `sh' instead of `cpp'. 15555 The shell is fully programmable, has macro substitution, can 15556 execute (or source) other shell scripts, and can inspect its 15557 environment. 15558 15559 Paul Eggert elaborates more: 15560 15561 With Autoconf, installers need not assume that Imake itself is 15562 already installed and working well. This may not seem like much 15563 of an advantage to people who are accustomed to Imake. But on 15564 many hosts Imake is not installed or the default installation is 15565 not working well, and requiring Imake to install a package hinders 15566 the acceptance of that package on those hosts. For example, the 15567 Imake template and configuration files might not be installed 15568 properly on a host, or the Imake build procedure might wrongly 15569 assume that all source files are in one big directory tree, or the 15570 Imake configuration might assume one compiler whereas the package 15571 or the installer needs to use another, or there might be a version 15572 mismatch between the Imake expected by the package and the Imake 15573 supported by the host. These problems are much rarer with 15574 Autoconf, where each package comes with its own independent 15575 configuration processor. 15576 15577 Also, Imake often suffers from unexpected interactions between 15578 `make' and the installer's C preprocessor. The fundamental problem 15579 here is that the C preprocessor was designed to preprocess C 15580 programs, not makefiles. This is much less of a problem with 15581 Autoconf, which uses the general-purpose preprocessor M4, and 15582 where the package's author (rather than the installer) does the 15583 preprocessing in a standard way. 15584 15585 Finally, Mark Eichin notes: 15586 15587 Imake isn't all that extensible, either. In order to add new 15588 features to Imake, you need to provide your own project template, 15589 and duplicate most of the features of the existing one. This 15590 means that for a sophisticated project, using the vendor-provided 15591 Imake templates fails to provide any leverage--since they don't 15592 cover anything that your own project needs (unless it is an X11 15593 program). 15594 15595 On the other side, though: 15596 15597 The one advantage that Imake has over `configure': `Imakefile' 15598 files tend to be much shorter (likewise, less redundant) than 15599 `Makefile.in' files. There is a fix to this, however--at least 15600 for the Kerberos V5 tree, we've modified things to call in common 15601 `post.in' and `pre.in' makefile fragments for the entire tree. 15602 This means that a lot of common things don't have to be 15603 duplicated, even though they normally are in `configure' setups. 15604 15605 15606File: autoconf.info, Node: Defining Directories, Next: autom4te.cache, Prev: Why Not Imake, Up: FAQ 15607 1560819.5 How Do I `#define' Installation Directories? 15609================================================= 15610 15611 My program needs library files, installed in `datadir' and 15612 similar. If I use 15613 AC_DEFINE_UNQUOTED([DATADIR], [$datadir], 15614 [Define to the read-only architecture-independent 15615 data directory.]) 15616 15617 I get 15618 #define DATADIR "${prefix}/share" 15619 15620As already explained, this behavior is on purpose, mandated by the GNU 15621Coding Standards, see *Note Installation Directory Variables::. There 15622are several means to achieve a similar goal: 15623 15624 - Do not use `AC_DEFINE' but use your makefile to pass the actual 15625 value of `datadir' via compilation flags. *Note Installation 15626 Directory Variables::, for the details. 15627 15628 - This solution can be simplified when compiling a program: you may 15629 either extend the `CPPFLAGS': 15630 15631 CPPFLAGS = -DDATADIR='"$(datadir)"' @CPPFLAGS@ 15632 15633 or create a dedicated header file: 15634 15635 DISTCLEANFILES = datadir.h 15636 datadir.h: Makefile 15637 echo '#define DATADIR "$(datadir)"' >$@ 15638 15639 - Use `AC_DEFINE' but have `configure' compute the literal value of 15640 `datadir' and others. Many people have wrapped macros to automate 15641 this task. For instance, the macro `AC_DEFINE_DIR' from the 15642 Autoconf Macro Archive (http://autoconf-archive.cryp.to/). 15643 15644 This solution does not conform to the GNU Coding Standards. 15645 15646 - Note that all the previous solutions hard wire the absolute name of 15647 these directories in the executables, which is not a good 15648 property. You may try to compute the names relative to `prefix', 15649 and try to find `prefix' at runtime, this way your package is 15650 relocatable. Some macros are already available to address this 15651 issue: see `adl_COMPUTE_RELATIVE_PATHS' and 15652 `adl_COMPUTE_STANDARD_RELATIVE_PATHS' on the Autoconf Macro 15653 Archive (http://autoconf-archive.cryp.to/). 15654 15655 15656File: autoconf.info, Node: autom4te.cache, Next: Present But Cannot Be Compiled, Prev: Defining Directories, Up: FAQ 15657 1565819.6 What is `autom4te.cache'? 15659============================== 15660 15661 What is this directory `autom4te.cache'? Can I safely remove it? 15662 15663 In the GNU Build System, `configure.ac' plays a central role and is 15664read by many tools: `autoconf' to create `configure', `autoheader' to 15665create `config.h.in', `automake' to create `Makefile.in', `autoscan' to 15666check the completeness of `configure.ac', `autoreconf' to check the GNU 15667Build System components that are used. To "read `configure.ac'" 15668actually means to compile it with M4, which can be a long process for 15669complex `configure.ac'. 15670 15671 This is why all these tools, instead of running directly M4, invoke 15672`autom4te' (*note autom4te Invocation::) which, while answering to a 15673specific demand, stores additional information in `autom4te.cache' for 15674future runs. For instance, if you run `autoconf', behind the scenes, 15675`autom4te' also stores information for the other tools, so that when 15676you invoke `autoheader' or `automake' etc., reprocessing `configure.ac' 15677is not needed. The speed up is frequently of 30%, and is increasing 15678with the size of `configure.ac'. 15679 15680 But it is and remains being simply a cache: you can safely remove it. 15681 15682 15683 Can I permanently get rid of it? 15684 15685 The creation of this cache can be disabled from `~/.autom4te.cfg', 15686see *Note Customizing autom4te::, for more details. You should be 15687aware that disabling the cache slows down the Autoconf test suite by 1568840%. The more GNU Build System components are used, the more the cache 15689is useful; for instance running `autoreconf -f' on the Core Utilities 15690is twice slower without the cache _although `--force' implies that the 15691cache is not fully exploited_, and eight times slower than without 15692`--force'. 15693 15694 15695File: autoconf.info, Node: Present But Cannot Be Compiled, Prev: autom4te.cache, Up: FAQ 15696 1569719.7 Header Present But Cannot Be Compiled 15698========================================== 15699 15700The most important guideline to bear in mind when checking for features 15701is to mimic as much as possible the intended use. Unfortunately, old 15702versions of `AC_CHECK_HEADER' and `AC_CHECK_HEADERS' failed to follow 15703this idea, and called the preprocessor, instead of the compiler, to 15704check for headers. As a result, incompatibilities between headers went 15705unnoticed during configuration, and maintainers finally had to deal 15706with this issue elsewhere. 15707 15708 As of Autoconf 2.56 both checks are performed, and `configure' 15709complains loudly if the compiler and the preprocessor do not agree. 15710For the time being the result used is that of the preprocessor, to give 15711maintainers time to adjust their `configure.ac', but in the future, 15712only the compiler will be considered. 15713 15714 Consider the following example: 15715 15716 $ cat number.h 15717 typedef int number; 15718 $ cat pi.h 15719 const number pi = 3; 15720 $ cat configure.ac 15721 AC_INIT([Example], [1.0], [bug-example@example.org]) 15722 AC_CHECK_HEADERS([pi.h]) 15723 $ autoconf -Wall 15724 $ ./configure 15725 checking for gcc... gcc 15726 checking for C compiler default output file name... a.out 15727 checking whether the C compiler works... yes 15728 checking whether we are cross compiling... no 15729 checking for suffix of executables... 15730 checking for suffix of object files... o 15731 checking whether we are using the GNU C compiler... yes 15732 checking whether gcc accepts -g... yes 15733 checking for gcc option to accept ISO C89... none needed 15734 checking how to run the C preprocessor... gcc -E 15735 checking for grep that handles long lines and -e... grep 15736 checking for egrep... grep -E 15737 checking for ANSI C header files... yes 15738 checking for sys/types.h... yes 15739 checking for sys/stat.h... yes 15740 checking for stdlib.h... yes 15741 checking for string.h... yes 15742 checking for memory.h... yes 15743 checking for strings.h... yes 15744 checking for inttypes.h... yes 15745 checking for stdint.h... yes 15746 checking for unistd.h... yes 15747 checking pi.h usability... no 15748 checking pi.h presence... yes 15749 configure: WARNING: pi.h: present but cannot be compiled 15750 configure: WARNING: pi.h: check for missing prerequisite headers? 15751 configure: WARNING: pi.h: see the Autoconf documentation 15752 configure: WARNING: pi.h: section "Present But Cannot Be Compiled" 15753 configure: WARNING: pi.h: proceeding with the preprocessor's result 15754 configure: WARNING: pi.h: in the future, the compiler will take precedence 15755 configure: WARNING: ## -------------------------------------- ## 15756 configure: WARNING: ## Report this to bug-example@example.org ## 15757 configure: WARNING: ## -------------------------------------- ## 15758 checking for pi.h... yes 15759 15760The proper way the handle this case is using the fourth argument (*note 15761Generic Headers::): 15762 15763 $ cat configure.ac 15764 AC_INIT([Example], [1.0], [bug-example@example.org]) 15765 AC_CHECK_HEADERS([number.h pi.h], [], [], 15766 [[#ifdef HAVE_NUMBER_H 15767 # include <number.h> 15768 #endif 15769 ]]) 15770 $ autoconf -Wall 15771 $ ./configure 15772 checking for gcc... gcc 15773 checking for C compiler default output... a.out 15774 checking whether the C compiler works... yes 15775 checking whether we are cross compiling... no 15776 checking for suffix of executables... 15777 checking for suffix of object files... o 15778 checking whether we are using the GNU C compiler... yes 15779 checking whether gcc accepts -g... yes 15780 checking for gcc option to accept ANSI C... none needed 15781 checking for number.h... yes 15782 checking for pi.h... yes 15783 15784 See *Note Particular Headers::, for a list of headers with their 15785prerequisite. 15786 15787 15788File: autoconf.info, Node: History, Next: Copying This Manual, Prev: FAQ, Up: Top 15789 1579020 History of Autoconf 15791********************** 15792 15793You may be wondering, Why was Autoconf originally written? How did it 15794get into its present form? (Why does it look like gorilla spit?) If 15795you're not wondering, then this chapter contains no information useful 15796to you, and you might as well skip it. If you _are_ wondering, then 15797let there be light.... 15798 15799* Menu: 15800 15801* Genesis:: Prehistory and naming of `configure' 15802* Exodus:: The plagues of M4 and Perl 15803* Leviticus:: The priestly code of portability arrives 15804* Numbers:: Growth and contributors 15805* Deuteronomy:: Approaching the promises of easy configuration 15806 15807 15808File: autoconf.info, Node: Genesis, Next: Exodus, Up: History 15809 1581020.1 Genesis 15811============ 15812 15813In June 1991 I was maintaining many of the GNU utilities for the Free 15814Software Foundation. As they were ported to more platforms and more 15815programs were added, the number of `-D' options that users had to 15816select in the makefile (around 20) became burdensome. Especially for 15817me--I had to test each new release on a bunch of different systems. So 15818I wrote a little shell script to guess some of the correct settings for 15819the fileutils package, and released it as part of fileutils 2.0. That 15820`configure' script worked well enough that the next month I adapted it 15821(by hand) to create similar `configure' scripts for several other GNU 15822utilities packages. Brian Berliner also adapted one of my scripts for 15823his CVS revision control system. 15824 15825 Later that summer, I learned that Richard Stallman and Richard Pixley 15826were developing similar scripts to use in the GNU compiler tools; so I 15827adapted my `configure' scripts to support their evolving interface: 15828using the file name `Makefile.in' as the templates; adding `+srcdir', 15829the first option (of many); and creating `config.status' files. 15830 15831 15832File: autoconf.info, Node: Exodus, Next: Leviticus, Prev: Genesis, Up: History 15833 1583420.2 Exodus 15835=========== 15836 15837As I got feedback from users, I incorporated many improvements, using 15838Emacs to search and replace, cut and paste, similar changes in each of 15839the scripts. As I adapted more GNU utilities packages to use 15840`configure' scripts, updating them all by hand became impractical. 15841Rich Murphey, the maintainer of the GNU graphics utilities, sent me 15842mail saying that the `configure' scripts were great, and asking if I 15843had a tool for generating them that I could send him. No, I thought, 15844but I should! So I started to work out how to generate them. And the 15845journey from the slavery of hand-written `configure' scripts to the 15846abundance and ease of Autoconf began. 15847 15848 Cygnus `configure', which was being developed at around that time, 15849is table driven; it is meant to deal mainly with a discrete number of 15850system types with a small number of mainly unguessable features (such as 15851details of the object file format). The automatic configuration system 15852that Brian Fox had developed for Bash takes a similar approach. For 15853general use, it seems to me a hopeless cause to try to maintain an 15854up-to-date database of which features each variant of each operating 15855system has. It's easier and more reliable to check for most features on 15856the fly--especially on hybrid systems that people have hacked on 15857locally or that have patches from vendors installed. 15858 15859 I considered using an architecture similar to that of Cygnus 15860`configure', where there is a single `configure' script that reads 15861pieces of `configure.in' when run. But I didn't want to have to 15862distribute all of the feature tests with every package, so I settled on 15863having a different `configure' made from each `configure.in' by a 15864preprocessor. That approach also offered more control and flexibility. 15865 15866 I looked briefly into using the Metaconfig package, by Larry Wall, 15867Harlan Stenn, and Raphael Manfredi, but I decided not to for several 15868reasons. The `Configure' scripts it produces are interactive, which I 15869find quite inconvenient; I didn't like the ways it checked for some 15870features (such as library functions); I didn't know that it was still 15871being maintained, and the `Configure' scripts I had seen didn't work on 15872many modern systems (such as System V R4 and NeXT); it wasn't flexible 15873in what it could do in response to a feature's presence or absence; I 15874found it confusing to learn; and it was too big and complex for my 15875needs (I didn't realize then how much Autoconf would eventually have to 15876grow). 15877 15878 I considered using Perl to generate my style of `configure' scripts, 15879but decided that M4 was better suited to the job of simple textual 15880substitutions: it gets in the way less, because output is implicit. 15881Plus, everyone already has it. (Initially I didn't rely on the GNU 15882extensions to M4.) Also, some of my friends at the University of 15883Maryland had recently been putting M4 front ends on several programs, 15884including `tvtwm', and I was interested in trying out a new language. 15885 15886 15887File: autoconf.info, Node: Leviticus, Next: Numbers, Prev: Exodus, Up: History 15888 1588920.3 Leviticus 15890============== 15891 15892Since my `configure' scripts determine the system's capabilities 15893automatically, with no interactive user intervention, I decided to call 15894the program that generates them Autoconfig. But with a version number 15895tacked on, that name would be too long for old Unix file systems, so I 15896shortened it to Autoconf. 15897 15898 In the fall of 1991 I called together a group of fellow questers 15899after the Holy Grail of portability (er, that is, alpha testers) to 15900give me feedback as I encapsulated pieces of my handwritten scripts in 15901M4 macros and continued to add features and improve the techniques used 15902in the checks. Prominent among the testers were Franc,ois Pinard, who 15903came up with the idea of making an Autoconf shell script to run M4 and 15904check for unresolved macro calls; Richard Pixley, who suggested running 15905the compiler instead of searching the file system to find include files 15906and symbols, for more accurate results; Karl Berry, who got Autoconf to 15907configure TeX and added the macro index to the documentation; and Ian 15908Lance Taylor, who added support for creating a C header file as an 15909alternative to putting `-D' options in a makefile, so he could use 15910Autoconf for his UUCP package. The alpha testers cheerfully adjusted 15911their files again and again as the names and calling conventions of the 15912Autoconf macros changed from release to release. They all contributed 15913many specific checks, great ideas, and bug fixes. 15914 15915 15916File: autoconf.info, Node: Numbers, Next: Deuteronomy, Prev: Leviticus, Up: History 15917 1591820.4 Numbers 15919============ 15920 15921In July 1992, after months of alpha testing, I released Autoconf 1.0, 15922and converted many GNU packages to use it. I was surprised by how 15923positive the reaction to it was. More people started using it than I 15924could keep track of, including people working on software that wasn't 15925part of the GNU Project (such as TCL, FSP, and Kerberos V5). Autoconf 15926continued to improve rapidly, as many people using the `configure' 15927scripts reported problems they encountered. 15928 15929 Autoconf turned out to be a good torture test for M4 implementations. 15930Unix M4 started to dump core because of the length of the macros that 15931Autoconf defined, and several bugs showed up in GNU M4 as well. 15932Eventually, we realized that we needed to use some features that only 15933GNU M4 has. 4.3BSD M4, in particular, has an impoverished set of 15934builtin macros; the System V version is better, but still doesn't 15935provide everything we need. 15936 15937 More development occurred as people put Autoconf under more stresses 15938(and to uses I hadn't anticipated). Karl Berry added checks for X11. 15939david zuhn contributed C++ support. Franc,ois Pinard made it diagnose 15940invalid arguments. Jim Blandy bravely coerced it into configuring GNU 15941Emacs, laying the groundwork for several later improvements. Roland 15942McGrath got it to configure the GNU C Library, wrote the `autoheader' 15943script to automate the creation of C header file templates, and added a 15944`--verbose' option to `configure'. Noah Friedman added the 15945`--autoconf-dir' option and `AC_MACRODIR' environment variable. (He 15946also coined the term "autoconfiscate" to mean "adapt a software package 15947to use Autoconf".) Roland and Noah improved the quoting protection in 15948`AC_DEFINE' and fixed many bugs, especially when I got sick of dealing 15949with portability problems from February through June, 1993. 15950 15951 15952File: autoconf.info, Node: Deuteronomy, Prev: Numbers, Up: History 15953 1595420.5 Deuteronomy 15955================ 15956 15957A long wish list for major features had accumulated, and the effect of 15958several years of patching by various people had left some residual 15959cruft. In April 1994, while working for Cygnus Support, I began a major 15960revision of Autoconf. I added most of the features of the Cygnus 15961`configure' that Autoconf had lacked, largely by adapting the relevant 15962parts of Cygnus `configure' with the help of david zuhn and Ken 15963Raeburn. These features include support for using `config.sub', 15964`config.guess', `--host', and `--target'; making links to files; and 15965running `configure' scripts in subdirectories. Adding these features 15966enabled Ken to convert GNU `as', and Rob Savoye to convert DejaGNU, to 15967using Autoconf. 15968 15969 I added more features in response to other peoples' requests. Many 15970people had asked for `configure' scripts to share the results of the 15971checks between runs, because (particularly when configuring a large 15972source tree, like Cygnus does) they were frustratingly slow. Mike 15973Haertel suggested adding site-specific initialization scripts. People 15974distributing software that had to unpack on MS-DOS asked for a way to 15975override the `.in' extension on the file names, which produced file 15976names like `config.h.in' containing two dots. Jim Avera did an 15977extensive examination of the problems with quoting in `AC_DEFINE' and 15978`AC_SUBST'; his insights led to significant improvements. Richard 15979Stallman asked that compiler output be sent to `config.log' instead of 15980`/dev/null', to help people debug the Emacs `configure' script. 15981 15982 I made some other changes because of my dissatisfaction with the 15983quality of the program. I made the messages showing results of the 15984checks less ambiguous, always printing a result. I regularized the 15985names of the macros and cleaned up coding style inconsistencies. I 15986added some auxiliary utilities that I had developed to help convert 15987source code packages to use Autoconf. With the help of Franc,ois 15988Pinard, I made the macros not interrupt each others' messages. (That 15989feature revealed some performance bottlenecks in GNU M4, which he 15990hastily corrected!) I reorganized the documentation around problems 15991people want to solve. And I began a test suite, because experience had 15992shown that Autoconf has a pronounced tendency to regress when we change 15993it. 15994 15995 Again, several alpha testers gave invaluable feedback, especially 15996Franc,ois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn, 15997and Mark Eichin. 15998 15999 Finally, version 2.0 was ready. And there was much rejoicing. (And 16000I have free time again. I think. Yeah, right.) 16001 16002 16003File: autoconf.info, Node: Copying This Manual, Next: Indices, Prev: History, Up: Top 16004 16005Appendix A Copying This Manual 16006****************************** 16007 16008* Menu: 16009 16010* GNU Free Documentation License:: License for copying this manual 16011 16012 16013File: autoconf.info, Node: GNU Free Documentation License, Up: Copying This Manual 16014 16015A.1 GNU Free Documentation License 16016================================== 16017 16018 Version 1.2, November 2002 16019 16020 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 16021 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA 16022 16023 Everyone is permitted to copy and distribute verbatim copies 16024 of this license document, but changing it is not allowed. 16025 16026 0. PREAMBLE 16027 16028 The purpose of this License is to make a manual, textbook, or other 16029 functional and useful document "free" in the sense of freedom: to 16030 assure everyone the effective freedom to copy and redistribute it, 16031 with or without modifying it, either commercially or 16032 noncommercially. Secondarily, this License preserves for the 16033 author and publisher a way to get credit for their work, while not 16034 being considered responsible for modifications made by others. 16035 16036 This License is a kind of "copyleft", which means that derivative 16037 works of the document must themselves be free in the same sense. 16038 It complements the GNU General Public License, which is a copyleft 16039 license designed for free software. 16040 16041 We have designed this License in order to use it for manuals for 16042 free software, because free software needs free documentation: a 16043 free program should come with manuals providing the same freedoms 16044 that the software does. But this License is not limited to 16045 software manuals; it can be used for any textual work, regardless 16046 of subject matter or whether it is published as a printed book. 16047 We recommend this License principally for works whose purpose is 16048 instruction or reference. 16049 16050 1. APPLICABILITY AND DEFINITIONS 16051 16052 This License applies to any manual or other work, in any medium, 16053 that contains a notice placed by the copyright holder saying it 16054 can be distributed under the terms of this License. Such a notice 16055 grants a world-wide, royalty-free license, unlimited in duration, 16056 to use that work under the conditions stated herein. The 16057 "Document", below, refers to any such manual or work. Any member 16058 of the public is a licensee, and is addressed as "you". You 16059 accept the license if you copy, modify or distribute the work in a 16060 way requiring permission under copyright law. 16061 16062 A "Modified Version" of the Document means any work containing the 16063 Document or a portion of it, either copied verbatim, or with 16064 modifications and/or translated into another language. 16065 16066 A "Secondary Section" is a named appendix or a front-matter section 16067 of the Document that deals exclusively with the relationship of the 16068 publishers or authors of the Document to the Document's overall 16069 subject (or to related matters) and contains nothing that could 16070 fall directly within that overall subject. (Thus, if the Document 16071 is in part a textbook of mathematics, a Secondary Section may not 16072 explain any mathematics.) The relationship could be a matter of 16073 historical connection with the subject or with related matters, or 16074 of legal, commercial, philosophical, ethical or political position 16075 regarding them. 16076 16077 The "Invariant Sections" are certain Secondary Sections whose 16078 titles are designated, as being those of Invariant Sections, in 16079 the notice that says that the Document is released under this 16080 License. If a section does not fit the above definition of 16081 Secondary then it is not allowed to be designated as Invariant. 16082 The Document may contain zero Invariant Sections. If the Document 16083 does not identify any Invariant Sections then there are none. 16084 16085 The "Cover Texts" are certain short passages of text that are 16086 listed, as Front-Cover Texts or Back-Cover Texts, in the notice 16087 that says that the Document is released under this License. A 16088 Front-Cover Text may be at most 5 words, and a Back-Cover Text may 16089 be at most 25 words. 16090 16091 A "Transparent" copy of the Document means a machine-readable copy, 16092 represented in a format whose specification is available to the 16093 general public, that is suitable for revising the document 16094 straightforwardly with generic text editors or (for images 16095 composed of pixels) generic paint programs or (for drawings) some 16096 widely available drawing editor, and that is suitable for input to 16097 text formatters or for automatic translation to a variety of 16098 formats suitable for input to text formatters. A copy made in an 16099 otherwise Transparent file format whose markup, or absence of 16100 markup, has been arranged to thwart or discourage subsequent 16101 modification by readers is not Transparent. An image format is 16102 not Transparent if used for any substantial amount of text. A 16103 copy that is not "Transparent" is called "Opaque". 16104 16105 Examples of suitable formats for Transparent copies include plain 16106 ASCII without markup, Texinfo input format, LaTeX input format, 16107 SGML or XML using a publicly available DTD, and 16108 standard-conforming simple HTML, PostScript or PDF designed for 16109 human modification. Examples of transparent image formats include 16110 PNG, XCF and JPG. Opaque formats include proprietary formats that 16111 can be read and edited only by proprietary word processors, SGML or 16112 XML for which the DTD and/or processing tools are not generally 16113 available, and the machine-generated HTML, PostScript or PDF 16114 produced by some word processors for output purposes only. 16115 16116 The "Title Page" means, for a printed book, the title page itself, 16117 plus such following pages as are needed to hold, legibly, the 16118 material this License requires to appear in the title page. For 16119 works in formats which do not have any title page as such, "Title 16120 Page" means the text near the most prominent appearance of the 16121 work's title, preceding the beginning of the body of the text. 16122 16123 A section "Entitled XYZ" means a named subunit of the Document 16124 whose title either is precisely XYZ or contains XYZ in parentheses 16125 following text that translates XYZ in another language. (Here XYZ 16126 stands for a specific section name mentioned below, such as 16127 "Acknowledgements", "Dedications", "Endorsements", or "History".) 16128 To "Preserve the Title" of such a section when you modify the 16129 Document means that it remains a section "Entitled XYZ" according 16130 to this definition. 16131 16132 The Document may include Warranty Disclaimers next to the notice 16133 which states that this License applies to the Document. These 16134 Warranty Disclaimers are considered to be included by reference in 16135 this License, but only as regards disclaiming warranties: any other 16136 implication that these Warranty Disclaimers may have is void and 16137 has no effect on the meaning of this License. 16138 16139 2. VERBATIM COPYING 16140 16141 You may copy and distribute the Document in any medium, either 16142 commercially or noncommercially, provided that this License, the 16143 copyright notices, and the license notice saying this License 16144 applies to the Document are reproduced in all copies, and that you 16145 add no other conditions whatsoever to those of this License. You 16146 may not use technical measures to obstruct or control the reading 16147 or further copying of the copies you make or distribute. However, 16148 you may accept compensation in exchange for copies. If you 16149 distribute a large enough number of copies you must also follow 16150 the conditions in section 3. 16151 16152 You may also lend copies, under the same conditions stated above, 16153 and you may publicly display copies. 16154 16155 3. COPYING IN QUANTITY 16156 16157 If you publish printed copies (or copies in media that commonly 16158 have printed covers) of the Document, numbering more than 100, and 16159 the Document's license notice requires Cover Texts, you must 16160 enclose the copies in covers that carry, clearly and legibly, all 16161 these Cover Texts: Front-Cover Texts on the front cover, and 16162 Back-Cover Texts on the back cover. Both covers must also clearly 16163 and legibly identify you as the publisher of these copies. The 16164 front cover must present the full title with all words of the 16165 title equally prominent and visible. You may add other material 16166 on the covers in addition. Copying with changes limited to the 16167 covers, as long as they preserve the title of the Document and 16168 satisfy these conditions, can be treated as verbatim copying in 16169 other respects. 16170 16171 If the required texts for either cover are too voluminous to fit 16172 legibly, you should put the first ones listed (as many as fit 16173 reasonably) on the actual cover, and continue the rest onto 16174 adjacent pages. 16175 16176 If you publish or distribute Opaque copies of the Document 16177 numbering more than 100, you must either include a 16178 machine-readable Transparent copy along with each Opaque copy, or 16179 state in or with each Opaque copy a computer-network location from 16180 which the general network-using public has access to download 16181 using public-standard network protocols a complete Transparent 16182 copy of the Document, free of added material. If you use the 16183 latter option, you must take reasonably prudent steps, when you 16184 begin distribution of Opaque copies in quantity, to ensure that 16185 this Transparent copy will remain thus accessible at the stated 16186 location until at least one year after the last time you 16187 distribute an Opaque copy (directly or through your agents or 16188 retailers) of that edition to the public. 16189 16190 It is requested, but not required, that you contact the authors of 16191 the Document well before redistributing any large number of 16192 copies, to give them a chance to provide you with an updated 16193 version of the Document. 16194 16195 4. MODIFICATIONS 16196 16197 You may copy and distribute a Modified Version of the Document 16198 under the conditions of sections 2 and 3 above, provided that you 16199 release the Modified Version under precisely this License, with 16200 the Modified Version filling the role of the Document, thus 16201 licensing distribution and modification of the Modified Version to 16202 whoever possesses a copy of it. In addition, you must do these 16203 things in the Modified Version: 16204 16205 A. Use in the Title Page (and on the covers, if any) a title 16206 distinct from that of the Document, and from those of 16207 previous versions (which should, if there were any, be listed 16208 in the History section of the Document). You may use the 16209 same title as a previous version if the original publisher of 16210 that version gives permission. 16211 16212 B. List on the Title Page, as authors, one or more persons or 16213 entities responsible for authorship of the modifications in 16214 the Modified Version, together with at least five of the 16215 principal authors of the Document (all of its principal 16216 authors, if it has fewer than five), unless they release you 16217 from this requirement. 16218 16219 C. State on the Title page the name of the publisher of the 16220 Modified Version, as the publisher. 16221 16222 D. Preserve all the copyright notices of the Document. 16223 16224 E. Add an appropriate copyright notice for your modifications 16225 adjacent to the other copyright notices. 16226 16227 F. Include, immediately after the copyright notices, a license 16228 notice giving the public permission to use the Modified 16229 Version under the terms of this License, in the form shown in 16230 the Addendum below. 16231 16232 G. Preserve in that license notice the full lists of Invariant 16233 Sections and required Cover Texts given in the Document's 16234 license notice. 16235 16236 H. Include an unaltered copy of this License. 16237 16238 I. Preserve the section Entitled "History", Preserve its Title, 16239 and add to it an item stating at least the title, year, new 16240 authors, and publisher of the Modified Version as given on 16241 the Title Page. If there is no section Entitled "History" in 16242 the Document, create one stating the title, year, authors, 16243 and publisher of the Document as given on its Title Page, 16244 then add an item describing the Modified Version as stated in 16245 the previous sentence. 16246 16247 J. Preserve the network location, if any, given in the Document 16248 for public access to a Transparent copy of the Document, and 16249 likewise the network locations given in the Document for 16250 previous versions it was based on. These may be placed in 16251 the "History" section. You may omit a network location for a 16252 work that was published at least four years before the 16253 Document itself, or if the original publisher of the version 16254 it refers to gives permission. 16255 16256 K. For any section Entitled "Acknowledgements" or "Dedications", 16257 Preserve the Title of the section, and preserve in the 16258 section all the substance and tone of each of the contributor 16259 acknowledgements and/or dedications given therein. 16260 16261 L. Preserve all the Invariant Sections of the Document, 16262 unaltered in their text and in their titles. Section numbers 16263 or the equivalent are not considered part of the section 16264 titles. 16265 16266 M. Delete any section Entitled "Endorsements". Such a section 16267 may not be included in the Modified Version. 16268 16269 N. Do not retitle any existing section to be Entitled 16270 "Endorsements" or to conflict in title with any Invariant 16271 Section. 16272 16273 O. Preserve any Warranty Disclaimers. 16274 16275 If the Modified Version includes new front-matter sections or 16276 appendices that qualify as Secondary Sections and contain no 16277 material copied from the Document, you may at your option 16278 designate some or all of these sections as invariant. To do this, 16279 add their titles to the list of Invariant Sections in the Modified 16280 Version's license notice. These titles must be distinct from any 16281 other section titles. 16282 16283 You may add a section Entitled "Endorsements", provided it contains 16284 nothing but endorsements of your Modified Version by various 16285 parties--for example, statements of peer review or that the text 16286 has been approved by an organization as the authoritative 16287 definition of a standard. 16288 16289 You may add a passage of up to five words as a Front-Cover Text, 16290 and a passage of up to 25 words as a Back-Cover Text, to the end 16291 of the list of Cover Texts in the Modified Version. Only one 16292 passage of Front-Cover Text and one of Back-Cover Text may be 16293 added by (or through arrangements made by) any one entity. If the 16294 Document already includes a cover text for the same cover, 16295 previously added by you or by arrangement made by the same entity 16296 you are acting on behalf of, you may not add another; but you may 16297 replace the old one, on explicit permission from the previous 16298 publisher that added the old one. 16299 16300 The author(s) and publisher(s) of the Document do not by this 16301 License give permission to use their names for publicity for or to 16302 assert or imply endorsement of any Modified Version. 16303 16304 5. COMBINING DOCUMENTS 16305 16306 You may combine the Document with other documents released under 16307 this License, under the terms defined in section 4 above for 16308 modified versions, provided that you include in the combination 16309 all of the Invariant Sections of all of the original documents, 16310 unmodified, and list them all as Invariant Sections of your 16311 combined work in its license notice, and that you preserve all 16312 their Warranty Disclaimers. 16313 16314 The combined work need only contain one copy of this License, and 16315 multiple identical Invariant Sections may be replaced with a single 16316 copy. If there are multiple Invariant Sections with the same name 16317 but different contents, make the title of each such section unique 16318 by adding at the end of it, in parentheses, the name of the 16319 original author or publisher of that section if known, or else a 16320 unique number. Make the same adjustment to the section titles in 16321 the list of Invariant Sections in the license notice of the 16322 combined work. 16323 16324 In the combination, you must combine any sections Entitled 16325 "History" in the various original documents, forming one section 16326 Entitled "History"; likewise combine any sections Entitled 16327 "Acknowledgements", and any sections Entitled "Dedications". You 16328 must delete all sections Entitled "Endorsements." 16329 16330 6. COLLECTIONS OF DOCUMENTS 16331 16332 You may make a collection consisting of the Document and other 16333 documents released under this License, and replace the individual 16334 copies of this License in the various documents with a single copy 16335 that is included in the collection, provided that you follow the 16336 rules of this License for verbatim copying of each of the 16337 documents in all other respects. 16338 16339 You may extract a single document from such a collection, and 16340 distribute it individually under this License, provided you insert 16341 a copy of this License into the extracted document, and follow 16342 this License in all other respects regarding verbatim copying of 16343 that document. 16344 16345 7. AGGREGATION WITH INDEPENDENT WORKS 16346 16347 A compilation of the Document or its derivatives with other 16348 separate and independent documents or works, in or on a volume of 16349 a storage or distribution medium, is called an "aggregate" if the 16350 copyright resulting from the compilation is not used to limit the 16351 legal rights of the compilation's users beyond what the individual 16352 works permit. When the Document is included in an aggregate, this 16353 License does not apply to the other works in the aggregate which 16354 are not themselves derivative works of the Document. 16355 16356 If the Cover Text requirement of section 3 is applicable to these 16357 copies of the Document, then if the Document is less than one half 16358 of the entire aggregate, the Document's Cover Texts may be placed 16359 on covers that bracket the Document within the aggregate, or the 16360 electronic equivalent of covers if the Document is in electronic 16361 form. Otherwise they must appear on printed covers that bracket 16362 the whole aggregate. 16363 16364 8. TRANSLATION 16365 16366 Translation is considered a kind of modification, so you may 16367 distribute translations of the Document under the terms of section 16368 4. Replacing Invariant Sections with translations requires special 16369 permission from their copyright holders, but you may include 16370 translations of some or all Invariant Sections in addition to the 16371 original versions of these Invariant Sections. You may include a 16372 translation of this License, and all the license notices in the 16373 Document, and any Warranty Disclaimers, provided that you also 16374 include the original English version of this License and the 16375 original versions of those notices and disclaimers. In case of a 16376 disagreement between the translation and the original version of 16377 this License or a notice or disclaimer, the original version will 16378 prevail. 16379 16380 If a section in the Document is Entitled "Acknowledgements", 16381 "Dedications", or "History", the requirement (section 4) to 16382 Preserve its Title (section 1) will typically require changing the 16383 actual title. 16384 16385 9. TERMINATION 16386 16387 You may not copy, modify, sublicense, or distribute the Document 16388 except as expressly provided for under this License. Any other 16389 attempt to copy, modify, sublicense or distribute the Document is 16390 void, and will automatically terminate your rights under this 16391 License. However, parties who have received copies, or rights, 16392 from you under this License will not have their licenses 16393 terminated so long as such parties remain in full compliance. 16394 16395 10. FUTURE REVISIONS OF THIS LICENSE 16396 16397 The Free Software Foundation may publish new, revised versions of 16398 the GNU Free Documentation License from time to time. Such new 16399 versions will be similar in spirit to the present version, but may 16400 differ in detail to address new problems or concerns. See 16401 `http://www.gnu.org/copyleft/'. 16402 16403 Each version of the License is given a distinguishing version 16404 number. If the Document specifies that a particular numbered 16405 version of this License "or any later version" applies to it, you 16406 have the option of following the terms and conditions either of 16407 that specified version or of any later version that has been 16408 published (not as a draft) by the Free Software Foundation. If 16409 the Document does not specify a version number of this License, 16410 you may choose any version ever published (not as a draft) by the 16411 Free Software Foundation. 16412 16413ADDENDUM: How to use this License for your documents 16414==================================================== 16415 16416To use this License in a document you have written, include a copy of 16417the License in the document and put the following copyright and license 16418notices just after the title page: 16419 16420 Copyright (C) YEAR YOUR NAME. 16421 Permission is granted to copy, distribute and/or modify this document 16422 under the terms of the GNU Free Documentation License, Version 1.2 16423 or any later version published by the Free Software Foundation; 16424 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 16425 Texts. A copy of the license is included in the section entitled ``GNU 16426 Free Documentation License''. 16427 16428 If you have Invariant Sections, Front-Cover Texts and Back-Cover 16429Texts, replace the "with...Texts." line with this: 16430 16431 with the Invariant Sections being LIST THEIR TITLES, with 16432 the Front-Cover Texts being LIST, and with the Back-Cover Texts 16433 being LIST. 16434 16435 If you have Invariant Sections without Cover Texts, or some other 16436combination of the three, merge those two alternatives to suit the 16437situation. 16438 16439 If your document contains nontrivial examples of program code, we 16440recommend releasing these examples in parallel under your choice of 16441free software license, such as the GNU General Public License, to 16442permit their use in free software. 16443 16444 16445File: autoconf.info, Node: Indices, Prev: Copying This Manual, Up: Top 16446 16447Appendix B Indices 16448****************** 16449 16450* Menu: 16451 16452* Environment Variable Index:: Index of environment variables used 16453* Output Variable Index:: Index of variables set in output files 16454* Preprocessor Symbol Index:: Index of C preprocessor symbols defined 16455* Autoconf Macro Index:: Index of Autoconf macros 16456* M4 Macro Index:: Index of M4, M4sugar, and M4sh macros 16457* Autotest Macro Index:: Index of Autotest macros 16458* Program & Function Index:: Index of those with portability problems 16459* Concept Index:: General index 16460 16461 16462File: autoconf.info, Node: Environment Variable Index, Next: Output Variable Index, Up: Indices 16463 16464B.1 Environment Variable Index 16465============================== 16466 16467This is an alphabetical list of the environment variables that Autoconf 16468checks. 16469 16470[index] 16471* Menu: 16472 16473* BIN_SH: Special Shell Variables. 16474 (line 27) 16475* CDPATH: Special Shell Variables. 16476 (line 31) 16477* CONFIG_COMMANDS: Obsolete config.status Use. 16478 (line 11) 16479* CONFIG_FILES: Obsolete config.status Use. 16480 (line 15) 16481* CONFIG_HEADERS: Obsolete config.status Use. 16482 (line 20) 16483* CONFIG_LINKS: Obsolete config.status Use. 16484 (line 25) 16485* CONFIG_SHELL: config.status Invocation. 16486 (line 81) 16487* CONFIG_SITE: Site Defaults. (line 10) 16488* CONFIG_STATUS: config.status Invocation. 16489 (line 90) 16490* DUALCASE: Special Shell Variables. 16491 (line 54) 16492* ENV: Special Shell Variables. 16493 (line 64) 16494* IFS: Special Shell Variables. 16495 (line 77) 16496* LANG: Special Shell Variables. 16497 (line 101) 16498* LANGUAGE: Special Shell Variables. 16499 (line 110) 16500* LC_ADDRESS: Special Shell Variables. 16501 (line 120) 16502* LC_ALL: Special Shell Variables. 16503 (line 101) 16504* LC_COLLATE: Special Shell Variables. 16505 (line 101) 16506* LC_CTYPE: Special Shell Variables. 16507 (line 101) 16508* LC_IDENTIFICATION: Special Shell Variables. 16509 (line 120) 16510* LC_MEASUREMENT: Special Shell Variables. 16511 (line 120) 16512* LC_MESSAGES: Special Shell Variables. 16513 (line 101) 16514* LC_MONETARY: Special Shell Variables. 16515 (line 101) 16516* LC_NAME: Special Shell Variables. 16517 (line 120) 16518* LC_NUMERIC: Special Shell Variables. 16519 (line 101) 16520* LC_PAPER: Special Shell Variables. 16521 (line 120) 16522* LC_TELEPHONE: Special Shell Variables. 16523 (line 120) 16524* LC_TIME: Special Shell Variables. 16525 (line 101) 16526* M4: autom4te Invocation. (line 10) 16527* MAIL: Special Shell Variables. 16528 (line 64) 16529* MAILPATH: Special Shell Variables. 16530 (line 64) 16531* NULLCMD: Special Shell Variables. 16532 (line 201) 16533* PATH_SEPARATOR: Special Shell Variables. 16534 (line 208) 16535* PS1: Special Shell Variables. 16536 (line 64) 16537* PS2: Special Shell Variables. 16538 (line 64) 16539* PS4: Special Shell Variables. 16540 (line 64) 16541* PWD: Special Shell Variables. 16542 (line 217) 16543* SIMPLE_BACKUP_SUFFIX: autoupdate Invocation. 16544 (line 16) 16545* WARNINGS <1>: autom4te Invocation. (line 58) 16546* WARNINGS <2>: autoheader Invocation. 16547 (line 77) 16548* WARNINGS <3>: autoreconf Invocation. 16549 (line 94) 16550* WARNINGS: autoconf Invocation. (line 63) 16551* XMKMF: System Services. (line 10) 16552 16553 16554File: autoconf.info, Node: Output Variable Index, Next: Preprocessor Symbol Index, Prev: Environment Variable Index, Up: Indices 16555 16556B.2 Output Variable Index 16557========================= 16558 16559This is an alphabetical list of the variables that Autoconf can 16560substitute into files that it creates, typically one or more makefiles. 16561*Note Setting Output Variables::, for more information on how this is 16562done. 16563 16564[index] 16565* Menu: 16566 16567* abs_builddir: Preset Output Variables. 16568 (line 143) 16569* abs_srcdir: Preset Output Variables. 16570 (line 157) 16571* abs_top_builddir: Preset Output Variables. 16572 (line 150) 16573* abs_top_srcdir: Preset Output Variables. 16574 (line 164) 16575* ALLOCA: Particular Functions. 16576 (line 10) 16577* AWK: Particular Programs. (line 10) 16578* bindir: Installation Directory Variables. 16579 (line 12) 16580* build: Canonicalizing. (line 26) 16581* build_alias: Canonicalizing. (line 9) 16582* build_cpu: Canonicalizing. (line 26) 16583* build_os: Canonicalizing. (line 26) 16584* build_vendor: Canonicalizing. (line 26) 16585* builddir: Preset Output Variables. 16586 (line 140) 16587* CC <1>: System Services. (line 49) 16588* CC: C Compiler. (line 61) 16589* CFLAGS <1>: C Compiler. (line 61) 16590* CFLAGS: Preset Output Variables. 16591 (line 15) 16592* configure_input: Preset Output Variables. 16593 (line 33) 16594* CPP: C Compiler. (line 98) 16595* CPPFLAGS: Preset Output Variables. 16596 (line 47) 16597* cross_compiling: Runtime. (line 56) 16598* CXX: C++ Compiler. (line 7) 16599* CXXCPP: C++ Compiler. (line 31) 16600* CXXFLAGS <1>: C++ Compiler. (line 7) 16601* CXXFLAGS: Preset Output Variables. 16602 (line 69) 16603* datadir: Installation Directory Variables. 16604 (line 15) 16605* datarootdir: Installation Directory Variables. 16606 (line 19) 16607* DEFS: Preset Output Variables. 16608 (line 73) 16609* docdir: Installation Directory Variables. 16610 (line 23) 16611* dvidir: Installation Directory Variables. 16612 (line 27) 16613* ECHO_C: Preset Output Variables. 16614 (line 83) 16615* ECHO_N: Preset Output Variables. 16616 (line 83) 16617* ECHO_T: Preset Output Variables. 16618 (line 83) 16619* EGREP: Particular Programs. (line 23) 16620* ERL <1>: Running the Compiler. 16621 (line 23) 16622* ERL <2>: Language Choice. (line 40) 16623* ERL: Erlang Compiler and Interpreter. 16624 (line 29) 16625* ERLANG_INSTALL_LIB_DIR <1>: Erlang Libraries. (line 52) 16626* ERLANG_INSTALL_LIB_DIR: Installation Directory Variables. 16627 (line 192) 16628* ERLANG_INSTALL_LIB_DIR_LIBRARY <1>: Erlang Libraries. (line 60) 16629* ERLANG_INSTALL_LIB_DIR_LIBRARY: Installation Directory Variables. 16630 (line 197) 16631* ERLANG_LIB_DIR: Erlang Libraries. (line 18) 16632* ERLANG_LIB_DIR_LIBRARY: Erlang Libraries. (line 26) 16633* ERLANG_LIB_VER_LIBRARY: Erlang Libraries. (line 26) 16634* ERLANG_ROOT_DIR: Erlang Libraries. (line 12) 16635* ERLC <1>: Language Choice. (line 40) 16636* ERLC: Erlang Compiler and Interpreter. 16637 (line 10) 16638* ERLCFLAGS <1>: Language Choice. (line 40) 16639* ERLCFLAGS <2>: Erlang Compiler and Interpreter. 16640 (line 10) 16641* ERLCFLAGS: Preset Output Variables. 16642 (line 95) 16643* exec_prefix: Installation Directory Variables. 16644 (line 30) 16645* EXEEXT <1>: Obsolete Macros. (line 165) 16646* EXEEXT: Compilers and Preprocessors. 16647 (line 6) 16648* F77: Fortran Compiler. (line 18) 16649* FC: Fortran Compiler. (line 39) 16650* FCFLAGS <1>: Fortran Compiler. (line 39) 16651* FCFLAGS: Preset Output Variables. 16652 (line 101) 16653* FCLIBS: Fortran Compiler. (line 79) 16654* FFLAGS <1>: Fortran Compiler. (line 18) 16655* FFLAGS: Preset Output Variables. 16656 (line 108) 16657* FGREP: Particular Programs. (line 28) 16658* FLIBS: Fortran Compiler. (line 79) 16659* GETGROUPS_LIBS: Particular Functions. 16660 (line 124) 16661* GETLOADAVG_LIBS: Particular Functions. 16662 (line 130) 16663* GREP: Particular Programs. (line 16) 16664* host: Canonicalizing. (line 34) 16665* host_alias: Canonicalizing. (line 9) 16666* host_cpu: Canonicalizing. (line 34) 16667* host_os: Canonicalizing. (line 34) 16668* host_vendor: Canonicalizing. (line 34) 16669* htmldir: Installation Directory Variables. 16670 (line 37) 16671* includedir: Installation Directory Variables. 16672 (line 40) 16673* infodir: Installation Directory Variables. 16674 (line 43) 16675* INSTALL: Particular Programs. (line 33) 16676* INSTALL_DATA: Particular Programs. (line 33) 16677* INSTALL_PROGRAM: Particular Programs. (line 33) 16678* INSTALL_SCRIPT: Particular Programs. (line 33) 16679* KMEM_GROUP: Particular Functions. 16680 (line 130) 16681* LDFLAGS: Preset Output Variables. 16682 (line 115) 16683* LEX: Particular Programs. (line 96) 16684* LEX_OUTPUT_ROOT: Particular Programs. (line 96) 16685* LEXLIB: Particular Programs. (line 96) 16686* libdir: Installation Directory Variables. 16687 (line 46) 16688* libexecdir: Installation Directory Variables. 16689 (line 49) 16690* LIBOBJDIR: AC_LIBOBJ vs LIBOBJS. 16691 (line 35) 16692* LIBOBJS <1>: Particular Structures. 16693 (line 34) 16694* LIBOBJS <2>: Generic Functions. (line 52) 16695* LIBOBJS: Particular Functions. 16696 (line 130) 16697* LIBS <1>: Obsolete Macros. (line 425) 16698* LIBS <2>: Posix Variants. (line 23) 16699* LIBS: Preset Output Variables. 16700 (line 129) 16701* LN_S: Particular Programs. (line 137) 16702* localedir: Installation Directory Variables. 16703 (line 52) 16704* localstatedir: Installation Directory Variables. 16705 (line 57) 16706* mandir: Installation Directory Variables. 16707 (line 60) 16708* MKDIR_P: Particular Programs. (line 65) 16709* NEED_SETGID: Particular Functions. 16710 (line 130) 16711* OBJC: Objective C Compiler. 16712 (line 7) 16713* OBJCCPP: Objective C Compiler. 16714 (line 26) 16715* OBJCFLAGS <1>: Objective C Compiler. 16716 (line 7) 16717* OBJCFLAGS: Preset Output Variables. 16718 (line 136) 16719* OBJEXT <1>: Obsolete Macros. (line 330) 16720* OBJEXT: Compilers and Preprocessors. 16721 (line 11) 16722* oldincludedir: Installation Directory Variables. 16723 (line 63) 16724* PACKAGE_BUGREPORT: Initializing configure. 16725 (line 44) 16726* PACKAGE_NAME: Initializing configure. 16727 (line 32) 16728* PACKAGE_STRING: Initializing configure. 16729 (line 41) 16730* PACKAGE_TARNAME: Initializing configure. 16731 (line 35) 16732* PACKAGE_VERSION: Initializing configure. 16733 (line 38) 16734* pdfdir: Installation Directory Variables. 16735 (line 66) 16736* POW_LIB: Particular Functions. 16737 (line 338) 16738* prefix: Installation Directory Variables. 16739 (line 69) 16740* program_transform_name: Transforming Names. (line 11) 16741* psdir: Installation Directory Variables. 16742 (line 74) 16743* RANLIB: Particular Programs. (line 156) 16744* sbindir: Installation Directory Variables. 16745 (line 77) 16746* SED: Particular Programs. (line 160) 16747* SET_MAKE: Output. (line 45) 16748* sharedstatedir: Installation Directory Variables. 16749 (line 81) 16750* srcdir: Preset Output Variables. 16751 (line 153) 16752* subdirs: Subdirectories. (line 12) 16753* sysconfdir: Installation Directory Variables. 16754 (line 85) 16755* target: Canonicalizing. (line 41) 16756* target_alias: Canonicalizing. (line 9) 16757* target_cpu: Canonicalizing. (line 41) 16758* target_os: Canonicalizing. (line 41) 16759* target_vendor: Canonicalizing. (line 41) 16760* top_builddir: Preset Output Variables. 16761 (line 146) 16762* top_srcdir: Preset Output Variables. 16763 (line 160) 16764* X_CFLAGS: System Services. (line 30) 16765* X_EXTRA_LIBS: System Services. (line 30) 16766* X_LIBS: System Services. (line 30) 16767* X_PRE_LIBS: System Services. (line 30) 16768* YACC: Particular Programs. (line 166) 16769 16770 16771File: autoconf.info, Node: Preprocessor Symbol Index, Next: Autoconf Macro Index, Prev: Output Variable Index, Up: Indices 16772 16773B.3 Preprocessor Symbol Index 16774============================= 16775 16776This is an alphabetical list of the C preprocessor symbols that the 16777Autoconf macros define. To work with Autoconf, C source code needs to 16778use these names in `#if' or `#ifdef' directives. 16779 16780[index] 16781* Menu: 16782 16783* __CHAR_UNSIGNED__: C Compiler. (line 251) 16784* __EXTENSIONS__: Posix Variants. (line 39) 16785* __PROTOTYPES: C Compiler. (line 301) 16786* _ALL_SOURCE: Posix Variants. (line 13) 16787* _FILE_OFFSET_BITS: System Services. (line 49) 16788* _GNU_SOURCE: Posix Variants. (line 18) 16789* _LARGE_FILES: System Services. (line 49) 16790* _LARGEFILE_SOURCE: Particular Functions. 16791 (line 116) 16792* _MINIX: Posix Variants. (line 33) 16793* _POSIX_1_SOURCE: Posix Variants. (line 33) 16794* _POSIX_PTHREAD_SEMANTICS: Posix Variants. (line 39) 16795* _POSIX_SOURCE: Posix Variants. (line 33) 16796* _POSIX_VERSION: Particular Headers. (line 208) 16797* _TANDEM_SOURCE: Posix Variants. (line 39) 16798* C_ALLOCA: Particular Functions. 16799 (line 10) 16800* C_GETLOADAVG: Particular Functions. 16801 (line 130) 16802* CLOSEDIR_VOID: Particular Functions. 16803 (line 58) 16804* const: C Compiler. (line 184) 16805* CXX_NO_MINUS_C_MINUS_O: C++ Compiler. (line 44) 16806* DGUX: Particular Functions. 16807 (line 130) 16808* DIRENT: Obsolete Macros. (line 146) 16809* F77_DUMMY_MAIN: Fortran Compiler. (line 107) 16810* F77_FUNC: Fortran Compiler. (line 166) 16811* F77_FUNC_: Fortran Compiler. (line 166) 16812* F77_MAIN: Fortran Compiler. (line 150) 16813* F77_NO_MINUS_C_MINUS_O: Fortran Compiler. (line 66) 16814* FC_FUNC: Fortran Compiler. (line 166) 16815* FC_FUNC_: Fortran Compiler. (line 166) 16816* FC_MAIN: Fortran Compiler. (line 150) 16817* FC_NO_MINUS_C_MINUS_O: Fortran Compiler. (line 66) 16818* FLEXIBLE_ARRAY_MEMBER: C Compiler. (line 265) 16819* GETGROUPS_T: Particular Types. (line 14) 16820* GETLODAVG_PRIVILEGED: Particular Functions. 16821 (line 130) 16822* GETPGRP_VOID: Particular Functions. 16823 (line 170) 16824* gid_t: Particular Types. (line 95) 16825* GWINSZ_IN_SYS_IOCTL: Particular Headers. (line 248) 16826* HAVE__BOOL: Particular Headers. (line 92) 16827* HAVE_ALLOCA_H: Particular Functions. 16828 (line 10) 16829* HAVE_C_VARARRAYS: C Compiler. (line 289) 16830* HAVE_CONFIG_H: Configuration Headers. 16831 (line 33) 16832* HAVE_DECL_STRERROR_R: Particular Functions. 16833 (line 321) 16834* HAVE_DECL_SYMBOL: Generic Declarations. 16835 (line 24) 16836* HAVE_DIRENT_H: Particular Headers. (line 15) 16837* HAVE_DOPRNT: Particular Functions. 16838 (line 359) 16839* HAVE_FUNCTION: Generic Functions. (line 25) 16840* HAVE_GETMNTENT: Particular Functions. 16841 (line 164) 16842* HAVE_HEADER: Generic Headers. (line 23) 16843* HAVE_INT16_T: Particular Types. (line 24) 16844* HAVE_INT32_T: Particular Types. (line 27) 16845* HAVE_INT64_T: Particular Types. (line 30) 16846* HAVE_INT8_T: Particular Types. (line 18) 16847* HAVE_INTMAX_T: Particular Types. (line 33) 16848* HAVE_INTPTR_T: Particular Types. (line 38) 16849* HAVE_LONG_DOUBLE <1>: Obsolete Macros. (line 29) 16850* HAVE_LONG_DOUBLE: Particular Types. (line 43) 16851* HAVE_LONG_DOUBLE_WIDER: Particular Types. (line 48) 16852* HAVE_LONG_FILE_NAMES: System Services. (line 71) 16853* HAVE_LONG_LONG_INT: Particular Types. (line 53) 16854* HAVE_LSTAT_EMPTY_STRING_BUG: Particular Functions. 16855 (line 295) 16856* HAVE_MALLOC: Particular Functions. 16857 (line 203) 16858* HAVE_MBRTOWC: Particular Functions. 16859 (line 245) 16860* HAVE_MMAP: Particular Functions. 16861 (line 255) 16862* HAVE_NDIR_H: Particular Headers. (line 15) 16863* HAVE_NLIST_H: Particular Functions. 16864 (line 130) 16865* HAVE_OBSTACK: Particular Functions. 16866 (line 260) 16867* HAVE_REALLOC: Particular Functions. 16868 (line 264) 16869* HAVE_RESOLV_H: Particular Headers. (line 63) 16870* HAVE_RESTARTABLE_SYSCALLS: Obsolete Macros. (line 463) 16871* HAVE_ST_BLKSIZE: Particular Structures. 16872 (line 26) 16873* HAVE_ST_BLOCKS: Particular Structures. 16874 (line 34) 16875* HAVE_ST_RDEV: Particular Structures. 16876 (line 40) 16877* HAVE_STAT_EMPTY_STRING_BUG: Particular Functions. 16878 (line 295) 16879* HAVE_STDBOOL_H: Particular Headers. (line 92) 16880* HAVE_STRCOLL: Particular Functions. 16881 (line 315) 16882* HAVE_STRERROR_R: Particular Functions. 16883 (line 321) 16884* HAVE_STRFTIME: Particular Functions. 16885 (line 331) 16886* HAVE_STRINGIZE: C Compiler. (line 255) 16887* HAVE_STRNLEN: Particular Functions. 16888 (line 348) 16889* HAVE_STRUCT_DIRENT_D_INO: Particular Structures. 16890 (line 9) 16891* HAVE_STRUCT_DIRENT_D_TYPE: Particular Structures. 16892 (line 21) 16893* HAVE_STRUCT_STAT_ST_BLKSIZE: Particular Structures. 16894 (line 26) 16895* HAVE_STRUCT_STAT_ST_BLOCKS: Particular Structures. 16896 (line 34) 16897* HAVE_STRUCT_STAT_ST_RDEV: Particular Structures. 16898 (line 40) 16899* HAVE_SYS_DIR_H: Particular Headers. (line 15) 16900* HAVE_SYS_NDIR_H: Particular Headers. (line 15) 16901* HAVE_SYS_WAIT_H: Particular Headers. (line 187) 16902* HAVE_TM_ZONE: Particular Structures. 16903 (line 56) 16904* HAVE_TYPEOF: C Compiler. (line 295) 16905* HAVE_TZNAME: Particular Structures. 16906 (line 56) 16907* HAVE_UINT16_T: Particular Types. (line 104) 16908* HAVE_UINT32_T: Particular Types. (line 108) 16909* HAVE_UINT64_T: Particular Types. (line 112) 16910* HAVE_UINT8_T: Particular Types. (line 99) 16911* HAVE_UINTMAX_T: Particular Types. (line 116) 16912* HAVE_UINTPTR_T: Particular Types. (line 121) 16913* HAVE_UNSIGNED_LONG_LONG_INT: Particular Types. (line 126) 16914* HAVE_UTIME_NULL: Particular Functions. 16915 (line 352) 16916* HAVE_VFORK_H: Particular Functions. 16917 (line 94) 16918* HAVE_VPRINTF: Particular Functions. 16919 (line 359) 16920* HAVE_WAIT3: Obsolete Macros. (line 189) 16921* HAVE_WORKING_FORK: Particular Functions. 16922 (line 94) 16923* HAVE_WORKING_VFORK: Particular Functions. 16924 (line 94) 16925* inline: C Compiler. (line 246) 16926* int16_t: Particular Types. (line 24) 16927* int32_t: Particular Types. (line 27) 16928* int64_t: Particular Types. (line 30) 16929* int8_t: Particular Types. (line 18) 16930* INT_16_BITS: Obsolete Macros. (line 242) 16931* intmax_t: Particular Types. (line 33) 16932* intptr_t: Particular Types. (line 38) 16933* LONG_64_BITS: Obsolete Macros. (line 293) 16934* LSTAT_FOLLOWS_SLASHED_SYMLINK: Particular Functions. 16935 (line 190) 16936* MAJOR_IN_MKDEV: Particular Headers. (line 58) 16937* MAJOR_IN_SYSMACROS: Particular Headers. (line 58) 16938* malloc: Particular Functions. 16939 (line 203) 16940* mbstate_t: Particular Types. (line 57) 16941* mode_t: Particular Types. (line 62) 16942* NDEBUG: Particular Headers. (line 10) 16943* NDIR: Obsolete Macros. (line 146) 16944* NEED_MEMORY_H: Obsolete Macros. (line 311) 16945* NEED_SETGID: Particular Functions. 16946 (line 130) 16947* NLIST_NAME_UNION: Particular Functions. 16948 (line 130) 16949* NO_MINUS_C_MINUS_O: C Compiler. (line 90) 16950* off_t: Particular Types. (line 66) 16951* PACKAGE_BUGREPORT: Initializing configure. 16952 (line 44) 16953* PACKAGE_NAME: Initializing configure. 16954 (line 32) 16955* PACKAGE_STRING: Initializing configure. 16956 (line 41) 16957* PACKAGE_TARNAME: Initializing configure. 16958 (line 35) 16959* PACKAGE_VERSION: Initializing configure. 16960 (line 38) 16961* PARAMS: C Compiler. (line 301) 16962* pid_t: Particular Types. (line 70) 16963* PROTOTYPES: C Compiler. (line 301) 16964* realloc: Particular Functions. 16965 (line 264) 16966* restrict: C Compiler. (line 212) 16967* RETSIGTYPE: Particular Types. (line 74) 16968* SELECT_TYPE_ARG1: Particular Functions. 16969 (line 272) 16970* SELECT_TYPE_ARG234: Particular Functions. 16971 (line 272) 16972* SELECT_TYPE_ARG5: Particular Functions. 16973 (line 272) 16974* SETPGRP_VOID: Particular Functions. 16975 (line 283) 16976* SETVBUF_REVERSED: Particular Functions. 16977 (line 307) 16978* size_t: Particular Types. (line 87) 16979* ssize_t: Particular Types. (line 91) 16980* STAT_MACROS_BROKEN: Particular Headers. (line 83) 16981* STDC_HEADERS: Particular Headers. (line 120) 16982* STRERROR_R_CHAR_P: Particular Functions. 16983 (line 321) 16984* SVR4: Particular Functions. 16985 (line 130) 16986* SYS_SIGLIST_DECLARED: Obsolete Macros. (line 132) 16987* SYSDIR: Obsolete Macros. (line 146) 16988* SYSNDIR: Obsolete Macros. (line 146) 16989* TIME_WITH_SYS_TIME: Particular Headers. (line 224) 16990* TM_IN_SYS_TIME: Particular Structures. 16991 (line 48) 16992* typeof: C Compiler. (line 295) 16993* uid_t: Particular Types. (line 95) 16994* uint16_t: Particular Types. (line 104) 16995* uint32_t: Particular Types. (line 108) 16996* uint64_t: Particular Types. (line 112) 16997* uint8_t: Particular Types. (line 99) 16998* uintmax_t: Particular Types. (line 116) 16999* uintptr_t: Particular Types. (line 121) 17000* UMAX: Particular Functions. 17001 (line 130) 17002* UMAX4_3: Particular Functions. 17003 (line 130) 17004* USG: Obsolete Macros. (line 577) 17005* vfork: Particular Functions. 17006 (line 94) 17007* volatile: C Compiler. (line 225) 17008* WORDS_BIGENDIAN: C Compiler. (line 167) 17009* X_DISPLAY_MISSING: System Services. (line 30) 17010* YYTEXT_POINTER: Particular Programs. (line 96) 17011 17012 17013File: autoconf.info, Node: Autoconf Macro Index, Next: M4 Macro Index, Prev: Preprocessor Symbol Index, Up: Indices 17014 17015B.4 Autoconf Macro Index 17016======================== 17017 17018This is an alphabetical list of the Autoconf macros. 17019 17020[index] 17021* Menu: 17022 17023* AC_AC_PROG_MKDIR_P: Particular Programs. (line 65) 17024* AC_AIX: Posix Variants. (line 13) 17025* AC_ALLOCA: Obsolete Macros. (line 20) 17026* AC_ARG_ARRAY: Obsolete Macros. (line 23) 17027* AC_ARG_ENABLE: Package Options. (line 40) 17028* AC_ARG_PROGRAM: Transforming Names. (line 11) 17029* AC_ARG_VAR: Setting Output Variables. 17030 (line 71) 17031* AC_ARG_WITH: External Software. (line 41) 17032* AC_BEFORE: Suggested Ordering. (line 28) 17033* AC_C_BIGENDIAN: C Compiler. (line 167) 17034* AC_C_CHAR_UNSIGNED: C Compiler. (line 251) 17035* AC_C_CONST: C Compiler. (line 184) 17036* AC_C_CROSS: Obsolete Macros. (line 26) 17037* AC_C_FLEXIBLE_ARRAY_MEMBER: C Compiler. (line 265) 17038* AC_C_INLINE: C Compiler. (line 246) 17039* AC_C_LONG_DOUBLE: Obsolete Macros. (line 29) 17040* AC_C_PROTOTYPES: C Compiler. (line 301) 17041* AC_C_RESTRICT: C Compiler. (line 212) 17042* AC_C_STRINGIZE: C Compiler. (line 255) 17043* AC_C_TYPEOF: C Compiler. (line 295) 17044* AC_C_VARARRAYS: C Compiler. (line 289) 17045* AC_C_VOLATILE: C Compiler. (line 225) 17046* AC_CACHE_CHECK: Caching Results. (line 30) 17047* AC_CACHE_LOAD: Cache Checkpointing. (line 13) 17048* AC_CACHE_SAVE: Cache Checkpointing. (line 17) 17049* AC_CACHE_VAL: Caching Results. (line 16) 17050* AC_CANONICAL_BUILD: Canonicalizing. (line 26) 17051* AC_CANONICAL_HOST: Canonicalizing. (line 34) 17052* AC_CANONICAL_SYSTEM: Obsolete Macros. (line 37) 17053* AC_CANONICAL_TARGET: Canonicalizing. (line 41) 17054* AC_CHAR_UNSIGNED: Obsolete Macros. (line 47) 17055* AC_CHECK_ALIGNOF: Generic Compiler Characteristics. 17056 (line 23) 17057* AC_CHECK_DECL: Generic Declarations. 17058 (line 11) 17059* AC_CHECK_DECLS: Generic Declarations. 17060 (line 24) 17061* AC_CHECK_DECLS_ONCE: Generic Declarations. 17062 (line 58) 17063* AC_CHECK_FILE: Files. (line 13) 17064* AC_CHECK_FILES: Files. (line 19) 17065* AC_CHECK_FUNC: Generic Functions. (line 15) 17066* AC_CHECK_FUNCS: Generic Functions. (line 25) 17067* AC_CHECK_FUNCS_ONCE: Generic Functions. (line 34) 17068* AC_CHECK_HEADER: Generic Headers. (line 13) 17069* AC_CHECK_HEADERS: Generic Headers. (line 23) 17070* AC_CHECK_HEADERS_ONCE: Generic Headers. (line 60) 17071* AC_CHECK_LIB: Libraries. (line 11) 17072* AC_CHECK_MEMBER: Generic Structures. (line 11) 17073* AC_CHECK_MEMBERS: Generic Structures. (line 25) 17074* AC_CHECK_PROG: Generic Programs. (line 23) 17075* AC_CHECK_PROGS: Generic Programs. (line 33) 17076* AC_CHECK_SIZEOF: Generic Compiler Characteristics. 17077 (line 8) 17078* AC_CHECK_TARGET_TOOL: Generic Programs. (line 43) 17079* AC_CHECK_TARGET_TOOLS: Generic Programs. (line 75) 17080* AC_CHECK_TOOL: Generic Programs. (line 59) 17081* AC_CHECK_TOOLS: Generic Programs. (line 88) 17082* AC_CHECK_TYPE <1>: Obsolete Macros. (line 50) 17083* AC_CHECK_TYPE: Generic Types. (line 11) 17084* AC_CHECK_TYPES: Generic Types. (line 16) 17085* AC_CHECKING: Obsolete Macros. (line 97) 17086* AC_COMPILE_CHECK: Obsolete Macros. (line 101) 17087* AC_COMPILE_IFELSE: Running the Compiler. 17088 (line 13) 17089* AC_COMPUTE_INT: Generic Compiler Characteristics. 17090 (line 30) 17091* AC_CONFIG_AUX_DIR: Input. (line 20) 17092* AC_CONFIG_COMMANDS: Configuration Commands. 17093 (line 13) 17094* AC_CONFIG_COMMANDS_POST: Configuration Commands. 17095 (line 41) 17096* AC_CONFIG_COMMANDS_PRE: Configuration Commands. 17097 (line 35) 17098* AC_CONFIG_FILES: Configuration Files. (line 9) 17099* AC_CONFIG_HEADERS: Configuration Headers. 17100 (line 33) 17101* AC_CONFIG_LIBOBJ_DIR: Generic Functions. (line 93) 17102* AC_CONFIG_LINKS: Configuration Links. (line 12) 17103* AC_CONFIG_MACRO_DIR: Input. (line 48) 17104* AC_CONFIG_SRCDIR: Input. (line 7) 17105* AC_CONFIG_SUBDIRS: Subdirectories. (line 12) 17106* AC_CONFIG_TESTDIR: Making testsuite Scripts. 17107 (line 37) 17108* AC_CONST: Obsolete Macros. (line 109) 17109* AC_COPYRIGHT: Notices. (line 21) 17110* AC_CROSS_CHECK: Obsolete Macros. (line 112) 17111* AC_CYGWIN: Obsolete Macros. (line 116) 17112* AC_DATAROOTDIR_CHECKED: Changed Directory Variables. 17113 (line 58) 17114* AC_DECL_SYS_SIGLIST: Obsolete Macros. (line 132) 17115* AC_DECL_YYTEXT: Obsolete Macros. (line 143) 17116* AC_DEFINE: Defining Symbols. (line 32) 17117* AC_DEFINE_UNQUOTED: Defining Symbols. (line 55) 17118* AC_DEFUN: Macro Definitions. (line 6) 17119* AC_DEFUN_ONCE: One-Shot Macros. (line 14) 17120* AC_DIAGNOSE: Reporting Messages. (line 11) 17121* AC_DIR_HEADER: Obsolete Macros. (line 146) 17122* AC_DYNIX_SEQ: Obsolete Macros. (line 157) 17123* AC_EGREP_CPP: Running the Preprocessor. 17124 (line 73) 17125* AC_EGREP_HEADER: Running the Preprocessor. 17126 (line 66) 17127* AC_EMXOS2: Obsolete Macros. (line 170) 17128* AC_ENABLE: Package Options. (line 61) 17129* AC_ERLANG_CHECK_LIB: Erlang Libraries. (line 26) 17130* AC_ERLANG_NEED_ERL: Erlang Compiler and Interpreter. 17131 (line 41) 17132* AC_ERLANG_NEED_ERLC: Erlang Compiler and Interpreter. 17133 (line 24) 17134* AC_ERLANG_PATH_ERL: Erlang Compiler and Interpreter. 17135 (line 29) 17136* AC_ERLANG_PATH_ERLC: Erlang Compiler and Interpreter. 17137 (line 10) 17138* AC_ERLANG_SUBST_INSTALL_LIB_DIR <1>: Erlang Libraries. (line 52) 17139* AC_ERLANG_SUBST_INSTALL_LIB_DIR: Installation Directory Variables. 17140 (line 192) 17141* AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR <1>: Erlang Libraries. (line 60) 17142* AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR: Installation Directory Variables. 17143 (line 197) 17144* AC_ERLANG_SUBST_LIB_DIR: Erlang Libraries. (line 18) 17145* AC_ERLANG_SUBST_ROOT_DIR: Erlang Libraries. (line 12) 17146* AC_ERROR: Obsolete Macros. (line 174) 17147* AC_EXEEXT: Obsolete Macros. (line 165) 17148* AC_F77_DUMMY_MAIN: Fortran Compiler. (line 107) 17149* AC_F77_FUNC: Fortran Compiler. (line 226) 17150* AC_F77_LIBRARY_LDFLAGS: Fortran Compiler. (line 79) 17151* AC_F77_MAIN: Fortran Compiler. (line 150) 17152* AC_F77_WRAPPERS: Fortran Compiler. (line 166) 17153* AC_FATAL: Reporting Messages. (line 33) 17154* AC_FC_FREEFORM: Fortran Compiler. (line 275) 17155* AC_FC_FUNC: Fortran Compiler. (line 226) 17156* AC_FC_LIBRARY_LDFLAGS: Fortran Compiler. (line 79) 17157* AC_FC_MAIN: Fortran Compiler. (line 150) 17158* AC_FC_SRCEXT: Fortran Compiler. (line 236) 17159* AC_FC_WRAPPERS: Fortran Compiler. (line 166) 17160* AC_FIND_X: Obsolete Macros. (line 177) 17161* AC_FIND_XTRA: Obsolete Macros. (line 180) 17162* AC_FOREACH: Obsolete Macros. (line 183) 17163* AC_FUNC_ALLOCA: Particular Functions. 17164 (line 10) 17165* AC_FUNC_CHECK: Obsolete Macros. (line 186) 17166* AC_FUNC_CHOWN: Particular Functions. 17167 (line 54) 17168* AC_FUNC_CLOSEDIR_VOID: Particular Functions. 17169 (line 58) 17170* AC_FUNC_ERROR_AT_LINE: Particular Functions. 17171 (line 70) 17172* AC_FUNC_FNMATCH: Particular Functions. 17173 (line 74) 17174* AC_FUNC_FNMATCH_GNU: Particular Functions. 17175 (line 86) 17176* AC_FUNC_FORK: Particular Functions. 17177 (line 94) 17178* AC_FUNC_FSEEKO: Particular Functions. 17179 (line 116) 17180* AC_FUNC_GETGROUPS: Particular Functions. 17181 (line 124) 17182* AC_FUNC_GETLOADAVG: Particular Functions. 17183 (line 130) 17184* AC_FUNC_GETMNTENT: Particular Functions. 17185 (line 164) 17186* AC_FUNC_GETPGRP: Particular Functions. 17187 (line 170) 17188* AC_FUNC_LSTAT: Particular Functions. 17189 (line 295) 17190* AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK: Particular Functions. 17191 (line 190) 17192* AC_FUNC_MALLOC: Particular Functions. 17193 (line 203) 17194* AC_FUNC_MBRTOWC: Particular Functions. 17195 (line 245) 17196* AC_FUNC_MEMCMP: Particular Functions. 17197 (line 235) 17198* AC_FUNC_MKTIME: Particular Functions. 17199 (line 249) 17200* AC_FUNC_MMAP: Particular Functions. 17201 (line 255) 17202* AC_FUNC_OBSTACK: Particular Functions. 17203 (line 260) 17204* AC_FUNC_REALLOC: Particular Functions. 17205 (line 264) 17206* AC_FUNC_SELECT_ARGTYPES: Particular Functions. 17207 (line 272) 17208* AC_FUNC_SETPGRP: Particular Functions. 17209 (line 283) 17210* AC_FUNC_SETVBUF_REVERSED: Particular Functions. 17211 (line 307) 17212* AC_FUNC_STAT: Particular Functions. 17213 (line 295) 17214* AC_FUNC_STRCOLL: Particular Functions. 17215 (line 315) 17216* AC_FUNC_STRERROR_R: Particular Functions. 17217 (line 321) 17218* AC_FUNC_STRFTIME: Particular Functions. 17219 (line 331) 17220* AC_FUNC_STRNLEN: Particular Functions. 17221 (line 348) 17222* AC_FUNC_STRTOD: Particular Functions. 17223 (line 338) 17224* AC_FUNC_STRTOLD: Particular Functions. 17225 (line 344) 17226* AC_FUNC_UTIME_NULL: Particular Functions. 17227 (line 352) 17228* AC_FUNC_VPRINTF: Particular Functions. 17229 (line 359) 17230* AC_FUNC_WAIT3: Obsolete Macros. (line 189) 17231* AC_GCC_TRADITIONAL: Obsolete Macros. (line 197) 17232* AC_GETGROUPS_T: Obsolete Macros. (line 200) 17233* AC_GETLOADAVG: Obsolete Macros. (line 203) 17234* AC_GNU_SOURCE: Posix Variants. (line 18) 17235* AC_HAVE_C_BACKSLASH_A: C Compiler. (line 159) 17236* AC_HAVE_FUNCS: Obsolete Macros. (line 206) 17237* AC_HAVE_HEADERS: Obsolete Macros. (line 209) 17238* AC_HAVE_LIBRARY: Obsolete Macros. (line 213) 17239* AC_HAVE_POUNDBANG: Obsolete Macros. (line 220) 17240* AC_HEADER_ASSERT: Particular Headers. (line 10) 17241* AC_HEADER_CHECK: Obsolete Macros. (line 223) 17242* AC_HEADER_DIRENT: Particular Headers. (line 15) 17243* AC_HEADER_EGREP: Obsolete Macros. (line 226) 17244* AC_HEADER_MAJOR: Particular Headers. (line 58) 17245* AC_HEADER_RESOLV: Particular Headers. (line 63) 17246* AC_HEADER_STAT: Particular Headers. (line 83) 17247* AC_HEADER_STDBOOL: Particular Headers. (line 92) 17248* AC_HEADER_STDC: Particular Headers. (line 120) 17249* AC_HEADER_SYS_WAIT: Particular Headers. (line 187) 17250* AC_HEADER_TIME: Particular Headers. (line 224) 17251* AC_HEADER_TIOCGWINSZ: Particular Headers. (line 248) 17252* AC_HELP_STRING <1>: Obsolete Macros. (line 229) 17253* AC_HELP_STRING: Pretty Help Strings. (line 14) 17254* AC_INCLUDES_DEFAULT: Default Includes. (line 29) 17255* AC_INIT <1>: Obsolete Macros. (line 232) 17256* AC_INIT: Initializing configure. 17257 (line 10) 17258* AC_INLINE: Obsolete Macros. (line 239) 17259* AC_INT_16_BITS: Obsolete Macros. (line 242) 17260* AC_IRIX_SUN: Obsolete Macros. (line 246) 17261* AC_ISC_POSIX: Posix Variants. (line 23) 17262* AC_LANG_ASSERT: Language Choice. (line 69) 17263* AC_LANG_C: Obsolete Macros. (line 260) 17264* AC_LANG_CALL: Generating Sources. (line 115) 17265* AC_LANG_CONFTEST: Generating Sources. (line 12) 17266* AC_LANG_CPLUSPLUS: Obsolete Macros. (line 263) 17267* AC_LANG_FORTRAN77: Obsolete Macros. (line 266) 17268* AC_LANG_FUNC_LINK_TRY: Generating Sources. (line 127) 17269* AC_LANG_POP: Language Choice. (line 56) 17270* AC_LANG_PROGRAM: Generating Sources. (line 53) 17271* AC_LANG_PUSH: Language Choice. (line 51) 17272* AC_LANG_RESTORE: Obsolete Macros. (line 269) 17273* AC_LANG_SAVE: Obsolete Macros. (line 274) 17274* AC_LANG_SOURCE: Generating Sources. (line 21) 17275* AC_LANG_WERROR: Generic Compiler Characteristics. 17276 (line 42) 17277* AC_LIBOBJ: Generic Functions. (line 52) 17278* AC_LIBSOURCE: Generic Functions. (line 61) 17279* AC_LIBSOURCES: Generic Functions. (line 85) 17280* AC_LINK_FILES: Obsolete Macros. (line 278) 17281* AC_LINK_IFELSE: Running the Linker. (line 24) 17282* AC_LN_S: Obsolete Macros. (line 290) 17283* AC_LONG_64_BITS: Obsolete Macros. (line 293) 17284* AC_LONG_DOUBLE: Obsolete Macros. (line 297) 17285* AC_LONG_FILE_NAMES: Obsolete Macros. (line 305) 17286* AC_MAJOR_HEADER: Obsolete Macros. (line 308) 17287* AC_MEMORY_H: Obsolete Macros. (line 311) 17288* AC_MINGW32: Obsolete Macros. (line 317) 17289* AC_MINIX: Posix Variants. (line 33) 17290* AC_MINUS_C_MINUS_O: Obsolete Macros. (line 321) 17291* AC_MMAP: Obsolete Macros. (line 324) 17292* AC_MODE_T: Obsolete Macros. (line 327) 17293* AC_MSG_CHECKING: Printing Messages. (line 24) 17294* AC_MSG_ERROR: Printing Messages. (line 56) 17295* AC_MSG_FAILURE: Printing Messages. (line 66) 17296* AC_MSG_NOTICE: Printing Messages. (line 46) 17297* AC_MSG_RESULT: Printing Messages. (line 35) 17298* AC_MSG_WARN: Printing Messages. (line 72) 17299* AC_OBJEXT: Obsolete Macros. (line 330) 17300* AC_OBSOLETE: Obsolete Macros. (line 336) 17301* AC_OFF_T: Obsolete Macros. (line 351) 17302* AC_OUTPUT <1>: Obsolete Macros. (line 354) 17303* AC_OUTPUT: Output. (line 13) 17304* AC_OUTPUT_COMMANDS: Obsolete Macros. (line 363) 17305* AC_PACKAGE_BUGREPORT: Initializing configure. 17306 (line 44) 17307* AC_PACKAGE_NAME: Initializing configure. 17308 (line 32) 17309* AC_PACKAGE_STRING: Initializing configure. 17310 (line 41) 17311* AC_PACKAGE_TARNAME: Initializing configure. 17312 (line 35) 17313* AC_PACKAGE_VERSION: Initializing configure. 17314 (line 38) 17315* AC_PATH_PROG: Generic Programs. (line 103) 17316* AC_PATH_PROGS: Generic Programs. (line 108) 17317* AC_PATH_TARGET_TOOL: Generic Programs. (line 113) 17318* AC_PATH_TOOL: Generic Programs. (line 118) 17319* AC_PATH_X: System Services. (line 10) 17320* AC_PATH_XTRA: System Services. (line 30) 17321* AC_PID_T: Obsolete Macros. (line 392) 17322* AC_PREFIX: Obsolete Macros. (line 395) 17323* AC_PREFIX_DEFAULT: Default Prefix. (line 16) 17324* AC_PREFIX_PROGRAM: Default Prefix. (line 25) 17325* AC_PREPROC_IFELSE: Running the Preprocessor. 17326 (line 20) 17327* AC_PREREQ: Notices. (line 10) 17328* AC_PRESERVE_HELP_ORDER: Help Formatting. (line 20) 17329* AC_PROG_AWK: Particular Programs. (line 10) 17330* AC_PROG_CC: C Compiler. (line 61) 17331* AC_PROG_CC_C89: C Compiler. (line 132) 17332* AC_PROG_CC_C99: C Compiler. (line 145) 17333* AC_PROG_CC_C_O: C Compiler. (line 90) 17334* AC_PROG_CC_STDC: C Compiler. (line 122) 17335* AC_PROG_CPP: C Compiler. (line 98) 17336* AC_PROG_CPP_WERROR: C Compiler. (line 111) 17337* AC_PROG_CXX: C++ Compiler. (line 7) 17338* AC_PROG_CXX_C_O: C++ Compiler. (line 44) 17339* AC_PROG_CXXCPP: C++ Compiler. (line 31) 17340* AC_PROG_EGREP: Particular Programs. (line 23) 17341* AC_PROG_F77: Fortran Compiler. (line 18) 17342* AC_PROG_F77_C_O: Fortran Compiler. (line 66) 17343* AC_PROG_FC: Fortran Compiler. (line 39) 17344* AC_PROG_FC_C_O: Fortran Compiler. (line 66) 17345* AC_PROG_FGREP: Particular Programs. (line 28) 17346* AC_PROG_GCC_TRADITIONAL: C Compiler. (line 311) 17347* AC_PROG_GREP: Particular Programs. (line 16) 17348* AC_PROG_INSTALL: Particular Programs. (line 33) 17349* AC_PROG_LEX: Particular Programs. (line 96) 17350* AC_PROG_LN_S: Particular Programs. (line 137) 17351* AC_PROG_MAKE_SET: Output. (line 45) 17352* AC_PROG_OBJC: Objective C Compiler. 17353 (line 7) 17354* AC_PROG_OBJCCPP: Objective C Compiler. 17355 (line 26) 17356* AC_PROG_RANLIB: Particular Programs. (line 156) 17357* AC_PROG_SED: Particular Programs. (line 160) 17358* AC_PROG_YACC: Particular Programs. (line 166) 17359* AC_PROGRAM_CHECK: Obsolete Macros. (line 404) 17360* AC_PROGRAM_EGREP: Obsolete Macros. (line 407) 17361* AC_PROGRAM_PATH: Obsolete Macros. (line 410) 17362* AC_PROGRAMS_CHECK: Obsolete Macros. (line 398) 17363* AC_PROGRAMS_PATH: Obsolete Macros. (line 401) 17364* AC_REMOTE_TAPE: Obsolete Macros. (line 413) 17365* AC_REPLACE_FNMATCH: Particular Functions. 17366 (line 368) 17367* AC_REPLACE_FUNCS: Generic Functions. (line 113) 17368* AC_REQUIRE: Prerequisite Macros. (line 17) 17369* AC_REQUIRE_AUX_FILE: Input. (line 37) 17370* AC_REQUIRE_CPP: Language Choice. (line 84) 17371* AC_RESTARTABLE_SYSCALLS: Obsolete Macros. (line 416) 17372* AC_RETSIGTYPE: Obsolete Macros. (line 419) 17373* AC_REVISION: Notices. (line 29) 17374* AC_RSH: Obsolete Macros. (line 422) 17375* AC_RUN_IFELSE: Runtime. (line 20) 17376* AC_SCO_INTL: Obsolete Macros. (line 425) 17377* AC_SEARCH_LIBS: Libraries. (line 49) 17378* AC_SET_MAKE: Obsolete Macros. (line 436) 17379* AC_SETVBUF_REVERSED: Obsolete Macros. (line 433) 17380* AC_SIZE_T: Obsolete Macros. (line 442) 17381* AC_SIZEOF_TYPE: Obsolete Macros. (line 439) 17382* AC_ST_BLKSIZE: Obsolete Macros. (line 454) 17383* AC_ST_BLOCKS: Obsolete Macros. (line 457) 17384* AC_ST_RDEV: Obsolete Macros. (line 460) 17385* AC_STAT_MACROS_BROKEN: Obsolete Macros. (line 445) 17386* AC_STDC_HEADERS: Obsolete Macros. (line 448) 17387* AC_STRCOLL: Obsolete Macros. (line 451) 17388* AC_STRUCT_DIRENT_D_INO: Particular Structures. 17389 (line 9) 17390* AC_STRUCT_DIRENT_D_TYPE: Particular Structures. 17391 (line 21) 17392* AC_STRUCT_ST_BLKSIZE: Particular Structures. 17393 (line 26) 17394* AC_STRUCT_ST_BLOCKS: Particular Structures. 17395 (line 34) 17396* AC_STRUCT_ST_RDEV: Particular Structures. 17397 (line 40) 17398* AC_STRUCT_TIMEZONE: Particular Structures. 17399 (line 56) 17400* AC_STRUCT_TM: Particular Structures. 17401 (line 48) 17402* AC_SUBST: Setting Output Variables. 17403 (line 13) 17404* AC_SUBST_FILE: Setting Output Variables. 17405 (line 30) 17406* AC_SYS_INTERPRETER: System Services. (line 42) 17407* AC_SYS_LARGEFILE: System Services. (line 49) 17408* AC_SYS_LONG_FILE_NAMES: System Services. (line 71) 17409* AC_SYS_POSIX_TERMIOS: System Services. (line 75) 17410* AC_SYS_RESTARTABLE_SYSCALLS: Obsolete Macros. (line 463) 17411* AC_SYS_SIGLIST_DECLARED: Obsolete Macros. (line 478) 17412* AC_TEST_CPP: Obsolete Macros. (line 481) 17413* AC_TEST_PROGRAM: Obsolete Macros. (line 484) 17414* AC_TIME_WITH_SYS_TIME: Obsolete Macros. (line 490) 17415* AC_TIMEZONE: Obsolete Macros. (line 487) 17416* AC_TRY_COMPILE: Obsolete Macros. (line 494) 17417* AC_TRY_CPP: Obsolete Macros. (line 513) 17418* AC_TRY_LINK: Obsolete Macros. (line 526) 17419* AC_TRY_LINK_FUNC: Obsolete Macros. (line 555) 17420* AC_TRY_RUN: Obsolete Macros. (line 560) 17421* AC_TYPE_GETGROUPS: Particular Types. (line 14) 17422* AC_TYPE_INT16_T: Particular Types. (line 24) 17423* AC_TYPE_INT32_T: Particular Types. (line 27) 17424* AC_TYPE_INT64_T: Particular Types. (line 30) 17425* AC_TYPE_INT8_T: Particular Types. (line 18) 17426* AC_TYPE_INTMAX_T: Particular Types. (line 33) 17427* AC_TYPE_INTPTR_T: Particular Types. (line 38) 17428* AC_TYPE_LONG_DOUBLE: Particular Types. (line 43) 17429* AC_TYPE_LONG_DOUBLE_WIDER: Particular Types. (line 48) 17430* AC_TYPE_LONG_LONG_INT: Particular Types. (line 53) 17431* AC_TYPE_MBSTATE_T: Particular Types. (line 57) 17432* AC_TYPE_MODE_T: Particular Types. (line 62) 17433* AC_TYPE_OFF_T: Particular Types. (line 66) 17434* AC_TYPE_PID_T: Particular Types. (line 70) 17435* AC_TYPE_SIGNAL: Particular Types. (line 74) 17436* AC_TYPE_SIZE_T: Particular Types. (line 87) 17437* AC_TYPE_SSIZE_T: Particular Types. (line 91) 17438* AC_TYPE_UID_T: Particular Types. (line 95) 17439* AC_TYPE_UINT16_T: Particular Types. (line 104) 17440* AC_TYPE_UINT32_T: Particular Types. (line 108) 17441* AC_TYPE_UINT64_T: Particular Types. (line 112) 17442* AC_TYPE_UINT8_T: Particular Types. (line 99) 17443* AC_TYPE_UINTMAX_T: Particular Types. (line 116) 17444* AC_TYPE_UINTPTR_T: Particular Types. (line 121) 17445* AC_TYPE_UNSIGNED_LONG_LONG_INT: Particular Types. (line 126) 17446* AC_UID_T: Obsolete Macros. (line 571) 17447* AC_UNISTD_H: Obsolete Macros. (line 574) 17448* AC_USE_SYSTEM_EXTENSIONS: Posix Variants. (line 39) 17449* AC_USG: Obsolete Macros. (line 577) 17450* AC_UTIME_NULL: Obsolete Macros. (line 582) 17451* AC_VALIDATE_CACHED_SYSTEM_TUPLE: Obsolete Macros. (line 585) 17452* AC_VERBOSE: Obsolete Macros. (line 590) 17453* AC_VFORK: Obsolete Macros. (line 593) 17454* AC_VPRINTF: Obsolete Macros. (line 596) 17455* AC_WAIT3: Obsolete Macros. (line 599) 17456* AC_WARN: Obsolete Macros. (line 602) 17457* AC_WARNING: Reporting Messages. (line 29) 17458* AC_WITH: External Software. (line 141) 17459* AC_WORDS_BIGENDIAN: Obsolete Macros. (line 605) 17460* AC_XENIX_DIR: Obsolete Macros. (line 608) 17461* AC_YYTEXT_POINTER: Obsolete Macros. (line 623) 17462* AH_BOTTOM: Autoheader Macros. (line 50) 17463* AH_HEADER: Configuration Headers. 17464 (line 56) 17465* AH_TEMPLATE: Autoheader Macros. (line 19) 17466* AH_TOP: Autoheader Macros. (line 47) 17467* AH_VERBATIM: Autoheader Macros. (line 40) 17468* AU_ALIAS: Obsoleting Macros. (line 34) 17469* AU_DEFUN: Obsoleting Macros. (line 18) 17470 17471 17472File: autoconf.info, Node: M4 Macro Index, Next: Autotest Macro Index, Prev: Autoconf Macro Index, Up: Indices 17473 17474B.5 M4 Macro Index 17475================== 17476 17477This is an alphabetical list of the M4, M4sugar, and M4sh macros. 17478 17479[index] 17480* Menu: 17481 17482* AS_BOURNE_COMPATIBLE: Programming in M4sh. (line 26) 17483* AS_CASE: Programming in M4sh. (line 32) 17484* AS_DIRNAME: Programming in M4sh. (line 37) 17485* AS_IF: Programming in M4sh. (line 42) 17486* AS_MESSAGE_FD: File Descriptor Macros. 17487 (line 17) 17488* AS_MESSAGE_LOG_FD: File Descriptor Macros. 17489 (line 27) 17490* AS_MKDIR_P: Programming in M4sh. (line 56) 17491* AS_ORIGINAL_STDIN_FD: File Descriptor Macros. 17492 (line 33) 17493* AS_SET_CATFILE: Programming in M4sh. (line 91) 17494* AS_SHELL_SANITIZE: Programming in M4sh. (line 67) 17495* AS_TR_CPP: Programming in M4sh. (line 74) 17496* AS_TR_SH: Programming in M4sh. (line 82) 17497* m4_append: Text processing Macros. 17498 (line 31) 17499* m4_append_uniq: Text processing Macros. 17500 (line 31) 17501* m4_bpatsubst: Redefined M4 Macros. (line 32) 17502* m4_bregexp: Redefined M4 Macros. (line 41) 17503* m4_builtin: Redefined M4 Macros. (line 6) 17504* m4_decr: Redefined M4 Macros. (line 6) 17505* m4_define: Redefined M4 Macros. (line 6) 17506* m4_defn: Redefined M4 Macros. (line 16) 17507* m4_dnl: Redefined M4 Macros. (line 13) 17508* m4_dquote: Evaluation Macros. (line 11) 17509* m4_dumpdef: Redefined M4 Macros. (line 6) 17510* m4_errprint: Redefined M4 Macros. (line 6) 17511* m4_esyscmd: Redefined M4 Macros. (line 6) 17512* m4_eval: Redefined M4 Macros. (line 6) 17513* m4_exit: Redefined M4 Macros. (line 20) 17514* m4_for: Looping constructs. (line 9) 17515* m4_foreach: Looping constructs. (line 16) 17516* m4_foreach_w: Looping constructs. (line 25) 17517* m4_format: Redefined M4 Macros. (line 6) 17518* m4_if: Redefined M4 Macros. (line 25) 17519* m4_ifdef: Redefined M4 Macros. (line 6) 17520* m4_include: Redefined M4 Macros. (line 29) 17521* m4_incr: Redefined M4 Macros. (line 6) 17522* m4_index: Redefined M4 Macros. (line 6) 17523* m4_indir: Redefined M4 Macros. (line 6) 17524* m4_len: Redefined M4 Macros. (line 6) 17525* m4_maketemp: Redefined M4 Macros. (line 77) 17526* m4_mkstemp: Redefined M4 Macros. (line 77) 17527* m4_normalize: Text processing Macros. 17528 (line 25) 17529* m4_pattern_allow: Forbidden Patterns. (line 28) 17530* m4_pattern_forbid: Forbidden Patterns. (line 15) 17531* m4_popdef: Redefined M4 Macros. (line 37) 17532* m4_pushdef: Redefined M4 Macros. (line 6) 17533* m4_quote: Evaluation Macros. (line 14) 17534* m4_re_escape: Text processing Macros. 17535 (line 10) 17536* m4_shift: Redefined M4 Macros. (line 6) 17537* m4_sinclude: Redefined M4 Macros. (line 29) 17538* m4_split: Text processing Macros. 17539 (line 19) 17540* m4_substr: Redefined M4 Macros. (line 6) 17541* m4_syscmd: Redefined M4 Macros. (line 6) 17542* m4_sysval: Redefined M4 Macros. (line 6) 17543* m4_tolower: Text processing Macros. 17544 (line 15) 17545* m4_toupper: Text processing Macros. 17546 (line 15) 17547* m4_translit: Redefined M4 Macros. (line 6) 17548* m4_undefine: Redefined M4 Macros. (line 6) 17549* m4_wrap: Redefined M4 Macros. (line 46) 17550 17551 17552File: autoconf.info, Node: Autotest Macro Index, Next: Program & Function Index, Prev: M4 Macro Index, Up: Indices 17553 17554B.6 Autotest Macro Index 17555======================== 17556 17557This is an alphabetical list of the Autotest macros. 17558 17559[index] 17560* Menu: 17561 17562* AT_CAPTURE_FILE: Writing testsuite.at. (line 63) 17563* AT_CHECK: Writing testsuite.at. (line 87) 17564* AT_CLEANUP: Writing testsuite.at. (line 76) 17565* AT_COPYRIGHT: Writing testsuite.at. (line 22) 17566* AT_DATA: Writing testsuite.at. (line 80) 17567* AT_INIT: Writing testsuite.at. (line 16) 17568* AT_KEYWORDS: Writing testsuite.at. (line 51) 17569* AT_SETUP: Writing testsuite.at. (line 45) 17570* AT_TESTED: Writing testsuite.at. (line 30) 17571* AT_XFAIL_IF: Writing testsuite.at. (line 68) 17572 17573 17574File: autoconf.info, Node: Program & Function Index, Next: Concept Index, Prev: Autotest Macro Index, Up: Indices 17575 17576B.7 Program and Function Index 17577============================== 17578 17579This is an alphabetical list of the programs and functions which 17580portability is discussed in this document. 17581 17582[index] 17583* Menu: 17584 17585* !: Limitations of Builtins. 17586 (line 23) 17587* .: Limitations of Builtins. 17588 (line 16) 17589* /usr/bin/ksh on Solaris: Shellology. (line 63) 17590* /usr/dt/bin/dtksh on Solaris: Shellology. (line 66) 17591* /usr/xpg4/bin/sh on Solaris: Shellology. (line 64) 17592* alloca: Particular Functions. 17593 (line 10) 17594* alloca.h: Particular Functions. 17595 (line 10) 17596* assert.h: Particular Headers. (line 10) 17597* Awk: Limitations of Usual Tools. 17598 (line 10) 17599* basename: Limitations of Usual Tools. 17600 (line 90) 17601* break: Limitations of Builtins. 17602 (line 42) 17603* case: Limitations of Builtins. 17604 (line 45) 17605* cat: Limitations of Usual Tools. 17606 (line 94) 17607* cc: Limitations of Usual Tools. 17608 (line 97) 17609* cd: Limitations of Builtins. 17610 (line 104) 17611* chmod: Limitations of Usual Tools. 17612 (line 130) 17613* chown: Particular Functions. 17614 (line 54) 17615* closedir: Particular Functions. 17616 (line 58) 17617* cmp: Limitations of Usual Tools. 17618 (line 140) 17619* cp: Limitations of Usual Tools. 17620 (line 147) 17621* ctype.h: Particular Headers. (line 120) 17622* date: Limitations of Usual Tools. 17623 (line 199) 17624* diff: Limitations of Usual Tools. 17625 (line 209) 17626* dirent.h: Particular Headers. (line 15) 17627* dirname: Limitations of Usual Tools. 17628 (line 215) 17629* echo: Limitations of Builtins. 17630 (line 124) 17631* egrep: Limitations of Usual Tools. 17632 (line 222) 17633* error_at_line: Particular Functions. 17634 (line 70) 17635* eval: Limitations of Builtins. 17636 (line 150) 17637* exit <1>: Limitations of Builtins. 17638 (line 194) 17639* exit: Function Portability. 17640 (line 12) 17641* export: Limitations of Builtins. 17642 (line 219) 17643* expr: Limitations of Usual Tools. 17644 (line 246) 17645* expr (|): Limitations of Usual Tools. 17646 (line 252) 17647* false: Limitations of Builtins. 17648 (line 245) 17649* fgrep: Limitations of Usual Tools. 17650 (line 343) 17651* find: Limitations of Usual Tools. 17652 (line 350) 17653* float.h: Particular Headers. (line 120) 17654* fnmatch: Particular Functions. 17655 (line 74) 17656* fnmatch.h: Particular Functions. 17657 (line 368) 17658* for: Limitations of Builtins. 17659 (line 249) 17660* fork: Particular Functions. 17661 (line 94) 17662* free: Function Portability. 17663 (line 22) 17664* fseeko: Particular Functions. 17665 (line 116) 17666* getgroups: Particular Functions. 17667 (line 124) 17668* getloadavg: Particular Functions. 17669 (line 130) 17670* getmntent: Particular Functions. 17671 (line 164) 17672* getpgid: Particular Functions. 17673 (line 170) 17674* getpgrp: Particular Functions. 17675 (line 170) 17676* grep: Limitations of Usual Tools. 17677 (line 364) 17678* if: Limitations of Builtins. 17679 (line 275) 17680* inttypes.h <1>: Particular Types. (line 6) 17681* inttypes.h: Header Portability. (line 16) 17682* isinf: Function Portability. 17683 (line 27) 17684* isnan: Function Portability. 17685 (line 27) 17686* join: Limitations of Usual Tools. 17687 (line 414) 17688* ksh: Shellology. (line 57) 17689* ksh88: Shellology. (line 57) 17690* ksh93: Shellology. (line 57) 17691* linux/irda.h: Header Portability. (line 23) 17692* linux/random.h: Header Portability. (line 26) 17693* ln: Limitations of Usual Tools. 17694 (line 427) 17695* ls: Limitations of Usual Tools. 17696 (line 439) 17697* lstat: Particular Functions. 17698 (line 190) 17699* make: Portable Make. (line 6) 17700* malloc <1>: Particular Functions. 17701 (line 203) 17702* malloc: Function Portability. 17703 (line 73) 17704* mbrtowc: Particular Functions. 17705 (line 245) 17706* memcmp: Particular Functions. 17707 (line 235) 17708* mkdir: Limitations of Usual Tools. 17709 (line 451) 17710* mktemp: Limitations of Usual Tools. 17711 (line 484) 17712* mktime: Particular Functions. 17713 (line 249) 17714* mmap: Particular Functions. 17715 (line 255) 17716* mv: Limitations of Usual Tools. 17717 (line 508) 17718* ndir.h: Particular Headers. (line 15) 17719* net/if.h: Header Portability. (line 29) 17720* netinet/if_ether.h: Header Portability. (line 49) 17721* nlist.h: Particular Functions. 17722 (line 147) 17723* od: Limitations of Usual Tools. 17724 (line 540) 17725* pdksh: Shellology. (line 77) 17726* printf: Limitations of Builtins. 17727 (line 304) 17728* putenv: Function Portability. 17729 (line 80) 17730* pwd: Limitations of Builtins. 17731 (line 317) 17732* read: Limitations of Builtins. 17733 (line 314) 17734* realloc <1>: Particular Functions. 17735 (line 264) 17736* realloc: Function Portability. 17737 (line 96) 17738* resolv.h: Particular Headers. (line 63) 17739* rm: Limitations of Usual Tools. 17740 (line 549) 17741* sed: Limitations of Usual Tools. 17742 (line 566) 17743* sed (t): Limitations of Usual Tools. 17744 (line 693) 17745* select: Particular Functions. 17746 (line 272) 17747* set: Limitations of Builtins. 17748 (line 348) 17749* setpgrp: Particular Functions. 17750 (line 283) 17751* setvbuf: Particular Functions. 17752 (line 307) 17753* shift: Limitations of Builtins. 17754 (line 402) 17755* signal: Function Portability. 17756 (line 101) 17757* signal.h: Particular Types. (line 74) 17758* snprintf: Function Portability. 17759 (line 112) 17760* source: Limitations of Builtins. 17761 (line 410) 17762* sprintf: Function Portability. 17763 (line 123) 17764* sscanf: Function Portability. 17765 (line 129) 17766* stat: Particular Functions. 17767 (line 295) 17768* stdarg.h: Particular Headers. (line 120) 17769* stdbool.h: Particular Headers. (line 92) 17770* stdint.h <1>: Particular Types. (line 6) 17771* stdint.h: Header Portability. (line 16) 17772* stdlib.h <1>: Particular Types. (line 6) 17773* stdlib.h <2>: Particular Headers. (line 120) 17774* stdlib.h: Header Portability. (line 72) 17775* strcoll: Particular Functions. 17776 (line 315) 17777* strerror_r <1>: Particular Functions. 17778 (line 321) 17779* strerror_r: Function Portability. 17780 (line 137) 17781* strftime: Particular Functions. 17782 (line 331) 17783* string.h: Particular Headers. (line 120) 17784* strings.h: Particular Headers. (line 137) 17785* strnlen <1>: Particular Functions. 17786 (line 348) 17787* strnlen: Function Portability. 17788 (line 143) 17789* strtod: Particular Functions. 17790 (line 338) 17791* strtold: Particular Functions. 17792 (line 344) 17793* sys/dir.h: Particular Headers. (line 15) 17794* sys/ioctl.h: Particular Headers. (line 248) 17795* sys/mkdev.h: Particular Headers. (line 58) 17796* sys/mount.h: Header Portability. (line 75) 17797* sys/ndir.h: Particular Headers. (line 15) 17798* sys/ptem.h: Header Portability. (line 79) 17799* sys/socket.h: Header Portability. (line 82) 17800* sys/stat.h: Particular Headers. (line 83) 17801* sys/sysmacros.h: Particular Headers. (line 58) 17802* sys/time.h <1>: Particular Structures. 17803 (line 48) 17804* sys/time.h: Particular Headers. (line 224) 17805* sys/types.h: Particular Types. (line 6) 17806* sys/ucred.h: Header Portability. (line 85) 17807* sys/wait.h: Particular Headers. (line 187) 17808* sysconf: Function Portability. 17809 (line 158) 17810* system.h: Particular Headers. (line 92) 17811* termios.h: Particular Headers. (line 248) 17812* test: Limitations of Builtins. 17813 (line 414) 17814* time.h <1>: Particular Structures. 17815 (line 48) 17816* time.h: Particular Headers. (line 224) 17817* touch: Limitations of Usual Tools. 17818 (line 753) 17819* trap: Limitations of Builtins. 17820 (line 499) 17821* true: Limitations of Builtins. 17822 (line 548) 17823* unistd.h: Particular Headers. (line 208) 17824* unlink: Function Portability. 17825 (line 162) 17826* unset: Limitations of Builtins. 17827 (line 559) 17828* unsetenv: Function Portability. 17829 (line 168) 17830* utime: Particular Functions. 17831 (line 352) 17832* va_copy: Function Portability. 17833 (line 173) 17834* va_list: Function Portability. 17835 (line 180) 17836* vfork: Particular Functions. 17837 (line 94) 17838* vfork.h: Particular Functions. 17839 (line 94) 17840* vprintf: Particular Functions. 17841 (line 359) 17842* vsnprintf: Function Portability. 17843 (line 112) 17844* vsprintf: Function Portability. 17845 (line 123) 17846* wchar.h: Particular Types. (line 57) 17847* X11/extensions/scrnsaver.h: Header Portability. (line 88) 17848 17849 17850File: autoconf.info, Node: Concept Index, Prev: Program & Function Index, Up: Indices 17851 17852B.8 Concept Index 17853================= 17854 17855This is an alphabetical list of the files, tools, and concepts 17856introduced in this document. 17857 17858[index] 17859* Menu: 17860 17861* "$@": Shell Substitutions. (line 31) 17862* $(COMMANDS): Shell Substitutions. (line 195) 17863* $<, explicit rules, and VPATH: $< in Explicit Rules. 17864 (line 6) 17865* ${VAR=EXPANDED-VALUE}: Shell Substitutions. (line 120) 17866* ${VAR=LITERAL}: Shell Substitutions. (line 90) 17867* @&t@: Quadrigraphs. (line 6) 17868* @S|@: Quadrigraphs. (line 6) 17869* ^ quoting: Shell Substitutions. (line 228) 17870* _m4_divert_diversion: New Macros. (line 6) 17871* `COMMANDS`: Shell Substitutions. (line 166) 17872* acconfig.h: acconfig.h. (line 6) 17873* aclocal.m4: Making configure Scripts. 17874 (line 6) 17875* Ash: Shellology. (line 16) 17876* autoconf: autoconf Invocation. (line 6) 17877* Autoconf upgrading <1>: Autoconf 2.13. (line 6) 17878* Autoconf upgrading: Autoconf 1. (line 6) 17879* autoheader: autoheader Invocation. 17880 (line 6) 17881* Autoheader macros: Autoheader Macros. (line 6) 17882* Autom4te Library: autom4te Invocation. (line 225) 17883* autom4te.cache: autom4te Invocation. (line 130) 17884* autom4te.cfg: autom4te Invocation. (line 259) 17885* Automake: Automake. (line 19) 17886* Automatic remaking: Automatic Remaking. (line 6) 17887* automatic rule rewriting and VPATH: Automatic Rule Rewriting. 17888 (line 6) 17889* autopoint: autoreconf Invocation. 17890 (line 27) 17891* autoreconf: autoreconf Invocation. 17892 (line 6) 17893* autoscan: autoscan Invocation. (line 6) 17894* Autotest: Using Autotest. (line 6) 17895* AUTOTEST_PATH: testsuite Invocation. 17896 (line 36) 17897* autoupdate: autoupdate Invocation. 17898 (line 6) 17899* Back trace <1>: autom4te Invocation. (line 86) 17900* Back trace: autoconf Invocation. (line 88) 17901* Bash: Shellology. (line 43) 17902* Bash 2.05 and later: Shellology. (line 49) 17903* Bootstrap: Bootstrapping. (line 6) 17904* BSD make and obj/: obj/ and Make. (line 6) 17905* buffer overruns: Buffer Overruns. (line 6) 17906* Build directories: Build Directories. (line 6) 17907* C function portability: Function Portability. 17908 (line 6) 17909* C types: Types. (line 6) 17910* Cache: Caching Results. (line 6) 17911* Cache variable: Cache Variable Names. 17912 (line 6) 17913* Cache, enabling: configure Invocation. 17914 (line 18) 17915* Canonical system type: Canonicalizing. (line 6) 17916* changequote: Changequote is Evil. (line 6) 17917* Coding style: Coding Style. (line 6) 17918* Command Substitution: Shell Substitutions. (line 166) 17919* Commands for configuration: Configuration Commands. 17920 (line 6) 17921* Comments in Makefile rules: Comments in Make Rules. 17922 (line 6) 17923* Common autoconf behavior: Common Behavior. (line 6) 17924* Compilers: Compilers and Preprocessors. 17925 (line 6) 17926* config.h: Configuration Headers. 17927 (line 6) 17928* config.h.bot: acconfig.h. (line 6) 17929* config.h.in: Header Templates. (line 6) 17930* config.h.top: acconfig.h. (line 6) 17931* config.status: config.status Invocation. 17932 (line 6) 17933* config.sub: Specifying Names. (line 61) 17934* Configuration actions: Configuration Actions. 17935 (line 6) 17936* Configuration commands: Configuration Commands. 17937 (line 6) 17938* Configuration file creation: Configuration Files. (line 6) 17939* Configuration Header: Configuration Headers. 17940 (line 6) 17941* Configuration Header Template: Header Templates. (line 6) 17942* Configuration links: Configuration Links. (line 6) 17943* configure <1>: Running configure Scripts. 17944 (line 6) 17945* configure: Making configure Scripts. 17946 (line 6) 17947* Configure subdirectories: Subdirectories. (line 6) 17948* configure.ac: Making configure Scripts. 17949 (line 27) 17950* configure.in: Making configure Scripts. 17951 (line 27) 17952* Copyright Notice <1>: Writing testsuite.at. 17953 (line 22) 17954* Copyright Notice: Notices. (line 21) 17955* Creating configuration files: Configuration Files. (line 6) 17956* Creating temporary files: Limitations of Usual Tools. 17957 (line 484) 17958* Cross compilation: Hosts and Cross-Compilation. 17959 (line 6) 17960* Darwin: Systemology. (line 23) 17961* datarootdir: Changed Directory Variables. 17962 (line 6) 17963* Declaration, checking: Declarations. (line 6) 17964* Default includes: Default Includes. (line 6) 17965* Dependencies between macros: Dependencies Between Macros. 17966 (line 6) 17967* Descriptors: File Descriptors. (line 6) 17968* descriptors: File Descriptor Macros. 17969 (line 6) 17970* Directories, build: Build Directories. (line 6) 17971* Directories, installation: Installation Directory Variables. 17972 (line 6) 17973* dnl <1>: Coding Style. (line 40) 17974* dnl: Macro Definitions. (line 37) 17975* double-colon rules and VPATH: VPATH and Double-colon. 17976 (line 6) 17977* Endianness: C Compiler. (line 167) 17978* Erlang: Erlang Compiler and Interpreter. 17979 (line 6) 17980* Erlang, Library, checking: Erlang Libraries. (line 6) 17981* exiting portably: Exiting Portably. (line 6) 17982* explicit rules, $<, and VPATH: $< in Explicit Rules. 17983 (line 6) 17984* External software: External Software. (line 6) 17985* F77: Fortran Compiler. (line 6) 17986* FDL, GNU Free Documentation License: GNU Free Documentation License. 17987 (line 6) 17988* File descriptors: File Descriptors. (line 6) 17989* file descriptors: File Descriptor Macros. 17990 (line 6) 17991* File system conventions: File System Conventions. 17992 (line 6) 17993* File, checking: Files. (line 6) 17994* floating point: Floating Point Portability. 17995 (line 6) 17996* Forbidden patterns: Forbidden Patterns. (line 6) 17997* Fortran: Fortran Compiler. (line 6) 17998* Function, checking: Particular Functions. 17999 (line 6) 18000* Gettext: autoreconf Invocation. 18001 (line 27) 18002* GNU build system: The GNU Build System. 18003 (line 6) 18004* Gnulib: Gnulib. (line 11) 18005* Header portability: Header Portability. (line 6) 18006* Header templates: Header Templates. (line 6) 18007* Header, checking: Header Files. (line 6) 18008* Help strings: Pretty Help Strings. (line 6) 18009* Here-documents: Here-Documents. (line 6) 18010* History of autoconf: History. (line 6) 18011* ifnames: ifnames Invocation. (line 6) 18012* Imake: Why Not Imake. (line 6) 18013* Includes, default: Default Includes. (line 6) 18014* input: File Descriptor Macros. 18015 (line 6) 18016* Install prefix: Default Prefix. (line 6) 18017* Installation directories: Installation Directory Variables. 18018 (line 6) 18019* Instantiation: Output. (line 13) 18020* Introduction: Introduction. (line 6) 18021* Korn shell: Shellology. (line 57) 18022* Ksh: Shellology. (line 57) 18023* Language: Language Choice. (line 6) 18024* Large file support: System Services. (line 49) 18025* LFS: System Services. (line 49) 18026* Library, checking: Libraries. (line 6) 18027* Libtool: Libtool. (line 14) 18028* License <1>: Copying This Manual. (line 6) 18029* License: Distributing. (line 6) 18030* Limitations of make: Portable Make. (line 6) 18031* Limitations of shell builtins: Limitations of Builtins. 18032 (line 6) 18033* Limitations of usual tools: Limitations of Usual Tools. 18034 (line 6) 18035* Links: Configuration Links. (line 12) 18036* Links for configuration: Configuration Links. (line 6) 18037* Listing directories: Limitations of Usual Tools. 18038 (line 439) 18039* low-level output: File Descriptor Macros. 18040 (line 6) 18041* M4: Programming in M4. (line 6) 18042* M4 quotation: M4 Quotation. (line 6) 18043* M4sugar: Programming in M4sugar. 18044 (line 6) 18045* Macro invocation stack <1>: autom4te Invocation. (line 86) 18046* Macro invocation stack: autoconf Invocation. (line 88) 18047* Macros, called once: One-Shot Macros. (line 6) 18048* Macros, obsoleting: Obsoleting Macros. (line 6) 18049* Macros, ordering: Suggested Ordering. (line 6) 18050* Macros, prerequisites: Prerequisite Macros. (line 6) 18051* make -k: make -k Status. (line 6) 18052* make and MAKEFLAGS: The Make Macro MAKEFLAGS. 18053 (line 6) 18054* make and SHELL: The Make Macro SHELL. 18055 (line 6) 18056* Makefile rules and comments: Comments in Make Rules. 18057 (line 6) 18058* Makefile substitutions: Makefile Substitutions. 18059 (line 6) 18060* MAKEFLAGS and make: The Make Macro MAKEFLAGS. 18061 (line 6) 18062* Making directories: Limitations of Usual Tools. 18063 (line 451) 18064* Messages, from autoconf: Reporting Messages. (line 6) 18065* Messages, from configure: Printing Messages. (line 6) 18066* Moving open files: Limitations of Usual Tools. 18067 (line 508) 18068* Notices in configure: Notices. (line 6) 18069* null pointers: Null Pointers. (line 6) 18070* obj/, subdirectory: obj/ and Make. (line 6) 18071* Obsolete constructs: Obsolete Constructs. (line 6) 18072* Obsoleting macros: Obsoleting Macros. (line 6) 18073* obstack: Particular Functions. 18074 (line 260) 18075* One-shot macros: One-Shot Macros. (line 6) 18076* Options, package: Package Options. (line 6) 18077* Ordering macros: Suggested Ordering. (line 6) 18078* Output variables <1>: Setting Output Variables. 18079 (line 6) 18080* Output variables: Preset Output Variables. 18081 (line 6) 18082* Output variables, special characters in: Special Chars in Variables. 18083 (line 6) 18084* output, low-level: File Descriptor Macros. 18085 (line 6) 18086* Outputting files: Output. (line 6) 18087* overflow, arithmetic: Integer Overflow. (line 6) 18088* Package options: Package Options. (line 6) 18089* package.m4: Making testsuite Scripts. 18090 (line 12) 18091* Patterns, forbidden: Forbidden Patterns. (line 6) 18092* portability: Varieties of Unportability. 18093 (line 6) 18094* Portability of C functions: Function Portability. 18095 (line 6) 18096* Portability of headers: Header Portability. (line 6) 18097* Portable C and C++ programming: Portable C and C++. (line 6) 18098* Portable shell programming: Portable Shell. (line 6) 18099* positional parameters: Shell Substitutions. (line 77) 18100* Posix termios headers: System Services. (line 75) 18101* Precious Variable: Setting Output Variables. 18102 (line 57) 18103* Prefix for install: Default Prefix. (line 6) 18104* Preprocessors: Compilers and Preprocessors. 18105 (line 6) 18106* prerequisite directories and VPATH: Tru64 Directory Magic. 18107 (line 6) 18108* Prerequisite macros: Prerequisite Macros. (line 6) 18109* Program names, transforming: Transforming Names. (line 6) 18110* Programs, checking: Alternative Programs. 18111 (line 6) 18112* QNX 4.25: Systemology. (line 37) 18113* quadrigraphs: Quadrigraphs. (line 6) 18114* quotation <1>: M4 Quotation. (line 6) 18115* quotation: Autoconf Language. (line 6) 18116* Remaking automatically: Automatic Remaking. (line 6) 18117* Revision: Notices. (line 29) 18118* Rule, Single Suffix Inference: Single Suffix Rules. (line 6) 18119* Separated Dependencies: Single Suffix Rules. (line 9) 18120* SHELL and make: The Make Macro SHELL. 18121 (line 6) 18122* Shell assignments: Assignments. (line 6) 18123* Shell builtins: Limitations of Builtins. 18124 (line 6) 18125* Shell file descriptors: File Descriptors. (line 6) 18126* Shell here-documents: Here-Documents. (line 6) 18127* Shell parentheses: Parentheses. (line 6) 18128* Shell slashes: Slashes. (line 6) 18129* Shell substitutions: Shell Substitutions. (line 6) 18130* Shell variables: Special Shell Variables. 18131 (line 6) 18132* Shellology: Shellology. (line 6) 18133* Single Suffix Inference Rule: Single Suffix Rules. (line 6) 18134* Site defaults: Site Defaults. (line 6) 18135* Site details: Site Details. (line 6) 18136* Special shell variables: Special Shell Variables. 18137 (line 6) 18138* standard input: File Descriptor Macros. 18139 (line 6) 18140* Standard symbols: Standard Symbols. (line 6) 18141* Structure, checking: Structures. (line 6) 18142* Subdirectory configure: Subdirectories. (line 6) 18143* Substitutions in makefiles: Makefile Substitutions. 18144 (line 6) 18145* Symbolic links: Limitations of Usual Tools. 18146 (line 427) 18147* System type <1>: Canonicalizing. (line 6) 18148* System type: Specifying Names. (line 6) 18149* Systemology: Systemology. (line 6) 18150* termios Posix headers: System Services. (line 75) 18151* test group: testsuite Scripts. (line 12) 18152* testsuite <1>: testsuite Invocation. 18153 (line 6) 18154* testsuite: testsuite Scripts. (line 6) 18155* timestamp resolution <1>: Timestamps and Make. (line 6) 18156* timestamp resolution: Limitations of Usual Tools. 18157 (line 162) 18158* Transforming program names: Transforming Names. (line 6) 18159* Tru64: Systemology. (line 44) 18160* Types: Types. (line 6) 18161* undefined macro: New Macros. (line 6) 18162* Unix version 7: Systemology. (line 49) 18163* Upgrading autoconf <1>: Autoconf 2.13. (line 6) 18164* Upgrading autoconf: Autoconf 1. (line 6) 18165* V7: Systemology. (line 49) 18166* Variable, Precious: Setting Output Variables. 18167 (line 57) 18168* Version: Notices. (line 10) 18169* volatile objects: Volatile Objects. (line 6) 18170* VPATH: VPATH and Make. (line 6) 18171* VPATH and automatic rule rewriting: Automatic Rule Rewriting. 18172 (line 6) 18173* VPATH and double-colon rules: VPATH and Double-colon. 18174 (line 6) 18175* VPATH and prerequisite directories: Tru64 Directory Magic. 18176 (line 6) 18177* VPATH, explicit rules, and $<: $< in Explicit Rules. 18178 (line 6) 18179* VPATH, resolving target pathnames: Make Target Lookup. (line 6) 18180* X Window System: System Services. (line 10) 18181* Zsh: Shellology. (line 97) 18182 18183 18184 18185Tag Table: 18186Node: Top2270 18187Node: Introduction19833 18188Node: The GNU Build System24874 18189Node: Automake25853 18190Node: Gnulib27803 18191Node: Libtool29112 18192Node: Pointers30534 18193Ref: Pointers-Footnote-131827 18194Node: Making configure Scripts31987 18195Node: Writing configure.ac35022 18196Node: Shell Script Compiler36457 18197Node: Autoconf Language38725 18198Node: configure.ac Layout44596 18199Node: autoscan Invocation46000 18200Node: ifnames Invocation48504 18201Node: autoconf Invocation49704 18202Node: autoreconf Invocation55030 18203Node: Setup59466 18204Node: Initializing configure60725 18205Node: Notices62902 18206Node: Input64554 18207Node: Output67279 18208Node: Configuration Actions69757 18209Node: Configuration Files74567 18210Node: Makefile Substitutions76047 18211Node: Preset Output Variables77789 18212Node: Installation Directory Variables84957 18213Node: Changed Directory Variables92349 18214Node: Build Directories94943 18215Node: Automatic Remaking96582 18216Node: Configuration Headers98741 18217Node: Header Templates102174 18218Node: autoheader Invocation103693 18219Node: Autoheader Macros106966 18220Node: Configuration Commands109231 18221Node: Configuration Links111025 18222Node: Subdirectories112449 18223Node: Default Prefix114901 18224Node: Existing Tests116323 18225Node: Common Behavior118125 18226Node: Standard Symbols118764 18227Node: Default Includes119345 18228Node: Alternative Programs121599 18229Node: Particular Programs122285 18230Node: Generic Programs130301 18231Node: Files136583 18232Node: Libraries137477 18233Node: Library Functions140785 18234Node: Function Portability141408 18235Node: Particular Functions150318 18236Node: Generic Functions166484 18237Node: Header Files172125 18238Node: Header Portability172758 18239Node: Particular Headers175627 18240Node: Generic Headers185565 18241Node: Declarations188596 18242Node: Particular Declarations189192 18243Node: Generic Declarations189416 18244Node: Structures192323 18245Node: Particular Structures192938 18246Node: Generic Structures195650 18247Node: Types197129 18248Node: Particular Types197649 18249Node: Generic Types202125 18250Node: Compilers and Preprocessors203544 18251Node: Specific Compiler Characteristics204736 18252Node: Generic Compiler Characteristics205841 18253Node: C Compiler208126 18254Node: C++ Compiler222144 18255Node: Objective C Compiler224343 18256Node: Erlang Compiler and Interpreter225728 18257Node: Fortran Compiler227731 18258Node: System Services242043 18259Node: Posix Variants245617 18260Node: Erlang Libraries247573 18261Node: Writing Tests251027 18262Node: Language Choice253051 18263Ref: Language Choice-Footnote-1256818 18264Node: Writing Test Programs256974 18265Node: Guidelines257552 18266Node: Test Functions259811 18267Node: Generating Sources261209 18268Node: Running the Preprocessor265888 18269Node: Running the Compiler269198 18270Node: Running the Linker270516 18271Node: Runtime272428 18272Node: Systemology276589 18273Node: Multiple Cases278938 18274Node: Results280521 18275Node: Defining Symbols281340 18276Node: Setting Output Variables285284 18277Node: Special Chars in Variables290583 18278Node: Caching Results291843 18279Node: Cache Variable Names295557 18280Node: Cache Files297119 18281Node: Cache Checkpointing299097 18282Node: Printing Messages300471 18283Node: Programming in M4304063 18284Node: M4 Quotation304934 18285Node: Active Characters305779 18286Ref: Active Characters-Footnote-1307135 18287Node: One Macro Call307157 18288Node: Quotation and Nested Macros308797 18289Node: Changequote is Evil311764 18290Node: Quadrigraphs314291 18291Node: Quotation Rule Of Thumb316344 18292Node: Using autom4te319233 18293Ref: Using autom4te-Footnote-1319884 18294Node: autom4te Invocation319933 18295Node: Customizing autom4te328439 18296Node: Programming in M4sugar329721 18297Node: Redefined M4 Macros330435 18298Node: Looping constructs333743 18299Node: Evaluation Macros334880 18300Node: Text processing Macros336182 18301Node: Forbidden Patterns337667 18302Node: Programming in M4sh339038 18303Node: File Descriptor Macros342954 18304Node: Writing Autoconf Macros345041 18305Node: Macro Definitions345842 18306Node: Macro Names347618 18307Node: Reporting Messages350203 18308Node: Dependencies Between Macros351560 18309Node: Prerequisite Macros352253 18310Node: Suggested Ordering355323 18311Node: One-Shot Macros356864 18312Node: Obsoleting Macros357788 18313Node: Coding Style359569 18314Node: Portable Shell367124 18315Node: Shellology369684 18316Node: Here-Documents375016 18317Node: File Descriptors377665 18318Node: File System Conventions381241 18319Node: Shell Substitutions387019 18320Node: Assignments395084 18321Node: Parentheses396973 18322Node: Slashes397786 18323Node: Special Shell Variables398638 18324Node: Limitations of Builtins407394 18325Node: Limitations of Usual Tools430255 18326Node: Portable Make461576 18327Node: $< in Ordinary Make Rules462907 18328Node: Failure in Make Rules463373 18329Node: Special Chars in Names464454 18330Node: Backslash-Newline-Newline465428 18331Node: Backslash-Newline Comments466055 18332Node: Long Lines in Makefiles466946 18333Node: Macros and Submakes467322 18334Node: The Make Macro MAKEFLAGS469432 18335Node: The Make Macro SHELL470317 18336Node: Comments in Make Rules472048 18337Node: obj/ and Make472534 18338Node: make -k Status473173 18339Node: VPATH and Make473795 18340Node: VPATH and Double-colon475046 18341Node: $< in Explicit Rules475418 18342Node: Automatic Rule Rewriting475885 18343Node: Tru64 Directory Magic481813 18344Node: Make Target Lookup482639 18345Node: Single Suffix Rules487081 18346Node: Timestamps and Make488427 18347Node: Portable C and C++489641 18348Node: Varieties of Unportability491224 18349Node: Integer Overflow493321 18350Node: Null Pointers494684 18351Node: Buffer Overruns495311 18352Node: Volatile Objects498100 18353Node: Floating Point Portability503778 18354Node: Exiting Portably504285 18355Node: Manual Configuration505761 18356Node: Specifying Names506594 18357Node: Canonicalizing509636 18358Node: Using System Type511893 18359Node: Site Configuration514704 18360Node: Help Formatting515600 18361Node: External Software516544 18362Node: Package Options522908 18363Node: Pretty Help Strings525964 18364Node: Site Details527784 18365Node: Transforming Names529017 18366Node: Transformation Options530099 18367Node: Transformation Examples530576 18368Node: Transformation Rules532297 18369Node: Site Defaults533843 18370Node: Running configure Scripts537764 18371Node: Basic Installation538778 18372Node: Compilers and Options541636 18373Node: Multiple Architectures542290 18374Node: Installation Names543178 18375Node: Optional Features544401 18376Node: System Type545185 18377Node: Sharing Defaults546507 18378Node: Defining Variables547145 18379Node: configure Invocation548037 18380Node: config.status Invocation549166 18381Node: Obsolete Constructs553411 18382Node: Obsolete config.status Use554363 18383Node: acconfig.h556136 18384Node: autoupdate Invocation558153 18385Node: Obsolete Macros559844 18386Node: Autoconf 1579801 18387Node: Changed File Names580867 18388Node: Changed Makefiles581617 18389Node: Changed Macros582705 18390Node: Changed Results583959 18391Node: Changed Macro Writing586079 18392Node: Autoconf 2.13587359 18393Node: Changed Quotation588568 18394Node: New Macros590486 18395Node: Hosts and Cross-Compilation592281 18396Node: AC_LIBOBJ vs LIBOBJS596580 18397Node: AC_FOO_IFELSE vs AC_TRY_FOO598195 18398Node: Using Autotest600198 18399Node: Using an Autotest Test Suite602639 18400Node: testsuite Scripts602932 18401Node: Autotest Logs607350 18402Node: Writing testsuite.at609693 18403Node: testsuite Invocation614559 18404Node: Making testsuite Scripts617991 18405Node: FAQ621979 18406Node: Distributing622720 18407Node: Why GNU M4623769 18408Node: Bootstrapping624638 18409Node: Why Not Imake625248 18410Node: Defining Directories629993 18411Node: autom4te.cache632040 18412Node: Present But Cannot Be Compiled633881 18413Node: History637734 18414Node: Genesis638521 18415Node: Exodus639699 18416Node: Leviticus642744 18417Node: Numbers644272 18418Node: Deuteronomy646187 18419Node: Copying This Manual648858 18420Node: GNU Free Documentation License649092 18421Node: Indices671492 18422Node: Environment Variable Index672132 18423Node: Output Variable Index677916 18424Node: Preprocessor Symbol Index692806 18425Node: Autoconf Macro Index709264 18426Node: M4 Macro Index741563 18427Node: Autotest Macro Index746693 18428Node: Program & Function Index747672 18429Node: Concept Index766346 18430 18431End Tag Table 18432