1 \input texinfo @c -*-texinfo-*-
2 @comment ========================================================
3 @comment %**start of header
4 @setfilename autoconf.info
9 @setcontentsaftertitlepage
15 @c The ARG is an optional argument. To be used for macro arguments in
16 @c their documentation (@defmac).
18 @r{[}@var{\varname\}@r{]}@c
21 @c @dvar(ARG, DEFAULT)
22 @c -------------------
23 @c The ARG is an optional argument, defaulting to DEFAULT. To be used
24 @c for macro arguments in their documentation (@defmac).
25 @macro dvar{varname, default}
26 @r{[}@var{\varname\} = @samp{\default\}@r{]}@c
29 @c Handling the indexes with Texinfo yields several different problems.
31 @c Because we want to drop out the AC_ part of the macro names in the
32 @c printed manual, but not in the other outputs, we need a layer above
33 @c the usual @acindex{} etc. That's why we first define indexes such as
34 @c acx meant to become the macro @acindex. First of all, using ``ac_''
35 @c does not work with makeinfo, and using ``ac1'' doesn't work with TeX.
36 @c So use something more regular ``acx''. Then you finish with a printed
37 @c index saying ``index is not existent''. Of course: you ought to use
38 @c two letters :( So you use capitals.
40 @c Second, when defining a macro in the TeX world, following spaces are
41 @c eaten. But then, since we embed @acxindex commands that use the end
42 @c of line as an end marker, the whole things wrecks itself. So make
43 @c sure you do *force* an additional end of line, add a ``@c''.
45 @c Finally, you might want to get rid of TeX expansion, using --expand
46 @c with texi2dvi. But then you wake up an old problem: we use macros
47 @c in @defmac etc. where TeX does perform the expansion, but not makeinfo.
49 @c Define an environment variable index.
51 @c Define an output variable index.
53 @c Define a CPP variable index.
55 @c Define a cache variable index.
57 @c Define an Autoconf macro index that @defmac doesn't write to.
59 @c Define an Autotest macro index that @defmac doesn't write to.
61 @c Define an M4sugar macro index that @defmac doesn't write to.
63 @c Define an index for *foreign* programs: `mv' etc. Used for the
64 @c portability sections and so on.
69 @c Shall we factor AC_ out of the Autoconf macro index etc.?
76 @c Registering an AC_\MACRO\.
83 @ifclear shortindexflag
91 @c Registering an AH_\MACRO\.
99 @c Registering an AS_\MACRO\.
100 @ifset shortindexflag
101 @macro asindex{macro}
106 @ifclear shortindexflag
107 @macro asindex{macro}
114 @c Registering an AT_\MACRO\.
115 @ifset shortindexflag
116 @macro atindex{macro}
121 @ifclear shortindexflag
122 @macro atindex{macro}
129 @c Registering an AU_\MACRO\.
130 @macro auindex{macro}
137 @c Indexing a header.
138 @macro hdrindex{macro}
139 @prindex @file{\macro\}
145 @c Registering an m4_\MACRO\.
146 @ifset shortindexflag
147 @macro msindex{macro}
152 @ifclear shortindexflag
153 @macro msindex{macro}
159 @c @caindex{VARIABLE}
160 @c ------------------
161 @c Registering an ac_cv_\VARIABLE\ cache variable.
162 @ifset shortindexflag
163 @macro caindex{macro}
167 @ifclear shortindexflag
168 @macro caindex{macro}
169 @CAindex ac_cv_\macro\
173 @c Define an index for functions: `alloca' etc. Used for the
174 @c portability sections and so on. We can't use `fn' (aka `fnindex),
175 @c since `@defmac' goes into it => we'd get all the macros too.
177 @c FIXME: Aaarg! It seems there are too many indices for TeX :(
179 @c ! No room for a new @write .
180 @c l.112 @defcodeindex fu
182 @c so don't define yet another one :( Just put some tags before each
183 @c @prindex which is actually a @funindex.
188 @c @c Put the programs and functions into their own index.
189 @c @syncodeindex fu pr
191 @comment %**end of header
192 @comment ========================================================
196 This manual (@value{UPDATED}) is for GNU Autoconf
197 (version @value{VERSION}),
198 a package for creating scripts to configure source code packages using
199 templates and an M4 macro package.
201 Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000,
202 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software
206 Permission is granted to copy, distribute and/or modify this document
207 under the terms of the GNU Free Documentation License,
208 Version 1.3 or any later version published by the Free Software
209 Foundation; with no Invariant Sections, with the Front-Cover texts
210 being ``A GNU Manual,'' and with the Back-Cover Texts as in
211 (a) below. A copy of the license is included in the section entitled
212 ``GNU Free Documentation License.''
214 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
215 modify this GNU manual. Buying copies from the FSF
216 supports it in developing GNU and promoting software
223 @dircategory Software development
225 * Autoconf: (autoconf). Create source code configuration scripts.
228 @dircategory Individual utilities
230 * autoscan: (autoconf)autoscan Invocation.
231 Semi-automatic @file{configure.ac} writing
232 * ifnames: (autoconf)ifnames Invocation. Listing conditionals in source.
233 * autoconf-invocation: (autoconf)autoconf Invocation.
234 How to create configuration scripts
235 * autoreconf: (autoconf)autoreconf Invocation.
236 Remaking multiple @command{configure} scripts
237 * autoheader: (autoconf)autoheader Invocation.
238 How to create configuration templates
239 * autom4te: (autoconf)autom4te Invocation.
240 The Autoconf executables backbone
241 * configure: (autoconf)configure Invocation. Configuring a package.
242 * autoupdate: (autoconf)autoupdate Invocation.
243 Automatic update of @file{configure.ac}
244 * config.status: (autoconf)config.status Invocation. Recreating configurations.
245 * testsuite: (autoconf)testsuite Invocation. Running an Autotest test suite.
250 @subtitle Creating Automatic Configuration Scripts
251 @subtitle for version @value{VERSION}, @value{UPDATED}
252 @author David MacKenzie
254 @author Akim Demaille
256 @vskip 0pt plus 1filll
269 @c The master menu, created with texinfo-master-menu, goes here.
272 * Introduction:: Autoconf's purpose, strengths, and weaknesses
273 * The GNU Build System:: A set of tools for portable software packages
274 * Making configure Scripts:: How to organize and produce Autoconf scripts
275 * Setup:: Initialization and output
276 * Existing Tests:: Macros that check for particular features
277 * Writing Tests:: How to write new feature checks
278 * Results:: What to do with results from feature checks
279 * Programming in M4:: Layers on top of which Autoconf is written
280 * Programming in M4sh:: Shell portability layer
281 * Writing Autoconf Macros:: Adding new macros to Autoconf
282 * Portable Shell:: Shell script portability pitfalls
283 * Portable Make:: Makefile portability pitfalls
284 * Portable C and C++:: C and C++ portability pitfalls
285 * Manual Configuration:: Selecting features that can't be guessed
286 * Site Configuration:: Local defaults for @command{configure}
287 * Running configure Scripts:: How to use the Autoconf output
288 * config.status Invocation:: Recreating a configuration
289 * Obsolete Constructs:: Kept for backward compatibility
290 * Using Autotest:: Creating portable test suites
291 * FAQ:: Frequent Autoconf Questions, with answers
292 * History:: History of Autoconf
293 * GNU Free Documentation License:: License for copying this manual
294 * Indices:: Indices of symbols, concepts, etc.
297 --- The Detailed Node Listing ---
301 * Automake:: Escaping makefile hell
302 * Gnulib:: The GNU portability library
303 * Libtool:: Building libraries portably
304 * Pointers:: More info on the GNU build system
306 Making @command{configure} Scripts
308 * Writing Autoconf Input:: What to put in an Autoconf input file
309 * autoscan Invocation:: Semi-automatic @file{configure.ac} writing
310 * ifnames Invocation:: Listing the conditionals in source code
311 * autoconf Invocation:: How to create configuration scripts
312 * autoreconf Invocation:: Remaking multiple @command{configure} scripts
314 Writing @file{configure.ac}
316 * Shell Script Compiler:: Autoconf as solution of a problem
317 * Autoconf Language:: Programming in Autoconf
318 * Autoconf Input Layout:: Standard organization of @file{configure.ac}
320 Initialization and Output Files
322 * Initializing configure:: Option processing etc.
323 * Versioning:: Dealing with Autoconf versions
324 * Notices:: Copyright, version numbers in @command{configure}
325 * Input:: Where Autoconf should find files
326 * Output:: Outputting results from the configuration
327 * Configuration Actions:: Preparing the output based on results
328 * Configuration Files:: Creating output files
329 * Makefile Substitutions:: Using output variables in makefiles
330 * Configuration Headers:: Creating a configuration header file
331 * Configuration Commands:: Running arbitrary instantiation commands
332 * Configuration Links:: Links depending on the configuration
333 * Subdirectories:: Configuring independent packages together
334 * Default Prefix:: Changing the default installation prefix
336 Substitutions in Makefiles
338 * Preset Output Variables:: Output variables that are always set
339 * Installation Directory Variables:: Other preset output variables
340 * Changed Directory Variables:: Warnings about @file{datarootdir}
341 * Build Directories:: Supporting multiple concurrent compiles
342 * Automatic Remaking:: Makefile rules for configuring
344 Configuration Header Files
346 * Header Templates:: Input for the configuration headers
347 * autoheader Invocation:: How to create configuration templates
348 * Autoheader Macros:: How to specify CPP templates
352 * Common Behavior:: Macros' standard schemes
353 * Alternative Programs:: Selecting between alternative programs
354 * Files:: Checking for the existence of files
355 * Libraries:: Library archives that might be missing
356 * Library Functions:: C library functions that might be missing
357 * Header Files:: Header files that might be missing
358 * Declarations:: Declarations that may be missing
359 * Structures:: Structures or members that might be missing
360 * Types:: Types that might be missing
361 * Compilers and Preprocessors:: Checking for compiling programs
362 * System Services:: Operating system services
363 * Posix Variants:: Special kludges for specific Posix variants
364 * Erlang Libraries:: Checking for the existence of Erlang libraries
368 * Standard Symbols:: Symbols defined by the macros
369 * Default Includes:: Includes used by the generic macros
373 * Particular Programs:: Special handling to find certain programs
374 * Generic Programs:: How to find other programs
378 * Function Portability:: Pitfalls with usual functions
379 * Particular Functions:: Special handling to find certain functions
380 * Generic Functions:: How to find other functions
384 * Header Portability:: Collected knowledge on common headers
385 * Particular Headers:: Special handling to find certain headers
386 * Generic Headers:: How to find other headers
390 * Particular Declarations:: Macros to check for certain declarations
391 * Generic Declarations:: How to find other declarations
395 * Particular Structures:: Macros to check for certain structure members
396 * Generic Structures:: How to find other structure members
400 * Particular Types:: Special handling to find certain types
401 * Generic Types:: How to find other types
403 Compilers and Preprocessors
405 * Specific Compiler Characteristics:: Some portability issues
406 * Generic Compiler Characteristics:: Language independent tests and features
407 * C Compiler:: Checking its characteristics
408 * C++ Compiler:: Likewise
409 * Objective C Compiler:: Likewise
410 * Objective C++ Compiler:: Likewise
411 * Erlang Compiler and Interpreter:: Likewise
412 * Fortran Compiler:: Likewise
416 * Language Choice:: Selecting which language to use for testing
417 * Writing Test Programs:: Forging source files for compilers
418 * Running the Preprocessor:: Detecting preprocessor symbols
419 * Running the Compiler:: Detecting language or header features
420 * Running the Linker:: Detecting library features
421 * Runtime:: Testing for runtime features
422 * Systemology:: A zoology of operating systems
423 * Multiple Cases:: Tests for several possible values
425 Writing Test Programs
427 * Guidelines:: General rules for writing test programs
428 * Test Functions:: Avoiding pitfalls in test programs
429 * Generating Sources:: Source program boilerplate
433 * Defining Symbols:: Defining C preprocessor symbols
434 * Setting Output Variables:: Replacing variables in output files
435 * Special Chars in Variables:: Characters to beware of in variables
436 * Caching Results:: Speeding up subsequent @command{configure} runs
437 * Printing Messages:: Notifying @command{configure} users
441 * Cache Variable Names:: Shell variables used in caches
442 * Cache Files:: Files @command{configure} uses for caching
443 * Cache Checkpointing:: Loading and saving the cache file
447 * M4 Quotation:: Protecting macros from unwanted expansion
448 * Using autom4te:: The Autoconf executables backbone
449 * Programming in M4sugar:: Convenient pure M4 macros
450 * Debugging via autom4te:: Figuring out what M4 was doing
454 * Common Shell Constructs:: Portability layer for common shell constructs
455 * Polymorphic Variables:: Support for indirect variable names
456 * Initialization Macros:: Macros to establish a sane shell environment
457 * File Descriptor Macros:: File descriptor macros for input and output
461 * Active Characters:: Characters that change the behavior of M4
462 * One Macro Call:: Quotation and one macro call
463 * Quoting and Parameters:: M4 vs. shell parameters
464 * Quotation and Nested Macros:: Macros calling macros
465 * Changequote is Evil:: Worse than INTERCAL: M4 + changequote
466 * Quadrigraphs:: Another way to escape special characters
467 * Balancing Parentheses:: Dealing with unbalanced parentheses
468 * Quotation Rule Of Thumb:: One parenthesis, one quote
470 Using @command{autom4te}
472 * autom4te Invocation:: A GNU M4 wrapper
473 * Customizing autom4te:: Customizing the Autoconf package
475 Programming in M4sugar
477 * Redefined M4 Macros:: M4 builtins changed in M4sugar
478 * Diagnostic Macros:: Diagnostic messages from M4sugar
479 * Diversion support:: Diversions in M4sugar
480 * Conditional constructs:: Conditions in M4
481 * Looping constructs:: Iteration in M4
482 * Evaluation Macros:: More quotation and evaluation control
483 * Text processing Macros:: String manipulation in M4
484 * Number processing Macros:: Arithmetic computation in M4
485 * Set manipulation Macros:: Set manipulation in M4
486 * Forbidden Patterns:: Catching unexpanded macros
488 Writing Autoconf Macros
490 * Macro Definitions:: Basic format of an Autoconf macro
491 * Macro Names:: What to call your new macros
492 * Reporting Messages:: Notifying @command{autoconf} users
493 * Dependencies Between Macros:: What to do when macros depend on other macros
494 * Obsoleting Macros:: Warning about old ways of doing things
495 * Coding Style:: Writing Autoconf macros @`a la Autoconf
497 Dependencies Between Macros
499 * Prerequisite Macros:: Ensuring required information
500 * Suggested Ordering:: Warning about possible ordering problems
501 * One-Shot Macros:: Ensuring a macro is called only once
503 Portable Shell Programming
505 * Shellology:: A zoology of shells
506 * Here-Documents:: Quirks and tricks
507 * File Descriptors:: FDs and redirections
508 * File System Conventions:: File names
509 * Shell Pattern Matching:: Pattern matching
510 * Shell Substitutions:: Variable and command expansions
511 * Assignments:: Varying side effects of assignments
512 * Parentheses:: Parentheses in shell scripts
513 * Slashes:: Slashes in shell scripts
514 * Special Shell Variables:: Variables you should not change
515 * Shell Functions:: What to look out for if you use them
516 * Limitations of Builtins:: Portable use of not so portable /bin/sh
517 * Limitations of Usual Tools:: Portable use of portable tools
519 Portable Make Programming
521 * $< in Ordinary Make Rules:: $< in ordinary rules
522 * Failure in Make Rules:: Failing portably in rules
523 * Special Chars in Names:: Special Characters in Macro Names
524 * Backslash-Newline-Newline:: Empty last lines in macro definitions
525 * Backslash-Newline Comments:: Spanning comments across line boundaries
526 * Long Lines in Makefiles:: Line length limitations
527 * Macros and Submakes:: @code{make macro=value} and submakes
528 * The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues
529 * The Make Macro SHELL:: @code{$(SHELL)} portability issues
530 * Parallel Make:: Parallel @command{make} quirks
531 * Comments in Make Rules:: Other problems with Make comments
532 * Newlines in Make Rules:: Using literal newlines in rules
533 * obj/ and Make:: Don't name a subdirectory @file{obj}
534 * make -k Status:: Exit status of @samp{make -k}
535 * VPATH and Make:: @code{VPATH} woes
536 * Single Suffix Rules:: Single suffix rules and separated dependencies
537 * Timestamps and Make:: Subsecond timestamp resolution
539 @code{VPATH} and Make
541 * Variables listed in VPATH:: @code{VPATH} must be literal on ancient hosts
542 * VPATH and Double-colon:: Problems with @samp{::} on ancient hosts
543 * $< in Explicit Rules:: @code{$<} does not work in ordinary rules
544 * Automatic Rule Rewriting:: @code{VPATH} goes wild on Solaris
545 * Tru64 Directory Magic:: @command{mkdir} goes wild on Tru64
546 * Make Target Lookup:: More details about @code{VPATH} lookup
548 Portable C and C++ Programming
550 * Varieties of Unportability:: How to make your programs unportable
551 * Integer Overflow:: When integers get too large
552 * Preprocessor Arithmetic:: @code{#if} expression problems
553 * Null Pointers:: Properties of null pointers
554 * Buffer Overruns:: Subscript errors and the like
555 * Volatile Objects:: @code{volatile} and signals
556 * Floating Point Portability:: Portable floating-point arithmetic
557 * Exiting Portably:: Exiting and the exit status
561 * Specifying Target Triplets:: Specifying target triplets
562 * Canonicalizing:: Getting the canonical system type
563 * Using System Type:: What to do with the system type
567 * Help Formatting:: Customizing @samp{configure --help}
568 * External Software:: Working with other optional software
569 * Package Options:: Selecting optional features
570 * Pretty Help Strings:: Formatting help string
571 * Option Checking:: Controlling checking of @command{configure} options
572 * Site Details:: Configuring site details
573 * Transforming Names:: Changing program names when installing
574 * Site Defaults:: Giving @command{configure} local defaults
576 Transforming Program Names When Installing
578 * Transformation Options:: @command{configure} options to transform names
579 * Transformation Examples:: Sample uses of transforming names
580 * Transformation Rules:: Makefile uses of transforming names
582 Running @command{configure} Scripts
584 * Basic Installation:: Instructions for typical cases
585 * Compilers and Options:: Selecting compilers and optimization
586 * Multiple Architectures:: Compiling for multiple architectures at once
587 * Installation Names:: Installing in different directories
588 * Optional Features:: Selecting optional features
589 * Particular Systems:: Particular systems
590 * System Type:: Specifying the system type
591 * Sharing Defaults:: Setting site-wide defaults for @command{configure}
592 * Defining Variables:: Specifying the compiler etc.
593 * configure Invocation:: Changing how @command{configure} runs
597 * Obsolete config.status Use:: Obsolete convention for @command{config.status}
598 * acconfig Header:: Additional entries in @file{config.h.in}
599 * autoupdate Invocation:: Automatic update of @file{configure.ac}
600 * Obsolete Macros:: Backward compatibility macros
601 * Autoconf 1:: Tips for upgrading your files
602 * Autoconf 2.13:: Some fresher tips
604 Upgrading From Version 1
606 * Changed File Names:: Files you might rename
607 * Changed Makefiles:: New things to put in @file{Makefile.in}
608 * Changed Macros:: Macro calls you might replace
609 * Changed Results:: Changes in how to check test results
610 * Changed Macro Writing:: Better ways to write your own macros
612 Upgrading From Version 2.13
614 * Changed Quotation:: Broken code which used to work
615 * New Macros:: Interaction with foreign macros
616 * Hosts and Cross-Compilation:: Bugward compatibility kludges
617 * AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token
618 * AC_ACT_IFELSE vs AC_TRY_ACT:: A more generic scheme for testing sources
620 Generating Test Suites with Autotest
622 * Using an Autotest Test Suite:: Autotest and the user
623 * Writing Testsuites:: Autotest macros
624 * testsuite Invocation:: Running @command{testsuite} scripts
625 * Making testsuite Scripts:: Using autom4te to create @command{testsuite}
627 Using an Autotest Test Suite
629 * testsuite Scripts:: The concepts of Autotest
630 * Autotest Logs:: Their contents
632 Frequent Autoconf Questions, with answers
634 * Distributing:: Distributing @command{configure} scripts
635 * Why GNU M4:: Why not use the standard M4?
636 * Bootstrapping:: Autoconf and GNU M4 require each other?
637 * Why Not Imake:: Why GNU uses @command{configure} instead of Imake
638 * Defining Directories:: Passing @code{datadir} to program
639 * Autom4te Cache:: What is it? Can I remove it?
640 * Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree
641 * Expanded Before Required:: Expanded Before Required
642 * Debugging:: Debugging @command{configure} scripts
646 * Genesis:: Prehistory and naming of @command{configure}
647 * Exodus:: The plagues of M4 and Perl
648 * Leviticus:: The priestly code of portability arrives
649 * Numbers:: Growth and contributors
650 * Deuteronomy:: Approaching the promises of easy configuration
654 * Environment Variable Index:: Index of environment variables used
655 * Output Variable Index:: Index of variables set in output files
656 * Preprocessor Symbol Index:: Index of C preprocessor symbols defined
657 * Cache Variable Index:: Index of documented cache variables
658 * Autoconf Macro Index:: Index of Autoconf macros
659 * M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
660 * Autotest Macro Index:: Index of Autotest macros
661 * Program & Function Index:: Index of those with portability problems
662 * Concept Index:: General index
667 @c ============================================================= Introduction.
670 @chapter Introduction
674 A physicist, an engineer, and a computer scientist were discussing the
675 nature of God. ``Surely a Physicist,'' said the physicist, ``because
676 early in the Creation, God made Light; and you know, Maxwell's
677 equations, the dual nature of electromagnetic waves, the relativistic
678 consequences@enddots{}'' ``An Engineer!,'' said the engineer, ``because
679 before making Light, God split the Chaos into Land and Water; it takes a
680 hell of an engineer to handle that big amount of mud, and orderly
681 separation of solids from liquids@enddots{}'' The computer scientist
682 shouted: ``And the Chaos, where do you think it was coming from, hmm?''
686 @c (via Franc,ois Pinard)
688 Autoconf is a tool for producing shell scripts that automatically
689 configure software source code packages to adapt to many kinds of
690 Posix-like systems. The configuration scripts produced by Autoconf
691 are independent of Autoconf when they are run, so their users do not
692 need to have Autoconf.
694 The configuration scripts produced by Autoconf require no manual user
695 intervention when run; they do not normally even need an argument
696 specifying the system type. Instead, they individually test for the
697 presence of each feature that the software package they are for might need.
698 (Before each check, they print a one-line message stating what they are
699 checking for, so the user doesn't get too bored while waiting for the
700 script to finish.) As a result, they deal well with systems that are
701 hybrids or customized from the more common Posix variants. There is
702 no need to maintain files that list the features supported by each
703 release of each variant of Posix.
705 For each software package that Autoconf is used with, it creates a
706 configuration script from a template file that lists the system features
707 that the package needs or can use. After the shell code to recognize
708 and respond to a system feature has been written, Autoconf allows it to
709 be shared by many software packages that can use (or need) that feature.
710 If it later turns out that the shell code needs adjustment for some
711 reason, it needs to be changed in only one place; all of the
712 configuration scripts can be regenerated automatically to take advantage
715 @c "Those who do not understand Unix are condemned to reinvent it, poorly."
716 @c --Henry Spencer, 1987 (see http://en.wikipedia.org/wiki/Unix_philosophy)
717 Those who do not understand Autoconf are condemned to reinvent it, poorly.
718 The primary goal of Autoconf is making the @emph{user's} life easier;
719 making the @emph{maintainer's} life easier is only a secondary goal.
720 Put another way, the primary goal is not to make the generation of
721 @file{configure} automatic for package maintainers (although patches
722 along that front are welcome, since package maintainers form the user
723 base of Autoconf); rather, the goal is to make @file{configure}
724 painless, portable, and predictable for the end user of each
725 @dfn{autoconfiscated} package. And to this degree, Autoconf is highly
726 successful at its goal --- most complaints to the Autoconf list are
727 about difficulties in writing Autoconf input, and not in the behavior of
728 the resulting @file{configure}. Even packages that don't use Autoconf
729 will generally provide a @file{configure} script, and the most common
730 complaint about these alternative home-grown scripts is that they fail
731 to meet one or more of the GNU Coding Standards that users
732 have come to expect from Autoconf-generated @file{configure} scripts.
734 The Metaconfig package is similar in purpose to Autoconf, but the
735 scripts it produces require manual user intervention, which is quite
736 inconvenient when configuring large source trees. Unlike Metaconfig
737 scripts, Autoconf scripts can support cross-compiling, if some care is
738 taken in writing them.
740 Autoconf does not solve all problems related to making portable
741 software packages---for a more complete solution, it should be used in
742 concert with other GNU build tools like Automake and
743 Libtool. These other tools take on jobs like the creation of a
744 portable, recursive makefile with all of the standard targets,
745 linking of shared libraries, and so on. @xref{The GNU Build System},
746 for more information.
748 Autoconf imposes some restrictions on the names of macros used with
749 @code{#if} in C programs (@pxref{Preprocessor Symbol Index}).
751 Autoconf requires GNU M4 version 1.4.6 or later in order to
752 generate the scripts. It uses features that some versions of M4,
753 including GNU M4 1.3, do not have. Autoconf works better
754 with GNU M4 version 1.4.14 or later, though this is not
757 @xref{Autoconf 1}, for information about upgrading from version 1.
758 @xref{History}, for the story of Autoconf's development. @xref{FAQ},
759 for answers to some common questions about Autoconf.
761 See the @uref{http://@/www.gnu.org/@/software/@/autoconf/,
762 Autoconf web page} for up-to-date information, details on the mailing
763 lists, pointers to a list of known bugs, etc.
765 Mail suggestions to @email{autoconf@@gnu.org, the Autoconf mailing
766 list}. Past suggestions are
767 @uref{http://@/lists.gnu.org/@/archive/@/html/@/autoconf/, archived}.
769 Mail bug reports to @email{bug-autoconf@@gnu.org, the
770 Autoconf Bugs mailing list}. Past bug reports are
771 @uref{http://@/lists.gnu.org/@/archive/@/html/@/bug-autoconf/, archived}.
773 If possible, first check that your bug is
774 not already solved in current development versions, and that it has not
775 been reported yet. Be sure to include all the needed information and a
776 short @file{configure.ac} that demonstrates the problem.
778 Autoconf's development tree is accessible via @command{git}; see the
779 @uref{http://@/savannah.gnu.org/@/projects/@/autoconf/, Autoconf
780 Summary} for details, or view
781 @uref{http://@/git.sv.gnu.org/@/gitweb/@/?p=autoconf.git, the actual
782 repository}. Anonymous CVS access is also available, see
783 @file{README} for more details. Patches relative to the
784 current @command{git} version can be sent for review to the
785 @email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}, with
786 discussion on prior patches
787 @uref{http://@/lists.gnu.org/@/archive/@/html/@/autoconf-@/patches/,
788 archived}; and all commits are posted in the read-only
789 @email{autoconf-commit@@gnu.org, Autoconf Commit mailing list}, which is
790 also @uref{http://@/lists.gnu.org/@/archive/@/html/@/autoconf-commit/,
793 Because of its mission, the Autoconf package itself
794 includes only a set of often-used
795 macros that have already demonstrated their usefulness. Nevertheless,
796 if you wish to share your macros, or find existing ones, see the
797 @uref{http://@/www.gnu.org/@/software/@/autoconf-archive/, Autoconf Macro
798 Archive}, which is kindly run by @email{simons@@cryp.to,
802 @c ================================================= The GNU Build System
804 @node The GNU Build System
805 @chapter The GNU Build System
806 @cindex GNU build system
808 Autoconf solves an important problem---reliable discovery of
809 system-specific build and runtime information---but this is only one
810 piece of the puzzle for the development of portable software. To this
811 end, the GNU project has developed a suite of integrated
812 utilities to finish the job Autoconf started: the GNU build
813 system, whose most important components are Autoconf, Automake, and
814 Libtool. In this chapter, we introduce you to those tools, point you
815 to sources of more information, and try to convince you to use the
816 entire GNU build system for your software.
819 * Automake:: Escaping makefile hell
820 * Gnulib:: The GNU portability library
821 * Libtool:: Building libraries portably
822 * Pointers:: More info on the GNU build system
828 The ubiquity of @command{make} means that a makefile is almost the
829 only viable way to distribute automatic build rules for software, but
830 one quickly runs into its numerous limitations. Its lack of
831 support for automatic dependency tracking, recursive builds in
832 subdirectories, reliable timestamps (e.g., for network file systems), and
833 so on, mean that developers must painfully (and often incorrectly)
834 reinvent the wheel for each project. Portability is non-trivial, thanks
835 to the quirks of @command{make} on many systems. On top of all this is the
836 manual labor required to implement the many standard targets that users
837 have come to expect (@code{make install}, @code{make distclean},
838 @code{make uninstall}, etc.). Since you are, of course, using Autoconf,
839 you also have to insert repetitive code in your @file{Makefile.in} to
840 recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions
841 provided by @command{configure}. Into this mess steps @dfn{Automake}.
844 Automake allows you to specify your build needs in a @file{Makefile.am}
845 file with a vastly simpler and more powerful syntax than that of a plain
846 makefile, and then generates a portable @file{Makefile.in} for
847 use with Autoconf. For example, the @file{Makefile.am} to build and
848 install a simple ``Hello world'' program might look like:
852 hello_SOURCES = hello.c
856 The resulting @file{Makefile.in} (~400 lines) automatically supports all
857 the standard targets, the substitutions provided by Autoconf, automatic
858 dependency tracking, @code{VPATH} building, and so on. @command{make}
859 builds the @code{hello} program, and @code{make install} installs it
860 in @file{/usr/local/bin} (or whatever prefix was given to
861 @command{configure}, if not @file{/usr/local}).
863 The benefits of Automake increase for larger packages (especially ones
864 with subdirectories), but even for small programs the added convenience
865 and portability can be substantial. And that's not all@enddots{}
870 GNU software has a well-deserved reputation for running on
871 many different types of systems. While our primary goal is to write
872 software for the GNU system, many users and developers have
873 been introduced to us through the systems that they were already using.
876 Gnulib is a central location for common GNU code, intended to
877 be shared among free software packages. Its components are typically
878 shared at the source level, rather than being a library that gets built,
879 installed, and linked against. The idea is to copy files from Gnulib
880 into your own source tree. There is no distribution tarball; developers
881 should just grab source modules from the repository. The source files
882 are available online, under various licenses, mostly GNU
885 Gnulib modules typically contain C source code along with Autoconf
886 macros used to configure the source code. For example, the Gnulib
887 @code{stdbool} module implements a @file{stdbool.h} header that nearly
888 conforms to C99, even on old-fashioned hosts that lack @file{stdbool.h}.
889 This module contains a source file for the replacement header, along
890 with an Autoconf macro that arranges to use the replacement header on
891 old-fashioned systems.
896 Often, one wants to build not only programs, but libraries, so that
897 other programs can benefit from the fruits of your labor. Ideally, one
898 would like to produce @emph{shared} (dynamically linked) libraries,
899 which can be used by multiple programs without duplication on disk or in
900 memory and can be updated independently of the linked programs.
901 Producing shared libraries portably, however, is the stuff of
902 nightmares---each system has its own incompatible tools, compiler flags,
903 and magic incantations. Fortunately, GNU provides a solution:
907 Libtool handles all the requirements of building shared libraries for
908 you, and at this time seems to be the @emph{only} way to do so with any
909 portability. It also handles many other headaches, such as: the
910 interaction of Make rules with the variable suffixes of
911 shared libraries, linking reliably with shared libraries before they are
912 installed by the superuser, and supplying a consistent versioning system
913 (so that different versions of a library can be installed or upgraded
914 without breaking binary compatibility). Although Libtool, like
915 Autoconf, can be used without Automake, it is most simply utilized in
916 conjunction with Automake---there, Libtool is used automatically
917 whenever shared libraries are needed, and you need not know its syntax.
922 Developers who are used to the simplicity of @command{make} for small
923 projects on a single system might be daunted at the prospect of
924 learning to use Automake and Autoconf. As your software is
925 distributed to more and more users, however, you otherwise
926 quickly find yourself putting lots of effort into reinventing the
927 services that the GNU build tools provide, and making the
928 same mistakes that they once made and overcame. (Besides, since
929 you're already learning Autoconf, Automake is a piece of cake.)
931 There are a number of places that you can go to for more information on
938 The project home pages for
939 @uref{http://@/www@/.gnu@/.org/@/software/@/autoconf/, Autoconf},
940 @uref{http://@/www@/.gnu@/.org/@/software/@/automake/, Automake},
941 @uref{http://@/www@/.gnu@/.org/@/software/@/gnulib/, Gnulib}, and
942 @uref{http://@/www@/.gnu@/.org/@/software/@/libtool/, Libtool}.
944 @item Automake Manual
946 @xref{Top, , Automake, automake, GNU Automake}, for more
947 information on Automake.
951 The book @cite{GNU Autoconf, Automake and
952 Libtool}@footnote{@cite{GNU Autoconf, Automake and Libtool},
953 by G. V. Vaughan, B. Elliston, T. Tromey, and I. L. Taylor. SAMS (originally
954 New Riders), 2000, ISBN 1578701902.} describes the complete GNU
955 build environment. You can also find
956 @uref{http://@/sources.redhat.com/@/autobook/, the entire book on-line}.
960 @c ================================================= Making configure Scripts.
962 @node Making configure Scripts
963 @chapter Making @command{configure} Scripts
964 @cindex @file{aclocal.m4}
965 @cindex @command{configure}
967 The configuration scripts that Autoconf produces are by convention
968 called @command{configure}. When run, @command{configure} creates several
969 files, replacing configuration parameters in them with appropriate
970 values. The files that @command{configure} creates are:
974 one or more @file{Makefile} files, usually one in each subdirectory of the
975 package (@pxref{Makefile Substitutions});
978 optionally, a C header file, the name of which is configurable,
979 containing @code{#define} directives (@pxref{Configuration Headers});
982 a shell script called @file{config.status} that, when run, recreates
983 the files listed above (@pxref{config.status Invocation});
986 an optional shell script normally called @file{config.cache}
987 (created when using @samp{configure --config-cache}) that
988 saves the results of running many of the tests (@pxref{Cache Files});
991 a file called @file{config.log} containing any messages produced by
992 compilers, to help debugging if @command{configure} makes a mistake.
995 @cindex @file{configure.in}
996 @cindex @file{configure.ac}
997 To create a @command{configure} script with Autoconf, you need to write an
998 Autoconf input file @file{configure.ac} (or @file{configure.in}) and run
999 @command{autoconf} on it. If you write your own feature tests to
1000 supplement those that come with Autoconf, you might also write files
1001 called @file{aclocal.m4} and @file{acsite.m4}. If you use a C header
1002 file to contain @code{#define} directives, you might also run
1003 @command{autoheader}, and you can distribute the generated file
1004 @file{config.h.in} with the package.
1006 Here is a diagram showing how the files that can be used in
1007 configuration are produced. Programs that are executed are suffixed by
1008 @samp{*}. Optional files are enclosed in square brackets (@samp{[]}).
1009 @command{autoconf} and @command{autoheader} also read the installed Autoconf
1010 macro files (by reading @file{autoconf.m4}).
1013 Files used in preparing a software package for distribution, when using
1016 your source files --> [autoscan*] --> [configure.scan] --> configure.ac
1020 | .------> autoconf* -----> configure
1021 [aclocal.m4] --+---+
1022 | `-----> [autoheader*] --> [config.h.in]
1030 Additionally, if you use Automake, the following additional productions
1037 [local macros] --+--> aclocal* --> aclocal.m4
1044 +--> automake* --> Makefile.in
1050 Files used in configuring a software package:
1053 .-------------> [config.cache]
1054 configure* ------------+-------------> config.log
1056 [config.h.in] -. v .-> [config.h] -.
1057 +--> config.status* -+ +--> make*
1058 Makefile.in ---' `-> Makefile ---'
1063 * Writing Autoconf Input:: What to put in an Autoconf input file
1064 * autoscan Invocation:: Semi-automatic @file{configure.ac} writing
1065 * ifnames Invocation:: Listing the conditionals in source code
1066 * autoconf Invocation:: How to create configuration scripts
1067 * autoreconf Invocation:: Remaking multiple @command{configure} scripts
1070 @node Writing Autoconf Input
1071 @section Writing @file{configure.ac}
1073 To produce a @command{configure} script for a software package, create a
1074 file called @file{configure.ac} that contains invocations of the
1075 Autoconf macros that test the system features your package needs or can
1076 use. Autoconf macros already exist to check for many features; see
1077 @ref{Existing Tests}, for their descriptions. For most other features,
1078 you can use Autoconf template macros to produce custom checks; see
1079 @ref{Writing Tests}, for information about them. For especially tricky
1080 or specialized features, @file{configure.ac} might need to contain some
1081 hand-crafted shell commands; see @ref{Portable Shell, , Portable Shell
1082 Programming}. The @command{autoscan} program can give you a good start
1083 in writing @file{configure.ac} (@pxref{autoscan Invocation}, for more
1086 Previous versions of Autoconf promoted the name @file{configure.in},
1087 which is somewhat ambiguous (the tool needed to process this file is not
1088 described by its extension), and introduces a slight confusion with
1089 @file{config.h.in} and so on (for which @samp{.in} means ``to be
1090 processed by @command{configure}''). Using @file{configure.ac} is now
1094 * Shell Script Compiler:: Autoconf as solution of a problem
1095 * Autoconf Language:: Programming in Autoconf
1096 * Autoconf Input Layout:: Standard organization of @file{configure.ac}
1099 @node Shell Script Compiler
1100 @subsection A Shell Script Compiler
1102 Just as for any other computer language, in order to properly program
1103 @file{configure.ac} in Autoconf you must understand @emph{what} problem
1104 the language tries to address and @emph{how} it does so.
1106 The problem Autoconf addresses is that the world is a mess. After all,
1107 you are using Autoconf in order to have your package compile easily on
1108 all sorts of different systems, some of them being extremely hostile.
1109 Autoconf itself bears the price for these differences: @command{configure}
1110 must run on all those systems, and thus @command{configure} must limit itself
1111 to their lowest common denominator of features.
1113 Naturally, you might then think of shell scripts; who needs
1114 @command{autoconf}? A set of properly written shell functions is enough to
1115 make it easy to write @command{configure} scripts by hand. Sigh!
1116 Unfortunately, even in 2008, where shells without any function support are
1117 far and few between, there are pitfalls to avoid when making use of them.
1118 Also, finding a Bourne shell that accepts shell functions is not trivial,
1119 even though there is almost always one on interesting porting targets.
1121 So, what is really needed is some kind of compiler, @command{autoconf},
1122 that takes an Autoconf program, @file{configure.ac}, and transforms it
1123 into a portable shell script, @command{configure}.
1125 How does @command{autoconf} perform this task?
1127 There are two obvious possibilities: creating a brand new language or
1128 extending an existing one. The former option is attractive: all
1129 sorts of optimizations could easily be implemented in the compiler and
1130 many rigorous checks could be performed on the Autoconf program
1131 (e.g., rejecting any non-portable construct). Alternatively, you can
1132 extend an existing language, such as the @code{sh} (Bourne shell)
1135 Autoconf does the latter: it is a layer on top of @code{sh}. It was
1136 therefore most convenient to implement @command{autoconf} as a macro
1137 expander: a program that repeatedly performs @dfn{macro expansions} on
1138 text input, replacing macro calls with macro bodies and producing a pure
1139 @code{sh} script in the end. Instead of implementing a dedicated
1140 Autoconf macro expander, it is natural to use an existing
1141 general-purpose macro language, such as M4, and implement the extensions
1142 as a set of M4 macros.
1145 @node Autoconf Language
1146 @subsection The Autoconf Language
1149 The Autoconf language differs from many other computer
1150 languages because it treats actual code the same as plain text. Whereas
1151 in C, for instance, data and instructions have different syntactic
1152 status, in Autoconf their status is rigorously the same. Therefore, we
1153 need a means to distinguish literal strings from text to be expanded:
1156 When calling macros that take arguments, there must not be any white
1157 space between the macro name and the open parenthesis.
1160 AC_INIT ([oops], [1.0]) # incorrect
1161 AC_INIT([hello], [1.0]) # good
1165 be enclosed within the quote characters @samp{[} and @samp{]}, and be
1166 separated by commas. Any leading blanks or newlines in arguments are ignored,
1167 unless they are quoted. You should always quote an argument that
1168 might contain a macro name, comma, parenthesis, or a leading blank or
1169 newline. This rule applies recursively for every macro
1170 call, including macros called from other macros. For more details on
1171 quoting rules, see @ref{Programming in M4}.
1176 AC_CHECK_HEADER([stdio.h],
1177 [AC_DEFINE([HAVE_STDIO_H], [1],
1178 [Define to 1 if you have <stdio.h>.])],
1179 [AC_MSG_ERROR([sorry, can't do anything for you])])
1183 is quoted properly. You may safely simplify its quotation to:
1186 AC_CHECK_HEADER([stdio.h],
1187 [AC_DEFINE([HAVE_STDIO_H], 1,
1188 [Define to 1 if you have <stdio.h>.])],
1189 [AC_MSG_ERROR([sorry, can't do anything for you])])
1193 because @samp{1} cannot contain a macro call. Here, the argument of
1194 @code{AC_MSG_ERROR} must be quoted; otherwise, its comma would be
1195 interpreted as an argument separator. Also, the second and third arguments
1196 of @samp{AC_CHECK_HEADER} must be quoted, since they contain
1197 macro calls. The three arguments @samp{HAVE_STDIO_H}, @samp{stdio.h},
1198 and @samp{Define to 1 if you have <stdio.h>.} do not need quoting, but
1199 if you unwisely defined a macro with a name like @samp{Define} or
1200 @samp{stdio} then they would need quoting. Cautious Autoconf users
1201 would keep the quotes, but many Autoconf users find such precautions
1202 annoying, and would rewrite the example as follows:
1205 AC_CHECK_HEADER(stdio.h,
1206 [AC_DEFINE(HAVE_STDIO_H, 1,
1207 [Define to 1 if you have <stdio.h>.])],
1208 [AC_MSG_ERROR([sorry, can't do anything for you])])
1212 This is safe, so long as you adopt good naming conventions and do not
1213 define macros with names like @samp{HAVE_STDIO_H}, @samp{stdio}, or
1214 @samp{h}. Though it is also safe here to omit the quotes around
1215 @samp{Define to 1 if you have <stdio.h>.} this is not recommended, as
1216 message strings are more likely to inadvertently contain commas.
1218 The following example is wrong and dangerous, as it is underquoted:
1221 AC_CHECK_HEADER(stdio.h,
1222 AC_DEFINE(HAVE_STDIO_H, 1,
1223 Define to 1 if you have <stdio.h>.),
1224 AC_MSG_ERROR([sorry, can't do anything for you]))
1227 In other cases, you may have to use text that also resembles a macro
1228 call. You must quote that text even when it is not passed as a macro
1229 argument. For example, these two approaches in @file{configure.ac}
1230 (quoting just the potential problems, or quoting the entire line) will
1231 protect your script in case autoconf ever adds a macro @code{AC_DC}:
1234 echo "Hard rock was here! --[AC_DC]"
1235 [echo "Hard rock was here! --AC_DC"]
1239 which results in this text in @file{configure}:
1242 echo "Hard rock was here! --AC_DC"
1243 echo "Hard rock was here! --AC_DC"
1247 When you use the same text in a macro argument, you must therefore have
1248 an extra quotation level (since one is stripped away by the macro
1249 substitution). In general, then, it is a good idea to @emph{use double
1250 quoting for all literal string arguments}, either around just the
1251 problematic portions, or over the entire argument:
1254 AC_MSG_WARN([[AC_DC] stinks --Iron Maiden])
1255 AC_MSG_WARN([[AC_DC stinks --Iron Maiden]])
1258 However, the above example triggers a warning about a possibly
1259 unexpanded macro when running @command{autoconf}, because it collides
1260 with the namespace of macros reserved for the Autoconf language. To be
1261 really safe, you can use additional escaping (either a quadrigraph, or
1262 creative shell constructs) to silence that particular warning:
1265 echo "Hard rock was here! --AC""_DC"
1266 AC_MSG_WARN([[AC@@&t@@_DC stinks --Iron Maiden]])
1269 You are now able to understand one of the constructs of Autoconf that
1270 has been continually misunderstood@enddots{} The rule of thumb is that
1271 @emph{whenever you expect macro expansion, expect quote expansion};
1272 i.e., expect one level of quotes to be lost. For instance:
1275 AC_COMPILE_IFELSE([char b[10];], [], [AC_MSG_ERROR([you lose])])
1279 is incorrect: here, the first argument of @code{AC_COMPILE_IFELSE} is
1280 @samp{char b[10];} and is expanded once, which results in
1281 @samp{char b10;}. (There was an idiom common in Autoconf's past to
1282 address this issue via the M4 @code{changequote} primitive, but do not
1283 use it!) Let's take a closer look: the author meant the first argument
1284 to be understood as a literal, and therefore it must be quoted twice:
1287 AC_COMPILE_IFELSE([[char b[10];]], [], [AC_MSG_ERROR([you lose])])
1291 Voil@`a, you actually produce @samp{char b[10];} this time!
1293 On the other hand, descriptions (e.g., the last parameter of
1294 @code{AC_DEFINE} or @code{AS_HELP_STRING}) are not literals---they
1295 are subject to line breaking, for example---and should not be double quoted.
1296 Even if these descriptions are short and are not actually broken, double
1297 quoting them yields weird results.
1299 Some macros take optional arguments, which this documentation represents
1300 as @ovar{arg} (not to be confused with the quote characters). You may
1301 just leave them empty, or use @samp{[]} to make the emptiness of the
1302 argument explicit, or you may simply omit the trailing commas. The
1303 three lines below are equivalent:
1306 AC_CHECK_HEADERS([stdio.h], [], [], [])
1307 AC_CHECK_HEADERS([stdio.h],,,)
1308 AC_CHECK_HEADERS([stdio.h])
1311 It is best to put each macro call on its own line in
1312 @file{configure.ac}. Most of the macros don't add extra newlines; they
1313 rely on the newline after the macro call to terminate the commands.
1314 This approach makes the generated @command{configure} script a little
1315 easier to read by not inserting lots of blank lines. It is generally
1316 safe to set shell variables on the same line as a macro call, because
1317 the shell allows assignments without intervening newlines.
1319 You can include comments in @file{configure.ac} files by starting them
1320 with the @samp{#}. For example, it is helpful to begin
1321 @file{configure.ac} files with a line like this:
1324 # Process this file with autoconf to produce a configure script.
1327 @node Autoconf Input Layout
1328 @subsection Standard @file{configure.ac} Layout
1330 The order in which @file{configure.ac} calls the Autoconf macros is not
1331 important, with a few exceptions. Every @file{configure.ac} must
1332 contain a call to @code{AC_INIT} before the checks, and a call to
1333 @code{AC_OUTPUT} at the end (@pxref{Output}). Additionally, some macros
1334 rely on other macros having been called first, because they check
1335 previously set values of some variables to decide what to do. These
1336 macros are noted in the individual descriptions (@pxref{Existing
1337 Tests}), and they also warn you when @command{configure} is created if they
1338 are called out of order.
1340 To encourage consistency, here is a suggested order for calling the
1341 Autoconf macros. Generally speaking, the things near the end of this
1342 list are those that could depend on things earlier in it. For example,
1343 library functions could be affected by types and libraries.
1347 Autoconf requirements
1348 @code{AC_INIT(@var{package}, @var{version}, @var{bug-report-address})}
1349 information on the package
1351 checks for libraries
1352 checks for header files
1354 checks for structures
1355 checks for compiler characteristics
1356 checks for library functions
1357 checks for system services
1358 @code{AC_CONFIG_FILES(@r{[}@var{file@dots{}}@r{]})}
1364 @node autoscan Invocation
1365 @section Using @command{autoscan} to Create @file{configure.ac}
1366 @cindex @command{autoscan}
1368 The @command{autoscan} program can help you create and/or maintain a
1369 @file{configure.ac} file for a software package. @command{autoscan}
1370 examines source files in the directory tree rooted at a directory given
1371 as a command line argument, or the current directory if none is given.
1372 It searches the source files for common portability problems and creates
1373 a file @file{configure.scan} which is a preliminary @file{configure.ac}
1374 for that package, and checks a possibly existing @file{configure.ac} for
1377 When using @command{autoscan} to create a @file{configure.ac}, you
1378 should manually examine @file{configure.scan} before renaming it to
1379 @file{configure.ac}; it probably needs some adjustments.
1380 Occasionally, @command{autoscan} outputs a macro in the wrong order
1381 relative to another macro, so that @command{autoconf} produces a warning;
1382 you need to move such macros manually. Also, if you want the package to
1383 use a configuration header file, you must add a call to
1384 @code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}). You might
1385 also have to change or add some @code{#if} directives to your program in
1386 order to make it work with Autoconf (@pxref{ifnames Invocation}, for
1387 information about a program that can help with that job).
1389 When using @command{autoscan} to maintain a @file{configure.ac}, simply
1390 consider adding its suggestions. The file @file{autoscan.log}
1391 contains detailed information on why a macro is requested.
1393 @command{autoscan} uses several data files (installed along with Autoconf)
1394 to determine which macros to output when it finds particular symbols in
1395 a package's source files. These data files all have the same format:
1396 each line consists of a symbol, one or more blanks, and the Autoconf macro to
1397 output if that symbol is encountered. Lines starting with @samp{#} are
1400 @command{autoscan} accepts the following options:
1405 Print a summary of the command line options and exit.
1409 Print the version number of Autoconf and exit.
1413 Print the names of the files it examines and the potentially interesting
1414 symbols it finds in them. This output can be voluminous.
1418 Don't remove temporary files.
1420 @item --include=@var{dir}
1422 Append @var{dir} to the include path. Multiple invocations accumulate.
1424 @item --prepend-include=@var{dir}
1426 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1429 @node ifnames Invocation
1430 @section Using @command{ifnames} to List Conditionals
1431 @cindex @command{ifnames}
1433 @command{ifnames} can help you write @file{configure.ac} for a software
1434 package. It prints the identifiers that the package already uses in C
1435 preprocessor conditionals. If a package has already been set up to have
1436 some portability, @command{ifnames} can thus help you figure out what its
1437 @command{configure} needs to check for. It may help fill in some gaps in a
1438 @file{configure.ac} generated by @command{autoscan} (@pxref{autoscan
1441 @command{ifnames} scans all of the C source files named on the command line
1442 (or the standard input, if none are given) and writes to the standard
1443 output a sorted list of all the identifiers that appear in those files
1444 in @code{#if}, @code{#elif}, @code{#ifdef}, or @code{#ifndef}
1445 directives. It prints each identifier on a line, followed by a
1446 space-separated list of the files in which that identifier occurs.
1449 @command{ifnames} accepts the following options:
1454 Print a summary of the command line options and exit.
1458 Print the version number of Autoconf and exit.
1461 @node autoconf Invocation
1462 @section Using @command{autoconf} to Create @command{configure}
1463 @cindex @command{autoconf}
1465 To create @command{configure} from @file{configure.ac}, run the
1466 @command{autoconf} program with no arguments. @command{autoconf} processes
1467 @file{configure.ac} with the M4 macro processor, using the
1468 Autoconf macros. If you give @command{autoconf} an argument, it reads that
1469 file instead of @file{configure.ac} and writes the configuration script
1470 to the standard output instead of to @command{configure}. If you give
1471 @command{autoconf} the argument @option{-}, it reads from the standard
1472 input instead of @file{configure.ac} and writes the configuration script
1473 to the standard output.
1475 The Autoconf macros are defined in several files. Some of the files are
1476 distributed with Autoconf; @command{autoconf} reads them first. Then it
1477 looks for the optional file @file{acsite.m4} in the directory that
1478 contains the distributed Autoconf macro files, and for the optional file
1479 @file{aclocal.m4} in the current directory. Those files can contain
1480 your site's or the package's own Autoconf macro definitions
1481 (@pxref{Writing Autoconf Macros}, for more information). If a macro is
1482 defined in more than one of the files that @command{autoconf} reads, the
1483 last definition it reads overrides the earlier ones.
1485 @command{autoconf} accepts the following options:
1490 Print a summary of the command line options and exit.
1494 Print the version number of Autoconf and exit.
1498 Report processing steps.
1502 Don't remove the temporary files.
1506 Remake @file{configure} even if newer than its input files.
1508 @item --include=@var{dir}
1510 Append @var{dir} to the include path. Multiple invocations accumulate.
1512 @item --prepend-include=@var{dir}
1514 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1516 @item --output=@var{file}
1517 @itemx -o @var{file}
1518 Save output (script or trace) to @var{file}. The file @option{-} stands
1519 for the standard output.
1521 @item --warnings=@var{category}
1522 @itemx -W @var{category}
1524 Report the warnings related to @var{category} (which can actually be a
1525 comma separated list). @xref{Reporting Messages}, macro
1526 @code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
1531 report all the warnings
1537 treats warnings as errors
1539 @item no-@var{category}
1540 disable warnings falling into @var{category}
1543 Warnings about @samp{syntax} are enabled by default, and the environment
1544 variable @env{WARNINGS}, a comma separated list of categories, is
1545 honored as well. Passing @option{-W @var{category}} actually behaves as if
1546 you had passed @option{--warnings syntax,$WARNINGS,@var{category}}. To
1547 disable the defaults and @env{WARNINGS}, and then
1548 enable warnings about obsolete constructs, use @option{-W
1552 @cindex Macro invocation stack
1553 Because @command{autoconf} uses @command{autom4te} behind the scenes, it
1554 displays a back trace for errors, but not for warnings; if you want
1555 them, just pass @option{-W error}. @xref{autom4te Invocation}, for some
1558 @item --trace=@var{macro}[:@var{format}]
1559 @itemx -t @var{macro}[:@var{format}]
1560 Do not create the @command{configure} script, but list the calls to
1561 @var{macro} according to the @var{format}. Multiple @option{--trace}
1562 arguments can be used to list several macros. Multiple @option{--trace}
1563 arguments for a single macro are not cumulative; instead, you should
1564 just make @var{format} as long as needed.
1566 The @var{format} is a regular string, with newlines if desired, and
1567 several special escape codes. It defaults to @samp{$f:$l:$n:$%}; see
1568 @ref{autom4te Invocation}, for details on the @var{format}.
1570 @item --initialization
1572 By default, @option{--trace} does not trace the initialization of the
1573 Autoconf macros (typically the @code{AC_DEFUN} definitions). This
1574 results in a noticeable speedup, but can be disabled by this option.
1578 It is often necessary to check the content of a @file{configure.ac}
1579 file, but parsing it yourself is extremely fragile and error-prone. It
1580 is suggested that you rely upon @option{--trace} to scan
1581 @file{configure.ac}. For instance, to find the list of variables that
1582 are substituted, use:
1586 $ @kbd{autoconf -t AC_SUBST}
1587 configure.ac:2:AC_SUBST:ECHO_C
1588 configure.ac:2:AC_SUBST:ECHO_N
1589 configure.ac:2:AC_SUBST:ECHO_T
1590 @i{More traces deleted}
1595 The example below highlights the difference between @samp{$@@},
1596 @samp{$*}, and @samp{$%}.
1600 $ @kbd{cat configure.ac}
1601 AC_DEFINE(This, is, [an
1603 $ @kbd{autoconf -t 'AC_DEFINE:@@: $@@}
1610 %: This:is:an [example]
1615 The @var{format} gives you a lot of freedom:
1619 $ @kbd{autoconf -t 'AC_SUBST:$$ac_subst@{"$1"@} = "$f:$l";'}
1620 $ac_subst@{"ECHO_C"@} = "configure.ac:2";
1621 $ac_subst@{"ECHO_N"@} = "configure.ac:2";
1622 $ac_subst@{"ECHO_T"@} = "configure.ac:2";
1623 @i{More traces deleted}
1628 A long @var{separator} can be used to improve the readability of complex
1629 structures, and to ease their parsing (for instance when no single
1630 character is suitable as a separator):
1634 $ @kbd{autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*'}
1635 ACLOCAL|:::::|aclocal|:::::|$missing_dir
1636 AUTOCONF|:::::|autoconf|:::::|$missing_dir
1637 AUTOMAKE|:::::|automake|:::::|$missing_dir
1638 @i{More traces deleted}
1642 @node autoreconf Invocation
1643 @section Using @command{autoreconf} to Update @command{configure} Scripts
1644 @cindex @command{autoreconf}
1646 Installing the various components of the GNU Build System can be
1647 tedious: running @command{autopoint} for Gettext, @command{automake} for
1648 @file{Makefile.in} etc.@: in each directory. It may be needed either
1649 because some tools such as @command{automake} have been updated on your
1650 system, or because some of the sources such as @file{configure.ac} have
1651 been updated, or finally, simply in order to install the GNU Build
1652 System in a fresh tree.
1654 @command{autoreconf} runs @command{autoconf}, @command{autoheader},
1655 @command{aclocal}, @command{automake}, @command{libtoolize}, and
1656 @command{autopoint} (when appropriate) repeatedly to update the
1657 GNU Build System in the specified directories and their
1658 subdirectories (@pxref{Subdirectories}). By default, it only remakes
1659 those files that are older than their sources. The environment variables
1660 @env{AUTOCONF}, @env{AUTOHEADER}, @env{AUTOMAKE}, @env{ACLOCAL},
1661 @env{AUTOPOINT}, @env{LIBTOOLIZE}, @env{M4}, and @env{MAKE} may be used
1662 to override the invocation of the respective tools.
1664 If you install a new version of some tool, you can make
1665 @command{autoreconf} remake @emph{all} of the files by giving it the
1666 @option{--force} option.
1668 @xref{Automatic Remaking}, for Make rules to automatically
1669 rebuild @command{configure} scripts when their source files change. That
1670 method handles the timestamps of configuration header templates
1671 properly, but does not pass @option{--autoconf-dir=@var{dir}} or
1672 @option{--localdir=@var{dir}}.
1675 @cindex @command{autopoint}
1676 Gettext supplies the @command{autopoint} command to add translation
1677 infrastructure to a source package. If you use @command{autopoint},
1678 your @file{configure.ac} should invoke both @code{AM_GNU_GETTEXT} and
1679 @code{AM_GNU_GETTEXT_VERSION(@var{gettext-version})}. @xref{autopoint
1680 Invocation, , Invoking the @code{autopoint} Program, gettext,
1681 GNU @code{gettext} utilities}, for further details.
1684 @command{autoreconf} accepts the following options:
1689 Print a summary of the command line options and exit.
1693 Print the version number of Autoconf and exit.
1697 Print the name of each directory @command{autoreconf} examines and the
1698 commands it runs. If given two or more times, pass @option{--verbose}
1699 to subordinate tools that support it.
1703 Don't remove the temporary files.
1707 Remake even @file{configure} scripts and configuration headers that are
1708 newer than their input files (@file{configure.ac} and, if present,
1713 Install the missing auxiliary files in the package. By default, files
1714 are copied; this can be changed with @option{--symlink}.
1716 If deemed appropriate, this option triggers calls to
1717 @samp{automake --add-missing},
1718 @samp{libtoolize}, @samp{autopoint}, etc.
1720 @item --no-recursive
1721 Do not rebuild files in subdirectories to configure (see @ref{Subdirectories},
1722 macro @code{AC_CONFIG_SUBDIRS}).
1726 When used with @option{--install}, install symbolic links to the missing
1727 auxiliary files instead of copying them.
1731 When the directories were configured, update the configuration by
1732 running @samp{./config.status --recheck && ./config.status}, and then
1735 @item --include=@var{dir}
1737 Append @var{dir} to the include path. Multiple invocations accumulate.
1738 Passed on to @command{aclocal}, @command{autoconf} and
1739 @command{autoheader} internally.
1741 @item --prepend-include=@var{dir}
1743 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1744 Passed on to @command{autoconf} and @command{autoheader} internally.
1746 @item --warnings=@var{category}
1747 @itemx -W @var{category}
1749 Report the warnings related to @var{category} (which can actually be a
1750 comma separated list).
1754 related to cross compilation issues.
1757 report the uses of obsolete constructs.
1763 dubious syntactic constructs.
1766 report all the warnings
1772 treats warnings as errors
1774 @item no-@var{category}
1775 disable warnings falling into @var{category}
1778 Warnings about @samp{syntax} are enabled by default, and the environment
1779 variable @env{WARNINGS}, a comma separated list of categories, is
1780 honored as well. Passing @option{-W @var{category}} actually behaves as if
1781 you had passed @option{--warnings syntax,$WARNINGS,@var{category}}. To
1782 disable the defaults and @env{WARNINGS}, and then
1783 enable warnings about obsolete constructs, use @option{-W
1787 If you want @command{autoreconf} to pass flags that are not listed here
1788 on to @command{aclocal}, set @code{ACLOCAL_AMFLAGS} in your @file{Makefile.am}.
1789 Due to a limitation in the Autoconf implementation these flags currently
1790 must be set on a single line in @file{Makefile.am}, without any
1793 @c ========================================= Initialization and Output Files.
1796 @chapter Initialization and Output Files
1798 Autoconf-generated @command{configure} scripts need some information about
1799 how to initialize, such as how to find the package's source files and
1800 about the output files to produce. The following sections describe the
1801 initialization and the creation of output files.
1804 * Initializing configure:: Option processing etc.
1805 * Versioning:: Dealing with Autoconf versions
1806 * Notices:: Copyright, version numbers in @command{configure}
1807 * Input:: Where Autoconf should find files
1808 * Output:: Outputting results from the configuration
1809 * Configuration Actions:: Preparing the output based on results
1810 * Configuration Files:: Creating output files
1811 * Makefile Substitutions:: Using output variables in makefiles
1812 * Configuration Headers:: Creating a configuration header file
1813 * Configuration Commands:: Running arbitrary instantiation commands
1814 * Configuration Links:: Links depending on the configuration
1815 * Subdirectories:: Configuring independent packages together
1816 * Default Prefix:: Changing the default installation prefix
1819 @node Initializing configure
1820 @section Initializing @command{configure}
1822 Every @command{configure} script must call @code{AC_INIT} before doing
1823 anything else that produces output. Calls to silent macros, such as
1824 @code{AC_DEFUN}, may also occur prior to @code{AC_INIT}, although these
1825 are generally used via @file{aclocal.m4}, since that is implicitly
1826 included before the start of @file{configure.ac}. The only other
1827 required macro is @code{AC_OUTPUT} (@pxref{Output}).
1830 @defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report}, @
1831 @ovar{tarname}, @ovar{url})
1833 Process any command-line arguments and perform various initializations
1836 Set the name of the @var{package} and its @var{version}. These are
1837 typically used in @option{--version} support, including that of
1838 @command{configure}. The optional argument @var{bug-report} should be
1839 the email to which users should send bug reports. The package
1840 @var{tarname} differs from @var{package}: the latter designates the full
1841 package name (e.g., @samp{GNU Autoconf}), while the former is meant for
1842 distribution tar ball names (e.g., @samp{autoconf}). It defaults to
1843 @var{package} with @samp{GNU } stripped, lower-cased, and all characters
1844 other than alphanumerics and underscores are changed to @samp{-}. If
1845 provided, @var{url} should be the home page for the package.
1847 The arguments of @code{AC_INIT} must be static, i.e., there should not
1848 be any shell computation, quotes, or newlines, but they can be computed
1849 by M4. This is because the package information strings are expanded at
1850 M4 time into several contexts, and must give the same text at shell time
1851 whether used in single-quoted strings, double-quoted strings, quoted
1852 here-documents, or unquoted here-documents. It is permissible to use
1853 @code{m4_esyscmd} or @code{m4_esyscmd_s} for computing a version string
1854 that changes with every commit to a version control system (in fact,
1855 Autoconf does just that, for all builds of the development tree made
1858 The following M4 macros (e.g., @code{AC_PACKAGE_NAME}), output variables
1859 (e.g., @code{PACKAGE_NAME}), and preprocessor symbols (e.g.,
1860 @code{PACKAGE_NAME}), are defined by @code{AC_INIT}:
1863 @item @code{AC_PACKAGE_NAME}, @code{PACKAGE_NAME}
1864 @acindex{PACKAGE_NAME}
1865 @ovindex PACKAGE_NAME
1866 @cvindex PACKAGE_NAME
1867 Exactly @var{package}.
1869 @item @code{AC_PACKAGE_TARNAME}, @code{PACKAGE_TARNAME}
1870 @acindex{PACKAGE_TARNAME}
1871 @ovindex PACKAGE_TARNAME
1872 @cvindex PACKAGE_TARNAME
1873 Exactly @var{tarname}, possibly generated from @var{package}.
1875 @item @code{AC_PACKAGE_VERSION}, @code{PACKAGE_VERSION}
1876 @acindex{PACKAGE_VERSION}
1877 @ovindex PACKAGE_VERSION
1878 @cvindex PACKAGE_VERSION
1879 Exactly @var{version}.
1881 @item @code{AC_PACKAGE_STRING}, @code{PACKAGE_STRING}
1882 @acindex{PACKAGE_STRING}
1883 @ovindex PACKAGE_STRING
1884 @cvindex PACKAGE_STRING
1885 Exactly @samp{@var{package} @var{version}}.
1887 @item @code{AC_PACKAGE_BUGREPORT}, @code{PACKAGE_BUGREPORT}
1888 @acindex{PACKAGE_BUGREPORT}
1889 @ovindex PACKAGE_BUGREPORT
1890 @cvindex PACKAGE_BUGREPORT
1891 Exactly @var{bug-report}, if one was provided.
1893 @item @code{AC_PACKAGE_URL}, @code{PACKAGE_URL}
1894 @acindex{PACKAGE_URL}
1895 @ovindex PACKAGE_URL
1896 @cvindex PACKAGE_URL
1897 Exactly @var{url}, if one was provided. If @var{url} was empty, but
1898 @var{package} begins with @samp{GNU }, then this defaults to
1899 @samp{http://@/www.gnu.org/@/software/@/@var{tarname}/}, otherwise, no URL is
1904 If your @command{configure} script does its own option processing, it
1905 should inspect @samp{$@@} or @samp{$*} immediately after calling
1906 @code{AC_INIT}, because other Autoconf macros liberally use the
1907 @command{set} command to process strings, and this has the side effect
1908 of updating @samp{$@@} and @samp{$*}. However, we suggest that you use
1909 standard macros like @code{AC_ARG_ENABLE} instead of attempting to
1910 implement your own option processing. @xref{Site Configuration}.
1913 @section Dealing with Autoconf versions
1914 @cindex Autoconf version
1915 @cindex version, Autoconf
1917 The following optional macros can be used to help choose the minimum
1918 version of Autoconf that can successfully compile a given
1919 @file{configure.ac}.
1921 @defmac AC_PREREQ (@var{version})
1924 Ensure that a recent enough version of Autoconf is being used. If the
1925 version of Autoconf being used to create @command{configure} is
1926 earlier than @var{version}, print an error message to the standard
1927 error output and exit with failure (exit status is 63). For example:
1930 AC_PREREQ([@value{VERSION}])
1933 This macro may be used before @code{AC_INIT}.
1936 @defmac AC_AUTOCONF_VERSION
1937 @acindex{AUTOCONF_VERSION}
1938 This macro was introduced in Autoconf 2.62. It identifies the version
1939 of Autoconf that is currently parsing the input file, in a format
1940 suitable for @code{m4_version_compare} (@pxref{m4_version_compare}); in
1941 other words, for this release of Autoconf, its value is
1942 @samp{@value{VERSION}}. One potential use of this macro is for writing
1943 conditional fallbacks based on when a feature was added to Autoconf,
1944 rather than using @code{AC_PREREQ} to require the newer version of
1945 Autoconf. However, remember that the Autoconf philosophy favors feature
1946 checks over version checks.
1948 You should not expand this macro directly; use
1949 @samp{m4_defn([AC_AUTOCONF_VERSION])} instead. This is because some
1951 have a beta version of Autoconf installed, with arbitrary letters
1952 included in its version string. This means it is possible for the
1953 version string to contain the name of a defined macro, such that
1954 expanding @code{AC_AUTOCONF_VERSION} would trigger the expansion of that
1955 macro during rescanning, and change the version string to be different
1956 than what you intended to check.
1960 @section Notices in @command{configure}
1961 @cindex Notices in @command{configure}
1963 The following macros manage version numbers for @command{configure}
1964 scripts. Using them is optional.
1966 @defmac AC_COPYRIGHT (@var{copyright-notice})
1968 @cindex Copyright Notice
1969 State that, in addition to the Free Software Foundation's copyright on
1970 the Autoconf macros, parts of your @command{configure} are covered by the
1971 @var{copyright-notice}.
1973 The @var{copyright-notice} shows up in both the head of
1974 @command{configure} and in @samp{configure --version}.
1978 @defmac AC_REVISION (@var{revision-info})
1981 Copy revision stamp @var{revision-info} into the @command{configure}
1982 script, with any dollar signs or double-quotes removed. This macro lets
1983 you put a revision stamp from @file{configure.ac} into @command{configure}
1984 without RCS or CVS changing it when you check in
1985 @command{configure}. That way, you can determine easily which revision of
1986 @file{configure.ac} a particular @command{configure} corresponds to.
1988 For example, this line in @file{configure.ac}:
1990 @c The @w prevents RCS from changing the example in the manual.
1992 AC_REVISION([@w{$}Revision: 1.30 $])
1996 produces this in @command{configure}:
2000 # From configure.ac Revision: 1.30
2006 @section Finding @command{configure} Input
2008 @anchor{AC_CONFIG_SRCDIR}
2009 @defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir})
2010 @acindex{CONFIG_SRCDIR}
2011 @var{unique-file-in-source-dir} is some file that is in the package's
2012 source directory; @command{configure} checks for this file's existence to
2013 make sure that the directory that it is told contains the source code in
2014 fact does. Occasionally people accidentally specify the wrong directory
2015 with @option{--srcdir}; this is a safety check. @xref{configure
2016 Invocation}, for more information.
2020 @c FIXME: Remove definitively once --install explained.
2022 @c Small packages may store all their macros in @code{aclocal.m4}. As the
2023 @c set of macros grows, or for maintenance reasons, a maintainer may prefer
2024 @c to split the macros in several files. In this case, Autoconf must be
2025 @c told which files to load, and in which order.
2027 @c @defmac AC_INCLUDE (@var{file}@dots{})
2028 @c @acindex{INCLUDE}
2029 @c @c FIXME: There is no longer shell globbing.
2030 @c Read the macro definitions that appear in the listed files. A list of
2031 @c space-separated file names or shell globbing patterns is expected. The
2032 @c files are read in the order they're listed.
2034 @c Because the order of definition of macros is important (only the last
2035 @c definition of a macro is used), beware that it is @code{AC_INIT} that
2036 @c loads @file{acsite.m4} and @file{aclocal.m4}. Note that
2037 @c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within
2038 @c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in
2039 @c the latter case, non-macro lines from included files may end up in the
2040 @c @file{configure} script, whereas in the former case, they'd be discarded
2041 @c just like any text that appear before @code{AC_INIT}.
2044 Packages that do manual configuration or use the @command{install} program
2045 might need to tell @command{configure} where to find some other shell
2046 scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places
2047 it looks are correct for most cases.
2049 @defmac AC_CONFIG_AUX_DIR (@var{dir})
2050 @acindex{CONFIG_AUX_DIR}
2051 Use the auxiliary build tools (e.g., @file{install-sh},
2052 @file{config.sub}, @file{config.guess}, Cygnus @command{configure},
2053 Automake and Libtool scripts, etc.)@: that are in directory @var{dir}.
2054 These are auxiliary files used in configuration. @var{dir} can be
2055 either absolute or relative to @file{@var{srcdir}}. The default is
2056 @file{@var{srcdir}} or @file{@var{srcdir}/..} or
2057 @file{@var{srcdir}/../..}, whichever is the first that contains
2058 @file{install-sh}. The other files are not checked for, so that using
2059 @code{AC_PROG_INSTALL} does not automatically require distributing the
2060 other auxiliary files. It checks for @file{install.sh} also, but that
2061 name is obsolete because some @command{make} have a rule that creates
2062 @file{install} from it if there is no makefile.
2064 The auxiliary directory is commonly named @file{build-aux}.
2065 If you need portability to DOS variants, do not name the
2066 auxiliary directory @file{aux}. @xref{File System Conventions}.
2069 @defmac AC_REQUIRE_AUX_FILE (@var{file})
2070 @acindex{REQUIRE_AUX_FILE}
2071 Declares that @var{file} is expected in the directory defined above. In
2072 Autoconf proper, this macro does nothing: its sole purpose is to be
2073 traced by third-party tools to produce a list of expected auxiliary
2074 files. For instance it is called by macros like @code{AC_PROG_INSTALL}
2075 (@pxref{Particular Programs}) or @code{AC_CANONICAL_BUILD}
2076 (@pxref{Canonicalizing}) to register the auxiliary files they need.
2079 Similarly, packages that use @command{aclocal} should declare where
2080 local macros can be found using @code{AC_CONFIG_MACRO_DIR}.
2082 @defmac AC_CONFIG_MACRO_DIR (@var{dir})
2083 @acindex{CONFIG_MACRO_DIR}
2084 Specify @var{dir} as the location of additional local Autoconf macros.
2085 This macro is intended for use by future versions of commands like
2086 @command{autoreconf} that trace macro calls. It should be called
2087 directly from @file{configure.ac} so that tools that install macros for
2088 @command{aclocal} can find the macros' declarations.
2090 Note that if you use @command{aclocal} from Automake to generate
2091 @file{aclocal.m4}, you must also set @code{ACLOCAL_AMFLAGS = -I
2092 @var{dir}} in your top-level @file{Makefile.am}. Due to a limitation in
2093 the Autoconf implementation of @command{autoreconf}, these include
2094 directives currently must be set on a single line in @file{Makefile.am},
2095 without any backslash-newlines.
2100 @section Outputting Files
2101 @cindex Outputting files
2103 Every Autoconf script, e.g., @file{configure.ac}, should finish by
2104 calling @code{AC_OUTPUT}. That is the macro that generates and runs
2105 @file{config.status}, which in turn creates the makefiles and any
2106 other files resulting from configuration. This is the only required
2107 macro besides @code{AC_INIT} (@pxref{Input}).
2112 @cindex Instantiation
2113 Generate @file{config.status} and launch it. Call this macro once, at
2114 the end of @file{configure.ac}.
2116 @file{config.status} performs all the configuration actions: all the
2117 output files (see @ref{Configuration Files}, macro
2118 @code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers},
2119 macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration
2120 Commands}, macro @code{AC_CONFIG_COMMANDS}), links (see
2121 @ref{Configuration Links}, macro @code{AC_CONFIG_LINKS}), subdirectories
2122 to configure (see @ref{Subdirectories}, macro @code{AC_CONFIG_SUBDIRS})
2125 The location of your @code{AC_OUTPUT} invocation is the exact point
2126 where configuration actions are taken: any code afterwards is
2127 executed by @command{configure} once @command{config.status} was run. If
2128 you want to bind actions to @command{config.status} itself
2129 (independently of whether @command{configure} is being run), see
2130 @ref{Configuration Commands, , Running Arbitrary Configuration
2134 Historically, the usage of @code{AC_OUTPUT} was somewhat different.
2135 @xref{Obsolete Macros}, for a description of the arguments that
2136 @code{AC_OUTPUT} used to support.
2139 If you run @command{make} in subdirectories, you should run it using the
2140 @command{make} variable @code{MAKE}. Most versions of @command{make} set
2141 @code{MAKE} to the name of the @command{make} program plus any options it
2142 was given. (But many do not include in it the values of any variables
2143 set on the command line, so those are not passed on automatically.)
2144 Some old versions of @command{make} do not set this variable. The
2145 following macro allows you to use it even with those versions.
2147 @anchor{AC_PROG_MAKE_SET}
2148 @defmac AC_PROG_MAKE_SET
2149 @acindex{PROG_MAKE_SET}
2151 If the Make command, @code{$MAKE} if set or else @samp{make}, predefines
2152 @code{$(MAKE)}, define output variable @code{SET_MAKE} to be empty.
2153 Otherwise, define @code{SET_MAKE} to a macro definition that sets
2154 @code{$(MAKE)}, such as @samp{MAKE=make}. Calls @code{AC_SUBST} for
2158 If you use this macro, place a line like this in each @file{Makefile.in}
2159 that runs @command{MAKE} on other directories:
2167 @node Configuration Actions
2168 @section Performing Configuration Actions
2169 @cindex Configuration actions
2171 @file{configure} is designed so that it appears to do everything itself,
2172 but there is actually a hidden slave: @file{config.status}.
2173 @file{configure} is in charge of examining your system, but it is
2174 @file{config.status} that actually takes the proper actions based on the
2175 results of @file{configure}. The most typical task of
2176 @file{config.status} is to @emph{instantiate} files.
2178 @acindex{CONFIG_@var{ITEMS}}
2179 This section describes the common behavior of the four standard
2180 instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS},
2181 @code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}. They all
2182 have this prototype:
2184 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
2187 AC_CONFIG_@var{ITEMS}(@var{tag}@dots{}, @r{[}@var{commands}@r{]}, @r{[}@var{init-cmds}@r{]})
2191 where the arguments are:
2195 A blank-or-newline-separated list of tags, which are typically the names of
2196 the files to instantiate.
2198 You are encouraged to use literals as @var{tags}. In particular, you
2202 @dots{} && my_foos="$my_foos fooo"
2203 @dots{} && my_foos="$my_foos foooo"
2204 AC_CONFIG_@var{ITEMS}([$my_foos])
2208 and use this instead:
2211 @dots{} && AC_CONFIG_@var{ITEMS}([fooo])
2212 @dots{} && AC_CONFIG_@var{ITEMS}([foooo])
2215 The macros @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use
2216 special @var{tag} values: they may have the form @samp{@var{output}} or
2217 @samp{@var{output}:@var{inputs}}. The file @var{output} is instantiated
2218 from its templates, @var{inputs} (defaulting to @samp{@var{output}.in}).
2220 @samp{AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk)]},
2221 for example, asks for
2222 the creation of the file @file{Makefile} that contains the expansion of the
2223 output variables in the concatenation of @file{boiler/top.mk} and
2224 @file{boiler/bot.mk}.
2226 The special value @samp{-} might be used to denote the standard output
2227 when used in @var{output}, or the standard input when used in the
2228 @var{inputs}. You most probably don't need to use this in
2229 @file{configure.ac}, but it is convenient when using the command line
2230 interface of @file{./config.status}, see @ref{config.status Invocation},
2233 The @var{inputs} may be absolute or relative file names. In the latter
2234 case they are first looked for in the build tree, and then in the source
2235 tree. Input files should be text files, and a line length below 2000
2236 bytes should be safe.
2239 Shell commands output literally into @file{config.status}, and
2240 associated with a tag that the user can use to tell @file{config.status}
2241 which commands to run. The commands are run each time a @var{tag}
2242 request is given to @file{config.status}, typically each time the file
2243 @file{@var{tag}} is created.
2245 The variables set during the execution of @command{configure} are
2246 @emph{not} available here: you first need to set them via the
2247 @var{init-cmds}. Nonetheless the following variables are precomputed:
2251 The name of the top source directory, assuming that the working
2252 directory is the top build directory. This
2253 is what the @command{configure} option @option{--srcdir} sets.
2256 The name of the top source directory, assuming that the working
2257 directory is the current build directory.
2259 @item ac_top_build_prefix
2260 The name of the top build directory, assuming that the working
2261 directory is the current build directory.
2262 It can be empty, or else ends with a slash, so that you may concatenate
2266 The name of the corresponding source directory, assuming that the
2267 working directory is the current build directory.
2270 The name of a temporary directory within the build tree, which you
2271 can use if you need to create additional temporary files. The
2272 directory is cleaned up when @command{config.status} is done or
2273 interrupted. Please use package-specific file name prefixes to
2274 avoid clashing with files that @command{config.status} may use
2279 The @dfn{current} directory refers to the directory (or
2280 pseudo-directory) containing the input part of @var{tags}. For
2284 AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [@dots{}], [@dots{}])
2288 with @option{--srcdir=../package} produces the following values:
2291 # Argument of --srcdir
2293 # Reversing deep/dir
2294 ac_top_build_prefix='../../'
2295 # Concatenation of $ac_top_build_prefix and srcdir
2296 ac_top_srcdir='../../../package'
2297 # Concatenation of $ac_top_srcdir and deep/dir
2298 ac_srcdir='../../../package/deep/dir'
2302 independently of @samp{in/in.in}.
2305 Shell commands output @emph{unquoted} near the beginning of
2306 @file{config.status}, and executed each time @file{config.status} runs
2307 (regardless of the tag). Because they are unquoted, for example,
2308 @samp{$var} is output as the value of @code{var}. @var{init-cmds}
2309 is typically used by @file{configure} to give @file{config.status} some
2310 variables it needs to run the @var{commands}.
2312 You should be extremely cautious in your variable names: all the
2313 @var{init-cmds} share the same name space and may overwrite each other
2314 in unpredictable ways. Sorry@enddots{}
2317 All these macros can be called multiple times, with different
2318 @var{tag} values, of course!
2321 @node Configuration Files
2322 @section Creating Configuration Files
2323 @cindex Creating configuration files
2324 @cindex Configuration file creation
2326 Be sure to read the previous section, @ref{Configuration Actions}.
2328 @anchor{AC_CONFIG_FILES}
2329 @defmac AC_CONFIG_FILES (@var{file}@dots{}, @ovar{cmds}, @ovar{init-cmds})
2330 @acindex{CONFIG_FILES}
2331 Make @code{AC_OUTPUT} create each @file{@var{file}} by copying an input
2332 file (by default @file{@var{file}.in}), substituting the output variable
2334 @c Before we used to have this feature, which was later rejected
2335 @c because it complicates the writing of makefiles:
2336 @c If the file would be unchanged, it is left untouched, to preserve
2338 This macro is one of the instantiating macros; see @ref{Configuration
2339 Actions}. @xref{Makefile Substitutions}, for more information on using
2340 output variables. @xref{Setting Output Variables}, for more information
2341 on creating them. This macro creates the directory that the file is in
2342 if it doesn't exist. Usually, makefiles are created this way,
2343 but other files, such as @file{.gdbinit}, can be specified as well.
2345 Typical calls to @code{AC_CONFIG_FILES} look like this:
2348 AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile])
2349 AC_CONFIG_FILES([autoconf], [chmod +x autoconf])
2352 You can override an input file name by appending to @var{file} a
2353 colon-separated list of input files. Examples:
2356 AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk]
2357 [lib/Makefile:boiler/lib.mk])
2361 Doing this allows you to keep your file names acceptable to
2363 to prepend and/or append boilerplate to the file.
2368 @node Makefile Substitutions
2369 @section Substitutions in Makefiles
2370 @cindex Substitutions in makefiles
2371 @cindex Makefile substitutions
2373 Each subdirectory in a distribution that contains something to be
2374 compiled or installed should come with a file @file{Makefile.in}, from
2375 which @command{configure} creates a file @file{Makefile} in that directory.
2376 To create @file{Makefile}, @command{configure} performs a simple variable
2377 substitution, replacing occurrences of @samp{@@@var{variable}@@} in
2378 @file{Makefile.in} with the value that @command{configure} has determined
2379 for that variable. Variables that are substituted into output files in
2380 this way are called @dfn{output variables}. They are ordinary shell
2381 variables that are set in @command{configure}. To make @command{configure}
2382 substitute a particular variable into the output files, the macro
2383 @code{AC_SUBST} must be called with that variable name as an argument.
2384 Any occurrences of @samp{@@@var{variable}@@} for other variables are
2385 left unchanged. @xref{Setting Output Variables}, for more information
2386 on creating output variables with @code{AC_SUBST}.
2388 A software package that uses a @command{configure} script should be
2389 distributed with a file @file{Makefile.in}, but no makefile; that
2390 way, the user has to properly configure the package for the local system
2391 before compiling it.
2393 @xref{Makefile Conventions, , Makefile Conventions, standards, The
2394 GNU Coding Standards}, for more information on what to put in
2398 * Preset Output Variables:: Output variables that are always set
2399 * Installation Directory Variables:: Other preset output variables
2400 * Changed Directory Variables:: Warnings about @file{datarootdir}
2401 * Build Directories:: Supporting multiple concurrent compiles
2402 * Automatic Remaking:: Makefile rules for configuring
2405 @node Preset Output Variables
2406 @subsection Preset Output Variables
2407 @cindex Output variables
2409 Some output variables are preset by the Autoconf macros. Some of the
2410 Autoconf macros set additional output variables, which are mentioned in
2411 the descriptions for those macros. @xref{Output Variable Index}, for a
2412 complete list of output variables. @xref{Installation Directory
2413 Variables}, for the list of the preset ones related to installation
2414 directories. Below are listed the other preset ones, many of which are
2415 precious variables (@pxref{Setting Output Variables},
2418 The preset variables which are available during @file{config.status}
2419 (@pxref{Configuration Actions}) may also be used during
2420 @command{configure} tests. For example, it is permissible to reference
2421 @samp{$srcdir} when constructing a list of directories to pass via
2422 option @option{-I} during a compiler feature check. When used in this
2423 manner, coupled with the fact that @command{configure} is always run
2424 from the top build directory, it is sufficient to use just
2425 @samp{$srcdir} instead of @samp{$top_srcdir}.
2427 @c Just say no to ASCII sorting! We're humans, not computers.
2428 @c These variables are listed as they would be in a dictionary:
2436 Debugging and optimization options for the C compiler. If it is not set
2437 in the environment when @command{configure} runs, the default value is set
2438 when you call @code{AC_PROG_CC} (or empty if you don't). @command{configure}
2439 uses this variable when compiling or linking programs to test for C features.
2441 If a compiler option affects only the behavior of the preprocessor
2442 (e.g., @option{-D@var{name}}), it should be put into @code{CPPFLAGS}
2443 instead. If it affects only the linker (e.g., @option{-L@var{directory}}),
2444 it should be put into @code{LDFLAGS} instead. If it
2445 affects only the compiler proper, @code{CFLAGS} is the natural home for
2446 it. If an option affects multiple phases of the compiler, though,
2447 matters get tricky. One approach to put such options directly into
2448 @code{CC}, e.g., @code{CC='gcc -m64'}. Another is to put them into both
2449 @code{CPPFLAGS} and @code{LDFLAGS}, but not into @code{CFLAGS}.
2451 However, remember that some @file{Makefile} variables are reserved by
2452 the GNU Coding Standards for the use of the ``user''---the person
2453 building the package. For instance, @code{CFLAGS} is one such variable.
2455 Sometimes package developers are tempted to set user variables such as
2456 @code{CFLAGS} because it appears to make their job easier. However, the
2457 package itself should never set a user variable, particularly not to
2458 include switches that are required for proper compilation of the
2459 package. Since these variables are documented as being for the package
2460 builder, that person rightfully expects to be able to override any of
2461 these variables at build time. If the package developer needs to add
2462 switches without interfering with the user, the proper way to do that is
2463 to introduce an additional variable. Automake makes this easy by
2464 introducing @code{AM_CFLAGS} (@pxref{Flag Variables Ordering, , ,
2465 automake, GNU Automake}), but the concept is the same even if
2466 Automake is not used.
2469 @defvar configure_input
2470 @ovindex configure_input
2471 A comment saying that the file was generated automatically by
2472 @command{configure} and giving the name of the input file.
2473 @code{AC_OUTPUT} adds a comment line containing this variable to the top
2474 of every makefile it creates. For other files, you should
2475 reference this variable in a comment at the top of each input file. For
2476 example, an input shell script should begin like this:
2480 # @@configure_input@@
2484 The presence of that line also reminds people editing the file that it
2485 needs to be processed by @command{configure} in order to be used.
2491 Preprocessor options for the C, C++, Objective C, and Objective C++
2492 preprocessors and compilers. If
2493 it is not set in the environment when @command{configure} runs, the default
2494 value is empty. @command{configure} uses this variable when preprocessing
2495 or compiling programs to test for C, C++, Objective C, and Objective C++
2498 This variable's contents should contain options like @option{-I},
2499 @option{-D}, and @option{-U} that affect only the behavior of the
2500 preprocessor. Please see the explanation of @code{CFLAGS} for what you
2501 can do if an option affects other phases of the compiler as well.
2503 Currently, @command{configure} always links as part of a single
2504 invocation of the compiler that also preprocesses and compiles, so it
2505 uses this variable also when linking programs. However, it is unwise to
2506 depend on this behavior because the GNU Coding Standards do
2507 not require it and many packages do not use @code{CPPFLAGS} when linking
2510 @xref{Special Chars in Variables}, for limitations that @code{CPPFLAGS}
2517 Debugging and optimization options for the C++ compiler. It acts like
2518 @code{CFLAGS}, but for C++ instead of C.
2523 @option{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADERS}
2524 is called, @command{configure} replaces @samp{@@DEFS@@} with
2525 @option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}). This
2526 variable is not defined while @command{configure} is performing its tests,
2527 only when creating the output files. @xref{Setting Output Variables}, for
2528 how to check the results of previous tests.
2537 How does one suppress the trailing newline from @command{echo} for
2538 question-answer message pairs? These variables provide a way:
2541 echo $ECHO_N "And the winner is... $ECHO_C"
2543 echo "$@{ECHO_T@}dead."
2547 Some old and uncommon @command{echo} implementations offer no means to
2548 achieve this, in which case @code{ECHO_T} is set to tab. You might not
2555 Debugging and optimization options for the Erlang compiler. If it is not set
2556 in the environment when @command{configure} runs, the default value is empty.
2557 @command{configure} uses this variable when compiling
2558 programs to test for Erlang features.
2564 Debugging and optimization options for the Fortran compiler. If it
2565 is not set in the environment when @command{configure} runs, the default
2566 value is set when you call @code{AC_PROG_FC} (or empty if you don't).
2567 @command{configure} uses this variable when compiling or linking
2568 programs to test for Fortran features.
2574 Debugging and optimization options for the Fortran 77 compiler. If it
2575 is not set in the environment when @command{configure} runs, the default
2576 value is set when you call @code{AC_PROG_F77} (or empty if you don't).
2577 @command{configure} uses this variable when compiling or linking
2578 programs to test for Fortran 77 features.
2584 Options for the linker. If it is not set
2585 in the environment when @command{configure} runs, the default value is empty.
2586 @command{configure} uses this variable when linking programs to test for
2587 C, C++, Objective C, Objective C++, and Fortran features.
2589 This variable's contents should contain options like @option{-s} and
2590 @option{-L} that affect only the behavior of the linker. Please see the
2591 explanation of @code{CFLAGS} for what you can do if an option also
2592 affects other phases of the compiler.
2594 Don't use this variable to pass library names
2595 (@option{-l}) to the linker; use @code{LIBS} instead.
2601 @option{-l} options to pass to the linker. The default value is empty,
2602 but some Autoconf macros may prepend extra libraries to this variable if
2603 those libraries are found and provide necessary functions, see
2604 @ref{Libraries}. @command{configure} uses this variable when linking
2605 programs to test for C, C++, Objective C, Objective C++, and Fortran
2612 Debugging and optimization options for the Objective C compiler. It
2613 acts like @code{CFLAGS}, but for Objective C instead of C.
2617 @evindex OBJCXXFLAGS
2618 @ovindex OBJCXXFLAGS
2619 Debugging and optimization options for the Objective C++ compiler. It
2620 acts like @code{CXXFLAGS}, but for Objective C++ instead of C++.
2625 Rigorously equal to @samp{.}. Added for symmetry only.
2628 @defvar abs_builddir
2629 @ovindex abs_builddir
2630 Absolute name of @code{builddir}.
2633 @defvar top_builddir
2634 @ovindex top_builddir
2635 The relative name of the top level of the current build tree. In the
2636 top-level directory, this is the same as @code{builddir}.
2639 @defvar top_build_prefix
2640 @ovindex top_build_prefix
2641 The relative name of the top level of the current build tree with final
2642 slash if nonemtpy. This is the same as @code{top_builddir}, except that
2643 it contains zero or more runs of @code{../}, so it should not be
2644 appended with a slash for concatenation. This helps for @command{make}
2645 implementations that otherwise do not treat @file{./file} and @file{file}
2646 as equal in the toplevel build directory.
2649 @defvar abs_top_builddir
2650 @ovindex abs_top_builddir
2651 Absolute name of @code{top_builddir}.
2656 The name of the directory that contains the source code for
2662 Absolute name of @code{srcdir}.
2667 The name of the top-level source code directory for the
2668 package. In the top-level directory, this is the same as @code{srcdir}.
2671 @defvar abs_top_srcdir
2672 @ovindex abs_top_srcdir
2673 Absolute name of @code{top_srcdir}.
2676 @node Installation Directory Variables
2677 @subsection Installation Directory Variables
2678 @cindex Installation directories
2679 @cindex Directories, installation
2681 The following variables specify the directories for
2682 package installation, see @ref{Directory Variables, , Variables for
2683 Installation Directories, standards, The GNU Coding
2684 Standards}, for more information. Each variable corresponds to an
2685 argument of @command{configure}; trailing slashes are stripped so that
2686 expressions such as @samp{$@{prefix@}/lib} expand with only one slash
2687 between directory names. See the end of this section for
2688 details on when and how to use these variables.
2692 The directory for installing executables that users run.
2697 The directory for installing idiosyncratic read-only
2698 architecture-independent data.
2702 @ovindex datarootdir
2703 The root of the directory tree for read-only architecture-independent
2709 The directory for installing documentation files (other than Info and
2715 The directory for installing documentation files in DVI format.
2719 @ovindex exec_prefix
2720 The installation prefix for architecture-dependent files. By default
2721 it's the same as @code{prefix}. You should avoid installing anything
2722 directly to @code{exec_prefix}. However, the default value for
2723 directories containing architecture-dependent files should be relative
2724 to @code{exec_prefix}.
2729 The directory for installing HTML documentation.
2734 The directory for installing C header files.
2739 The directory for installing documentation in Info format.
2744 The directory for installing object code libraries.
2749 The directory for installing executables that other programs run.
2754 The directory for installing locale-dependent but
2755 architecture-independent data, such as message catalogs. This directory
2756 usually has a subdirectory per locale.
2759 @defvar localstatedir
2760 @ovindex localstatedir
2761 The directory for installing modifiable single-machine data.
2766 The top-level directory for installing documentation in man format.
2769 @defvar oldincludedir
2770 @ovindex oldincludedir
2771 The directory for installing C header files for non-GCC compilers.
2776 The directory for installing PDF documentation.
2781 The common installation prefix for all files. If @code{exec_prefix}
2782 is defined to a different value, @code{prefix} is used only for
2783 architecture-independent files.
2788 The directory for installing PostScript documentation.
2793 The directory for installing executables that system
2797 @defvar sharedstatedir
2798 @ovindex sharedstatedir
2799 The directory for installing modifiable architecture-independent data.
2804 The directory for installing read-only single-machine data.
2808 Most of these variables have values that rely on @code{prefix} or
2809 @code{exec_prefix}. It is deliberate that the directory output
2810 variables keep them unexpanded: typically @samp{@@datarootdir@@} is
2811 replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}, and
2812 @samp{@@datadir@@} is replaced by @samp{$@{datarootdir@}}.
2814 This behavior is mandated by the GNU Coding Standards, so that when
2819 she can still specify a different prefix from the one specified to
2820 @command{configure}, in which case, if needed, the package should hard
2821 code dependencies corresponding to the make-specified prefix.
2824 she can specify a different installation location, in which case the
2825 package @emph{must} still depend on the location which was compiled in
2826 (i.e., never recompile when @samp{make install} is run). This is an
2827 extremely important feature, as many people may decide to install all
2828 the files of a package grouped together, and then install links from
2829 the final locations to there.
2832 In order to support these features, it is essential that
2833 @code{datarootdir} remains defined as @samp{$@{prefix@}/share},
2834 so that its value can be expanded based
2835 on the current value of @code{prefix}.
2837 A corollary is that you should not use these variables except in
2838 makefiles. For instance, instead of trying to evaluate @code{datadir}
2839 in @file{configure} and hard-coding it in makefiles using
2840 e.g., @samp{AC_DEFINE_UNQUOTED([DATADIR], ["$datadir"], [Data directory.])},
2842 @option{-DDATADIR='$(datadir)'} to your makefile's definition of
2843 @code{CPPFLAGS} (@code{AM_CPPFLAGS} if you are also using Automake).
2845 Similarly, you should not rely on @code{AC_CONFIG_FILES} to replace
2846 @code{bindir} and friends in your shell scripts and other files; instead,
2847 let @command{make} manage their replacement. For instance Autoconf
2848 ships templates of its shell scripts ending with @samp{.in}, and uses a
2849 makefile snippet similar to the following to build scripts like
2850 @command{autoheader} and @command{autom4te}:
2855 -e 's|@@bindir[@@]|$(bindir)|g' \
2856 -e 's|@@pkgdatadir[@@]|$(pkgdatadir)|g' \
2857 -e 's|@@prefix[@@]|$(prefix)|g'
2861 autoheader autom4te: Makefile
2864 test -f ./$@@.in || srcdir=$(srcdir)/; \
2865 $(edit) $$@{srcdir@}$@@.in >$@@.tmp
2866 @c $$ restore font-lock
2873 autoheader: $(srcdir)/autoheader.in
2874 autom4te: $(srcdir)/autom4te.in
2878 Some details are noteworthy:
2881 @item @samp{@@bindir[@@]}
2882 The brackets prevent @command{configure} from replacing
2883 @samp{@@bindir@@} in the Sed expression itself.
2884 Brackets are preferable to a backslash here, since
2885 Posix says @samp{\@@} is not portable.
2887 @item @samp{$(bindir)}
2888 Don't use @samp{@@bindir@@}! Use the matching makefile variable
2891 @item @samp{$(pkgdatadir)}
2892 The example takes advantage of the variable @samp{$(pkgdatadir)}
2893 provided by Automake; it is equivalent to @samp{$(datadir)/$(PACKAGE)}.
2896 Don't use @samp{/} in the Sed expressions that replace file names since
2898 variables you use, such as @samp{$(bindir)}, contain @samp{/}.
2899 Use a shell metacharacter instead, such as @samp{|}.
2901 @item special characters
2902 File names, file name components, and the value of @code{VPATH} should
2903 not contain shell metacharacters or white
2904 space. @xref{Special Chars in Variables}.
2906 @item dependency on @file{Makefile}
2907 Since @code{edit} uses values that depend on the configuration specific
2908 values (@code{prefix}, etc.)@: and not only on @code{VERSION} and so forth,
2909 the output depends on @file{Makefile}, not @file{configure.ac}.
2912 The main rule is generic, and uses @samp{$@@} extensively to
2913 avoid the need for multiple copies of the rule.
2915 @item Separated dependencies and single suffix rules
2916 You can't use them! The above snippet cannot be (portably) rewritten
2920 autoconf autoheader: Makefile
2930 @xref{Single Suffix Rules}, for details.
2932 @item @samp{$(srcdir)}
2933 Be sure to specify the name of the source directory,
2934 otherwise the package won't support separated builds.
2937 For the more specific installation of Erlang libraries, the following variables
2940 @defvar ERLANG_INSTALL_LIB_DIR
2941 @ovindex ERLANG_INSTALL_LIB_DIR
2942 @acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
2943 The common parent directory of Erlang library installation directories.
2944 This variable is set by calling the @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR}
2945 macro in @file{configure.ac}.
2948 @defvar ERLANG_INSTALL_LIB_DIR_@var{library}
2949 @ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
2950 @acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
2951 The installation directory for Erlang library @var{library}.
2952 This variable is set by using the
2953 @samp{AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR}
2954 macro in @file{configure.ac}.
2957 @xref{Erlang Libraries}, for details.
2960 @node Changed Directory Variables
2961 @subsection Changed Directory Variables
2962 @cindex @file{datarootdir}
2964 In Autoconf 2.60, the set of directory variables has changed, and the
2965 defaults of some variables have been adjusted
2966 (@pxref{Installation Directory Variables}) to changes in the
2967 GNU Coding Standards. Notably, @file{datadir}, @file{infodir}, and
2968 @file{mandir} are now expressed in terms of @file{datarootdir}. If you are
2969 upgrading from an earlier Autoconf version, you may need to adjust your files
2970 to ensure that the directory variables are substituted correctly
2971 (@pxref{Defining Directories}), and that a definition of @file{datarootdir} is
2972 in place. For example, in a @file{Makefile.in}, adding
2975 datarootdir = @@datarootdir@@
2979 is usually sufficient. If you use Automake to create @file{Makefile.in},
2980 it will add this for you.
2982 To help with the transition, Autoconf warns about files that seem to use
2983 @code{datarootdir} without defining it. In some cases, it then expands
2984 the value of @code{$datarootdir} in substitutions of the directory
2985 variables. The following example shows such a warning:
2988 $ @kbd{cat configure.ac}
2990 AC_CONFIG_FILES([Makefile])
2992 $ @kbd{cat Makefile.in}
2994 datadir = @@datadir@@
2997 configure: creating ./config.status
2998 config.status: creating Makefile
2999 config.status: WARNING:
3000 Makefile.in seems to ignore the --datarootdir setting
3001 $ @kbd{cat Makefile}
3003 datadir = $@{prefix@}/share
3006 Usually one can easily change the file to accommodate both older and newer
3010 $ @kbd{cat Makefile.in}
3012 datarootdir = @@datarootdir@@
3013 datadir = @@datadir@@
3015 configure: creating ./config.status
3016 config.status: creating Makefile
3017 $ @kbd{cat Makefile}
3019 datarootdir = $@{prefix@}/share
3020 datadir = $@{datarootdir@}
3023 @acindex{DATAROOTDIR_CHECKED}
3024 In some cases, however, the checks may not be able to detect that a suitable
3025 initialization of @code{datarootdir} is in place, or they may fail to detect
3026 that such an initialization is necessary in the output file. If, after
3027 auditing your package, there are still spurious @file{configure} warnings about
3028 @code{datarootdir}, you may add the line
3031 AC_DEFUN([AC_DATAROOTDIR_CHECKED])
3035 to your @file{configure.ac} to disable the warnings. This is an exception
3036 to the usual rule that you should not define a macro whose name begins with
3037 @code{AC_} (@pxref{Macro Names}).
3041 @node Build Directories
3042 @subsection Build Directories
3043 @cindex Build directories
3044 @cindex Directories, build
3046 You can support compiling a software package for several architectures
3047 simultaneously from the same copy of the source code. The object files
3048 for each architecture are kept in their own directory.
3050 To support doing this, @command{make} uses the @code{VPATH} variable to
3051 find the files that are in the source directory. GNU Make
3052 can do this. Most other recent @command{make} programs can do this as
3053 well, though they may have difficulties and it is often simpler to
3054 recommend GNU @command{make} (@pxref{VPATH and Make}). Older
3055 @command{make} programs do not support @code{VPATH}; when using them, the
3056 source code must be in the same directory as the object files.
3058 If you are using GNU Automake, the remaining details in this
3059 section are already covered for you, based on the contents of your
3060 @file{Makefile.am}. But if you are using Autoconf in isolation, then
3061 supporting @code{VPATH} requires the following in your
3069 Do not set @code{VPATH} to the value of another variable (@pxref{Variables
3072 @command{configure} substitutes the correct value for @code{srcdir} when
3073 it produces @file{Makefile}.
3075 Do not use the @command{make} variable @code{$<}, which expands to the
3076 file name of the file in the source directory (found with @code{VPATH}),
3077 except in implicit rules. (An implicit rule is one such as @samp{.c.o},
3078 which tells how to create a @file{.o} file from a @file{.c} file.) Some
3079 versions of @command{make} do not set @code{$<} in explicit rules; they
3080 expand it to an empty value.
3082 Instead, Make command lines should always refer to source
3083 files by prefixing them with @samp{$(srcdir)/}. For example:
3086 time.info: time.texinfo
3087 $(MAKEINFO) '$(srcdir)/time.texinfo'
3090 @node Automatic Remaking
3091 @subsection Automatic Remaking
3092 @cindex Automatic remaking
3093 @cindex Remaking automatically
3095 You can put rules like the following in the top-level @file{Makefile.in}
3096 for a package to automatically update the configuration information when
3097 you change the configuration files. This example includes all of the
3098 optional files, such as @file{aclocal.m4} and those related to
3099 configuration header files. Omit from the @file{Makefile.in} rules for
3100 any of these files that your package does not use.
3102 The @samp{$(srcdir)/} prefix is included because of limitations in the
3103 @code{VPATH} mechanism.
3105 The @file{stamp-} files are necessary because the timestamps of
3106 @file{config.h.in} and @file{config.h} are not changed if remaking
3107 them does not change their contents. This feature avoids unnecessary
3108 recompilation. You should include the file @file{stamp-h.in} in your
3109 package's distribution, so that @command{make} considers
3110 @file{config.h.in} up to date. Don't use @command{touch}
3111 (@pxref{touch, , Limitations of Usual Tools}); instead, use
3112 @command{echo} (using
3113 @command{date} would cause needless differences, hence CVS
3118 $(srcdir)/configure: configure.ac aclocal.m4
3119 cd '$(srcdir)' && autoconf
3121 # autoheader might not change config.h.in, so touch a stamp file.
3122 $(srcdir)/config.h.in: stamp-h.in
3123 $(srcdir)/stamp-h.in: configure.ac aclocal.m4
3124 cd '$(srcdir)' && autoheader
3125 echo timestamp > '$(srcdir)/stamp-h.in'
3128 stamp-h: config.h.in config.status
3131 Makefile: Makefile.in config.status
3134 config.status: configure
3135 ./config.status --recheck
3140 (Be careful if you copy these lines directly into your makefile, as you
3141 need to convert the indented lines to start with the tab character.)
3143 In addition, you should use
3146 AC_CONFIG_FILES([stamp-h], [echo timestamp > stamp-h])
3150 so @file{config.status} ensures that @file{config.h} is considered up to
3151 date. @xref{Output}, for more information about @code{AC_OUTPUT}.
3153 @xref{config.status Invocation}, for more examples of handling
3154 configuration-related dependencies.
3156 @node Configuration Headers
3157 @section Configuration Header Files
3158 @cindex Configuration Header
3159 @cindex @file{config.h}
3161 When a package contains more than a few tests that define C preprocessor
3162 symbols, the command lines to pass @option{-D} options to the compiler
3163 can get quite long. This causes two problems. One is that the
3164 @command{make} output is hard to visually scan for errors. More
3165 seriously, the command lines can exceed the length limits of some
3166 operating systems. As an alternative to passing @option{-D} options to
3167 the compiler, @command{configure} scripts can create a C header file
3168 containing @samp{#define} directives. The @code{AC_CONFIG_HEADERS}
3169 macro selects this kind of output. Though it can be called anywhere
3170 between @code{AC_INIT} and @code{AC_OUTPUT}, it is customary to call
3171 it right after @code{AC_INIT}.
3173 The package should @samp{#include} the configuration header file before
3174 any other header files, to prevent inconsistencies in declarations (for
3175 example, if it redefines @code{const}).
3177 To provide for VPATH builds, remember to pass the C compiler a @option{-I.}
3178 option (or @option{-I..}; whichever directory contains @file{config.h}).
3179 Even if you use @samp{#include "config.h"}, the preprocessor searches only
3180 the directory of the currently read file, i.e., the source directory, not
3181 the build directory.
3183 With the appropriate @option{-I} option, you can use
3184 @samp{#include <config.h>}. Actually, it's a good habit to use it,
3185 because in the rare case when the source directory contains another
3186 @file{config.h}, the build directory should be searched first.
3189 @defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds})
3190 @acindex{CONFIG_HEADERS}
3191 @cvindex HAVE_CONFIG_H
3192 This macro is one of the instantiating macros; see @ref{Configuration
3193 Actions}. Make @code{AC_OUTPUT} create the file(s) in the
3194 blank-or-newline-separated list @var{header} containing C preprocessor
3195 @code{#define} statements, and replace @samp{@@DEFS@@} in generated
3196 files with @option{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}.
3197 The usual name for @var{header} is @file{config.h}.
3199 If @var{header} already exists and its contents are identical to what
3200 @code{AC_OUTPUT} would put in it, it is left alone. Doing this allows
3201 making some changes in the configuration without needlessly causing
3202 object files that depend on the header file to be recompiled.
3204 Usually the input file is named @file{@var{header}.in}; however, you can
3205 override the input file name by appending to @var{header} a
3206 colon-separated list of input files. For example, you might need to make
3207 the input file name acceptable to DOS variants:
3210 AC_CONFIG_HEADERS([config.h:config.hin])
3217 This macro is defined as the name of the first declared config header
3218 and undefined if no config headers have been declared up to this point.
3219 A third-party macro may, for example, require use of a config header
3220 without invoking AC_CONFIG_HEADERS twice, like this:
3223 AC_CONFIG_COMMANDS_PRE(
3224 [m4_ifndef([AH_HEADER], [AC_CONFIG_HEADERS([config.h])])])
3229 @xref{Configuration Actions}, for more details on @var{header}.
3232 * Header Templates:: Input for the configuration headers
3233 * autoheader Invocation:: How to create configuration templates
3234 * Autoheader Macros:: How to specify CPP templates
3237 @node Header Templates
3238 @subsection Configuration Header Templates
3239 @cindex Configuration Header Template
3240 @cindex Header templates
3241 @cindex @file{config.h.in}
3243 Your distribution should contain a template file that looks as you want
3244 the final header file to look, including comments, with @code{#undef}
3245 statements which are used as hooks. For example, suppose your
3246 @file{configure.ac} makes these calls:
3249 AC_CONFIG_HEADERS([conf.h])
3250 AC_CHECK_HEADERS([unistd.h])
3254 Then you could have code like the following in @file{conf.h.in}.
3255 The @file{conf.h} created by @command{configure} defines @samp{HAVE_UNISTD_H}
3256 to 1, if and only if the system has @file{unistd.h}.
3260 /* Define as 1 if you have unistd.h. */
3261 #undef HAVE_UNISTD_H
3265 The format of the template file is stricter than what the C preprocessor
3266 is required to accept. A directive line should contain only whitespace,
3267 @samp{#undef}, and @samp{HAVE_UNISTD_H}. The use of @samp{#define}
3268 instead of @samp{#undef}, or of comments on the same line as
3269 @samp{#undef}, is strongly discouraged. Each hook should only be listed
3270 once. Other preprocessor lines, such as @samp{#ifdef} or
3271 @samp{#include}, are copied verbatim from the template into the
3274 Since it is a tedious task to keep a template header up to date, you may
3275 use @command{autoheader} to generate it, see @ref{autoheader Invocation}.
3277 During the instantiation of the header, each @samp{#undef} line in the
3278 template file for each symbol defined by @samp{AC_DEFINE} is changed to an
3279 appropriate @samp{#define}. If the corresponding @samp{AC_DEFINE} has not
3280 been executed during the @command{configure} run, the @samp{#undef} line is
3281 commented out. (This is important, e.g., for @samp{_POSIX_SOURCE}:
3282 on many systems, it can be implicitly defined by the compiler, and
3283 undefining it in the header would then break compilation of subsequent
3286 Currently, @emph{all} remaining @samp{#undef} lines in the header
3287 template are commented out, whether or not there was a corresponding
3288 @samp{AC_DEFINE} for the macro name; but this behavior is not guaranteed
3289 for future releases of Autoconf.
3291 Generally speaking, since you should not use @samp{#define}, and you
3292 cannot guarantee whether a @samp{#undef} directive in the header
3293 template will be converted to a @samp{#define} or commented out in the
3294 generated header file, the template file cannot be used for conditional
3295 definition effects. Consequently, if you need to use the construct
3306 you must place it outside of the template.
3307 If you absolutely need to hook it to the config header itself, please put
3308 the directives to a separate file, and @samp{#include} that file from the
3309 config header template. If you are using @command{autoheader}, you would
3310 probably use @samp{AH_BOTTOM} to append the @samp{#include} directive.
3313 @node autoheader Invocation
3314 @subsection Using @command{autoheader} to Create @file{config.h.in}
3315 @cindex @command{autoheader}
3317 The @command{autoheader} program can create a template file of C
3318 @samp{#define} statements for @command{configure} to use.
3319 It searches for the first invocation of @code{AC_CONFIG_HEADERS} in
3320 @file{configure} sources to determine the name of the template.
3321 (If the first call of @code{AC_CONFIG_HEADERS} specifies more than one
3322 input file name, @command{autoheader} uses the first one.)
3324 It is recommended that only one input file is used. If you want to append
3325 a boilerplate code, it is preferable to use
3326 @samp{AH_BOTTOM([#include <conf_post.h>])}.
3327 File @file{conf_post.h} is not processed during the configuration then,
3328 which make things clearer. Analogically, @code{AH_TOP} can be used to
3329 prepend a boilerplate code.
3331 In order to do its job, @command{autoheader} needs you to document all
3332 of the symbols that you might use. Typically this is done via an
3333 @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED} call whose first argument
3334 is a literal symbol and whose third argument describes the symbol
3335 (@pxref{Defining Symbols}). Alternatively, you can use
3336 @code{AH_TEMPLATE} (@pxref{Autoheader Macros}), or you can supply a
3337 suitable input file for a subsequent configuration header file.
3338 Symbols defined by Autoconf's builtin tests are already documented properly;
3339 you need to document only those that you
3342 You might wonder why @command{autoheader} is needed: after all, why
3343 would @command{configure} need to ``patch'' a @file{config.h.in} to
3344 produce a @file{config.h} instead of just creating @file{config.h} from
3345 scratch? Well, when everything rocks, the answer is just that we are
3346 wasting our time maintaining @command{autoheader}: generating
3347 @file{config.h} directly is all that is needed. When things go wrong,
3348 however, you'll be thankful for the existence of @command{autoheader}.
3350 The fact that the symbols are documented is important in order to
3351 @emph{check} that @file{config.h} makes sense. The fact that there is a
3352 well-defined list of symbols that should be defined (or not) is
3353 also important for people who are porting packages to environments where
3354 @command{configure} cannot be run: they just have to @emph{fill in the
3357 But let's come back to the point: the invocation of @command{autoheader}@dots{}
3359 If you give @command{autoheader} an argument, it uses that file instead
3360 of @file{configure.ac} and writes the header file to the standard output
3361 instead of to @file{config.h.in}. If you give @command{autoheader} an
3362 argument of @option{-}, it reads the standard input instead of
3363 @file{configure.ac} and writes the header file to the standard output.
3365 @command{autoheader} accepts the following options:
3370 Print a summary of the command line options and exit.
3374 Print the version number of Autoconf and exit.
3378 Report processing steps.
3382 Don't remove the temporary files.
3386 Remake the template file even if newer than its input files.
3388 @item --include=@var{dir}
3390 Append @var{dir} to the include path. Multiple invocations accumulate.
3392 @item --prepend-include=@var{dir}
3394 Prepend @var{dir} to the include path. Multiple invocations accumulate.
3396 @item --warnings=@var{category}
3397 @itemx -W @var{category}
3399 Report the warnings related to @var{category} (which can actually be a
3400 comma separated list). Current categories include:
3404 report the uses of obsolete constructs
3407 report all the warnings
3413 treats warnings as errors
3415 @item no-@var{category}
3416 disable warnings falling into @var{category}
3423 @node Autoheader Macros
3424 @subsection Autoheader Macros
3425 @cindex Autoheader macros
3427 @command{autoheader} scans @file{configure.ac} and figures out which C
3428 preprocessor symbols it might define. It knows how to generate
3429 templates for symbols defined by @code{AC_CHECK_HEADERS},
3430 @code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional
3431 symbol, you must define a template for it. If there are missing
3432 templates, @command{autoheader} fails with an error message.
3434 The template for a @var{symbol} is created
3435 by @command{autoheader} from
3436 the @var{description} argument to an @code{AC_DEFINE};
3437 see @ref{Defining Symbols}.
3439 For special needs, you can use the following macros.
3442 @defmac AH_TEMPLATE (@var{key}, @var{description})
3444 Tell @command{autoheader} to generate a template for @var{key}. This macro
3445 generates standard templates just like @code{AC_DEFINE} when a
3446 @var{description} is given.
3451 AH_TEMPLATE([CRAY_STACKSEG_END],
3452 [Define to one of _getb67, GETB67, getb67
3453 for Cray-2 and Cray-YMP systems. This
3454 function is required for alloca.c support
3459 generates the following template, with the description properly
3463 /* Define to one of _getb67, GETB67, getb67 for Cray-2 and
3464 Cray-YMP systems. This function is required for alloca.c
3465 support on those systems. */
3466 #undef CRAY_STACKSEG_END
3471 @defmac AH_VERBATIM (@var{key}, @var{template})
3473 Tell @command{autoheader} to include the @var{template} as-is in the header
3474 template file. This @var{template} is associated with the @var{key},
3475 which is used to sort all the different templates and guarantee their
3476 uniqueness. It should be a symbol that can be defined via @code{AC_DEFINE}.
3480 @defmac AH_TOP (@var{text})
3482 Include @var{text} at the top of the header template file.
3486 @defmac AH_BOTTOM (@var{text})
3488 Include @var{text} at the bottom of the header template file.
3492 Please note that @var{text} gets included ``verbatim'' to the template file,
3493 not to the resulting config header, so it can easily get mangled when the
3494 template is processed. There is rarely a need for something other than
3497 AH_BOTTOM([#include <custom.h>])
3502 @node Configuration Commands
3503 @section Running Arbitrary Configuration Commands
3504 @cindex Configuration commands
3505 @cindex Commands for configuration
3507 You can execute arbitrary commands before, during, and after
3508 @file{config.status} is run. The three following macros accumulate the
3509 commands to run when they are called multiple times.
3510 @code{AC_CONFIG_COMMANDS} replaces the obsolete macro
3511 @code{AC_OUTPUT_COMMANDS}; see @ref{Obsolete Macros}, for details.
3513 @anchor{AC_CONFIG_COMMANDS}
3514 @defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds})
3515 @acindex{CONFIG_COMMANDS}
3516 Specify additional shell commands to run at the end of
3517 @file{config.status}, and shell commands to initialize any variables
3518 from @command{configure}. Associate the commands with @var{tag}.
3519 Since typically the @var{cmds} create a file, @var{tag} should
3520 naturally be the name of that file. If needed, the directory hosting
3521 @var{tag} is created. This macro is one of the instantiating macros;
3522 see @ref{Configuration Actions}.
3524 Here is an unrealistic example:
3527 AC_CONFIG_COMMANDS([fubar],
3528 [echo this is extra $fubar, and so on.],
3532 Here is a better one:
3534 AC_CONFIG_COMMANDS([timestamp], [date >timestamp])
3538 The following two macros look similar, but in fact they are not of the same
3539 breed: they are executed directly by @file{configure}, so you cannot use
3540 @file{config.status} to rerun them.
3542 @c Yet it is good to leave them here. The user sees them together and
3543 @c decides which best fits their needs.
3545 @defmac AC_CONFIG_COMMANDS_PRE (@var{cmds})
3546 @acindex{CONFIG_COMMANDS_PRE}
3547 Execute the @var{cmds} right before creating @file{config.status}.
3549 This macro presents the last opportunity to call @code{AC_SUBST},
3550 @code{AC_DEFINE}, or @code{AC_CONFIG_@var{ITEMS}} macros.
3553 @defmac AC_CONFIG_COMMANDS_POST (@var{cmds})
3554 @acindex{CONFIG_COMMANDS_POST}
3555 Execute the @var{cmds} right after creating @file{config.status}.
3561 @node Configuration Links
3562 @section Creating Configuration Links
3563 @cindex Configuration links
3564 @cindex Links for configuration
3566 You may find it convenient to create links whose destinations depend upon
3567 results of tests. One can use @code{AC_CONFIG_COMMANDS} but the
3568 creation of relative symbolic links can be delicate when the package is
3569 built in a directory different from the source directory.
3571 @anchor{AC_CONFIG_LINKS}
3572 @defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @
3574 @acindex{CONFIG_LINKS}
3576 Make @code{AC_OUTPUT} link each of the existing files @var{source} to
3577 the corresponding link name @var{dest}. Makes a symbolic link if
3578 possible, otherwise a hard link if possible, otherwise a copy. The
3579 @var{dest} and @var{source} names should be relative to the top level
3580 source or build directory. This macro is one of the instantiating
3581 macros; see @ref{Configuration Actions}.
3583 For example, this call:
3586 AC_CONFIG_LINKS([host.h:config/$machine.h
3587 object.h:config/$obj_format.h])
3591 creates in the current directory @file{host.h} as a link to
3592 @file{@var{srcdir}/config/$machine.h}, and @file{object.h} as a
3593 link to @file{@var{srcdir}/config/$obj_format.h}.
3595 The tempting value @samp{.} for @var{dest} is invalid: it makes it
3596 impossible for @samp{config.status} to guess the links to establish.
3600 ./config.status host.h object.h
3603 to create the links.
3608 @node Subdirectories
3609 @section Configuring Other Packages in Subdirectories
3610 @cindex Configure subdirectories
3611 @cindex Subdirectory configure
3613 In most situations, calling @code{AC_OUTPUT} is sufficient to produce
3614 makefiles in subdirectories. However, @command{configure} scripts
3615 that control more than one independent package can use
3616 @code{AC_CONFIG_SUBDIRS} to run @command{configure} scripts for other
3617 packages in subdirectories.
3619 @defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{})
3620 @acindex{CONFIG_SUBDIRS}
3622 Make @code{AC_OUTPUT} run @command{configure} in each subdirectory
3623 @var{dir} in the given blank-or-newline-separated list. Each @var{dir} should
3624 be a literal, i.e., please do not use:
3627 @c If you change this example, adjust tests/torture.at:Non-literal AC_CONFIG_SUBDIRS.
3628 if test "x$package_foo_enabled" = xyes; then
3629 my_subdirs="$my_subdirs foo"
3631 AC_CONFIG_SUBDIRS([$my_subdirs])
3635 because this prevents @samp{./configure --help=recursive} from
3636 displaying the options of the package @code{foo}. Instead, you should
3640 if test "x$package_foo_enabled" = xyes; then
3641 AC_CONFIG_SUBDIRS([foo])
3645 If a given @var{dir} is not found at @command{configure} run time, a
3646 warning is reported; if the subdirectory is optional, write:
3649 if test -d "$srcdir/foo"; then
3650 AC_CONFIG_SUBDIRS([foo])
3654 @c NB: Yes, below we mean configure.in, not configure.ac.
3655 If a given @var{dir} contains @command{configure.gnu}, it is run instead
3656 of @command{configure}. This is for packages that might use a
3657 non-Autoconf script @command{Configure}, which can't be called through a
3658 wrapper @command{configure} since it would be the same file on
3659 case-insensitive file systems. Likewise, if a @var{dir} contains
3660 @file{configure.in} but no @command{configure}, the Cygnus
3661 @command{configure} script found by @code{AC_CONFIG_AUX_DIR} is used.
3663 The subdirectory @command{configure} scripts are given the same command
3664 line options that were given to this @command{configure} script, with minor
3665 changes if needed, which include:
3669 adjusting a relative name for the cache file;
3672 adjusting a relative name for the source directory;
3675 propagating the current value of @code{$prefix}, including if it was
3676 defaulted, and if the default values of the top level and of the subdirectory
3677 @file{configure} differ.
3680 This macro also sets the output variable @code{subdirs} to the list of
3681 directories @samp{@var{dir} @dots{}}. Make rules can use
3682 this variable to determine which subdirectories to recurse into.
3684 This macro may be called multiple times.
3687 @node Default Prefix
3688 @section Default Prefix
3689 @cindex Install prefix
3690 @cindex Prefix for install
3692 By default, @command{configure} sets the prefix for files it installs to
3693 @file{/usr/local}. The user of @command{configure} can select a different
3694 prefix using the @option{--prefix} and @option{--exec-prefix} options.
3695 There are two ways to change the default: when creating
3696 @command{configure}, and when running it.
3698 Some software packages might want to install in a directory other than
3699 @file{/usr/local} by default. To accomplish that, use the
3700 @code{AC_PREFIX_DEFAULT} macro.
3702 @defmac AC_PREFIX_DEFAULT (@var{prefix})
3703 @acindex{PREFIX_DEFAULT}
3704 Set the default installation prefix to @var{prefix} instead of
3708 It may be convenient for users to have @command{configure} guess the
3709 installation prefix from the location of a related program that they
3710 have already installed. If you wish to do that, you can call
3711 @code{AC_PREFIX_PROGRAM}.
3713 @anchor{AC_PREFIX_PROGRAM}
3714 @defmac AC_PREFIX_PROGRAM (@var{program})
3715 @acindex{PREFIX_PROGRAM}
3716 If the user did not specify an installation prefix (using the
3717 @option{--prefix} option), guess a value for it by looking for
3718 @var{program} in @env{PATH}, the way the shell does. If @var{program}
3719 is found, set the prefix to the parent of the directory containing
3720 @var{program}, else default the prefix as described above
3721 (@file{/usr/local} or @code{AC_PREFIX_DEFAULT}). For example, if
3722 @var{program} is @code{gcc} and the @env{PATH} contains
3723 @file{/usr/local/gnu/bin/gcc}, set the prefix to @file{/usr/local/gnu}.
3728 @c ======================================================== Existing tests
3730 @node Existing Tests
3731 @chapter Existing Tests
3733 These macros test for particular system features that packages might
3734 need or want to use. If you need to test for a kind of feature that
3735 none of these macros check for, you can probably do it by calling
3736 primitive test macros with appropriate arguments (@pxref{Writing
3739 These tests print messages telling the user which feature they're
3740 checking for, and what they find. They cache their results for future
3741 @command{configure} runs (@pxref{Caching Results}).
3743 Some of these macros set output variables. @xref{Makefile
3744 Substitutions}, for how to get their values. The phrase ``define
3745 @var{name}'' is used below as a shorthand to mean ``define the C
3746 preprocessor symbol @var{name} to the value 1''. @xref{Defining
3747 Symbols}, for how to get those symbol definitions into your program.
3750 * Common Behavior:: Macros' standard schemes
3751 * Alternative Programs:: Selecting between alternative programs
3752 * Files:: Checking for the existence of files
3753 * Libraries:: Library archives that might be missing
3754 * Library Functions:: C library functions that might be missing
3755 * Header Files:: Header files that might be missing
3756 * Declarations:: Declarations that may be missing
3757 * Structures:: Structures or members that might be missing
3758 * Types:: Types that might be missing
3759 * Compilers and Preprocessors:: Checking for compiling programs
3760 * System Services:: Operating system services
3761 * Posix Variants:: Special kludges for specific Posix variants
3762 * Erlang Libraries:: Checking for the existence of Erlang libraries
3765 @node Common Behavior
3766 @section Common Behavior
3767 @cindex Common autoconf behavior
3769 Much effort has been expended to make Autoconf easy to learn. The most
3770 obvious way to reach this goal is simply to enforce standard interfaces
3771 and behaviors, avoiding exceptions as much as possible. Because of
3772 history and inertia, unfortunately, there are still too many exceptions
3773 in Autoconf; nevertheless, this section describes some of the common
3777 * Standard Symbols:: Symbols defined by the macros
3778 * Default Includes:: Includes used by the generic macros
3781 @node Standard Symbols
3782 @subsection Standard Symbols
3783 @cindex Standard symbols
3785 All the generic macros that @code{AC_DEFINE} a symbol as a result of
3786 their test transform their @var{argument} values to a standard alphabet.
3787 First, @var{argument} is converted to upper case and any asterisks
3788 (@samp{*}) are each converted to @samp{P}. Any remaining characters
3789 that are not alphanumeric are converted to underscores.
3794 AC_CHECK_TYPES([struct $Expensive*])
3798 defines the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check
3802 @node Default Includes
3803 @subsection Default Includes
3804 @cindex Default includes
3805 @cindex Includes, default
3807 Several tests depend upon a set of header files. Since these headers
3808 are not universally available, tests actually have to provide a set of
3809 protected includes, such as:
3813 #ifdef TIME_WITH_SYS_TIME
3814 # include <sys/time.h>
3817 # ifdef HAVE_SYS_TIME_H
3818 # include <sys/time.h>
3827 Unless you know exactly what you are doing, you should avoid using
3828 unconditional includes, and check the existence of the headers you
3829 include beforehand (@pxref{Header Files}).
3831 Most generic macros use the following macro to provide the default set
3834 @defmac AC_INCLUDES_DEFAULT (@ovar{include-directives})
3835 @acindex{INCLUDES_DEFAULT}
3836 Expand to @var{include-directives} if defined, otherwise to:
3841 #ifdef HAVE_SYS_TYPES_H
3842 # include <sys/types.h>
3844 #ifdef HAVE_SYS_STAT_H
3845 # include <sys/stat.h>
3848 # include <stdlib.h>
3849 # include <stddef.h>
3851 # ifdef HAVE_STDLIB_H
3852 # include <stdlib.h>
3855 #ifdef HAVE_STRING_H
3856 # if !defined STDC_HEADERS && defined HAVE_MEMORY_H
3857 # include <memory.h>
3859 # include <string.h>
3861 #ifdef HAVE_STRINGS_H
3862 # include <strings.h>
3864 #ifdef HAVE_INTTYPES_H
3865 # include <inttypes.h>
3867 #ifdef HAVE_STDINT_H
3868 # include <stdint.h>
3870 #ifdef HAVE_UNISTD_H
3871 # include <unistd.h>
3876 If the default includes are used, then check for the presence of these
3877 headers and their compatibility, i.e., you don't need to run
3878 @code{AC_HEADER_STDC}, nor check for @file{stdlib.h} etc.
3880 These headers are checked for in the same order as they are included.
3881 For instance, on some systems @file{string.h} and @file{strings.h} both
3882 exist, but conflict. Then @code{HAVE_STRING_H} is defined, not
3883 @code{HAVE_STRINGS_H}.
3886 @node Alternative Programs
3887 @section Alternative Programs
3888 @cindex Programs, checking
3890 These macros check for the presence or behavior of particular programs.
3891 They are used to choose between several alternative programs and to
3892 decide what to do once one has been chosen. If there is no macro
3893 specifically defined to check for a program you need, and you don't need
3894 to check for any special properties of it, then you can use one of the
3895 general program-check macros.
3898 * Particular Programs:: Special handling to find certain programs
3899 * Generic Programs:: How to find other programs
3902 @node Particular Programs
3903 @subsection Particular Program Checks
3905 These macros check for particular programs---whether they exist, and
3906 in some cases whether they support certain features.
3912 Check for @code{gawk}, @code{mawk}, @code{nawk}, and @code{awk}, in that
3913 order, and set output variable @code{AWK} to the first one that is found.
3914 It tries @code{gawk} first because that is reported to be the
3915 best implementation. The result can be overridden by setting the
3916 variable @code{AWK} or the cache variable @code{ac_cv_prog_AWK}.
3919 @defmac AC_PROG_GREP
3923 Look for the best available @code{grep} or @code{ggrep} that accepts the
3924 longest input lines possible, and that supports multiple @option{-e} options.
3925 Set the output variable @code{GREP} to whatever is chosen.
3926 @xref{grep, , Limitations of Usual Tools}, for more information about
3927 portability problems with the @command{grep} command family. The result
3928 can be overridden by setting the @code{GREP} variable and is cached in the
3929 @code{ac_cv_path_GREP} variable.
3932 @defmac AC_PROG_EGREP
3933 @acindex{PROG_EGREP}
3936 Check whether @code{$GREP -E} works, or else look for the best available
3937 @code{egrep} or @code{gegrep} that accepts the longest input lines possible.
3938 Set the output variable @code{EGREP} to whatever is chosen. The result
3939 can be overridden by setting the @code{EGREP} variable and is cached in the
3940 @code{ac_cv_path_EGREP} variable.
3943 @defmac AC_PROG_FGREP
3944 @acindex{PROG_FGREP}
3947 Check whether @code{$GREP -F} works, or else look for the best available
3948 @code{fgrep} or @code{gfgrep} that accepts the longest input lines possible.
3949 Set the output variable @code{FGREP} to whatever is chosen. The result
3950 can be overridden by setting the @code{FGREP} variable and is cached in the
3951 @code{ac_cv_path_FGREP} variable.
3954 @defmac AC_PROG_INSTALL
3955 @acindex{PROG_INSTALL}
3957 @ovindex INSTALL_PROGRAM
3958 @ovindex INSTALL_DATA
3959 @ovindex INSTALL_SCRIPT
3960 @caindex path_install
3961 Set output variable @code{INSTALL} to the name of a BSD-compatible
3962 @command{install} program, if one is found in the current @env{PATH}.
3963 Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c},
3964 checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its
3965 default directories) to determine @var{dir} (@pxref{Output}). Also set
3966 the variables @code{INSTALL_PROGRAM} and @code{INSTALL_SCRIPT} to
3967 @samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}.
3969 @samp{@@INSTALL@@} is special, as its value may vary for different
3970 configuration files.
3972 This macro screens out various instances of @command{install} known not to
3973 work. It prefers to find a C program rather than a shell script, for
3974 speed. Instead of @file{install-sh}, it can also use @file{install.sh},
3975 but that name is obsolete because some @command{make} programs have a rule
3976 that creates @file{install} from it if there is no makefile. Further, this
3977 macro requires @command{install} to be able to install multiple files into a
3978 target directory in a single invocation.
3980 Autoconf comes with a copy of @file{install-sh} that you can use. If
3981 you use @code{AC_PROG_INSTALL}, you must include either
3982 @file{install-sh} or @file{install.sh} in your distribution; otherwise
3983 @command{configure} produces an error message saying it can't find
3984 them---even if the system you're on has a good @command{install} program.
3985 This check is a safety measure to prevent you from accidentally leaving
3986 that file out, which would prevent your package from installing on
3987 systems that don't have a BSD-compatible @command{install} program.
3989 If you need to use your own installation program because it has features
3990 not found in standard @command{install} programs, there is no reason to use
3991 @code{AC_PROG_INSTALL}; just put the file name of your program into your
3992 @file{Makefile.in} files.
3994 The result of the test can be overridden by setting the variable
3995 @code{INSTALL} or the cache variable @code{ac_cv_path_install}.
3998 @defmac AC_PROG_MKDIR_P
3999 @acindex{PROG_MKDIR_P}
4002 Set output variable @code{MKDIR_P} to a program that ensures that for
4003 each argument, a directory named by this argument exists, creating it
4004 and its parent directories if needed, and without race conditions when
4005 two instances of the program attempt to make the same directory at
4006 nearly the same time.
4008 This macro uses the @samp{mkdir -p} command if possible. Otherwise, it
4009 falls back on invoking @command{install-sh} with the @option{-d} option,
4010 so your package should
4011 contain @file{install-sh} as described under @code{AC_PROG_INSTALL}.
4012 An @file{install-sh} file that predates Autoconf 2.60 or Automake 1.10
4013 is vulnerable to race conditions, so if you want to support parallel
4015 different packages into the same directory you need to make sure you
4016 have an up-to-date @file{install-sh}. In particular, be careful about
4017 using @samp{autoreconf -if} if your Automake predates Automake 1.10.
4019 This macro is related to the @code{AS_MKDIR_P} macro (@pxref{Programming
4020 in M4sh}), but it sets an output variable intended for use in other
4021 files, whereas @code{AS_MKDIR_P} is intended for use in scripts like
4022 @command{configure}. Also, @code{AS_MKDIR_P} does not accept options,
4023 but @code{MKDIR_P} supports the @option{-m} option, e.g., a makefile
4024 might invoke @code{$(MKDIR_P) -m 0 dir} to create an inaccessible
4025 directory, and conversely a makefile should use @code{$(MKDIR_P) --
4026 $(FOO)} if @var{FOO} might yield a value that begins with @samp{-}.
4027 Finally, @code{AS_MKDIR_P} does not check for race condition
4028 vulnerability, whereas @code{AC_PROG_MKDIR_P} does.
4030 @samp{@@MKDIR_P@@} is special, as its value may vary for different
4031 configuration files.
4033 The result of the test can be overridden by setting the variable
4034 @code{MKDIR_P} or the cache variable @code{ac_cv_path_mkdir}.
4037 @anchor{AC_PROG_LEX}
4042 @cvindex YYTEXT_POINTER
4043 @ovindex LEX_OUTPUT_ROOT
4045 If @code{flex} is found, set output variable @code{LEX} to @samp{flex}
4046 and @code{LEXLIB} to @option{-lfl}, if that library is in a standard
4047 place. Otherwise set @code{LEX} to @samp{lex} and @code{LEXLIB} to
4048 @option{-ll}, if found. If neither variant is available, set @code{LEX}
4049 to @samp{:}; for packages that ship the generated @file{file.yy.c}
4050 alongside the source @file{file.l}, this default allows users without a
4051 lexer generator to still build the package even if the timestamp for
4052 @file{file.l} is inadvertantly changed.
4054 Define @code{YYTEXT_POINTER} if @code{yytext} defaults to @samp{char *} instead
4055 of to @samp{char []}. Also set output variable @code{LEX_OUTPUT_ROOT} to
4056 the base of the file name that the lexer generates; usually
4057 @file{lex.yy}, but sometimes something else. These results vary
4058 according to whether @code{lex} or @code{flex} is being used.
4060 You are encouraged to use Flex in your sources, since it is both more
4061 pleasant to use than plain Lex and the C source it produces is portable.
4062 In order to ensure portability, however, you must either provide a
4063 function @code{yywrap} or, if you don't use it (e.g., your scanner has
4064 no @samp{#include}-like feature), simply include a @samp{%noyywrap}
4065 statement in the scanner's source. Once this done, the scanner is
4066 portable (unless @emph{you} felt free to use nonportable constructs) and
4067 does not depend on any library. In this case, and in this case only, it
4068 is suggested that you use this Autoconf snippet:
4072 if test "x$LEX" != xflex; then
4073 LEX="$SHELL $missing_dir/missing flex"
4074 AC_SUBST([LEX_OUTPUT_ROOT], [lex.yy])
4075 AC_SUBST([LEXLIB], [''])
4079 The shell script @command{missing} can be found in the Automake
4082 Remember that the user may have supplied an alternate location in
4083 @env{LEX}, so if Flex is required, it is better to check that the user
4084 provided something sufficient by parsing the output of @samp{$LEX
4085 --version} than by simply relying on @code{test "x$LEX" = xflex}.
4087 To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes
4088 (indirectly) this macro twice, which causes an annoying but benign
4089 ``@code{AC_PROG_LEX} invoked multiple times'' warning. Future versions
4090 of Automake will fix this issue; meanwhile, just ignore this message.
4092 As part of running the test, this macro may delete any file in the
4093 configuration directory named @file{lex.yy.c} or @file{lexyy.c}.
4095 The result of this test can be influenced by setting the variable
4096 @code{LEX} or the cache variable @code{ac_cv_prog_LEX}.
4099 @anchor{AC_PROG_LN_S}
4100 @defmac AC_PROG_LN_S
4103 If @samp{ln -s} works on the current file system (the operating system
4104 and file system support symbolic links), set the output variable
4105 @code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set
4106 @code{LN_S} to @samp{ln}, and otherwise set it to @samp{cp -p}.
4108 If you make a link in a directory other than the current directory, its
4109 meaning depends on whether @samp{ln} or @samp{ln -s} is used. To safely
4110 create links using @samp{$(LN_S)}, either find out which form is used
4111 and adjust the arguments, or always invoke @code{ln} in the directory
4112 where the link is to be created.
4114 In other words, it does not work to do:
4122 (cd /x && $(LN_S) foo bar)
4126 @defmac AC_PROG_RANLIB
4127 @acindex{PROG_RANLIB}
4129 @c @caindex prog_RANLIB
4130 @c @caindex prog_ac_ct_RANLIB
4131 Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib}
4132 is found, and otherwise to @samp{:} (do nothing).
4139 Set output variable @code{SED} to a Sed implementation that conforms to
4140 Posix and does not have arbitrary length limits. Report an error if no
4141 acceptable Sed is found. @xref{sed, , Limitations of Usual Tools}, for more
4142 information about portability problems with Sed.
4144 The result of this test can be overridden by setting the @code{SED} variable
4145 and is cached in the @code{ac_cv_path_SED} variable.
4148 @defmac AC_PROG_YACC
4154 If @code{bison} is found, set output variable @code{YACC} to @samp{bison
4155 -y}. Otherwise, if @code{byacc} is found, set @code{YACC} to
4156 @samp{byacc}. Otherwise set @code{YACC} to @samp{yacc}.
4157 The result of this test can be influenced by setting the variable
4158 @code{YACC} or the cache variable @code{ac_cv_prog_YACC}.
4161 @node Generic Programs
4162 @subsection Generic Program and File Checks
4164 These macros are used to find programs not covered by the ``particular''
4165 test macros. If you need to check the behavior of a program as well as
4166 find out whether it is present, you have to write your own test for it
4167 (@pxref{Writing Tests}). By default, these macros use the environment
4168 variable @env{PATH}. If you need to check for a program that might not
4169 be in the user's @env{PATH}, you can pass a modified path to use
4173 AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd],
4174 [$PATH$PATH_SEPARATOR/usr/libexec$PATH_SEPARATOR]dnl
4175 [/usr/sbin$PATH_SEPARATOR/usr/etc$PATH_SEPARATOR/etc])
4178 You are strongly encouraged to declare the @var{variable} passed to
4179 @code{AC_CHECK_PROG} etc.@: as precious, @xref{Setting Output Variables},
4180 @code{AC_ARG_VAR}, for more details.
4182 @anchor{AC_CHECK_PROG}
4183 @defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @
4184 @var{value-if-found}, @ovar{value-if-not-found}, @dvar{path, $PATH}, @
4186 @acindex{CHECK_PROG}
4187 @caindex prog_@var{variable}
4188 Check whether program @var{prog-to-check-for} exists in @var{path}. If
4189 it is found, set @var{variable} to @var{value-if-found}, otherwise to
4190 @var{value-if-not-found}, if given. Always pass over @var{reject} (an
4191 absolute file name) even if it is the first found in the search path; in
4192 that case, set @var{variable} using the absolute file name of the
4193 @var{prog-to-check-for} found that is not @var{reject}. If
4194 @var{variable} was already set, do nothing. Calls @code{AC_SUBST} for
4195 @var{variable}. The result of this test can be overridden by setting the
4196 @var{variable} variable or the cache variable
4197 @code{ac_cv_prog_@var{variable}}.
4200 @anchor{AC_CHECK_PROGS}
4201 @defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @
4202 @ovar{value-if-not-found}, @dvar{path, $PATH})
4203 @acindex{CHECK_PROGS}
4204 @caindex prog_@var{variable}
4205 Check for each program in the blank-separated list
4206 @var{progs-to-check-for} existing in the @var{path}. If one is found, set
4207 @var{variable} to the name of that program. Otherwise, continue
4208 checking the next program in the list. If none of the programs in the
4209 list are found, set @var{variable} to @var{value-if-not-found}; if
4210 @var{value-if-not-found} is not specified, the value of @var{variable}
4211 is not changed. Calls @code{AC_SUBST} for @var{variable}. The result of
4212 this test can be overridden by setting the @var{variable} variable or the
4213 cache variable @code{ac_cv_prog_@var{variable}}.
4216 @defmac AC_CHECK_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @
4217 @ovar{value-if-not-found}, @dvar{path, $PATH})
4218 @acindex{CHECK_TARGET_TOOL}
4219 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
4220 with a prefix of the target type as determined by
4221 @code{AC_CANONICAL_TARGET}, followed by a dash (@pxref{Canonicalizing}).
4222 If the tool cannot be found with a prefix, and if the build and target
4223 types are equal, then it is also searched for without a prefix.
4225 As noted in @ref{Specifying Target Triplets}, the
4226 target is rarely specified, because most of the time it is the same
4227 as the host: it is the type of system for which any compiler tool in
4228 the package produces code. What this macro looks for is,
4229 for example, @emph{a tool @r{(assembler, linker, etc.)}@: that the
4230 compiler driver @r{(@command{gcc} for the GNU C Compiler)}
4231 uses to produce objects, archives or executables}.
4234 @defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for}, @
4235 @ovar{value-if-not-found}, @dvar{path, $PATH})
4236 @acindex{CHECK_TOOL}
4237 @c @caindex prog_@var{VARIABLE}
4238 @c @caindex prog_ac_ct_@var{VARIABLE}
4239 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
4240 with a prefix of the host type as specified by @option{--host}, followed by a
4241 dash. For example, if the user runs
4242 @samp{configure --build=x86_64-gnu --host=i386-gnu}, then this call:
4244 AC_CHECK_TOOL([RANLIB], [ranlib], [:])
4247 sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in
4248 @var{path}, or otherwise to @samp{ranlib} if that program exists in
4249 @var{path}, or to @samp{:} if neither program exists.
4251 When cross-compiling, this macro will issue a warning if no program
4252 prefixed with the host type could be found.
4253 For more information, see @ref{Specifying Target Triplets}.
4256 @defmac AC_CHECK_TARGET_TOOLS (@var{variable}, @var{progs-to-check-for}, @
4257 @ovar{value-if-not-found}, @dvar{path, $PATH})
4258 @acindex{CHECK_TARGET_TOOLS}
4259 Like @code{AC_CHECK_TARGET_TOOL}, each of the tools in the list
4260 @var{progs-to-check-for} are checked with a prefix of the target type as
4261 determined by @code{AC_CANONICAL_TARGET}, followed by a dash
4262 (@pxref{Canonicalizing}). If none of the tools can be found with a
4263 prefix, and if the build and target types are equal, then the first one
4264 without a prefix is used. If a tool is found, set @var{variable} to
4265 the name of that program. If none of the tools in the list are found,
4266 set @var{variable} to @var{value-if-not-found}; if @var{value-if-not-found}
4267 is not specified, the value of @var{variable} is not changed. Calls
4268 @code{AC_SUBST} for @var{variable}.
4271 @defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @
4272 @ovar{value-if-not-found}, @dvar{path, $PATH})
4273 @acindex{CHECK_TOOLS}
4274 Like @code{AC_CHECK_TOOL}, each of the tools in the list
4275 @var{progs-to-check-for} are checked with a prefix of the host type as
4276 determined by @code{AC_CANONICAL_HOST}, followed by a dash
4277 (@pxref{Canonicalizing}). If none of the tools can be found with a
4278 prefix, then the first one without a prefix is used. If a tool is found,
4279 set @var{variable} to the name of that program. If none of the tools in
4280 the list are found, set @var{variable} to @var{value-if-not-found}; if
4281 @var{value-if-not-found} is not specified, the value of @var{variable}
4282 is not changed. Calls @code{AC_SUBST} for @var{variable}.
4284 When cross-compiling, this macro will issue a warning if no program
4285 prefixed with the host type could be found.
4286 For more information, see @ref{Specifying Target Triplets}.
4289 @anchor{AC_PATH_PROG}
4290 @defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for}, @
4291 @ovar{value-if-not-found}, @dvar{path, $PATH})
4293 @caindex path_@var{variable}
4294 Like @code{AC_CHECK_PROG}, but set @var{variable} to the absolute
4295 name of @var{prog-to-check-for} if found. The result of this test
4296 can be overridden by setting the @var{variable} variable. A positive
4297 result of this test is cached in the @code{ac_cv_path_@var{variable}}
4301 @anchor{AC_PATH_PROGS}
4302 @defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for}, @
4303 @ovar{value-if-not-found}, @dvar{path, $PATH})
4304 @acindex{PATH_PROGS}
4305 @caindex path_@var{variable}
4306 Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for}
4307 are found, set @var{variable} to the absolute name of the program
4308 found. The result of this test can be overridden by setting the
4309 @var{variable} variable. A positive result of this test is cached in
4310 the @code{ac_cv_path_@var{variable}} variable.
4313 @defmac AC_PATH_PROGS_FEATURE_CHECK (@var{variable}, @
4314 @var{progs-to-check-for}, @var{feature-test}, @
4315 @ovar{action-if-not-found}, @dvar{path, $PATH})
4316 @acindex{PATH_PROGS_FEATURE_CHECK}
4317 @caindex path_@var{variable}
4318 This macro was introduced in Autoconf 2.62. If @var{variable} is not
4319 empty, then set the cache variable @code{ac_cv_path_@var{variable}} to
4320 its value. Otherwise, check for each program in the blank-separated
4321 list @var{progs-to-check-for} existing in @var{path}. For each program
4322 found, execute @var{feature-test} with @code{ac_path_@var{variable}}
4323 set to the absolute name of the candidate program. If no invocation of
4324 @var{feature-test} sets the shell variable
4325 @code{ac_cv_path_@var{variable}}, then @var{action-if-not-found} is
4326 executed. @var{feature-test} will be run even when
4327 @code{ac_cv_path_@var{variable}} is set, to provide the ability to
4328 choose a better candidate found later in @var{path}; to accept the
4329 current setting and bypass all futher checks, @var{feature-test} can
4330 execute @code{ac_path_@var{variable}_found=:}.
4332 Note that this macro has some subtle differences from
4333 @code{AC_CHECK_PROGS}. It is designed to be run inside
4334 @code{AC_CACHE_VAL}, therefore, it should have no side effects. In
4335 particular, @var{variable} is not set to the final value of
4336 @code{ac_cv_path_@var{variable}}, nor is @code{AC_SUBST} automatically
4337 run. Also, on failure, any action can be performed, whereas
4338 @code{AC_CHECK_PROGS} only performs
4339 @code{@var{variable}=@var{value-if-not-found}}.
4341 Here is an example, similar to what Autoconf uses in its own configure
4342 script. It will search for an implementation of @command{m4} that
4343 supports the @code{indir} builtin, even if it goes by the name
4344 @command{gm4} or is not the first implementation on @env{PATH}.
4347 AC_CACHE_CHECK([for m4 that supports indir], [ac_cv_path_M4],
4348 [AC_PATH_PROGS_FEATURE_CHECK([M4], [m4 gm4],
4349 [[m4out=`echo 'changequote([,])indir([divnum])' | $ac_path_M4`
4350 test "x$m4out" = x0 \
4351 && ac_cv_path_M4=$ac_path_M4 ac_path_M4_found=:]],
4352 [AC_MSG_ERROR([could not find m4 that supports indir])])])
4353 AC_SUBST([M4], [$ac_cv_path_M4])
4357 @defmac AC_PATH_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @
4358 @ovar{value-if-not-found}, @dvar{path, $PATH})
4359 @acindex{PATH_TARGET_TOOL}
4360 Like @code{AC_CHECK_TARGET_TOOL}, but set @var{variable} to the absolute
4361 name of the program if it is found.
4364 @defmac AC_PATH_TOOL (@var{variable}, @var{prog-to-check-for}, @
4365 @ovar{value-if-not-found}, @dvar{path, $PATH})
4367 Like @code{AC_CHECK_TOOL}, but set @var{variable} to the absolute
4368 name of the program if it is found.
4370 When cross-compiling, this macro will issue a warning if no program
4371 prefixed with the host type could be found.
4372 For more information, see @ref{Specifying Target Triplets}.
4378 @cindex File, checking
4380 You might also need to check for the existence of files. Before using
4381 these macros, ask yourself whether a runtime test might not be a better
4382 solution. Be aware that, like most Autoconf macros, they test a feature
4383 of the host machine, and therefore, they die when cross-compiling.
4385 @defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @
4386 @ovar{action-if-not-found})
4387 @acindex{CHECK_FILE}
4388 @caindex file_@var{file}
4389 Check whether file @var{file} exists on the native system. If it is
4390 found, execute @var{action-if-found}, otherwise do
4391 @var{action-if-not-found}, if given. The result of this test is cached
4392 in the @code{ac_cv_file_@var{file}} variable, with characters not
4393 suitable for a variable name mapped to underscores.
4396 @defmac AC_CHECK_FILES (@var{files}, @ovar{action-if-found}, @
4397 @ovar{action-if-not-found})
4398 @acindex{CHECK_FILES}
4399 @caindex file_@var{file}
4400 Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}.
4401 Additionally, defines @samp{HAVE_@var{file}} (@pxref{Standard Symbols})
4402 for each file found. The results of each test are cached in the
4403 @code{ac_cv_file_@var{file}} variable, with characters not suitable for
4404 a variable name mapped to underscores.
4409 @section Library Files
4410 @cindex Library, checking
4412 The following macros check for the presence of certain C, C++, or Fortran
4413 library archive files.
4415 @anchor{AC_CHECK_LIB}
4416 @defmac AC_CHECK_LIB (@var{library}, @var{function}, @
4417 @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
4419 @caindex lib_@var{library}_@var{function}
4420 Test whether the library @var{library} is available by trying to link
4421 a test program that calls function @var{function} with the library.
4422 @var{function} should be a function provided by the library.
4424 name of the library; e.g., to check for @option{-lmp}, use @samp{mp} as
4425 the @var{library} argument.
4427 @var{action-if-found} is a list of shell commands to run if the link
4428 with the library succeeds; @var{action-if-not-found} is a list of shell
4429 commands to run if the link fails. If @var{action-if-found} is not
4430 specified, the default action prepends @option{-l@var{library}} to
4431 @code{LIBS} and defines @samp{HAVE_LIB@var{library}} (in all
4432 capitals). This macro is intended to support building @code{LIBS} in
4433 a right-to-left (least-dependent to most-dependent) fashion such that
4434 library dependencies are satisfied as a natural side effect of
4435 consecutive tests. Linkers are sensitive to library ordering
4436 so the order in which @code{LIBS} is generated is important to reliable
4437 detection of libraries.
4439 If linking with @var{library} results in unresolved symbols that would
4440 be resolved by linking with additional libraries, give those libraries
4441 as the @var{other-libraries} argument, separated by spaces:
4442 e.g., @option{-lXt -lX11}. Otherwise, this macro may fail to detect
4443 that @var{library} is present, because linking the test program can
4444 fail with unresolved symbols. The @var{other-libraries} argument
4445 should be limited to cases where it is desirable to test for one library
4446 in the presence of another that is not already in @code{LIBS}.
4448 @code{AC_CHECK_LIB} requires some care in usage, and should be avoided
4449 in some common cases. Many standard functions like @code{gethostbyname}
4450 appear in the standard C library on some hosts, and in special libraries
4451 like @code{nsl} on other hosts. On some hosts the special libraries
4452 contain variant implementations that you may not want to use. These
4453 days it is normally better to use @code{AC_SEARCH_LIBS([gethostbyname],
4454 [nsl])} instead of @code{AC_CHECK_LIB([nsl], [gethostbyname])}.
4456 The result of this test is cached in the
4457 @code{ac_cv_lib_@var{library}_@var{function}} variable.
4460 @anchor{AC_SEARCH_LIBS}
4461 @defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}, @
4462 @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
4463 @acindex{SEARCH_LIBS}
4464 @caindex search_@var{function}
4465 Search for a library defining @var{function} if it's not already
4466 available. This equates to calling
4467 @samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])])} first with
4468 no libraries, then for each library listed in @var{search-libs}.
4470 Prepend @option{-l@var{library}} to @code{LIBS} for the first library found
4471 to contain @var{function}, and run @var{action-if-found}. If the
4472 function is not found, run @var{action-if-not-found}.
4474 If linking with @var{library} results in unresolved symbols that would
4475 be resolved by linking with additional libraries, give those libraries
4476 as the @var{other-libraries} argument, separated by spaces:
4477 e.g., @option{-lXt -lX11}. Otherwise, this macro fails to detect
4478 that @var{function} is present, because linking the test program
4479 always fails with unresolved symbols.
4481 The result of this test is cached in the
4482 @code{ac_cv_search_@var{function}} variable as @samp{none required} if
4483 @var{function} is already available, as @samp{no} if no library
4484 containing @var{function} was found, otherwise as the
4485 @option{-l@var{library}} option that needs to be prepended to @code{LIBS}.
4490 @node Library Functions
4491 @section Library Functions
4493 The following macros check for particular C library functions.
4494 If there is no macro specifically defined to check for a function you need,
4495 and you don't need to check for any special properties of
4496 it, then you can use one of the general function-check macros.
4499 * Function Portability:: Pitfalls with usual functions
4500 * Particular Functions:: Special handling to find certain functions
4501 * Generic Functions:: How to find other functions
4504 @node Function Portability
4505 @subsection Portability of C Functions
4506 @cindex Portability of C functions
4507 @cindex C function portability
4509 Most usual functions can either be missing, or be buggy, or be limited
4510 on some architectures. This section tries to make an inventory of these
4511 portability issues. By definition, this list always requires
4512 additions. Please help us keeping it as complete as possible.
4517 @prindex @code{exit}
4518 On ancient hosts, @code{exit} returned @code{int}.
4519 This is because @code{exit} predates @code{void}, and there was a long
4520 tradition of it returning @code{int}.
4522 On current hosts, the problem more likely is that @code{exit} is not
4523 declared, due to C++ problems of some sort or another. For this reason
4524 we suggest that test programs not invoke @code{exit}, but return from
4525 @code{main} instead.
4529 @prindex @code{free}
4530 The C standard says a call @code{free (NULL)} does nothing, but
4531 some old systems don't support this (e.g., NextStep).
4537 @prindex @code{isinf}
4538 @prindex @code{isnan}
4539 The C99 standard says that @code{isinf} and @code{isnan} are
4540 macros. On some systems just macros are available
4541 (e.g., HP-UX and Solaris 10), on
4542 some systems both macros and functions (e.g., glibc 2.3.2), and on some
4543 systems only functions (e.g., IRIX 6 and Solaris 9). In some cases
4544 these functions are declared in nonstandard headers like
4545 @code{<sunmath.h>} and defined in non-default libraries like
4546 @option{-lm} or @option{-lsunmath}.
4548 The C99 @code{isinf} and @code{isnan} macros work correctly with
4549 @code{long double} arguments, but pre-C99 systems that use functions
4550 typically assume @code{double} arguments. On such a system,
4551 @code{isinf} incorrectly returns true for a finite @code{long double}
4552 argument that is outside the range of @code{double}.
4554 The best workaround for these issues is to use gnulib modules
4555 @code{isinf} and @code{isnan} (@pxref{Gnulib}). But a lighter weight
4556 solution involves code like the following.
4563 (sizeof (x) == sizeof (long double) ? isnan_ld (x) \
4564 : sizeof (x) == sizeof (double) ? isnan_d (x) \
4566 static inline int isnan_f (float x) @{ return x != x; @}
4567 static inline int isnan_d (double x) @{ return x != x; @}
4568 static inline int isnan_ld (long double x) @{ return x != x; @}
4573 (sizeof (x) == sizeof (long double) ? isinf_ld (x) \
4574 : sizeof (x) == sizeof (double) ? isinf_d (x) \
4576 static inline int isinf_f (float x)
4577 @{ return !isnan (x) && isnan (x - x); @}
4578 static inline int isinf_d (double x)
4579 @{ return !isnan (x) && isnan (x - x); @}
4580 static inline int isinf_ld (long double x)
4581 @{ return !isnan (x) && isnan (x - x); @}
4585 Use @code{AC_C_INLINE} (@pxref{C Compiler}) so that this code works on
4586 compilers that lack the @code{inline} keyword. Some optimizing
4587 compilers mishandle these definitions, but systems with that bug
4588 typically have many other floating point corner-case compliance problems
4589 anyway, so it's probably not worth worrying about.
4593 @prindex @code{malloc}
4594 The C standard says a call @code{malloc (0)} is implementation
4595 dependent. It can return either @code{NULL} or a new non-null pointer.
4596 The latter is more common (e.g., the GNU C Library) but is by
4597 no means universal. @code{AC_FUNC_MALLOC}
4598 can be used to insist on non-@code{NULL} (@pxref{Particular Functions}).
4602 @prindex @code{putenv}
4603 Posix prefers @code{setenv} to @code{putenv}; among other things,
4604 @code{putenv} is not required of all Posix implementations, but
4607 Posix specifies that @code{putenv} puts the given string directly in
4608 @code{environ}, but some systems make a copy of it instead (e.g.,
4609 glibc 2.0, or BSD). And when a copy is made, @code{unsetenv} might
4610 not free it, causing a memory leak (e.g., FreeBSD 4).
4612 On some systems @code{putenv ("FOO")} removes @samp{FOO} from the
4613 environment, but this is not standard usage and it dumps core
4614 on some systems (e.g., AIX).
4616 On MinGW, a call @code{putenv ("FOO=")} removes @samp{FOO} from the
4617 environment, rather than inserting it with an empty value.
4619 @item @code{realloc}
4621 @prindex @code{realloc}
4622 The C standard says a call @code{realloc (NULL, size)} is equivalent
4623 to @code{malloc (size)}, but some old systems don't support this (e.g.,
4626 @item @code{signal} handler
4628 @prindex @code{signal}
4629 @prindex @code{sigaction}
4630 Normally @code{signal} takes a handler function with a return type of
4631 @code{void}, but some old systems required @code{int} instead. Any
4632 actual @code{int} value returned is not used; this is only a
4633 difference in the function prototype demanded.
4635 All systems we know of in current use return @code{void}. The
4636 @code{int} was to support K&R C, where of course @code{void} is not
4637 available. The obsolete macro @code{AC_TYPE_SIGNAL}
4638 (@pxref{AC_TYPE_SIGNAL}) can be used to establish the correct type in
4641 In most cases, it is more robust to use @code{sigaction} when it is
4642 available, rather than @code{signal}.
4644 @item @code{snprintf}
4645 @c @fuindex snprintf
4646 @prindex @code{snprintf}
4647 @c @fuindex vsnprintf
4648 @prindex @code{vsnprintf}
4649 The C99 standard says that if the output array isn't big enough
4650 and if no other errors occur, @code{snprintf} and @code{vsnprintf}
4651 truncate the output and return the number of bytes that ought to have
4652 been produced. Some older systems return the truncated length (e.g.,
4653 GNU C Library 2.0.x or IRIX 6.5), some a negative value
4654 (e.g., earlier GNU C Library versions), and some the buffer
4655 length without truncation (e.g., 32-bit Solaris 7). Also, some buggy
4656 older systems ignore the length and overrun the buffer (e.g., 64-bit
4659 @item @code{sprintf}
4661 @prindex @code{sprintf}
4662 @c @fuindex vsprintf
4663 @prindex @code{vsprintf}
4664 The C standard says @code{sprintf} and @code{vsprintf} return the
4665 number of bytes written. On some ancient systems (SunOS 4 for
4666 instance) they return the buffer pointer instead, but these no
4667 longer need to be worried about.
4671 @prindex @code{sscanf}
4672 On various old systems, e.g., HP-UX 9, @code{sscanf} requires
4674 input string be writable (though it doesn't actually change it). This
4675 can be a problem when using @command{gcc} since it normally puts
4676 constant strings in read-only memory (@pxref{Incompatibilities,
4677 Incompatibilities of GCC, , gcc, Using and
4678 Porting the GNU Compiler Collection}). Apparently in some cases even
4679 having format strings read-only can be a problem.
4681 @item @code{strerror_r}
4682 @c @fuindex strerror_r
4683 @prindex @code{strerror_r}
4684 Posix specifies that @code{strerror_r} returns an @code{int}, but many
4685 systems (e.g., GNU C Library version 2.2.4) provide a
4686 different version returning a @code{char *}. @code{AC_FUNC_STRERROR_R}
4687 can detect which is in use (@pxref{Particular Functions}).
4689 @item @code{strnlen}
4691 @prindex @code{strnlen}
4692 AIX 4.3 provides a broken version which produces the
4696 strnlen ("foobar", 0) = 0
4697 strnlen ("foobar", 1) = 3
4698 strnlen ("foobar", 2) = 2
4699 strnlen ("foobar", 3) = 1
4700 strnlen ("foobar", 4) = 0
4701 strnlen ("foobar", 5) = 6
4702 strnlen ("foobar", 6) = 6
4703 strnlen ("foobar", 7) = 6
4704 strnlen ("foobar", 8) = 6
4705 strnlen ("foobar", 9) = 6
4708 @item @code{sysconf}
4710 @prindex @code{sysconf}
4711 @code{_SC_PAGESIZE} is standard, but some older systems (e.g., HP-UX
4712 9) have @code{_SC_PAGE_SIZE} instead. This can be tested with
4717 @prindex @code{unlink}
4718 The Posix spec says that @code{unlink} causes the given file to be
4719 removed only after there are no more open file handles for it. Some
4720 non-Posix hosts have trouble with this requirement, though,
4721 and some DOS variants even corrupt the file system.
4723 @item @code{unsetenv}
4724 @c @fuindex unsetenv
4725 @prindex @code{unsetenv}
4726 On MinGW, @code{unsetenv} is not available, but a variable @samp{FOO}
4727 can be removed with a call @code{putenv ("FOO=")}, as described under
4728 @code{putenv} above.
4730 @item @code{va_copy}
4732 @prindex @code{va_copy}
4733 The C99 standard provides @code{va_copy} for copying
4734 @code{va_list} variables. It may be available in older environments
4735 too, though possibly as @code{__va_copy} (e.g., @command{gcc} in strict
4736 pre-C99 mode). These can be tested with @code{#ifdef}. A fallback to
4737 @code{memcpy (&dst, &src, sizeof (va_list))} gives maximum
4740 @item @code{va_list}
4742 @prindex @code{va_list}
4743 @code{va_list} is not necessarily just a pointer. It can be a
4744 @code{struct} (e.g., @command{gcc} on Alpha), which means @code{NULL} is
4745 not portable. Or it can be an array (e.g., @command{gcc} in some
4746 PowerPC configurations), which means as a function parameter it can be
4747 effectively call-by-reference and library routines might modify the
4748 value back in the caller (e.g., @code{vsnprintf} in the GNU C Library
4751 @item Signed @code{>>}
4752 Normally the C @code{>>} right shift of a signed type replicates the
4753 high bit, giving a so-called ``arithmetic'' shift. But care should be
4754 taken since Standard C doesn't require that behavior. On those
4755 few processors without a native arithmetic shift (for instance Cray
4756 vector systems) zero bits may be shifted in, the same as a shift of an
4759 @item Integer @code{/}
4760 C divides signed integers by truncating their quotient toward zero,
4761 yielding the same result as Fortran. However, before C99 the standard
4762 allowed C implementations to take the floor or ceiling of the quotient
4763 in some cases. Hardly any implementations took advantage of this
4764 freedom, though, and it's probably not worth worrying about this issue
4769 @node Particular Functions
4770 @subsection Particular Function Checks
4771 @cindex Function, checking
4773 These macros check for particular C functions---whether they exist, and
4774 in some cases how they respond when given certain arguments.
4776 @anchor{AC_FUNC_ALLOCA}
4777 @defmac AC_FUNC_ALLOCA
4778 @acindex{FUNC_ALLOCA}
4780 @cvindex HAVE_ALLOCA_H
4783 @prindex @code{alloca}
4785 @c @caindex working_alloca_h
4786 Check how to get @code{alloca}. Tries to get a builtin version by
4787 checking for @file{alloca.h} or the predefined C preprocessor macros
4788 @code{__GNUC__} and @code{_AIX}. If this macro finds @file{alloca.h},
4789 it defines @code{HAVE_ALLOCA_H}.
4791 If those attempts fail, it looks for the function in the standard C
4792 library. If any of those methods succeed, it defines
4793 @code{HAVE_ALLOCA}. Otherwise, it sets the output variable
4794 @code{ALLOCA} to @samp{$@{LIBOBJDIR@}alloca.o} and defines
4795 @code{C_ALLOCA} (so programs can periodically call @samp{alloca (0)} to
4796 garbage collect). This variable is separate from @code{LIBOBJS} so
4797 multiple programs can share the value of @code{ALLOCA} without needing
4798 to create an actual library, in case only some of them use the code in
4799 @code{LIBOBJS}. The @samp{$@{LIBOBJDIR@}} prefix serves the same
4800 purpose as in @code{LIBOBJS} (@pxref{AC_LIBOBJ vs LIBOBJS}).
4802 This macro does not try to get @code{alloca} from the System V R3
4803 @file{libPW} or the System V R4 @file{libucb} because those libraries
4804 contain some incompatible functions that cause trouble. Some versions
4805 do not even contain @code{alloca} or contain a buggy version. If you
4806 still want to use their @code{alloca}, use @code{ar} to extract
4807 @file{alloca.o} from them instead of compiling @file{alloca.c}.
4809 Source files that use @code{alloca} should start with a piece of code
4810 like the following, to declare it properly.
4814 #ifdef HAVE_ALLOCA_H
4815 # include <alloca.h>
4816 #elif defined __GNUC__
4817 # define alloca __builtin_alloca
4819 # define alloca __alloca
4820 #elif defined _MSC_VER
4821 # include <malloc.h>
4822 # define alloca _alloca
4824 # include <stddef.h>
4828 void *alloca (size_t);
4834 @defmac AC_FUNC_CHOWN
4835 @acindex{FUNC_CHOWN}
4838 @prindex @code{chown}
4839 @caindex func_chown_works
4840 If the @code{chown} function is available and works (in particular, it
4841 should accept @option{-1} for @code{uid} and @code{gid}), define
4842 @code{HAVE_CHOWN}. The result of this macro is cached in the
4843 @code{ac_cv_func_chown_works} variable.
4846 @anchor{AC_FUNC_CLOSEDIR_VOID}
4847 @defmac AC_FUNC_CLOSEDIR_VOID
4848 @acindex{FUNC_CLOSEDIR_VOID}
4849 @cvindex CLOSEDIR_VOID
4850 @c @fuindex closedir
4851 @prindex @code{closedir}
4852 @caindex func_closedir_void
4853 If the @code{closedir} function does not return a meaningful value,
4854 define @code{CLOSEDIR_VOID}. Otherwise, callers ought to check its
4855 return value for an error indicator.
4857 Currently this test is implemented by running a test program. When
4858 cross compiling the pessimistic assumption that @code{closedir} does not
4859 return a meaningful value is made.
4861 The result of this macro is cached in the @code{ac_cv_func_closedir_void}
4864 This macro is obsolescent, as @code{closedir} returns a meaningful value
4865 on current systems. New programs need not use this macro.
4868 @defmac AC_FUNC_ERROR_AT_LINE
4869 @acindex{FUNC_ERROR_AT_LINE}
4870 @c @fuindex error_at_line
4871 @prindex @code{error_at_line}
4872 @caindex lib_error_at_line
4873 If the @code{error_at_line} function is not found, require an
4874 @code{AC_LIBOBJ} replacement of @samp{error}.
4876 The result of this macro is cached in the @code{ac_cv_lib_error_at_line}
4880 @defmac AC_FUNC_FNMATCH
4881 @acindex{FUNC_FNMATCH}
4883 @prindex @code{fnmatch}
4884 @caindex func_fnmatch_works
4885 If the @code{fnmatch} function conforms to Posix, define
4886 @code{HAVE_FNMATCH}. Detect common implementation bugs, for example,
4887 the bugs in Solaris 2.4.
4889 Unlike the other specific
4890 @code{AC_FUNC} macros, @code{AC_FUNC_FNMATCH} does not replace a
4891 broken/missing @code{fnmatch}. This is for historical reasons.
4892 See @code{AC_REPLACE_FNMATCH} below.
4894 The result of this macro is cached in the @code{ac_cv_func_fnmatch_works}
4897 This macro is obsolescent. New programs should use Gnulib's
4898 @code{fnmatch-posix} module. @xref{Gnulib}.
4901 @defmac AC_FUNC_FNMATCH_GNU
4902 @acindex{FUNC_FNMATCH_GNU}
4904 @prindex @code{fnmatch}
4905 @caindex func_fnmatch_gnu
4906 Behave like @code{AC_REPLACE_FNMATCH} (@emph{replace}) but also test
4907 whether @code{fnmatch} supports GNU extensions. Detect common
4908 implementation bugs, for example, the bugs in the GNU C
4911 The result of this macro is cached in the @code{ac_cv_func_fnmatch_gnu}
4914 This macro is obsolescent. New programs should use Gnulib's
4915 @code{fnmatch-gnu} module. @xref{Gnulib}.
4918 @anchor{AC_FUNC_FORK}
4919 @defmac AC_FUNC_FORK
4921 @cvindex HAVE_VFORK_H
4922 @cvindex HAVE_WORKING_FORK
4923 @cvindex HAVE_WORKING_VFORK
4926 @prindex @code{fork}
4928 @prindex @code{vfork}
4930 @c @caindex func_fork
4931 @c @caindex func_fork_works
4932 This macro checks for the @code{fork} and @code{vfork} functions. If a
4933 working @code{fork} is found, define @code{HAVE_WORKING_FORK}. This macro
4934 checks whether @code{fork} is just a stub by trying to run it.
4936 If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working
4937 @code{vfork} is found, define @code{HAVE_WORKING_VFORK}. Otherwise,
4938 define @code{vfork} to be @code{fork} for backward compatibility with
4939 previous versions of @command{autoconf}. This macro checks for several known
4940 errors in implementations of @code{vfork} and considers the system to not
4941 have a working @code{vfork} if it detects any of them. It is not considered
4942 to be an implementation error if a child's invocation of @code{signal}
4943 modifies the parent's signal handler, since child processes rarely change
4944 their signal handlers.
4946 Since this macro defines @code{vfork} only for backward compatibility with
4947 previous versions of @command{autoconf} you're encouraged to define it
4948 yourself in new code:
4951 #ifndef HAVE_WORKING_VFORK
4958 @defmac AC_FUNC_FSEEKO
4959 @acindex{FUNC_FSEEKO}
4960 @cvindex _LARGEFILE_SOURCE
4961 @cvindex HAVE_FSEEKO
4963 @prindex @code{fseeko}
4965 @prindex @code{ftello}
4966 @c @caindex sys_largefile_source
4967 If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}.
4968 Define @code{_LARGEFILE_SOURCE} if necessary to make the prototype
4969 visible on some systems (e.g., glibc 2.2). Otherwise linkage problems
4970 may occur when compiling with @code{AC_SYS_LARGEFILE} on
4971 largefile-sensitive systems where @code{off_t} does not default to a
4972 64bit entity. All systems with @code{fseeko} also supply @code{ftello}.
4975 @defmac AC_FUNC_GETGROUPS
4976 @acindex{FUNC_GETGROUPS}
4977 @cvindex HAVE_GETGROUPS
4978 @ovindex GETGROUPS_LIBS
4979 @c @fuindex getgroups
4980 @prindex @code{getgroups}
4981 @caindex func_getgroups_works
4982 If the @code{getgroups} function is available and works (unlike on
4983 Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define
4984 @code{HAVE_GETGROUPS}. Set @code{GETGROUPS_LIBS} to any libraries
4985 needed to get that function. This macro runs @code{AC_TYPE_GETGROUPS}.
4988 @anchor{AC_FUNC_GETLOADAVG}
4989 @defmac AC_FUNC_GETLOADAVG
4990 @acindex{FUNC_GETLOADAVG}
4995 @cvindex HAVE_NLIST_H
4996 @cvindex NLIST_NAME_UNION
4997 @cvindex GETLOADAVG_PRIVILEGED
4998 @cvindex NEED_SETGID
4999 @cvindex C_GETLOADAVG
5001 @ovindex NEED_SETGID
5003 @ovindex GETLOADAVG_LIBS
5004 @c @fuindex getloadavg
5005 @prindex @code{getloadavg}
5006 Check how to get the system load averages. To perform its tests
5007 properly, this macro needs the file @file{getloadavg.c}; therefore, be
5008 sure to set the @code{AC_LIBOBJ} replacement directory properly (see
5009 @ref{Generic Functions}, @code{AC_CONFIG_LIBOBJ_DIR}).
5011 If the system has the @code{getloadavg} function, define
5012 @code{HAVE_GETLOADAVG}, and set @code{GETLOADAVG_LIBS} to any libraries
5013 necessary to get that function. Also add @code{GETLOADAVG_LIBS} to
5014 @code{LIBS}. Otherwise, require an @code{AC_LIBOBJ} replacement for
5015 @samp{getloadavg} with source code in @file{@var{dir}/getloadavg.c}, and
5016 possibly define several other C preprocessor macros and output
5021 Define @code{C_GETLOADAVG}.
5024 Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on
5029 If @file{nlist.h} is found, define @code{HAVE_NLIST_H}.
5032 If @samp{struct nlist} has an @samp{n_un.n_name} member, define
5033 @code{HAVE_STRUCT_NLIST_N_UN_N_NAME}. The obsolete symbol
5034 @code{NLIST_NAME_UNION} is still defined, but do not depend upon it.
5037 Programs may need to be installed set-group-ID (or set-user-ID) for
5038 @code{getloadavg} to work. In this case, define
5039 @code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID}
5040 to @samp{true} (and otherwise to @samp{false}), and set
5041 @code{KMEM_GROUP} to the name of the group that should own the installed
5045 The @code{AC_FUNC_GETLOADAVG} macro is obsolescent. New programs should
5046 use Gnulib's @code{getloadavg} module. @xref{Gnulib}.
5049 @anchor{AC_FUNC_GETMNTENT}
5050 @defmac AC_FUNC_GETMNTENT
5051 @acindex{FUNC_GETMNTENT}
5052 @cvindex HAVE_GETMNTENT
5053 @c @fuindex getmntent
5054 @prindex @code{getmntent}
5055 @caindex search_getmntent
5056 Check for @code{getmntent} in the standard C library, and then in the
5057 @file{sun}, @file{seq}, and @file{gen} libraries, for UNICOS,
5058 IRIX 4, PTX, and UnixWare, respectively. Then, if
5059 @code{getmntent} is available, define @code{HAVE_GETMNTENT} and set
5060 @code{ac_cv_func_getmntent} to @code{yes}. Otherwise set
5061 @code{ac_cv_func_getmntent} to @code{no}.
5063 The result of this macro can be overridden by setting the cache variable
5064 @code{ac_cv_search_getmntent}.
5067 @defmac AC_FUNC_GETPGRP
5068 @acindex{FUNC_GETPGRP}
5069 @cvindex GETPGRP_VOID
5072 @prindex @code{getpgid}
5073 @prindex @code{getpgrp}
5074 @caindex func_getpgrp_void
5075 Define @code{GETPGRP_VOID} if it is an error to pass 0 to
5076 @code{getpgrp}; this is the Posix behavior. On older BSD
5077 systems, you must pass 0 to @code{getpgrp}, as it takes an argument and
5078 behaves like Posix's @code{getpgid}.
5088 This macro does not check whether
5089 @code{getpgrp} exists at all; if you need to work in that situation,
5090 first call @code{AC_CHECK_FUNC} for @code{getpgrp}.
5092 The result of this macro is cached in the @code{ac_cv_func_getpgrp_void}
5095 This macro is obsolescent, as current systems have a @code{getpgrp}
5096 whose signature conforms to Posix. New programs need not use this macro.
5099 @defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
5100 @acindex{FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK}
5101 @cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK
5103 @prindex @code{lstat}
5104 @caindex func_lstat_dereferences_slashed_symlink
5105 If @file{link} is a symbolic link, then @code{lstat} should treat
5106 @file{link/} the same as @file{link/.}. However, many older
5107 @code{lstat} implementations incorrectly ignore trailing slashes.
5109 It is safe to assume that if @code{lstat} incorrectly ignores
5110 trailing slashes, then other symbolic-link-aware functions like
5111 @code{unlink} also incorrectly ignore trailing slashes.
5113 If @code{lstat} behaves properly, define
5114 @code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an
5115 @code{AC_LIBOBJ} replacement of @code{lstat}.
5117 The result of this macro is cached in the
5118 @code{ac_cv_func_lstat_dereferences_slashed_symlink} variable.
5121 @defmac AC_FUNC_MALLOC
5122 @acindex{FUNC_MALLOC}
5123 @cvindex HAVE_MALLOC
5126 @prindex @code{malloc}
5127 @caindex func_malloc_0_nonnull
5128 If the @code{malloc} function is compatible with the GNU C
5129 library @code{malloc} (i.e., @samp{malloc (0)} returns a valid
5130 pointer), define @code{HAVE_MALLOC} to 1. Otherwise define
5131 @code{HAVE_MALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
5132 @samp{malloc}, and define @code{malloc} to @code{rpl_malloc} so that the
5133 native @code{malloc} is not used in the main project.
5135 Typically, the replacement file @file{malloc.c} should look like (note
5136 the @samp{#undef malloc}):
5142 #include <sys/types.h>
5146 /* Allocate an N-byte block of memory from the heap.
5147 If N is zero, allocate a 1-byte block. */
5150 rpl_malloc (size_t n)
5158 The result of this macro is cached in the
5159 @code{ac_cv_func_malloc_0_nonnull} variable.
5162 @defmac AC_FUNC_MBRTOWC
5163 @acindex{FUNC_MBRTOWC}
5164 @cvindex HAVE_MBRTOWC
5166 @prindex @code{mbrtowc}
5167 @caindex func_mbrtowc
5168 Define @code{HAVE_MBRTOWC} to 1 if the function @code{mbrtowc} and the
5169 type @code{mbstate_t} are properly declared.
5171 The result of this macro is cached in the @code{ac_cv_func_mbrtowc}
5175 @defmac AC_FUNC_MEMCMP
5176 @acindex{FUNC_MEMCMP}
5179 @prindex @code{memcmp}
5180 @caindex func_memcmp_working
5181 If the @code{memcmp} function is not available, or does not work on
5182 8-bit data (like the one on SunOS 4.1.3), or fails when comparing 16
5183 bytes or more and with at least one buffer not starting on a 4-byte
5184 boundary (such as the one on NeXT x86 OpenStep), require an
5185 @code{AC_LIBOBJ} replacement for @samp{memcmp}.
5187 The result of this macro is cached in the
5188 @code{ac_cv_func_memcmp_working} variable.
5190 This macro is obsolescent, as current systems have a working
5191 @code{memcmp}. New programs need not use this macro.
5194 @defmac AC_FUNC_MKTIME
5195 @acindex{FUNC_MKTIME}
5198 @prindex @code{mktime}
5199 @caindex func_working_mktime
5200 If the @code{mktime} function is not available, or does not work
5201 correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}.
5202 For the purposes of this test, @code{mktime} should conform to the
5203 Posix standard and should be the inverse of
5206 The result of this macro is cached in the
5207 @code{ac_cv_func_working_mktime} variable.
5210 @anchor{AC_FUNC_MMAP}
5211 @defmac AC_FUNC_MMAP
5215 @prindex @code{mmap}
5216 @caindex func_mmap_fixed_mapped
5217 If the @code{mmap} function exists and works correctly, define
5218 @code{HAVE_MMAP}. This checks only private fixed mapping of already-mapped
5221 The result of this macro is cached in the
5222 @code{ac_cv_func_mmap_fixed_mapped} variable.
5225 @defmac AC_FUNC_OBSTACK
5226 @acindex{FUNC_OBSTACK}
5227 @cvindex HAVE_OBSTACK
5229 @caindex func_obstack
5230 If the obstacks are found, define @code{HAVE_OBSTACK}, else require an
5231 @code{AC_LIBOBJ} replacement for @samp{obstack}.
5233 The result of this macro is cached in the @code{ac_cv_func_obstack}
5237 @defmac AC_FUNC_REALLOC
5238 @acindex{FUNC_REALLOC}
5239 @cvindex HAVE_REALLOC
5242 @prindex @code{realloc}
5243 @caindex func_realloc_0_nonnull
5244 If the @code{realloc} function is compatible with the GNU C
5245 library @code{realloc} (i.e., @samp{realloc (NULL, 0)} returns a
5246 valid pointer), define @code{HAVE_REALLOC} to 1. Otherwise define
5247 @code{HAVE_REALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
5248 @samp{realloc}, and define @code{realloc} to @code{rpl_realloc} so that
5249 the native @code{realloc} is not used in the main project. See
5250 @code{AC_FUNC_MALLOC} for details.
5252 The result of this macro is cached in the
5253 @code{ac_cv_func_realloc_0_nonnull} variable.
5256 @defmac AC_FUNC_SELECT_ARGTYPES
5257 @acindex{FUNC_SELECT_ARGTYPES}
5258 @cvindex SELECT_TYPE_ARG1
5259 @cvindex SELECT_TYPE_ARG234
5260 @cvindex SELECT_TYPE_ARG5
5262 @prindex @code{select}
5263 @c @caindex func_select_args
5264 Determines the correct type to be passed for each of the
5265 @code{select} function's arguments, and defines those types
5266 in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and
5267 @code{SELECT_TYPE_ARG5} respectively. @code{SELECT_TYPE_ARG1} defaults
5268 to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *},
5269 and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}.
5271 This macro is obsolescent, as current systems have a @code{select} whose
5272 signature conforms to Posix. New programs need not use this macro.
5275 @defmac AC_FUNC_SETPGRP
5276 @acindex{FUNC_SETPGRP}
5277 @cvindex SETPGRP_VOID
5279 @prindex @code{setpgrp}
5280 @caindex func_setpgrp_void
5281 If @code{setpgrp} takes no argument (the Posix version), define
5282 @code{SETPGRP_VOID}. Otherwise, it is the BSD version, which takes
5283 two process IDs as arguments. This macro does not check whether
5284 @code{setpgrp} exists at all; if you need to work in that situation,
5285 first call @code{AC_CHECK_FUNC} for @code{setpgrp}.
5287 The result of this macro is cached in the @code{ac_cv_func_setpgrp_void}
5290 This macro is obsolescent, as current systems have a @code{setpgrp}
5291 whose signature conforms to Posix. New programs need not use this macro.
5294 @defmac AC_FUNC_STAT
5295 @defmacx AC_FUNC_LSTAT
5297 @acindex{FUNC_LSTAT}
5298 @cvindex HAVE_STAT_EMPTY_STRING_BUG
5299 @cvindex HAVE_LSTAT_EMPTY_STRING_BUG
5301 @prindex @code{stat}
5303 @prindex @code{lstat}
5304 @caindex func_stat_empty_string_bug
5305 @caindex func_lstat_empty_string_bug
5306 Determine whether @code{stat} or @code{lstat} have the bug that it
5307 succeeds when given the zero-length file name as argument. The @code{stat}
5308 and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do
5311 If it does, then define @code{HAVE_STAT_EMPTY_STRING_BUG} (or
5312 @code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ}
5315 The results of these macros are cached in the
5316 @code{ac_cv_func_stat_empty_string_bug} and the
5317 @code{ac_cv_func_lstat_empty_string_bug} variables, respectively.
5319 These macros are obsolescent, as no current systems have the bug.
5320 New programs need not use these macros.
5323 @anchor{AC_FUNC_STRCOLL}
5324 @defmac AC_FUNC_STRCOLL
5325 @acindex{FUNC_STRCOLL}
5326 @cvindex HAVE_STRCOLL
5328 @prindex @code{strcoll}
5329 @caindex func_strcoll_works
5330 If the @code{strcoll} function exists and works correctly, define
5331 @code{HAVE_STRCOLL}. This does a bit more than
5332 @samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect
5333 definitions of @code{strcoll} that should not be used.
5335 The result of this macro is cached in the @code{ac_cv_func_strcoll_works}
5339 @defmac AC_FUNC_STRERROR_R
5340 @acindex{FUNC_STRERROR_R}
5341 @cvindex HAVE_STRERROR_R
5342 @cvindex HAVE_DECL_STRERROR_R
5343 @cvindex STRERROR_R_CHAR_P
5344 @c @fuindex strerror_r
5345 @caindex func_strerror_r_char_p
5346 @prindex @code{strerror_r}
5347 If @code{strerror_r} is available, define @code{HAVE_STRERROR_R}, and if
5348 it is declared, define @code{HAVE_DECL_STRERROR_R}. If it returns a
5349 @code{char *} message, define @code{STRERROR_R_CHAR_P}; otherwise it
5350 returns an @code{int} error number. The Thread-Safe Functions option of
5351 Posix requires @code{strerror_r} to return @code{int}, but
5352 many systems (including, for example, version 2.2.4 of the GNU C
5353 Library) return a @code{char *} value that is not necessarily equal to
5354 the buffer argument.
5356 The result of this macro is cached in the
5357 @code{ac_cv_func_strerror_r_char_p} variable.
5360 @anchor{AC_FUNC_STRFTIME}
5361 @defmac AC_FUNC_STRFTIME
5362 @acindex{FUNC_STRFTIME}
5363 @cvindex HAVE_STRFTIME
5364 @c @fuindex strftime
5365 @prindex @code{strftime}
5366 Check for @code{strftime} in the @file{intl} library, for SCO Unix.
5367 Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}.
5369 This macro is obsolescent, as no current systems require the @file{intl}
5370 library for @code{strftime}. New programs need not use this macro.
5373 @defmac AC_FUNC_STRTOD
5374 @acindex{FUNC_STRTOD}
5377 @prindex @code{strtod}
5378 @caindex func_strtod
5380 If the @code{strtod} function does not exist or doesn't work correctly,
5381 ask for an @code{AC_LIBOBJ} replacement of @samp{strtod}. In this case,
5382 because @file{strtod.c} is likely to need @samp{pow}, set the output
5383 variable @code{POW_LIB} to the extra library needed.
5385 This macro caches its result in the @code{ac_cv_func_strtod} variable
5386 and depends upon the result in the @code{ac_cv_func_pow} variable.
5389 @defmac AC_FUNC_STRTOLD
5390 @acindex{FUNC_STRTOLD}
5391 @cvindex HAVE_STRTOLD
5392 @prindex @code{strtold}
5393 @caindex func_strtold
5394 If the @code{strtold} function exists and conforms to C99, define
5395 @code{HAVE_STRTOLD}.
5397 This macro caches its result in the @code{ac_cv_func_strtold} variable.
5400 @defmac AC_FUNC_STRNLEN
5401 @acindex{FUNC_STRNLEN}
5402 @cvindex HAVE_STRNLEN
5404 @prindex @code{strnlen}
5405 @caindex func_strnlen_working
5406 If the @code{strnlen} function is not available, or is buggy (like the one
5407 from AIX 4.3), require an @code{AC_LIBOBJ} replacement for it.
5409 This macro caches its result in the @code{ac_cv_func_strnlen_working}
5413 @anchor{AC_FUNC_UTIME_NULL}
5414 @defmac AC_FUNC_UTIME_NULL
5415 @acindex{FUNC_UTIME_NULL}
5416 @cvindex HAVE_UTIME_NULL
5418 @prindex @code{utime}
5419 @caindex func_utime_null
5420 If @samp{utime (@var{file}, NULL)} sets @var{file}'s timestamp to
5421 the present, define @code{HAVE_UTIME_NULL}.
5423 This macro caches its result in the @code{ac_cv_func_utime_null}
5426 This macro is obsolescent, as all current systems have a @code{utime}
5427 that behaves this way. New programs need not use this macro.
5430 @anchor{AC_FUNC_VPRINTF}
5431 @defmac AC_FUNC_VPRINTF
5432 @acindex{FUNC_VPRINTF}
5433 @cvindex HAVE_VPRINTF
5434 @cvindex HAVE_DOPRNT
5436 @prindex @code{vprintf}
5437 @c @fuindex vsprintf
5438 @prindex @code{vsprintf}
5439 If @code{vprintf} is found, define @code{HAVE_VPRINTF}. Otherwise, if
5440 @code{_doprnt} is found, define @code{HAVE_DOPRNT}. (If @code{vprintf}
5441 is available, you may assume that @code{vfprintf} and @code{vsprintf}
5442 are also available.)
5444 This macro is obsolescent, as all current systems have @code{vprintf}.
5445 New programs need not use this macro.
5448 @defmac AC_REPLACE_FNMATCH
5449 @acindex{REPLACE_FNMATCH}
5451 @prindex @code{fnmatch}
5452 @hdrindex{fnmatch.h}
5453 @caindex func_fnmatch_works
5454 If the @code{fnmatch} function does not conform to Posix (see
5455 @code{AC_FUNC_FNMATCH}), ask for its @code{AC_LIBOBJ} replacement.
5457 The files @file{fnmatch.c}, @file{fnmatch_loop.c}, and @file{fnmatch_.h}
5458 in the @code{AC_LIBOBJ} replacement directory are assumed to contain a
5459 copy of the source code of GNU @code{fnmatch}. If necessary,
5460 this source code is compiled as an @code{AC_LIBOBJ} replacement, and the
5461 @file{fnmatch_.h} file is linked to @file{fnmatch.h} so that it can be
5462 included in place of the system @code{<fnmatch.h>}.
5464 This macro caches its result in the @code{ac_cv_func_fnmatch_works}
5467 This macro is obsolescent, as it assumes the use of particular source
5468 files. New programs should use Gnulib's @code{fnmatch-posix} module,
5469 which provides this macro along with the source files. @xref{Gnulib}.
5474 @node Generic Functions
5475 @subsection Generic Function Checks
5477 These macros are used to find functions not covered by the ``particular''
5478 test macros. If the functions might be in libraries other than the
5479 default C library, first call @code{AC_CHECK_LIB} for those libraries.
5480 If you need to check the behavior of a function as well as find out
5481 whether it is present, you have to write your own test for
5482 it (@pxref{Writing Tests}).
5484 @anchor{AC_CHECK_FUNC}
5485 @defmac AC_CHECK_FUNC (@var{function}, @ovar{action-if-found}, @
5486 @ovar{action-if-not-found})
5487 @acindex{CHECK_FUNC}
5488 @caindex func_@var{function}
5489 If C function @var{function} is available, run shell commands
5490 @var{action-if-found}, otherwise @var{action-if-not-found}. If you just
5491 want to define a symbol if the function is available, consider using
5492 @code{AC_CHECK_FUNCS} instead. This macro checks for functions with C
5493 linkage even when @code{AC_LANG(C++)} has been called, since C is more
5494 standardized than C++. (@pxref{Language Choice}, for more information
5495 about selecting the language for checks.)
5497 This macro caches its result in the @code{ac_cv_func_@var{function}}
5501 @anchor{AC_CHECK_FUNCS}
5502 @defmac AC_CHECK_FUNCS (@var{function}@dots{}, @ovar{action-if-found}, @
5503 @ovar{action-if-not-found})
5504 @acindex{CHECK_FUNCS}
5505 @cvindex HAVE_@var{function}
5506 For each @var{function} enumerated in the blank-or-newline-separated argument
5507 list, define @code{HAVE_@var{function}} (in all capitals) if it is available.
5508 If @var{action-if-found} is given, it is additional shell code to
5509 execute when one of the functions is found. You can give it a value of
5510 @samp{break} to break out of the loop on the first match. If
5511 @var{action-if-not-found} is given, it is executed when one of the
5512 functions is not found.
5514 Results are cached for each @var{function} as in @code{AC_CHECK_FUNC}.
5517 @defmac AC_CHECK_FUNCS_ONCE (@var{function}@dots{})
5518 @acindex{CHECK_FUNCS_ONCE}
5519 @cvindex HAVE_@var{function}
5520 For each @var{function} enumerated in the blank-or-newline-separated argument
5521 list, define @code{HAVE_@var{function}} (in all capitals) if it is available.
5522 This is a once-only variant of @code{AC_CHECK_FUNCS}. It generates the
5523 checking code at most once, so that @command{configure} is smaller and
5524 faster; but the checks cannot be conditionalized and are always done once,
5525 early during the @command{configure} run.
5530 Autoconf follows a philosophy that was formed over the years by those
5531 who have struggled for portability: isolate the portability issues in
5532 specific files, and then program as if you were in a Posix
5533 environment. Some functions may be missing or unfixable, and your
5534 package must be ready to replace them.
5536 Suitable replacements for many such problem functions are available from
5537 Gnulib (@pxref{Gnulib}).
5539 @defmac AC_LIBOBJ (@var{function})
5542 Specify that @samp{@var{function}.c} must be included in the executables
5543 to replace a missing or broken implementation of @var{function}.
5545 Technically, it adds @samp{@var{function}.$ac_objext} to the output
5546 variable @code{LIBOBJS} if it is not already in, and calls
5547 @code{AC_LIBSOURCE} for @samp{@var{function}.c}. You should not
5548 directly change @code{LIBOBJS}, since this is not traceable.
5551 @defmac AC_LIBSOURCE (@var{file})
5553 Specify that @var{file} might be needed to compile the project. If you
5554 need to know what files might be needed by a @file{configure.ac}, you
5555 should trace @code{AC_LIBSOURCE}. @var{file} must be a literal.
5557 This macro is called automatically from @code{AC_LIBOBJ}, but you must
5558 call it explicitly if you pass a shell variable to @code{AC_LIBOBJ}. In
5559 that case, since shell variables cannot be traced statically, you must
5560 pass to @code{AC_LIBSOURCE} any possible files that the shell variable
5561 might cause @code{AC_LIBOBJ} to need. For example, if you want to pass
5562 a variable @code{$foo_or_bar} to @code{AC_LIBOBJ} that holds either
5563 @code{"foo"} or @code{"bar"}, you should do:
5566 AC_LIBSOURCE([foo.c])
5567 AC_LIBSOURCE([bar.c])
5568 AC_LIBOBJ([$foo_or_bar])
5572 There is usually a way to avoid this, however, and you are encouraged to
5573 simply call @code{AC_LIBOBJ} with literal arguments.
5575 Note that this macro replaces the obsolete @code{AC_LIBOBJ_DECL}, with
5576 slightly different semantics: the old macro took the function name,
5577 e.g., @code{foo}, as its argument rather than the file name.
5580 @defmac AC_LIBSOURCES (@var{files})
5581 @acindex{LIBSOURCES}
5582 Like @code{AC_LIBSOURCE}, but accepts one or more @var{files} in a
5583 comma-separated M4 list. Thus, the above example might be rewritten:
5586 AC_LIBSOURCES([foo.c, bar.c])
5587 AC_LIBOBJ([$foo_or_bar])
5591 @defmac AC_CONFIG_LIBOBJ_DIR (@var{directory})
5592 @acindex{CONFIG_LIBOBJ_DIR}
5593 Specify that @code{AC_LIBOBJ} replacement files are to be found in
5594 @var{directory}, a name relative to the top level of the
5595 source tree. The replacement directory defaults to @file{.}, the top
5596 level directory, and the most typical value is @file{lib}, corresponding
5597 to @samp{AC_CONFIG_LIBOBJ_DIR([lib])}.
5599 @command{configure} might need to know the replacement directory for the
5600 following reasons: (i) some checks use the replacement files, (ii) some
5601 macros bypass broken system headers by installing links to the
5602 replacement headers (iii) when used in conjunction with Automake,
5603 within each makefile, @var{directory} is used as a relative path
5604 from @code{$(top_srcdir)} to each object named in @code{LIBOBJS} and
5605 @code{LTLIBOBJS}, etc.
5610 It is common to merely check for the existence of a function, and ask
5611 for its @code{AC_LIBOBJ} replacement if missing. The following macro is
5612 a convenient shorthand.
5614 @defmac AC_REPLACE_FUNCS (@var{function}@dots{})
5615 @acindex{REPLACE_FUNCS}
5616 @cvindex HAVE_@var{function}
5618 Like @code{AC_CHECK_FUNCS}, but uses @samp{AC_LIBOBJ(@var{function})} as
5619 @var{action-if-not-found}. You can declare your replacement function by
5620 enclosing the prototype in @samp{#ifndef HAVE_@var{function}}. If the
5621 system has the function, it probably declares it in a header file you
5622 should be including, so you shouldn't redeclare it lest your declaration
5627 @section Header Files
5628 @cindex Header, checking
5630 The following macros check for the presence of certain C header files.
5631 If there is no macro specifically defined to check for a header file you need,
5632 and you don't need to check for any special properties of
5633 it, then you can use one of the general header-file check macros.
5636 * Header Portability:: Collected knowledge on common headers
5637 * Particular Headers:: Special handling to find certain headers
5638 * Generic Headers:: How to find other headers
5641 @node Header Portability
5642 @subsection Portability of Headers
5643 @cindex Portability of headers
5644 @cindex Header portability
5646 This section tries to collect knowledge about common headers, and the
5647 problems they cause. By definition, this list always requires
5648 additions. Please help us keeping it as complete as possible.
5652 @item @file{limits.h}
5653 C99 says that @file{limits.h} defines @code{LLONG_MIN},
5654 @code{LLONG_MAX}, and @code{ULLONG_MAX}, but many almost-C99
5655 environments (e.g., default GCC 4.0.2 + glibc 2.4) do not
5658 @item @file{inttypes.h} vs.@: @file{stdint.h}
5659 @hdrindex{inttypes.h}
5661 The C99 standard says that @file{inttypes.h} includes
5662 @file{stdint.h}, so there's no need to include @file{stdint.h}
5663 separately in a standard environment. Some implementations have
5664 @file{inttypes.h} but not @file{stdint.h} (e.g., Solaris 7), but we don't
5665 know of any implementation that has @file{stdint.h} but not
5668 @item @file{linux/irda.h}
5669 @hdrindex{linux/irda.h}
5670 It requires @file{linux/types.h} and @file{sys/socket.h}.
5672 @item @file{linux/random.h}
5673 @hdrindex{linux/random.h}
5674 It requires @file{linux/types.h}.
5676 @item @file{net/if.h}
5678 On Darwin, this file requires that @file{sys/socket.h} be included
5679 beforehand. One should run:
5682 AC_CHECK_HEADERS([sys/socket.h])
5683 AC_CHECK_HEADERS([net/if.h], [], [],
5686 # include <stdlib.h>
5687 # include <stddef.h>
5689 # ifdef HAVE_STDLIB_H
5690 # include <stdlib.h>
5693 #ifdef HAVE_SYS_SOCKET_H
5694 # include <sys/socket.h>
5699 @item @file{netinet/if_ether.h}
5700 @hdrindex{netinet/if_ether.h}
5701 On Darwin, this file requires that @file{stdio.h} and
5702 @file{sys/socket.h} be included beforehand. One should run:
5705 AC_CHECK_HEADERS([sys/socket.h])
5706 AC_CHECK_HEADERS([netinet/if_ether.h], [], [],
5709 # include <stdlib.h>
5710 # include <stddef.h>
5712 # ifdef HAVE_STDLIB_H
5713 # include <stdlib.h>
5716 #ifdef HAVE_SYS_SOCKET_H
5717 # include <sys/socket.h>
5722 @item @file{stdint.h}
5723 See above, item @file{inttypes.h} vs.@: @file{stdint.h}.
5725 @item @file{stdlib.h}
5727 On many systems (e.g., Darwin), @file{stdio.h} is a prerequisite.
5729 @item @file{sys/mount.h}
5730 @hdrindex{sys/mount.h}
5731 On FreeBSD 4.8 on ia32 and using gcc version 2.95.4,
5732 @file{sys/params.h} is a prerequisite.
5734 @item @file{sys/ptem.h}
5735 @hdrindex{sys/ptem.h}
5736 On Solaris 8, @file{sys/stream.h} is a prerequisite.
5738 @item @file{sys/socket.h}
5739 @hdrindex{sys/socket.h}
5740 On Darwin, @file{stdlib.h} is a prerequisite.
5742 @item @file{sys/ucred.h}
5743 @hdrindex{sys/ucred.h}
5744 On Tru64 5.1, @file{sys/types.h} is a prerequisite.
5746 @item @file{X11/extensions/scrnsaver.h}
5747 @hdrindex{X11/extensions/scrnsaver.h}
5748 Using XFree86, this header requires @file{X11/Xlib.h}, which is probably
5749 so required that you might not even consider looking for it.
5752 AC_CHECK_HEADERS([X11/extensions/scrnsaver.h], [], [],
5753 [[#include <X11/Xlib.h>
5759 @node Particular Headers
5760 @subsection Particular Header Checks
5762 These macros check for particular system header files---whether they
5763 exist, and in some cases whether they declare certain symbols.
5765 @defmac AC_HEADER_ASSERT
5766 @acindex{HEADER_ASSERT}
5769 Check whether to enable assertions in the style of @file{assert.h}.
5770 Assertions are enabled by default, but the user can override this by
5771 invoking @command{configure} with the @option{--disable-assert} option.
5774 @anchor{AC_HEADER_DIRENT}
5775 @defmac AC_HEADER_DIRENT
5776 @acindex{HEADER_DIRENT}
5777 @cvindex HAVE_DIRENT_H
5778 @cvindex HAVE_NDIR_H
5779 @cvindex HAVE_SYS_DIR_H
5780 @cvindex HAVE_SYS_NDIR_H
5782 @hdrindex{sys/ndir.h}
5783 @hdrindex{sys/dir.h}
5785 Check for the following header files. For the first one that is
5786 found and defines @samp{DIR}, define the listed C preprocessor macro:
5788 @multitable {@file{sys/ndir.h}} {@code{HAVE_SYS_NDIR_H}}
5789 @item @file{dirent.h} @tab @code{HAVE_DIRENT_H}
5790 @item @file{sys/ndir.h} @tab @code{HAVE_SYS_NDIR_H}
5791 @item @file{sys/dir.h} @tab @code{HAVE_SYS_DIR_H}
5792 @item @file{ndir.h} @tab @code{HAVE_NDIR_H}
5795 The directory-library declarations in your source code should look
5796 something like the following:
5800 #include <sys/types.h>
5801 #ifdef HAVE_DIRENT_H
5802 # include <dirent.h>
5803 # define NAMLEN(dirent) strlen ((dirent)->d_name)
5805 # define dirent direct
5806 # define NAMLEN(dirent) ((dirent)->d_namlen)
5807 # ifdef HAVE_SYS_NDIR_H
5808 # include <sys/ndir.h>
5810 # ifdef HAVE_SYS_DIR_H
5811 # include <sys/dir.h>
5820 Using the above declarations, the program would declare variables to be
5821 of type @code{struct dirent}, not @code{struct direct}, and would access
5822 the length of a directory entry name by passing a pointer to a
5823 @code{struct dirent} to the @code{NAMLEN} macro.
5825 This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries.
5827 This macro is obsolescent, as all current systems with directory
5828 libraries have @code{<dirent.h>}. New programs need not use this macro.
5830 Also see @code{AC_STRUCT_DIRENT_D_INO} and
5831 @code{AC_STRUCT_DIRENT_D_TYPE} (@pxref{Particular Structures}).
5834 @anchor{AC_HEADER_MAJOR}
5835 @defmac AC_HEADER_MAJOR
5836 @acindex{HEADER_MAJOR}
5837 @cvindex MAJOR_IN_MKDEV
5838 @cvindex MAJOR_IN_SYSMACROS
5839 @hdrindex{sys/mkdev.h}
5840 @hdrindex{sys/sysmacros.h}
5841 If @file{sys/types.h} does not define @code{major}, @code{minor}, and
5842 @code{makedev}, but @file{sys/mkdev.h} does, define
5843 @code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define
5844 @code{MAJOR_IN_SYSMACROS}.
5847 @defmac AC_HEADER_RESOLV
5848 @acindex{HEADER_RESOLV}
5849 @cvindex HAVE_RESOLV_H
5851 Checks for header @file{resolv.h}, checking for prerequisites first.
5852 To properly use @file{resolv.h}, your code should contain something like
5856 #ifdef HAVE_SYS_TYPES_H
5857 # include <sys/types.h>
5859 #ifdef HAVE_NETINET_IN_H
5860 # include <netinet/in.h> /* inet_ functions / structs */
5862 #ifdef HAVE_ARPA_NAMESER_H
5863 # include <arpa/nameser.h> /* DNS HEADER struct */
5872 @anchor{AC_HEADER_STAT}
5873 @defmac AC_HEADER_STAT
5874 @acindex{HEADER_STAT}
5875 @cvindex STAT_MACROS_BROKEN
5876 @hdrindex{sys/stat.h}
5877 If the macros @code{S_ISDIR}, @code{S_ISREG}, etc.@: defined in
5878 @file{sys/stat.h} do not work properly (returning false positives),
5879 define @code{STAT_MACROS_BROKEN}. This is the case on Tektronix UTekV,
5880 Amdahl UTS and Motorola System V/88.
5882 This macro is obsolescent, as no current systems have the bug.
5883 New programs need not use this macro.
5886 @defmac AC_HEADER_STDBOOL
5887 @acindex{HEADER_STDBOOL}
5888 @cvindex HAVE_STDBOOL_H
5890 @hdrindex{stdbool.h}
5892 @caindex header_stdbool_h
5893 If @file{stdbool.h} exists and conforms to C99, define
5894 @code{HAVE_STDBOOL_H} to 1; if the type @code{_Bool} is defined, define
5895 @code{HAVE__BOOL} to 1. To fulfill the C99 requirements, your
5896 @file{system.h} could contain the following code:
5899 #ifdef HAVE_STDBOOL_H
5900 # include <stdbool.h>
5906 # define _Bool signed char
5912 # define __bool_true_false_are_defined 1
5916 Alternatively you can use the @samp{stdbool} package of Gnulib
5917 (@pxref{Gnulib}); it packages the above code into a replacement header
5918 and contains a few other bells and whistles.
5920 This macro caches its result in the @code{ac_cv_header_stdbool_h}
5924 @anchor{AC_HEADER_STDC}
5925 @defmac AC_HEADER_STDC
5926 @acindex{HEADER_STDC}
5927 @cvindex STDC_HEADERS
5933 @caindex header_stdc
5934 Define @code{STDC_HEADERS} if the system has C header files
5935 conforming to ANSI C89 (ISO C90).
5936 Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h},
5937 @file{string.h}, and @file{float.h}; if the system has those, it
5938 probably has the rest of the C89 header files. This macro also
5939 checks whether @file{string.h} declares @code{memchr} (and thus
5940 presumably the other @code{mem} functions), whether @file{stdlib.h}
5941 declare @code{free} (and thus presumably @code{malloc} and other related
5942 functions), and whether the @file{ctype.h} macros work on characters
5943 with the high bit set, as the C standard requires.
5945 If you use this macro, your code can refer to @code{STDC_HEADERS} to
5946 determine whether the system has conforming header files (and probably C
5949 This macro caches its result in the @code{ac_cv_header_stdc} variable.
5951 This macro is obsolescent, as current systems have conforming header
5952 files. New programs need not use this macro.
5955 @hdrindex{strings.h}
5956 Nowadays @file{string.h} is part of the C standard and declares functions like
5957 @code{strcpy}, and @file{strings.h} is standardized by Posix and declares
5958 BSD functions like @code{bcopy}; but
5959 historically, string functions were a major sticking point in this area.
5960 If you still want to worry about portability to ancient systems without
5961 standard headers, there is so much variation
5962 that it is probably easier to declare the functions you use than to
5963 figure out exactly what the system header files declare. Some ancient systems
5964 contained a mix of functions from the C standard and from BSD;
5965 some were mostly standard but lacked @samp{memmove}; some defined the
5966 BSD functions as macros in @file{string.h} or
5967 @file{strings.h}; some had only the BSD functions but
5968 @file{string.h}; some declared the memory functions in @file{memory.h},
5969 some in @file{string.h}; etc. It is probably sufficient to check for
5970 one string function and one memory function; if the library had the
5971 standard versions of those then it probably had most of the others.
5972 If you put the following in @file{configure.ac}:
5975 # This example is obsolescent.
5976 # Nowadays you can omit these macro calls.
5978 AC_CHECK_FUNCS([strchr memcpy])
5982 then, in your code, you can use declarations like this:
5986 /* This example is obsolescent.
5987 Nowadays you can just #include <string.h>. */
5989 # include <string.h>
5991 # ifndef HAVE_STRCHR
5992 # define strchr index
5993 # define strrchr rindex
5995 char *strchr (), *strrchr ();
5996 # ifndef HAVE_MEMCPY
5997 # define memcpy(d, s, n) bcopy ((s), (d), (n))
5998 # define memmove(d, s, n) bcopy ((s), (d), (n))
6005 If you use a function like @code{memchr}, @code{memset}, @code{strtok},
6006 or @code{strspn}, which have no BSD equivalent, then macros don't
6007 suffice to port to ancient hosts; you must provide an implementation of
6008 each function. An easy
6009 way to incorporate your implementations only when needed (since the ones
6010 in system C libraries may be hand optimized) is to, taking @code{memchr}
6011 for example, put it in @file{memchr.c} and use
6012 @samp{AC_REPLACE_FUNCS([memchr])}.
6015 @defmac AC_HEADER_SYS_WAIT
6016 @acindex{HEADER_SYS_WAIT}
6017 @cvindex HAVE_SYS_WAIT_H
6018 @hdrindex{sys/wait.h}
6019 @caindex header_sys_wait_h
6020 If @file{sys/wait.h} exists and is compatible with Posix, define
6021 @code{HAVE_SYS_WAIT_H}. Incompatibility can occur if @file{sys/wait.h}
6022 does not exist, or if it uses the old BSD @code{union wait} instead
6023 of @code{int} to store a status value. If @file{sys/wait.h} is not
6024 Posix compatible, then instead of including it, define the
6025 Posix macros with their usual interpretations. Here is an
6030 #include <sys/types.h>
6031 #ifdef HAVE_SYS_WAIT_H
6032 # include <sys/wait.h>
6035 # define WEXITSTATUS(stat_val) ((unsigned int) (stat_val) >> 8)
6038 # define WIFEXITED(stat_val) (((stat_val) & 255) == 0)
6044 This macro caches its result in the @code{ac_cv_header_sys_wait_h}
6047 This macro is obsolescent, as current systems are compatible with Posix.
6048 New programs need not use this macro.
6051 @cvindex _POSIX_VERSION
6053 @code{_POSIX_VERSION} is defined when @file{unistd.h} is included on
6054 Posix systems. If there is no @file{unistd.h}, it is definitely
6055 not a Posix system. However, some non-Posix systems do
6056 have @file{unistd.h}.
6058 The way to check whether the system supports Posix is:
6062 #ifdef HAVE_UNISTD_H
6063 # include <sys/types.h>
6064 # include <unistd.h>
6067 #ifdef _POSIX_VERSION
6068 /* Code for Posix systems. */
6073 @anchor{AC_HEADER_TIME}
6074 @defmac AC_HEADER_TIME
6075 @acindex{HEADER_TIME}
6076 @cvindex TIME_WITH_SYS_TIME
6078 @hdrindex{sys/time.h}
6079 @caindex header_time
6080 If a program may include both @file{time.h} and @file{sys/time.h},
6081 define @code{TIME_WITH_SYS_TIME}. On some ancient systems,
6082 @file{sys/time.h} included @file{time.h}, but @file{time.h} was not
6083 protected against multiple inclusion, so programs could not explicitly
6084 include both files. This macro is useful in programs that use, for
6085 example, @code{struct timeval} as well as
6086 @code{struct tm}. It is best used in conjunction with
6087 @code{HAVE_SYS_TIME_H}, which can be checked for using
6088 @code{AC_CHECK_HEADERS([sys/time.h])}.
6092 #ifdef TIME_WITH_SYS_TIME
6093 # include <sys/time.h>
6096 # ifdef HAVE_SYS_TIME_H
6097 # include <sys/time.h>
6106 This macro caches its result in the @code{ac_cv_header_time} variable.
6108 This macro is obsolescent, as current systems can include both files
6109 when they exist. New programs need not use this macro.
6113 @defmac AC_HEADER_TIOCGWINSZ
6114 @acindex{HEADER_TIOCGWINSZ}
6115 @cvindex GWINSZ_IN_SYS_IOCTL
6116 @hdrindex{sys/ioctl.h}
6117 @hdrindex{termios.h}
6118 @c FIXME: I need clarifications from Jim.
6119 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
6120 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
6121 found in @file{<termios.h>}.
6127 #ifdef HAVE_TERMIOS_H
6128 # include <termios.h>
6131 #ifdef GWINSZ_IN_SYS_IOCTL
6132 # include <sys/ioctl.h>
6138 @node Generic Headers
6139 @subsection Generic Header Checks
6141 These macros are used to find system header files not covered by the
6142 ``particular'' test macros. If you need to check the contents of a header
6143 as well as find out whether it is present, you have to write your own
6144 test for it (@pxref{Writing Tests}).
6146 @anchor{AC_CHECK_HEADER}
6147 @defmac AC_CHECK_HEADER (@var{header-file}, @ovar{action-if-found}, @
6148 @ovar{action-if-not-found}, @ovar{includes})
6149 @acindex{CHECK_HEADER}
6150 @caindex header_@var{header-file}
6151 If the system header file @var{header-file} is compilable, execute shell
6152 commands @var{action-if-found}, otherwise execute
6153 @var{action-if-not-found}. If you just want to define a symbol if the
6154 header file is available, consider using @code{AC_CHECK_HEADERS}
6157 @var{includes} is decoded to determine the appropriate include
6158 directives. If omitted or empty, @file{configure} will check for both header
6159 existence (with the preprocessor) and usability (with the compiler),
6160 using @code{AC_INCLUDES_DEFAULT} for the compile test. If
6161 there is a discrepancy between the results, a warning is issued to the
6162 user, and the compiler results are favored (@pxref{Present But
6163 Cannot Be Compiled}). In general, favoring the compiler results means
6164 that a header will be treated as not found even though the file exists,
6165 because you did not provide enough prerequisites.
6167 Providing a non-empty @var{includes} argument allows the code to provide
6168 any prerequisites prior to including the header under test; it is common
6169 to use the argument @code{AC_INCLUDES_DEFAULT} (@pxref{Default
6170 Includes}). With an explicit fourth argument, no preprocessor test is
6171 needed. As a special case, an @var{includes} of exactly @samp{-}
6172 triggers the older preprocessor check, which merely determines existence
6173 of the file in the preprocessor search path; this should only be used as
6174 a last resort (it is safer to determine the actual prerequisites and
6175 perform a compiler check, or else use @code{AC_PREPROC_IFELSE} to make
6176 it obvious that only a preprocessor check is desired).
6178 This macro caches its result in the @code{ac_cv_header_@var{header-file}}
6179 variable, with characters not suitable for a variable name mapped to
6183 @anchor{AC_CHECK_HEADERS}
6184 @defmac AC_CHECK_HEADERS (@var{header-file}@dots{}, @
6185 @ovar{action-if-found}, @ovar{action-if-not-found}, @
6187 @acindex{CHECK_HEADERS}
6188 @cvindex HAVE_@var{header}
6189 @caindex header_@var{header-file}
6190 For each given system header file @var{header-file} in the
6191 blank-separated argument list that exists, define
6192 @code{HAVE_@var{header-file}} (in all capitals). If @var{action-if-found}
6193 is given, it is additional shell code to execute when one of the header
6194 files is found. You can give it a value of @samp{break} to break out of
6195 the loop on the first match. If @var{action-if-not-found} is given, it
6196 is executed when one of the header files is not found.
6198 @var{includes} is interpreted as in @code{AC_CHECK_HEADER}, in order to
6199 choose the set of preprocessor directives supplied before the header
6202 This macro caches its result in the @code{ac_cv_header_@var{header-file}}
6203 variable, with characters not suitable for a variable name mapped to
6207 Previous versions of Autoconf merely checked whether the header was
6208 accepted by the preprocessor. This was changed because the old test was
6209 inappropriate for typical uses. Headers are typically used to compile,
6210 not merely to preprocess, and the old behavior sometimes accepted
6211 headers that clashed at compile-time (@pxref{Present But Cannot Be
6212 Compiled}). If you need to check whether a header is preprocessable,
6213 you can use @code{AC_PREPROC_IFELSE} (@pxref{Running the Preprocessor}).
6215 Actually requiring a header to compile improves the robustness of the
6216 test, but it also requires
6217 that you make sure that headers that must be included before the
6218 @var{header-file} be part of the @var{includes}, (@pxref{Default
6219 Includes}). If looking for @file{bar.h}, which requires that
6220 @file{foo.h} be included before if it exists, we suggest the following
6224 AC_CHECK_HEADERS([foo.h])
6225 AC_CHECK_HEADERS([bar.h], [], [],
6232 The following variant generates smaller, faster @command{configure}
6233 files if you do not need the full power of @code{AC_CHECK_HEADERS}.
6235 @defmac AC_CHECK_HEADERS_ONCE (@var{header-file}@dots{})
6236 @acindex{CHECK_HEADERS_ONCE}
6237 @cvindex HAVE_@var{header}
6238 For each given system header file @var{header-file} in the
6239 blank-separated argument list that exists, define
6240 @code{HAVE_@var{header-file}} (in all capitals).
6241 This is a once-only variant of @code{AC_CHECK_HEADERS}. It generates the
6242 checking code at most once, so that @command{configure} is smaller and
6243 faster; but the checks cannot be conditionalized and are always done once,
6244 early during the @command{configure} run. Thus, this macro is only safe
6245 for checking headers that do not have prerequisites beyond what
6246 @code{AC_INCLUDES_DEFAULT} provides.
6250 @section Declarations
6251 @cindex Declaration, checking
6253 The following macros check for the declaration of variables and
6254 functions. If there is no macro specifically defined to check for a
6255 symbol you need, then you can use the general macros (@pxref{Generic
6256 Declarations}) or, for more complex tests, you may use
6257 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
6260 * Particular Declarations:: Macros to check for certain declarations
6261 * Generic Declarations:: How to find other declarations
6264 @node Particular Declarations
6265 @subsection Particular Declaration Checks
6267 There are no specific macros for declarations.
6269 @node Generic Declarations
6270 @subsection Generic Declaration Checks
6272 These macros are used to find declarations not covered by the ``particular''
6275 @defmac AC_CHECK_DECL (@var{symbol}, @ovar{action-if-found}, @
6276 @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
6277 @acindex{CHECK_DECL}
6278 @caindex have_decl_@var{symbol}
6279 If @var{symbol} (a function, variable, or constant) is not declared in
6280 @var{includes} and a declaration is needed, run the shell commands
6281 @var{action-if-not-found}, otherwise @var{action-if-found}.
6282 @var{includes} is a series of include directives, defaulting to
6283 @code{AC_INCLUDES_DEFAULT} (@pxref{Default Includes}), which are used
6284 prior to the declaration under test.
6286 This macro actually tests whether @var{symbol} is defined as a macro or
6287 can be used as an r-value, not whether it is really declared, because it
6288 is much safer to avoid introducing extra declarations when they are not
6289 needed. In order to facilitate use of C++ and overloaded function
6290 declarations, it is possible to specify function argument types in
6291 parentheses for types which can be zero-initialized:
6294 AC_CHECK_DECL([basename(char *)])
6297 This macro caches its result in the @code{ac_cv_have_decl_@var{symbol}}
6298 variable, with characters not suitable for a variable name mapped to
6302 @anchor{AC_CHECK_DECLS}
6303 @defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @
6304 @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
6305 @acindex{CHECK_DECLS}
6306 @cvindex HAVE_DECL_@var{symbol}
6307 @caindex have_decl_@var{symbol}
6308 For each of the @var{symbols} (@emph{comma}-separated list with optional
6309 function argument types for C++ overloads), define
6310 @code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
6311 @var{symbol} is declared, otherwise to @samp{0}. If
6312 @var{action-if-not-found} is given, it is additional shell code to
6313 execute when one of the function declarations is needed, otherwise
6314 @var{action-if-found} is executed.
6316 @var{includes} is a series of include directives, defaulting to
6317 @code{AC_INCLUDES_DEFAULT} (@pxref{Default Includes}), which are used
6318 prior to the declarations under test.
6320 This macro uses an M4 list as first argument:
6322 AC_CHECK_DECLS([strdup])
6323 AC_CHECK_DECLS([strlen])
6324 AC_CHECK_DECLS([malloc, realloc, calloc, free])
6325 AC_CHECK_DECLS([j0], [], [], [[#include <math.h>]])
6326 AC_CHECK_DECLS([[basename(char *)], [dirname(char *)]])
6329 Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not
6330 declared, @code{HAVE_DECL_@var{symbol}} is defined to @samp{0} instead
6331 of leaving @code{HAVE_DECL_@var{symbol}} undeclared. When you are
6332 @emph{sure} that the check was performed, use
6333 @code{HAVE_DECL_@var{symbol}} in @code{#if}:
6336 #if !HAVE_DECL_SYMBOL
6337 extern char *symbol;
6342 If the test may have not been performed, however, because it is safer
6343 @emph{not} to declare a symbol than to use a declaration that conflicts
6344 with the system's one, you should use:
6347 #if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC
6348 void *malloc (size_t *s);
6353 You fall into the second category only in extreme situations: either
6354 your files may be used without being configured, or they are used during
6355 the configuration. In most cases the traditional approach is enough.
6357 This macro caches its results in @code{ac_cv_have_decl_@var{symbol}}
6358 variables, with characters not suitable for a variable name mapped to
6362 @defmac AC_CHECK_DECLS_ONCE (@var{symbols})
6363 @acindex{CHECK_DECLS_ONCE}
6364 @cvindex HAVE_DECL_@var{symbol}
6365 For each of the @var{symbols} (@emph{comma}-separated list), define
6366 @code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
6367 @var{symbol} is declared in the default include files, otherwise to
6368 @samp{0}. This is a once-only variant of @code{AC_CHECK_DECLS}. It
6369 generates the checking code at most once, so that @command{configure} is
6370 smaller and faster; but the checks cannot be conditionalized and are
6371 always done once, early during the @command{configure} run.
6377 @cindex Structure, checking
6379 The following macros check for the presence of certain members in C
6380 structures. If there is no macro specifically defined to check for a
6381 member you need, then you can use the general structure-member macros
6382 (@pxref{Generic Structures}) or, for more complex tests, you may use
6383 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
6386 * Particular Structures:: Macros to check for certain structure members
6387 * Generic Structures:: How to find other structure members
6390 @node Particular Structures
6391 @subsection Particular Structure Checks
6393 The following macros check for certain structures or structure members.
6395 @defmac AC_STRUCT_DIRENT_D_INO
6396 @acindex{STRUCT_DIRENT_D_INO}
6397 @cvindex HAVE_STRUCT_DIRENT_D_INO
6398 @c @caindex header_dirent_dirent_h
6399 @c @caindex member_struct_dirent_d_ino
6400 Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
6401 Headers}). Then, if @code{struct dirent} contains a @code{d_ino}
6402 member, define @code{HAVE_STRUCT_DIRENT_D_INO}.
6404 @code{HAVE_STRUCT_DIRENT_D_INO} indicates only the presence of
6405 @code{d_ino}, not whether its contents are always reliable.
6406 Traditionally, a zero @code{d_ino} indicated a deleted directory entry,
6407 though current systems hide this detail from the user and never return
6408 zero @code{d_ino} values.
6409 Many current systems report an incorrect @code{d_ino} for a directory
6410 entry that is a mount point.
6413 @defmac AC_STRUCT_DIRENT_D_TYPE
6414 @acindex{STRUCT_DIRENT_D_TYPE}
6415 @cvindex HAVE_STRUCT_DIRENT_D_TYPE
6416 @c @caindex header_dirent_dirent_h
6417 @c @caindex member_struct_dirent_d_type
6418 Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
6419 Headers}). Then, if @code{struct dirent} contains a @code{d_type}
6420 member, define @code{HAVE_STRUCT_DIRENT_D_TYPE}.
6423 @anchor{AC_STRUCT_ST_BLOCKS}
6424 @defmac AC_STRUCT_ST_BLOCKS
6425 @acindex{STRUCT_ST_BLOCKS}
6426 @cvindex HAVE_STRUCT_STAT_ST_BLOCKS
6427 @cvindex HAVE_ST_BLOCKS
6429 @caindex member_struct_stat_st_blocks
6430 If @code{struct stat} contains an @code{st_blocks} member, define
6431 @code{HAVE_STRUCT_STAT_ST_BLOCKS}. Otherwise, require an
6432 @code{AC_LIBOBJ} replacement of @samp{fileblocks}. The former name,
6433 @code{HAVE_ST_BLOCKS} is to be avoided, as its support will cease in the
6436 This macro caches its result in the @code{ac_cv_member_struct_stat_st_blocks}
6440 @defmac AC_STRUCT_TM
6442 @cvindex TM_IN_SYS_TIME
6444 @hdrindex{sys/time.h}
6445 If @file{time.h} does not define @code{struct tm}, define
6446 @code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h}
6447 had better define @code{struct tm}.
6449 This macro is obsolescent, as @file{time.h} defines @code{struct tm} in
6450 current systems. New programs need not use this macro.
6453 @anchor{AC_STRUCT_TIMEZONE}
6454 @defmac AC_STRUCT_TIMEZONE
6455 @acindex{STRUCT_TIMEZONE}
6456 @cvindex HAVE_DECL_TZNAME
6457 @cvindex HAVE_STRUCT_TM_TM_ZONE
6458 @cvindex HAVE_TM_ZONE
6459 @cvindex HAVE_TZNAME
6460 @c @caindex member_struct_tm_tm_zone
6461 @c @caindex struct_tm
6462 Figure out how to get the current timezone. If @code{struct tm} has a
6463 @code{tm_zone} member, define @code{HAVE_STRUCT_TM_TM_ZONE} (and the
6464 obsoleted @code{HAVE_TM_ZONE}). Otherwise, if the external array
6465 @code{tzname} is found, define @code{HAVE_TZNAME}; if it is declared,
6466 define @code{HAVE_DECL_TZNAME}.
6469 @node Generic Structures
6470 @subsection Generic Structure Checks
6472 These macros are used to find structure members not covered by the
6473 ``particular'' test macros.
6475 @defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @
6476 @ovar{action-if-found}, @ovar{action-if-not-found}, @
6477 @dvar{includes, AC_INCLUDES_DEFAULT})
6478 @acindex{CHECK_MEMBER}
6479 @caindex member_@var{aggregate}_@var{member}
6480 Check whether @var{member} is a member of the aggregate @var{aggregate}.
6481 If no @var{includes} are specified, the default includes are used
6482 (@pxref{Default Includes}).
6485 AC_CHECK_MEMBER([struct passwd.pw_gecos], [],
6486 [AC_MSG_ERROR([we need `passwd.pw_gecos'])],
6487 [[#include <pwd.h>]])
6490 You can use this macro for submembers:
6493 AC_CHECK_MEMBER(struct top.middle.bot)
6496 This macro caches its result in the
6497 @code{av_cv_member_@var{aggregate}_@var{member}} variable, with
6498 characters not suitable for a variable name mapped to underscores.
6501 @anchor{AC_CHECK_MEMBERS}
6502 @defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @
6503 @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
6504 @acindex{CHECK_MEMBERS}
6505 @cvindex HAVE_@var{aggregate}_@var{member}
6506 Check for the existence of each @samp{@var{aggregate}.@var{member}} of
6507 @var{members} using the previous macro. When @var{member} belongs to
6508 @var{aggregate}, define @code{HAVE_@var{aggregate}_@var{member}} (in all
6509 capitals, with spaces and dots replaced by underscores). If
6510 @var{action-if-found} is given, it is executed for each of the found
6511 members. If @var{action-if-not-found} is given, it is executed for each
6512 of the members that could not be found.
6514 @var{includes} is a series of include directives, defaulting to
6515 @code{AC_INCLUDES_DEFAULT} (@pxref{Default Includes}), which are used
6516 prior to the members under test.
6518 This macro uses M4 lists:
6520 AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])
6530 The following macros check for C types, either builtin or typedefs. If
6531 there is no macro specifically defined to check for a type you need, and
6532 you don't need to check for any special properties of it, then you can
6533 use a general type-check macro.
6536 * Particular Types:: Special handling to find certain types
6537 * Generic Types:: How to find other types
6540 @node Particular Types
6541 @subsection Particular Type Checks
6543 @hdrindex{sys/types.h}
6546 @hdrindex{inttypes.h}
6547 These macros check for particular C types in @file{sys/types.h},
6548 @file{stdlib.h}, @file{stdint.h}, @file{inttypes.h} and others, if they
6551 The Gnulib @code{stdint} module is an alternate way to define many of
6552 these symbols; it is useful if you prefer your code to assume a
6553 C99-or-better environment. @xref{Gnulib}.
6555 @anchor{AC_TYPE_GETGROUPS}
6556 @defmac AC_TYPE_GETGROUPS
6557 @acindex{TYPE_GETGROUPS}
6558 @cvindex GETGROUPS_T
6559 @caindex type_getgroups
6560 Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int}
6561 is the base type of the array argument to @code{getgroups}.
6563 This macro caches the base type in the @code{ac_cv_type_getgroups}
6567 @defmac AC_TYPE_INT8_T
6568 @acindex{TYPE_INT8_T}
6569 @cvindex HAVE_INT8_T
6572 If @file{stdint.h} or @file{inttypes.h} does not define the type
6573 @code{int8_t}, define @code{int8_t} to a signed
6574 integer type that is exactly 8 bits wide and that uses two's complement
6575 representation, if such a type exists.
6576 If you are worried about porting to hosts that lack such a type, you can
6577 use the results of this macro in C89-or-later code as follows:
6581 # include <stdint.h>
6583 #if defined INT8_MAX || defined int8_t
6584 @emph{code using int8_t}
6586 @emph{complicated alternative using >8-bit 'signed char'}
6590 This macro caches the type in the @code{ac_cv_c_int8_t} variable.
6593 @defmac AC_TYPE_INT16_T
6594 @acindex{TYPE_INT16_T}
6595 @cvindex HAVE_INT16_T
6598 This is like @code{AC_TYPE_INT8_T}, except for 16-bit integers.
6601 @defmac AC_TYPE_INT32_T
6602 @acindex{TYPE_INT32_T}
6603 @cvindex HAVE_INT32_T
6606 This is like @code{AC_TYPE_INT8_T}, except for 32-bit integers.
6609 @defmac AC_TYPE_INT64_T
6610 @acindex{TYPE_INT64_T}
6611 @cvindex HAVE_INT64_T
6614 This is like @code{AC_TYPE_INT8_T}, except for 64-bit integers.
6617 @defmac AC_TYPE_INTMAX_T
6618 @acindex{TYPE_INTMAX_T}
6619 @cvindex HAVE_INTMAX_T
6621 @c @caindex type_intmax_t
6622 If @file{stdint.h} or @file{inttypes.h} defines the type @code{intmax_t},
6623 define @code{HAVE_INTMAX_T}. Otherwise, define @code{intmax_t} to the
6624 widest signed integer type.
6627 @defmac AC_TYPE_INTPTR_T
6628 @acindex{TYPE_INTPTR_T}
6629 @cvindex HAVE_INTPTR_T
6631 @c @caindex type_intptr_t
6632 If @file{stdint.h} or @file{inttypes.h} defines the type @code{intptr_t},
6633 define @code{HAVE_INTPTR_T}. Otherwise, define @code{intptr_t} to a
6634 signed integer type wide enough to hold a pointer, if such a type
6638 @defmac AC_TYPE_LONG_DOUBLE
6639 @acindex{TYPE_LONG_DOUBLE}
6640 @cvindex HAVE_LONG_DOUBLE
6641 @caindex type_long_double
6642 If the C compiler supports a working @code{long double} type, define
6643 @code{HAVE_LONG_DOUBLE}. The @code{long double} type might have the
6644 same range and precision as @code{double}.
6646 This macro caches its result in the @code{ac_cv_type_long_double}
6649 This macro is obsolescent, as current C compilers support @code{long
6650 double}. New programs need not use this macro.
6653 @defmac AC_TYPE_LONG_DOUBLE_WIDER
6654 @acindex{TYPE_LONG_DOUBLE_WIDER}
6655 @cvindex HAVE_LONG_DOUBLE_WIDER
6656 @caindex type_long_double_wider
6657 If the C compiler supports a working @code{long double} type with more
6658 range or precision than the @code{double} type, define
6659 @code{HAVE_LONG_DOUBLE_WIDER}.
6661 This macro caches its result in the @code{ac_cv_type_long_double_wider}
6665 @defmac AC_TYPE_LONG_LONG_INT
6666 @acindex{TYPE_LONG_LONG_INT}
6667 @cvindex HAVE_LONG_LONG_INT
6668 @caindex type_long_long_int
6669 If the C compiler supports a working @code{long long int} type, define
6670 @code{HAVE_LONG_LONG_INT}. However, this test does not test
6671 @code{long long int} values in preprocessor @code{#if} expressions,
6672 because too many compilers mishandle such expressions.
6673 @xref{Preprocessor Arithmetic}.
6675 This macro caches its result in the @code{ac_cv_type_long_long_int}
6679 @defmac AC_TYPE_MBSTATE_T
6680 @acindex{TYPE_MBSTATE_T}
6683 @caindex type_mbstate_t
6684 Define @code{HAVE_MBSTATE_T} if @code{<wchar.h>} declares the
6685 @code{mbstate_t} type. Also, define @code{mbstate_t} to be a type if
6686 @code{<wchar.h>} does not declare it.
6688 This macro caches its result in the @code{ac_cv_type_mbstate_t}
6692 @anchor{AC_TYPE_MODE_T}
6693 @defmac AC_TYPE_MODE_T
6694 @acindex{TYPE_MODE_T}
6696 @caindex type_mode_t
6697 Define @code{mode_t} to a suitable type, if standard headers do not
6700 This macro caches its result in the @code{ac_cv_type_mode_t} variable.
6703 @anchor{AC_TYPE_OFF_T}
6704 @defmac AC_TYPE_OFF_T
6705 @acindex{TYPE_OFF_T}
6708 Define @code{off_t} to a suitable type, if standard headers do not
6711 This macro caches its result in the @code{ac_cv_type_off_t} variable.
6714 @anchor{AC_TYPE_PID_T}
6715 @defmac AC_TYPE_PID_T
6716 @acindex{TYPE_PID_T}
6719 Define @code{pid_t} to a suitable type, if standard headers do not
6722 This macro caches its result in the @code{ac_cv_type_pid_t} variable.
6725 @anchor{AC_TYPE_SIZE_T}
6726 @defmac AC_TYPE_SIZE_T
6727 @acindex{TYPE_SIZE_T}
6729 @caindex type_size_t
6730 Define @code{size_t} to a suitable type, if standard headers do not
6733 This macro caches its result in the @code{ac_cv_type_size_t} variable.
6736 @defmac AC_TYPE_SSIZE_T
6737 @acindex{TYPE_SSIZE_T}
6739 @caindex type_ssize_t
6740 Define @code{ssize_t} to a suitable type, if standard headers do not
6743 This macro caches its result in the @code{ac_cv_type_ssize_t} variable.
6746 @anchor{AC_TYPE_UID_T}
6747 @defmac AC_TYPE_UID_T
6748 @acindex{TYPE_UID_T}
6752 Define @code{uid_t} and @code{gid_t} to suitable types, if standard
6753 headers do not define them.
6755 This macro caches its result in the @code{ac_cv_type_uid_t} variable.
6758 @defmac AC_TYPE_UINT8_T
6759 @acindex{TYPE_UINT8_T}
6760 @cvindex HAVE_UINT8_T
6763 If @file{stdint.h} or @file{inttypes.h} does not define the type
6764 @code{uint8_t}, define @code{uint8_t} to an
6765 unsigned integer type that is exactly 8 bits wide, if such a type
6767 This is like @code{AC_TYPE_INT8_T}, except for unsigned integers.
6770 @defmac AC_TYPE_UINT16_T
6771 @acindex{TYPE_UINT16_T}
6772 @cvindex HAVE_UINT16_T
6775 This is like @code{AC_TYPE_UINT8_T}, except for 16-bit integers.
6778 @defmac AC_TYPE_UINT32_T
6779 @acindex{TYPE_UINT32_T}
6780 @cvindex HAVE_UINT32_T
6783 This is like @code{AC_TYPE_UINT8_T}, except for 32-bit integers.
6786 @defmac AC_TYPE_UINT64_T
6787 @acindex{TYPE_UINT64_T}
6788 @cvindex HAVE_UINT64_T
6791 This is like @code{AC_TYPE_UINT8_T}, except for 64-bit integers.
6794 @defmac AC_TYPE_UINTMAX_T
6795 @acindex{TYPE_UINTMAX_T}
6796 @cvindex HAVE_UINTMAX_T
6798 @c @caindex type_uintmax_t
6799 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintmax_t},
6800 define @code{HAVE_UINTMAX_T}. Otherwise, define @code{uintmax_t} to the
6801 widest unsigned integer type.
6804 @defmac AC_TYPE_UINTPTR_T
6805 @acindex{TYPE_UINTPTR_T}
6806 @cvindex HAVE_UINTPTR_T
6808 @c @caindex type_uintptr_t
6809 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintptr_t},
6810 define @code{HAVE_UINTPTR_T}. Otherwise, define @code{uintptr_t} to an
6811 unsigned integer type wide enough to hold a pointer, if such a type
6815 @defmac AC_TYPE_UNSIGNED_LONG_LONG_INT
6816 @acindex{TYPE_UNSIGNED_LONG_LONG_INT}
6817 @cvindex HAVE_UNSIGNED_LONG_LONG_INT
6818 @caindex type_unsigned_long_long_int
6819 If the C compiler supports a working @code{unsigned long long int} type,
6820 define @code{HAVE_UNSIGNED_LONG_LONG_INT}. However, this test does not test
6821 @code{unsigned long long int} values in preprocessor @code{#if} expressions,
6822 because too many compilers mishandle such expressions.
6823 @xref{Preprocessor Arithmetic}.
6825 This macro caches its result in the @code{ac_cv_type_unsigned_long_long_int}
6830 @subsection Generic Type Checks
6832 These macros are used to check for types not covered by the ``particular''
6835 @defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @
6836 @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
6837 @acindex{CHECK_TYPE}
6838 @caindex type_@var{type}
6839 Check whether @var{type} is defined. It may be a compiler builtin type
6840 or defined by the @var{includes}. @var{includes} is a series of include
6841 directives, defaulting to @code{AC_INCLUDES_DEFAULT} (@pxref{Default
6842 Includes}), which are used prior to the type under test.
6844 In C, @var{type} must be a type-name, so that the expression @samp{sizeof
6845 (@var{type})} is valid (but @samp{sizeof ((@var{type}))} is not). The
6846 same test is applied when compiling for C++, which means that in C++
6847 @var{type} should be a type-id and should not be an anonymous
6848 @samp{struct} or @samp{union}.
6850 This macro caches its result in the @code{ac_cv_type_@var{type}}
6851 variable, with @samp{*} mapped to @samp{p} and other characters not
6852 suitable for a variable name mapped to underscores.
6856 @defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @
6857 @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
6858 @acindex{CHECK_TYPES}
6859 @cvindex HAVE_@var{type}
6860 For each @var{type} of the @var{types} that is defined, define
6861 @code{HAVE_@var{type}} (in all capitals). Each @var{type} must follow
6862 the rules of @code{AC_CHECK_TYPE}. If no @var{includes} are
6863 specified, the default includes are used (@pxref{Default Includes}). If
6864 @var{action-if-found} is given, it is additional shell code to execute
6865 when one of the types is found. If @var{action-if-not-found} is given,
6866 it is executed when one of the types is not found.
6868 This macro uses M4 lists:
6870 AC_CHECK_TYPES([ptrdiff_t])
6871 AC_CHECK_TYPES([unsigned long long int, uintmax_t])
6872 AC_CHECK_TYPES([float_t], [], [], [[#include <math.h>]])
6877 Autoconf, up to 2.13, used to provide to another version of
6878 @code{AC_CHECK_TYPE}, broken by design. In order to keep backward
6879 compatibility, a simple heuristic, quite safe but not totally, is
6880 implemented. In case of doubt, read the documentation of the former
6881 @code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}.
6884 @node Compilers and Preprocessors
6885 @section Compilers and Preprocessors
6887 @cindex Preprocessors
6890 All the tests for compilers (@code{AC_PROG_CC}, @code{AC_PROG_CXX},
6891 @code{AC_PROG_F77}) define the output variable @code{EXEEXT} based on
6892 the output of the compiler, typically to the empty string if
6893 Posix and @samp{.exe} if a DOS variant.
6896 They also define the output variable @code{OBJEXT} based on the
6897 output of the compiler, after @file{.c} files have been excluded, typically
6898 to @samp{o} if Posix, @samp{obj} if a DOS variant.
6900 If the compiler being used does not produce executables, the tests fail. If
6901 the executables can't be run, and cross-compilation is not enabled, they
6902 fail too. @xref{Manual Configuration}, for more on support for cross
6906 * Specific Compiler Characteristics:: Some portability issues
6907 * Generic Compiler Characteristics:: Language independent tests and features
6908 * C Compiler:: Checking its characteristics
6909 * C++ Compiler:: Likewise
6910 * Objective C Compiler:: Likewise
6911 * Objective C++ Compiler:: Likewise
6912 * Erlang Compiler and Interpreter:: Likewise
6913 * Fortran Compiler:: Likewise
6916 @node Specific Compiler Characteristics
6917 @subsection Specific Compiler Characteristics
6919 Some compilers exhibit different behaviors.
6922 @item Static/Dynamic Expressions
6923 Autoconf relies on a trick to extract one bit of information from the C
6924 compiler: using negative array sizes. For instance the following
6925 excerpt of a C source demonstrates how to test whether @samp{int} objects are 4
6929 static int test_array[sizeof (int) == 4 ? 1 : -1];
6933 To our knowledge, there is a single compiler that does not support this
6934 trick: the HP C compilers (the real ones, not only the
6935 ``bundled'') on HP-UX 11.00.
6936 They incorrectly reject the above program with the diagnostic
6937 ``Variable-length arrays cannot have static storage.''
6938 This bug comes from HP compilers' mishandling of @code{sizeof (int)},
6939 not from the @code{? 1 : -1}, and
6940 Autoconf works around this problem by casting @code{sizeof (int)} to
6941 @code{long int} before comparing it.
6944 @node Generic Compiler Characteristics
6945 @subsection Generic Compiler Characteristics
6947 @anchor{AC_CHECK_SIZEOF}
6948 @defmac AC_CHECK_SIZEOF (@var{type-or-expr}, @ovar{unused}, @
6949 @dvar{includes, AC_INCLUDES_DEFAULT})
6950 @acindex{CHECK_SIZEOF}
6951 @cvindex SIZEOF_@var{type-or-expr}
6952 @caindex sizeof_@var{type-or-expr}
6953 Define @code{SIZEOF_@var{type-or-expr}} (@pxref{Standard Symbols}) to be
6954 the size in bytes of @var{type-or-expr}, which may be either a type or
6955 an expression returning a value that has a size. If the expression
6956 @samp{sizeof (@var{type-or-expr})} is invalid, the result is 0.
6957 @var{includes} is a series of include directives, defaulting to
6958 @code{AC_INCLUDES_DEFAULT} (@pxref{Default Includes}), which are used
6959 prior to the expression under test.
6961 This macro now works even when cross-compiling. The @var{unused}
6962 argument was used when cross-compiling.
6964 For example, the call
6967 @c If you change this example, adjust tests/semantics.at:AC_CHECK_SIZEOF struct.
6968 AC_CHECK_SIZEOF([int *])
6972 defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems.
6974 This macro caches its result in the @code{ac_cv_sizeof_@var{type-or-expr}}
6975 variable, with @samp{*} mapped to @samp{p} and other characters not
6976 suitable for a variable name mapped to underscores.
6979 @defmac AC_CHECK_ALIGNOF (@var{type}, @dvar{includes, AC_INCLUDES_DEFAULT})
6980 @acindex{CHECK_ALIGNOF}
6981 @cvindex ALIGNOF_@var{type}
6982 @caindex alignof_@var{type-or-expr}
6983 Define @code{ALIGNOF_@var{type}} (@pxref{Standard Symbols}) to be the
6984 alignment in bytes of @var{type}. @samp{@var{type} y;} must be valid as
6985 a structure member declaration. If @samp{type} is unknown, the result
6986 is 0. If no @var{includes} are specified, the default includes are used
6987 (@pxref{Default Includes}).
6989 This macro caches its result in the @code{ac_cv_alignof_@var{type-or-expr}}
6990 variable, with @samp{*} mapped to @samp{p} and other characters not
6991 suitable for a variable name mapped to underscores.
6994 @defmac AC_COMPUTE_INT (@var{var}, @var{expression}, @
6995 @dvar{includes, AC_INCLUDES_DEFAULT}, @ovar{action-if-fails})
6996 @acindex{COMPUTE_INT}
6997 Store into the shell variable @var{var} the value of the integer
6998 @var{expression}. The
6999 value should fit in an initializer in a C variable of type @code{signed
7000 long}. To support cross compilation (in which case, the macro only works on
7001 hosts that use twos-complement arithmetic), it should be possible to evaluate
7002 the expression at compile-time. If no @var{includes} are specified, the
7003 default includes are used (@pxref{Default Includes}).
7005 Execute @var{action-if-fails} if the value cannot be determined correctly.
7008 @defmac AC_LANG_WERROR
7009 @acindex{LANG_WERROR}
7010 Normally Autoconf ignores warnings generated by the compiler, linker, and
7011 preprocessor. If this macro is used, warnings count as fatal
7012 errors for the current language. This macro is useful when the
7013 results of configuration are used where warnings are unacceptable; for
7014 instance, if parts of a program are built with the GCC
7016 option. If the whole program is built using @option{-Werror} it is
7017 often simpler to put @option{-Werror} in the compiler flags (@code{CFLAGS},
7024 @ovindex OPENMP_CFLAGS
7025 @ovindex OPENMP_CXXFLAGS
7026 @ovindex OPENMP_FFLAGS
7027 @ovindex OPENMP_FCFLAGS
7028 OpenMP (@url{http://@/www.openmp.org/}) specifies extensions of C, C++,
7029 and Fortran that simplify optimization of shared memory parallelism,
7030 which is a common problem on multicore CPUs.
7032 If the current language is C, the macro @code{AC_OPENMP} sets the
7033 variable @code{OPENMP_CFLAGS} to the C compiler flags needed for
7034 supporting OpenMP@. @code{OPENMP_CFLAGS} is set to empty if the
7035 compiler already supports OpenMP, if it has no way to activate OpenMP
7036 support, or if the user rejects OpenMP support by invoking
7037 @samp{configure} with the @samp{--disable-openmp} option.
7039 @code{OPENMP_CFLAGS} needs to be used when compiling programs, when
7040 preprocessing program source, and when linking programs. Therefore you
7041 need to add @code{$(OPENMP_CFLAGS)} to the @code{CFLAGS} of C programs
7042 that use OpenMP@. If you preprocess OpenMP-specific C code, you also
7043 need to add @code{$(OPENMP_CFLAGS)} to @code{CPPFLAGS}. The presence of
7044 OpenMP support is revealed at compile time by the preprocessor macro
7047 Linking a program with @code{OPENMP_CFLAGS} typically adds one more
7048 shared library to the program's dependencies, so its use is recommended
7049 only on programs that actually require OpenMP.
7051 If the current language is C++, @code{AC_OPENMP} sets the variable
7052 @code{OPENMP_CXXFLAGS}, suitably for the C++ compiler. The same remarks
7055 If the current language is Fortran 77 or Fortran, @code{AC_OPENMP} sets
7056 the variable @code{OPENMP_FFLAGS} or @code{OPENMP_FCFLAGS},
7057 respectively. Similar remarks as for C hold, except that
7058 @code{CPPFLAGS} is not used for Fortran, and no preprocessor macro
7059 signals OpenMP support.
7061 For portability, it is best to avoid spaces between @samp{#} and
7062 @samp{pragma omp}. That is, write @samp{#pragma omp}, not
7063 @samp{# pragma omp}. The Sun WorkShop 6.2 C compiler chokes on the
7068 @subsection C Compiler Characteristics
7070 The following macros provide ways to find and exercise a C Compiler.
7071 There are a few constructs that ought to be avoided, but do not deserve
7072 being checked for, since they can easily be worked around.
7075 @item Don't use lines containing solitary backslashes
7076 They tickle a bug in the HP-UX C compiler (checked on
7078 11.00, and 11i). When given the following source:
7083 * A comment with backslash-newlines in it. %@{ %@} *\
7087 " A string with backslash-newlines in it %@{ %@} \\
7089 char apostrophe = '\\
7097 the compiler incorrectly fails with the diagnostics ``Non-terminating
7098 comment at end of file'' and ``Missing @samp{#endif} at end of file.''
7099 Removing the lines with solitary backslashes solves the problem.
7101 @item Don't compile several files at once if output matters to you
7102 Some compilers, such as HP's, report names of files being
7103 compiled when given more than one file operand. For instance:
7112 This can cause problems if you observe the output of the compiler to
7113 detect failures. Invoking @samp{cc -c a.c && cc -c b.c && cc -o c a.o
7114 b.o} solves the issue.
7116 @item Don't rely on @code{#error} failing
7117 The IRIX C compiler does not fail when #error is preprocessed; it
7118 simply emits a diagnostic and continues, exiting successfully. So,
7119 instead of an error directive like @code{#error "Unsupported word size"}
7120 it is more portable to use an invalid directive like @code{#Unsupported
7121 word size} in Autoconf tests. In ordinary source code, @code{#error} is
7122 OK, since installers with inadequate compilers like IRIX can simply
7123 examine these compilers' diagnostic output.
7125 @item Don't rely on correct @code{#line} support
7126 On Solaris, @command{c89} (at least Sun C 5.3 through 5.8)
7127 diagnoses @code{#line} directives whose line
7128 numbers are greater than 32767. Nothing in Posix
7129 makes this invalid. That is why Autoconf stopped issuing
7130 @code{#line} directives.
7133 @defmac AC_PROG_CC (@ovar{compiler-search-list})
7139 @caindex prog_cc_c89
7140 Determine a C compiler to use. If @code{CC} is not already set in the
7141 environment, check for @code{gcc} and @code{cc}, then for other C
7142 compilers. Set output variable @code{CC} to the name of the compiler
7145 This macro may, however, be invoked with an optional first argument
7146 which, if specified, must be a blank-separated list of C compilers to
7147 search for. This just gives the user an opportunity to specify an
7148 alternative search list for the C compiler. For example, if you didn't
7149 like the default order, then you could invoke @code{AC_PROG_CC} like
7153 AC_PROG_CC([gcc cl cc])
7156 If the C compiler does not handle function prototypes correctly by
7157 default, try to add an option to output variable @code{CC} to make it
7158 so. This macro tries various options that select standard-conformance
7159 modes on various systems.
7161 After calling this macro you can check whether the C compiler has been
7162 set to accept ANSI C89 (ISO C90); if not, the shell
7164 @code{ac_cv_prog_cc_c89} is set to @samp{no}. See also
7165 @code{AC_C_PROTOTYPES} below.
7167 If using the GNU C compiler, set shell variable @code{GCC} to
7168 @samp{yes}. If output variable @code{CFLAGS} was not already set, set
7169 it to @option{-g -O2} for the GNU C compiler (@option{-O2} on systems
7170 where GCC does not accept @option{-g}), or @option{-g} for
7171 other compilers. If your package does not like this default, then it is
7172 acceptable to insert the line @samp{: $@{CFLAGS=""@}} after @code{AC_INIT}
7173 and before @code{AC_PROG_CC} to select an empty default instead.
7175 Many Autoconf macros use a compiler, and thus call
7176 @samp{AC_REQUIRE([AC_PROG_CC])} to ensure that the compiler has been
7177 determined before the body of the outermost @code{AC_DEFUN} macro.
7178 Although @code{AC_PROG_CC} is safe to directly expand multiple times, it
7179 performs certain checks (such as the proper value of @env{EXEEXT}) only
7180 on the first invocation. Therefore, care must be used when invoking
7181 this macro from within another macro rather than at the top level
7182 (@pxref{Expanded Before Required}).
7185 @anchor{AC_PROG_CC_C_O}
7186 @defmac AC_PROG_CC_C_O
7187 @acindex{PROG_CC_C_O}
7188 @cvindex NO_MINUS_C_MINUS_O
7189 @caindex prog_cc_@var{compiler}_c_o
7190 If the C compiler does not accept the @option{-c} and @option{-o} options
7191 simultaneously, define @code{NO_MINUS_C_MINUS_O}. This macro actually
7192 tests both the compiler found by @code{AC_PROG_CC}, and, if different,
7193 the first @code{cc} in the path. The test fails if one fails. This
7194 macro was created for GNU Make to choose the default C compilation
7197 For the compiler @var{compiler}, this macro caches its result in the
7198 @code{ac_cv_prog_cc_@var{compiler}_c_o} variable.
7206 Set output variable @code{CPP} to a command that runs the
7207 C preprocessor. If @samp{$CC -E} doesn't work, @file{/lib/cpp} is used.
7208 It is only portable to run @code{CPP} on files with a @file{.c}
7211 Some preprocessors don't indicate missing include files by the error
7212 status. For such preprocessors an internal variable is set that causes
7213 other macros to check the standard error from the preprocessor and
7214 consider the test failed if any warnings have been reported.
7215 For most preprocessors, though, warnings do not cause include-file
7216 tests to fail unless @code{AC_PROG_CPP_WERROR} is also specified.
7219 @defmac AC_PROG_CPP_WERROR
7220 @acindex{PROG_CPP_WERROR}
7222 This acts like @code{AC_PROG_CPP}, except it treats warnings from the
7223 preprocessor as errors even if the preprocessor exit status indicates
7224 success. This is useful for avoiding headers that generate mandatory
7225 warnings, such as deprecation notices.
7229 The following macros check for C compiler or machine architecture
7230 features. To check for characteristics not listed here, use
7231 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
7232 @code{AC_RUN_IFELSE} (@pxref{Runtime}).
7234 @defmac AC_PROG_CC_STDC
7235 @acindex{PROG_CC_STDC}
7236 @caindex prog_cc_stdc
7237 If the C compiler cannot compile ISO Standard C (currently
7238 C99), try to add an option to output variable @code{CC} to make it work.
7239 If the compiler does not support C99, fall back to supporting
7242 After calling this macro you can check whether the C compiler has been
7243 set to accept Standard C; if not, the shell variable
7244 @code{ac_cv_prog_cc_stdc} is set to @samp{no}.
7247 @defmac AC_PROG_CC_C89
7248 @acindex{PROG_CC_C89}
7249 @caindex prog_cc_c89
7250 If the C compiler is not in ANSI C89 (ISO C90) mode by
7251 default, try to add an option to output variable @code{CC} to make it
7252 so. This macro tries various options that select ANSI C89 on
7253 some system or another, preferring extended functionality modes over
7254 strict conformance modes. It considers the compiler to be in
7255 ANSI C89 mode if it handles function prototypes correctly.
7257 After calling this macro you can check whether the C compiler has been
7258 set to accept ANSI C89; if not, the shell variable
7259 @code{ac_cv_prog_cc_c89} is set to @samp{no}.
7261 This macro is called automatically by @code{AC_PROG_CC}.
7264 @defmac AC_PROG_CC_C99
7265 @acindex{PROG_CC_C99}
7266 @caindex prog_cc_c99
7267 If the C compiler is not in C99 mode by default, try to add an
7268 option to output variable @code{CC} to make it so. This macro tries
7269 various options that select C99 on some system or another, preferring
7270 extended functionality modes over strict conformance modes. It
7271 considers the compiler to be in C99 mode if it handles @code{_Bool},
7272 @code{//} comments, flexible array members, @code{inline}, signed and
7273 unsigned @code{long long int}, mixed code and declarations, named
7274 initialization of structs,
7275 @code{restrict}, @code{va_copy}, varargs macros, variable declarations
7276 in @code{for} loops, and variable length arrays.
7278 After calling this macro you can check whether the C compiler has been
7279 set to accept C99; if not, the shell variable
7280 @code{ac_cv_prog_cc_c99} is set to @samp{no}.
7283 @defmac AC_C_BACKSLASH_A
7284 @acindex{C_BACKSLASH_A}
7285 @cvindex HAVE_C_BACKSLASH_A
7286 Define @samp{HAVE_C_BACKSLASH_A} to 1 if the C compiler understands
7289 This macro is obsolescent, as current C compilers understand @samp{\a}.
7290 New programs need not use this macro.
7293 @anchor{AC_C_BIGENDIAN}
7294 @defmac AC_C_BIGENDIAN (@ovar{action-if-true}, @ovar{action-if-false}, @
7295 @ovar{action-if-unknown}, @ovar{action-if-universal})
7296 @acindex{C_BIGENDIAN}
7297 @cvindex WORDS_BIGENDIAN
7299 If words are stored with the most significant byte first (like Motorola
7300 and SPARC CPUs), execute @var{action-if-true}. If words are stored with
7301 the least significant byte first (like Intel and VAX CPUs), execute
7302 @var{action-if-false}.
7304 This macro runs a test-case if endianness cannot be determined from the
7305 system header files. When cross-compiling, the test-case is not run but
7306 grep'ed for some magic values. @var{action-if-unknown} is executed if
7307 the latter case fails to determine the byte sex of the host system.
7309 In some cases a single run of a compiler can generate code for multiple
7310 architectures. This can happen, for example, when generating Mac OS X
7311 universal binary files, which work on both PowerPC and Intel
7312 architectures. In this case, the different variants might be for
7313 different architectures whose endiannesses differ. If
7314 @command{configure} detects this, it executes @var{action-if-universal}
7315 instead of @var{action-if-unknown}.
7317 The default for @var{action-if-true} is to define
7318 @samp{WORDS_BIGENDIAN}. The default for @var{action-if-false} is to do
7319 nothing. The default for @var{action-if-unknown} is to
7320 abort configure and tell the installer how to bypass this test.
7321 And finally, the default for @var{action-if-universal} is to ensure that
7322 @samp{WORDS_BIGENDIAN} is defined if and only if a universal build is
7323 detected and the current code is big-endian; this default works only if
7324 @command{autoheader} is used (@pxref{autoheader Invocation}).
7326 If you use this macro without specifying @var{action-if-universal}, you
7327 should also use @code{AC_CONFIG_HEADERS}; otherwise
7328 @samp{WORDS_BIGENDIAN} may be set incorrectly for Mac OS X universal
7337 If the C compiler does not fully support the @code{const} keyword,
7338 define @code{const} to be empty. Some C compilers that do
7339 not define @code{__STDC__} do support @code{const}; some compilers that
7340 define @code{__STDC__} do not completely support @code{const}. Programs
7341 can simply use @code{const} as if every C compiler supported it; for
7342 those that don't, the makefile or configuration header file
7343 defines it as empty.
7345 Occasionally installers use a C++ compiler to compile C code, typically
7346 because they lack a C compiler. This causes problems with @code{const},
7347 because C and C++ treat @code{const} differently. For example:
7354 is valid in C but not in C++. These differences unfortunately cannot be
7355 papered over by defining @code{const} to be empty.
7357 If @command{autoconf} detects this situation, it leaves @code{const} alone,
7358 as this generally yields better results in practice. However, using a
7359 C++ compiler to compile C code is not recommended or supported, and
7360 installers who run into trouble in this area should get a C compiler
7361 like GCC to compile their C code.
7363 This macro caches its result in the @code{ac_cv_c_const} variable.
7365 This macro is obsolescent, as current C compilers support @code{const}.
7366 New programs need not use this macro.
7369 @defmac AC_C_RESTRICT
7370 @acindex{C_RESTRICT}
7373 If the C compiler recognizes a variant spelling for the @code{restrict}
7374 keyword (@code{__restrict}, @code{__restrict__}, or @code{_Restrict}),
7375 then define @code{restrict} to that; this is more likely to do the right
7376 thing with compilers that support language variants where plain
7377 @code{restrict} is not a keyword. Otherwise, if the C compiler
7378 recognizes the @code{restrict} keyword, don't do anything.
7379 Otherwise, define @code{restrict} to be empty.
7380 Thus, programs may simply use @code{restrict} as if every C compiler
7381 supported it; for those that do not, the makefile
7382 or configuration header defines it away.
7384 Although support in C++ for the @code{restrict} keyword is not
7385 required, several C++ compilers do accept the keyword.
7386 This macro works for them, too.
7388 This macro caches @samp{no} in the @code{ac_cv_c_restrict} variable
7389 if @code{restrict} is not supported, and a supported spelling otherwise.
7392 @defmac AC_C_VOLATILE
7393 @acindex{C_VOLATILE}
7395 If the C compiler does not understand the keyword @code{volatile},
7396 define @code{volatile} to be empty. Programs can simply use
7397 @code{volatile} as if every C compiler supported it; for those that do
7398 not, the makefile or configuration header defines it as
7401 If the correctness of your program depends on the semantics of
7402 @code{volatile}, simply defining it to be empty does, in a sense, break
7403 your code. However, given that the compiler does not support
7404 @code{volatile}, you are at its mercy anyway. At least your
7405 program compiles, when it wouldn't before.
7406 @xref{Volatile Objects}, for more about @code{volatile}.
7408 In general, the @code{volatile} keyword is a standard C feature, so
7409 you might expect that @code{volatile} is available only when
7410 @code{__STDC__} is defined. However, Ultrix 4.3's native compiler does
7411 support volatile, but does not define @code{__STDC__}.
7413 This macro is obsolescent, as current C compilers support @code{volatile}.
7414 New programs need not use this macro.
7417 @anchor{AC_C_INLINE}
7421 If the C compiler supports the keyword @code{inline}, do nothing.
7422 Otherwise define @code{inline} to @code{__inline__} or @code{__inline}
7423 if it accepts one of those, otherwise define @code{inline} to be empty.
7426 @anchor{AC_C_CHAR_UNSIGNED}
7427 @defmac AC_C_CHAR_UNSIGNED
7428 @acindex{C_CHAR_UNSIGNED}
7429 @cvindex __CHAR_UNSIGNED__
7430 If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__},
7431 unless the C compiler predefines it.
7433 These days, using this macro is not necessary. The same information can
7434 be determined by this portable alternative, thus avoiding the use of
7435 preprocessor macros in the namespace reserved for the implementation.
7440 # define CHAR_UNSIGNED 1
7445 @defmac AC_C_STRINGIZE
7446 @acindex{C_STRINGIZE}
7447 @cvindex HAVE_STRINGIZE
7448 If the C preprocessor supports the stringizing operator, define
7449 @code{HAVE_STRINGIZE}. The stringizing operator is @samp{#} and is
7450 found in macros such as this:
7456 This macro is obsolescent, as current C compilers support the
7457 stringizing operator. New programs need not use this macro.
7460 @defmac AC_C_FLEXIBLE_ARRAY_MEMBER
7461 @acindex{C_FLEXIBLE_ARRAY_MEMBER}
7462 @cvindex FLEXIBLE_ARRAY_MEMBER
7463 If the C compiler supports flexible array members, define
7464 @code{FLEXIBLE_ARRAY_MEMBER} to nothing; otherwise define it to 1.
7465 That way, a declaration like this:
7471 double val[FLEXIBLE_ARRAY_MEMBER];
7476 will let applications use the ``struct hack'' even with compilers that
7477 do not support flexible array members. To allocate and use such an
7478 object, you can use code like this:
7482 size_t n = compute_value_count ();
7484 malloc (offsetof (struct s, val)
7485 + n * sizeof (double));
7487 for (i = 0; i < n; i++)
7488 p->val[i] = compute_value (i);
7492 @defmac AC_C_VARARRAYS
7493 @acindex{C_VARARRAYS}
7494 @cvindex HAVE_C_VARARRAYS
7495 If the C compiler supports variable-length arrays, define
7496 @code{HAVE_C_VARARRAYS}. A variable-length array is an array of automatic
7497 storage duration whose length is determined at run time, when the array
7503 @cvindex HAVE_TYPEOF
7505 If the C compiler supports GCC's @code{typeof} syntax either
7507 through a different spelling of the keyword (e.g., @code{__typeof__}),
7508 define @code{HAVE_TYPEOF}. If the support is available only through a
7509 different spelling, define @code{typeof} to that spelling.
7512 @defmac AC_C_PROTOTYPES
7513 @acindex{C_PROTOTYPES}
7515 @cvindex __PROTOTYPES
7517 If function prototypes are understood by the compiler (as determined by
7518 @code{AC_PROG_CC}), define @code{PROTOTYPES} and @code{__PROTOTYPES}.
7519 Defining @code{__PROTOTYPES} is for the benefit of
7520 header files that cannot use macros that infringe on user name space.
7522 This macro is obsolescent, as current C compilers support prototypes.
7523 New programs need not use this macro.
7526 @anchor{AC_PROG_GCC_TRADITIONAL}
7527 @defmac AC_PROG_GCC_TRADITIONAL
7528 @acindex{PROG_GCC_TRADITIONAL}
7530 Add @option{-traditional} to output variable @code{CC} if using the
7531 GNU C compiler and @code{ioctl} does not work properly without
7532 @option{-traditional}. That usually happens when the fixed header files
7533 have not been installed on an old system.
7535 This macro is obsolescent, since current versions of the GNU C
7536 compiler fix the header files automatically when installed.
7541 @subsection C++ Compiler Characteristics
7544 @defmac AC_PROG_CXX (@ovar{compiler-search-list})
7550 Determine a C++ compiler to use. Check whether the environment variable
7551 @code{CXX} or @code{CCC} (in that order) is set; if so, then set output
7552 variable @code{CXX} to its value.
7554 Otherwise, if the macro is invoked without an argument, then search for
7555 a C++ compiler under the likely names (first @code{g++} and @code{c++}
7556 then other names). If none of those checks succeed, then as a last
7557 resort set @code{CXX} to @code{g++}.
7559 This macro may, however, be invoked with an optional first argument
7560 which, if specified, must be a blank-separated list of C++ compilers to
7561 search for. This just gives the user an opportunity to specify an
7562 alternative search list for the C++ compiler. For example, if you
7563 didn't like the default order, then you could invoke @code{AC_PROG_CXX}
7567 AC_PROG_CXX([gcc cl KCC CC cxx cc++ xlC aCC c++ g++])
7570 If using the GNU C++ compiler, set shell variable @code{GXX} to
7571 @samp{yes}. If output variable @code{CXXFLAGS} was not already set, set
7572 it to @option{-g -O2} for the GNU C++ compiler (@option{-O2} on
7573 systems where G++ does not accept @option{-g}), or @option{-g} for other
7574 compilers. If your package does not like this default, then it is
7575 acceptable to insert the line @samp{: $@{CXXFLAGS=""@}} after @code{AC_INIT}
7576 and before @code{AC_PROG_CXX} to select an empty default instead.
7580 @defmac AC_PROG_CXXCPP
7581 @acindex{PROG_CXXCPP}
7584 Set output variable @code{CXXCPP} to a command that runs the C++
7585 preprocessor. If @samp{$CXX -E} doesn't work, @file{/lib/cpp} is used.
7586 It is portable to run @code{CXXCPP} only on files with a @file{.c},
7587 @file{.C}, @file{.cc}, or @file{.cpp} extension.
7589 Some preprocessors don't indicate missing include files by the error
7590 status. For such preprocessors an internal variable is set that causes
7591 other macros to check the standard error from the preprocessor and
7592 consider the test failed if any warnings have been reported. However,
7593 it is not known whether such broken preprocessors exist for C++.
7596 @defmac AC_PROG_CXX_C_O
7597 @acindex{PROG_CXX_C_O}
7598 @cvindex CXX_NO_MINUS_C_MINUS_O
7599 Test whether the C++ compiler accepts the options @option{-c} and
7600 @option{-o} simultaneously, and define @code{CXX_NO_MINUS_C_MINUS_O},
7605 @node Objective C Compiler
7606 @subsection Objective C Compiler Characteristics
7609 @defmac AC_PROG_OBJC (@ovar{compiler-search-list})
7615 Determine an Objective C compiler to use. If @code{OBJC} is not already
7616 set in the environment, check for Objective C compilers. Set output
7617 variable @code{OBJC} to the name of the compiler found.
7619 This macro may, however, be invoked with an optional first argument
7620 which, if specified, must be a blank-separated list of Objective C compilers to
7621 search for. This just gives the user an opportunity to specify an
7622 alternative search list for the Objective C compiler. For example, if you
7623 didn't like the default order, then you could invoke @code{AC_PROG_OBJC}
7627 AC_PROG_OBJC([gcc objcc objc])
7630 If using the GNU Objective C compiler, set shell variable
7631 @code{GOBJC} to @samp{yes}. If output variable @code{OBJCFLAGS} was not
7632 already set, set it to @option{-g -O2} for the GNU Objective C
7633 compiler (@option{-O2} on systems where @command{gcc} does not accept
7634 @option{-g}), or @option{-g} for other compilers.
7637 @defmac AC_PROG_OBJCPP
7638 @acindex{PROG_OBJCPP}
7641 Set output variable @code{OBJCPP} to a command that runs the Objective C
7642 preprocessor. If @samp{$OBJC -E} doesn't work, @file{/lib/cpp} is used.
7646 @node Objective C++ Compiler
7647 @subsection Objective C++ Compiler Characteristics
7650 @defmac AC_PROG_OBJCXX (@ovar{compiler-search-list})
7651 @acindex{PROG_OBJCXX}
7653 @evindex OBJCXXFLAGS
7655 @ovindex OBJCXXFLAGS
7656 Determine an Objective C++ compiler to use. If @code{OBJCXX} is not already
7657 set in the environment, check for Objective C++ compilers. Set output
7658 variable @code{OBJCXX} to the name of the compiler found.
7660 This macro may, however, be invoked with an optional first argument
7661 which, if specified, must be a blank-separated list of Objective C++ compilers
7662 to search for. This just gives the user an opportunity to specify an
7663 alternative search list for the Objective C++ compiler. For example, if you
7664 didn't like the default order, then you could invoke @code{AC_PROG_OBJCXX}
7668 AC_PROG_OBJCXX([gcc g++ objcc++ objcxx])
7671 If using the GNU Objective C++ compiler, set shell variable
7672 @code{GOBJCXX} to @samp{yes}. If output variable @code{OBJCXXFLAGS} was not
7673 already set, set it to @option{-g -O2} for the GNU Objective C++
7674 compiler (@option{-O2} on systems where @command{gcc} does not accept
7675 @option{-g}), or @option{-g} for other compilers.
7678 @defmac AC_PROG_OBJCXXCPP
7679 @acindex{PROG_OBJCXXCPP}
7682 Set output variable @code{OBJCXXCPP} to a command that runs the Objective C++
7683 preprocessor. If @samp{$OBJCXX -E} doesn't work, @file{/lib/cpp} is used.
7687 @node Erlang Compiler and Interpreter
7688 @subsection Erlang Compiler and Interpreter Characteristics
7691 Autoconf defines the following macros for determining paths to the essential
7692 Erlang/OTP programs:
7694 @defmac AC_ERLANG_PATH_ERLC (@ovar{value-if-not-found}, @dvar{path, $PATH})
7695 @acindex{ERLANG_PATH_ERLC}
7700 Determine an Erlang compiler to use. If @code{ERLC} is not already set in the
7701 environment, check for @command{erlc}. Set output variable @code{ERLC} to the
7702 complete path of the compiler command found. In addition, if @code{ERLCFLAGS}
7703 is not set in the environment, set it to an empty value.
7705 The two optional arguments have the same meaning as the two last arguments of
7706 macro @code{AC_PROG_PATH} for looking for the @command{erlc} program. For
7707 example, to look for @command{erlc} only in the @file{/usr/lib/erlang/bin}
7711 AC_ERLANG_PATH_ERLC([not found], [/usr/lib/erlang/bin])
7715 @defmac AC_ERLANG_NEED_ERLC (@dvar{path, $PATH})
7716 @acindex{ERLANG_NEED_ERLC}
7717 A simplified variant of the @code{AC_ERLANG_PATH_ERLC} macro, that prints an
7718 error message and exits the @command{configure} script if the @command{erlc}
7719 program is not found.
7722 @defmac AC_ERLANG_PATH_ERL (@ovar{value-if-not-found}, @dvar{path, $PATH})
7723 @acindex{ERLANG_PATH_ERL}
7726 Determine an Erlang interpreter to use. If @code{ERL} is not already
7728 environment, check for @command{erl}. Set output variable @code{ERL} to the
7729 complete path of the interpreter command found.
7731 The two optional arguments have the same meaning as the two last arguments of
7732 macro @code{AC_PROG_PATH} for looking for the @command{erl} program. For
7733 example, to look for @command{erl} only in the @file{/usr/lib/erlang/bin}
7737 AC_ERLANG_PATH_ERL([not found], [/usr/lib/erlang/bin])
7741 @defmac AC_ERLANG_NEED_ERL (@dvar{path, $PATH})
7742 @acindex{ERLANG_NEED_ERL}
7743 A simplified variant of the @code{AC_ERLANG_PATH_ERL} macro, that prints an
7744 error message and exits the @command{configure} script if the @command{erl}
7745 program is not found.
7749 @node Fortran Compiler
7750 @subsection Fortran Compiler Characteristics
7754 The Autoconf Fortran support is divided into two categories: legacy
7755 Fortran 77 macros (@code{F77}), and modern Fortran macros (@code{FC}).
7756 The former are intended for traditional Fortran 77 code, and have output
7757 variables like @code{F77}, @code{FFLAGS}, and @code{FLIBS}. The latter
7758 are for newer programs that can (or must) compile under the newer
7759 Fortran standards, and have output variables like @code{FC},
7760 @code{FCFLAGS}, and @code{FCLIBS}.
7762 Except for the macros @code{AC_FC_SRCEXT}, @code{AC_FC_FREEFORM},
7763 @code{AC_FC_FIXEDFORM}, and @code{AC_FC_LINE_LENGTH} (see below), the
7764 @code{FC} and @code{F77} macros behave almost identically, and so they
7765 are documented together in this section.
7768 @defmac AC_PROG_F77 (@ovar{compiler-search-list})
7774 Determine a Fortran 77 compiler to use. If @code{F77} is not already
7775 set in the environment, then check for @code{g77} and @code{f77}, and
7776 then some other names. Set the output variable @code{F77} to the name
7777 of the compiler found.
7779 This macro may, however, be invoked with an optional first argument
7780 which, if specified, must be a blank-separated list of Fortran 77
7781 compilers to search for. This just gives the user an opportunity to
7782 specify an alternative search list for the Fortran 77 compiler. For
7783 example, if you didn't like the default order, then you could invoke
7784 @code{AC_PROG_F77} like this:
7787 AC_PROG_F77([fl32 f77 fort77 xlf g77 f90 xlf90])
7790 If using @code{g77} (the GNU Fortran 77 compiler), then
7791 set the shell variable @code{G77} to @samp{yes}.
7792 If the output variable @code{FFLAGS} was not already set in the
7793 environment, then set it to @option{-g -02} for @code{g77} (or @option{-O2}
7794 where @code{g77} does not accept @option{-g}). Otherwise, set
7795 @code{FFLAGS} to @option{-g} for all other Fortran 77 compilers.
7798 @defmac AC_PROG_FC (@ovar{compiler-search-list}, @ovar{dialect})
7804 Determine a Fortran compiler to use. If @code{FC} is not already set in
7805 the environment, then @code{dialect} is a hint to indicate what Fortran
7806 dialect to search for; the default is to search for the newest available
7807 dialect. Set the output variable @code{FC} to the name of the compiler
7810 By default, newer dialects are preferred over older dialects, but if
7811 @code{dialect} is specified then older dialects are preferred starting
7812 with the specified dialect. @code{dialect} can currently be one of
7813 Fortran 77, Fortran 90, or Fortran 95. However, this is only a hint of
7814 which compiler @emph{name} to prefer (e.g., @code{f90} or @code{f95}),
7815 and no attempt is made to guarantee that a particular language standard
7816 is actually supported. Thus, it is preferable that you avoid the
7817 @code{dialect} option, and use AC_PROG_FC only for code compatible with
7818 the latest Fortran standard.
7820 This macro may, alternatively, be invoked with an optional first argument
7821 which, if specified, must be a blank-separated list of Fortran
7822 compilers to search for, just as in @code{AC_PROG_F77}.
7824 If the output variable @code{FCFLAGS} was not already set in the
7825 environment, then set it to @option{-g -02} for GNU @code{g77} (or
7826 @option{-O2} where @code{g77} does not accept @option{-g}). Otherwise,
7827 set @code{FCFLAGS} to @option{-g} for all other Fortran compilers.
7830 @defmac AC_PROG_F77_C_O
7831 @defmacx AC_PROG_FC_C_O
7832 @acindex{PROG_F77_C_O}
7833 @acindex{PROG_FC_C_O}
7834 @cvindex F77_NO_MINUS_C_MINUS_O
7835 @cvindex FC_NO_MINUS_C_MINUS_O
7836 Test whether the Fortran compiler accepts the options @option{-c} and
7837 @option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} or
7838 @code{FC_NO_MINUS_C_MINUS_O}, respectively, if it does not.
7841 The following macros check for Fortran compiler characteristics.
7842 To check for characteristics not listed here, use
7843 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
7844 @code{AC_RUN_IFELSE} (@pxref{Runtime}), making sure to first set the
7845 current language to Fortran 77 or Fortran via @code{AC_LANG([Fortran 77])}
7846 or @code{AC_LANG(Fortran)} (@pxref{Language Choice}).
7849 @defmac AC_F77_LIBRARY_LDFLAGS
7850 @defmacx AC_FC_LIBRARY_LDFLAGS
7851 @acindex{F77_LIBRARY_LDFLAGS}
7853 @acindex{FC_LIBRARY_LDFLAGS}
7855 Determine the linker flags (e.g., @option{-L} and @option{-l}) for the
7856 @dfn{Fortran intrinsic and runtime libraries} that are required to
7857 successfully link a Fortran program or shared library. The output
7858 variable @code{FLIBS} or @code{FCLIBS} is set to these flags (which
7859 should be included after @code{LIBS} when linking).
7861 This macro is intended to be used in those situations when it is
7862 necessary to mix, e.g., C++ and Fortran source code in a single
7863 program or shared library (@pxref{Mixing Fortran 77 With C and C++, , ,
7864 automake, GNU Automake}).
7866 For example, if object files from a C++ and Fortran compiler must be
7867 linked together, then the C++ compiler/linker must be used for linking
7868 (since special C++-ish things need to happen at link time like calling
7869 global constructors, instantiating templates, enabling exception
7872 However, the Fortran intrinsic and runtime libraries must be linked in
7873 as well, but the C++ compiler/linker doesn't know by default how to add
7874 these Fortran 77 libraries. Hence, this macro was created to determine
7875 these Fortran libraries.
7877 The macros @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
7878 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} are probably also necessary to
7879 link C/C++ with Fortran; see below. Further, it is highly recommended
7880 that you use @code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers})
7881 because the complex defines that the function wrapper macros create
7882 may not work with C/C++ compiler drivers.
7885 @defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
7886 @defmacx AC_FC_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
7887 @acindex{F77_DUMMY_MAIN}
7888 @cvindex F77_DUMMY_MAIN
7889 With many compilers, the Fortran libraries detected by
7890 @code{AC_F77_LIBRARY_LDFLAGS} or @code{AC_FC_LIBRARY_LDFLAGS} provide
7891 their own @code{main} entry function that initializes things like
7892 Fortran I/O, and which then calls a user-provided entry function named
7893 (say) @code{MAIN__} to run the user's program. The
7894 @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
7895 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros figure out how to deal with
7898 When using Fortran for purely numerical functions (no I/O, etc.)@: often
7899 one prefers to provide one's own @code{main} and skip the Fortran
7900 library initializations. In this case, however, one may still need to
7901 provide a dummy @code{MAIN__} routine in order to prevent linking errors
7902 on some systems. @code{AC_F77_DUMMY_MAIN} or @code{AC_FC_DUMMY_MAIN}
7903 detects whether any such routine is @emph{required} for linking, and
7904 what its name is; the shell variable @code{F77_DUMMY_MAIN} or
7905 @code{FC_DUMMY_MAIN} holds this name, @code{unknown} when no solution
7906 was found, and @code{none} when no such dummy main is needed.
7908 By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} or
7909 @code{FC_DUMMY_MAIN} to the name of this routine (e.g., @code{MAIN__})
7910 @emph{if} it is required. @var{action-if-not-found} defaults to
7911 exiting with an error.
7913 In order to link with Fortran routines, the user's C/C++ program should
7914 then include the following code to define the dummy main if it is
7918 @c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage.
7919 #ifdef F77_DUMMY_MAIN
7923 int F77_DUMMY_MAIN () @{ return 1; @}
7927 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
7929 Note that this macro is called automatically from @code{AC_F77_WRAPPERS}
7930 or @code{AC_FC_WRAPPERS}; there is generally no need to call it
7931 explicitly unless one wants to change the default actions.
7940 As discussed above, many Fortran libraries allow you to provide an entry
7941 point called (say) @code{MAIN__} instead of the usual @code{main}, which
7942 is then called by a @code{main} function in the Fortran libraries that
7943 initializes things like Fortran I/O@. The
7944 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros detect whether it is
7945 @emph{possible} to utilize such an alternate main function, and defines
7946 @code{F77_MAIN} and @code{FC_MAIN} to the name of the function. (If no
7947 alternate main function name is found, @code{F77_MAIN} and @code{FC_MAIN} are
7948 simply defined to @code{main}.)
7950 Thus, when calling Fortran routines from C that perform things like I/O,
7951 one should use this macro and declare the "main" function like so:
7954 @c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage.
7958 int F77_MAIN (int argc, char *argv[]);
7961 (Again, replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
7964 @defmac AC_F77_WRAPPERS
7965 @defmacx AC_FC_WRAPPERS
7966 @acindex{F77_WRAPPERS}
7969 @acindex{FC_WRAPPERS}
7972 Defines C macros @code{F77_FUNC (name, NAME)}, @code{FC_FUNC (name, NAME)},
7973 @code{F77_FUNC_(name, NAME)}, and @code{FC_FUNC_(name, NAME)} to properly
7974 mangle the names of C/C++ identifiers, and identifiers with underscores,
7975 respectively, so that they match the name-mangling scheme used by the
7978 Fortran is case-insensitive, and in order to achieve this the Fortran
7979 compiler converts all identifiers into a canonical case and format. To
7980 call a Fortran subroutine from C or to write a C function that is
7981 callable from Fortran, the C program must explicitly use identifiers in
7982 the format expected by the Fortran compiler. In order to do this, one
7983 simply wraps all C identifiers in one of the macros provided by
7984 @code{AC_F77_WRAPPERS} or @code{AC_FC_WRAPPERS}. For example, suppose
7985 you have the following Fortran 77 subroutine:
7988 @c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage.
7989 subroutine foobar (x, y)
7990 double precision x, y
7996 You would then declare its prototype in C or C++ as:
7999 @c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage.
8000 #define FOOBAR_F77 F77_FUNC (foobar, FOOBAR)
8002 extern "C" /* prevent C++ name mangling */
8004 void FOOBAR_F77 (double *x, double *y);
8007 Note that we pass both the lowercase and uppercase versions of the
8008 function name to @code{F77_FUNC} so that it can select the right one.
8009 Note also that all parameters to Fortran 77 routines are passed as
8010 pointers (@pxref{Mixing Fortran 77 With C and C++, , , automake, GNU
8013 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
8015 Although Autoconf tries to be intelligent about detecting the
8016 name-mangling scheme of the Fortran compiler, there may be Fortran
8017 compilers that it doesn't support yet. In this case, the above code
8018 generates a compile-time error, but some other behavior
8019 (e.g., disabling Fortran-related features) can be induced by checking
8020 whether @code{F77_FUNC} or @code{FC_FUNC} is defined.
8022 Now, to call that routine from a C program, we would do something like:
8025 @c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage.
8027 double x = 2.7183, y;
8028 FOOBAR_F77 (&x, &y);
8032 If the Fortran identifier contains an underscore (e.g., @code{foo_bar}),
8033 you should use @code{F77_FUNC_} or @code{FC_FUNC_} instead of
8034 @code{F77_FUNC} or @code{FC_FUNC} (with the same arguments). This is
8035 because some Fortran compilers mangle names differently if they contain
8039 @defmac AC_F77_FUNC (@var{name}, @ovar{shellvar})
8040 @defmacx AC_FC_FUNC (@var{name}, @ovar{shellvar})
8043 Given an identifier @var{name}, set the shell variable @var{shellvar} to
8044 hold the mangled version @var{name} according to the rules of the
8045 Fortran linker (see also @code{AC_F77_WRAPPERS} or
8046 @code{AC_FC_WRAPPERS}). @var{shellvar} is optional; if it is not
8047 supplied, the shell variable is simply @var{name}. The purpose of
8048 this macro is to give the caller a way to access the name-mangling
8049 information other than through the C preprocessor as above, for example,
8050 to call Fortran routines from some language other than C/C++.
8053 @defmac AC_FC_SRCEXT (@var{ext}, @ovar{action-if-success}, @
8054 @ovar{action-if-failure})
8056 By default, the @code{FC} macros perform their tests using a @file{.f}
8057 extension for source-code files. Some compilers, however, only enable
8058 newer language features for appropriately named files, e.g., Fortran 90
8059 features only for @file{.f90} files. On the other hand, some other
8060 compilers expect all source files to end in @file{.f} and require
8061 special flags to support other file name extensions. The
8062 @code{AC_FC_SRCEXT} macro deals with both of these issues.
8064 The @code{AC_FC_SRCEXT} tries to get the @code{FC} compiler to accept files
8065 ending with the extension .@var{ext} (i.e., @var{ext} does @emph{not}
8066 contain the dot). If any special compiler flags are needed for this, it
8067 stores them in the output variable @code{FCFLAGS_}@var{ext}. This
8068 extension and these flags are then used for all subsequent @code{FC} tests
8069 (until @code{AC_FC_SRCEXT} is called again).
8071 For example, you would use @code{AC_FC_SRCEXT(f90)} to employ the
8072 @file{.f90} extension in future tests, and it would set the
8073 @code{FCFLAGS_f90} output variable with any extra flags that are needed
8074 to compile such files.
8076 The @code{FCFLAGS_}@var{ext} can @emph{not} be simply absorbed into
8077 @code{FCFLAGS}, for two reasons based on the limitations of some
8078 compilers. First, only one @code{FCFLAGS_}@var{ext} can be used at a
8079 time, so files with different extensions must be compiled separately.
8080 Second, @code{FCFLAGS_}@var{ext} must appear @emph{immediately} before
8081 the source-code file name when compiling. So, continuing the example
8082 above, you might compile a @file{foo.f90} file in your makefile with the
8087 $(FC) -c $(FCFLAGS) $(FCFLAGS_f90) '$(srcdir)/foo.f90'
8090 If @code{AC_FC_SRCEXT} succeeds in compiling files with the @var{ext}
8091 extension, it calls @var{action-if-success} (defaults to nothing). If
8092 it fails, and cannot find a way to make the @code{FC} compiler accept such
8093 files, it calls @var{action-if-failure} (defaults to exiting with an
8098 @defmac AC_FC_FREEFORM (@ovar{action-if-success}, @ovar{action-if-failure})
8099 @acindex{FC_FREEFORM}
8101 The @code{AC_FC_FREEFORM} tries to ensure that the Fortran compiler
8102 (@code{$FC}) allows free-format source code (as opposed to the older
8103 fixed-format style from Fortran 77). If necessary, it may add some
8104 additional flags to @code{FCFLAGS}.
8106 This macro is most important if you are using the default @file{.f}
8107 extension, since many compilers interpret this extension as indicating
8108 fixed-format source unless an additional flag is supplied. If you
8109 specify a different extension with @code{AC_FC_SRCEXT}, such as
8110 @file{.f90}, then @code{AC_FC_FREEFORM} ordinarily succeeds without
8111 modifying @code{FCFLAGS}. For extensions which the compiler does not
8112 know about, the flag set by the @code{AC_FC_SRCEXT} macro might let
8113 the compiler assume Fortran 77 by default, however.
8115 If @code{AC_FC_FREEFORM} succeeds in compiling free-form source, it
8116 calls @var{action-if-success} (defaults to nothing). If it fails, it
8117 calls @var{action-if-failure} (defaults to exiting with an error
8121 @defmac AC_FC_FIXEDFORM (@ovar{action-if-success}, @ovar{action-if-failure})
8122 @acindex{FC_FIXEDFORM}
8124 The @code{AC_FC_FIXEDFORM} tries to ensure that the Fortran compiler
8125 (@code{$FC}) allows the old fixed-format source code (as opposed to
8126 free-format style). If necessary, it may add some additional flags to
8129 This macro is needed for some compilers alias names like @command{xlf95}
8130 which assume free-form source code by default, and in case you want to
8131 use fixed-form source with an extension like @file{.f90} which many
8132 compilers interpret as free-form by default. If you specify a different
8133 extension with @code{AC_FC_SRCEXT}, such as @file{.f}, then
8134 @code{AC_FC_FIXEDFORM} ordinarily succeeds without modifying
8137 If @code{AC_FC_FIXEDFORM} succeeds in compiling fixed-form source, it
8138 calls @var{action-if-success} (defaults to nothing). If it fails, it
8139 calls @var{action-if-failure} (defaults to exiting with an error
8143 @defmac AC_FC_LINE_LENGTH (@ovar{length}, @ovar{action-if-success}, @
8144 @ovar{action-if-failure})
8145 @acindex{FC_LINE_LENGTH}
8147 The @code{AC_FC_LINE_LENGTH} macro tries to ensure that the Fortran compiler
8148 (@code{$FC}) accepts long source code lines. The @var{length} argument
8149 may be given as 80, 132, or unlimited, and defaults to 132. Note that
8150 line lengths above 254 columns are not portable, and some compilers
8151 do not accept more than 132 columns at least for fixed format source.
8152 If necessary, it may add some additional flags to @code{FCFLAGS}.
8154 If @code{AC_FC_LINE_LENGTH} succeeds in compiling fixed-form source, it
8155 calls @var{action-if-success} (defaults to nothing). If it fails, it
8156 calls @var{action-if-failure} (defaults to exiting with an error
8161 @node System Services
8162 @section System Services
8164 The following macros check for operating system services or capabilities.
8170 @cindex X Window System
8171 Try to locate the X Window System include files and libraries. If the
8172 user gave the command line options @option{--x-includes=@var{dir}} and
8173 @option{--x-libraries=@var{dir}}, use those directories.
8175 If either or both were not given, get the missing values by running
8176 @code{xmkmf} (or an executable pointed to by the @code{XMKMF}
8177 environment variable) on a trivial @file{Imakefile} and examining the
8178 makefile that it produces. Setting @code{XMKMF} to @samp{false}
8179 disables this method.
8181 If this method fails to find the X Window System, @command{configure}
8182 looks for the files in several directories where they often reside.
8183 If either method is successful, set the shell variables
8184 @code{x_includes} and @code{x_libraries} to their locations, unless they
8185 are in directories the compiler searches by default.
8187 If both methods fail, or the user gave the command line option
8188 @option{--without-x}, set the shell variable @code{no_x} to @samp{yes};
8189 otherwise set it to the empty string.
8192 @anchor{AC_PATH_XTRA}
8193 @defmac AC_PATH_XTRA
8197 @ovindex X_EXTRA_LIBS
8199 @cvindex X_DISPLAY_MISSING
8200 An enhanced version of @code{AC_PATH_X}. It adds the C compiler flags
8201 that X needs to output variable @code{X_CFLAGS}, and the X linker flags
8202 to @code{X_LIBS}. Define @code{X_DISPLAY_MISSING} if X is not
8205 This macro also checks for special libraries that some systems need in
8206 order to compile X programs. It adds any that the system needs to
8207 output variable @code{X_EXTRA_LIBS}. And it checks for special X11R6
8208 libraries that need to be linked with before @option{-lX11}, and adds
8209 any found to the output variable @code{X_PRE_LIBS}.
8211 @c This is an incomplete kludge. Make a real way to do it.
8212 @c If you need to check for other X functions or libraries yourself, then
8213 @c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to
8214 @c @code{LIBS} temporarily, like this: (FIXME - add example)
8217 @anchor{AC_SYS_INTERPRETER}
8218 @defmac AC_SYS_INTERPRETER
8219 @acindex{SYS_INTERPRETER}
8220 Check whether the system supports starting scripts with a line of the
8221 form @samp{#!/bin/sh} to select the interpreter to use for the script.
8222 After running this macro, shell code in @file{configure.ac} can check
8223 the shell variable @code{interpval}; it is set to @samp{yes}
8224 if the system supports @samp{#!}, @samp{no} if not.
8227 @defmac AC_SYS_LARGEFILE
8228 @acindex{SYS_LARGEFILE}
8229 @cvindex _FILE_OFFSET_BITS
8230 @cvindex _LARGE_FILES
8232 @cindex Large file support
8234 Arrange for 64-bit file offsets, known as
8235 @uref{http://@/www.unix-systems@/.org/@/version2/@/whatsnew/@/lfs20mar.html,
8236 large-file support}. On some hosts, one must use special compiler
8237 options to build programs that can access large files. Append any such
8238 options to the output variable @code{CC}. Define
8239 @code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary.
8241 Large-file support can be disabled by configuring with the
8242 @option{--disable-largefile} option.
8244 If you use this macro, check that your program works even when
8245 @code{off_t} is wider than @code{long int}, since this is common when
8246 large-file support is enabled. For example, it is not correct to print
8247 an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld",
8250 The LFS introduced the @code{fseeko} and @code{ftello} functions to
8251 replace their C counterparts @code{fseek} and @code{ftell} that do not
8252 use @code{off_t}. Take care to use @code{AC_FUNC_FSEEKO} to make their
8253 prototypes available when using them and large-file support is
8257 @anchor{AC_SYS_LONG_FILE_NAMES}
8258 @defmac AC_SYS_LONG_FILE_NAMES
8259 @acindex{SYS_LONG_FILE_NAMES}
8260 @cvindex HAVE_LONG_FILE_NAMES
8261 If the system supports file names longer than 14 characters, define
8262 @code{HAVE_LONG_FILE_NAMES}.
8265 @defmac AC_SYS_POSIX_TERMIOS
8266 @acindex{SYS_POSIX_TERMIOS}
8267 @cindex Posix termios headers
8268 @cindex termios Posix headers
8269 @caindex sys_posix_termios
8270 Check to see if the Posix termios headers and functions are available on the
8271 system. If so, set the shell variable @code{ac_cv_sys_posix_termios} to
8272 @samp{yes}. If not, set the variable to @samp{no}.
8275 @node Posix Variants
8276 @section Posix Variants
8278 The following macro makes it possible to use features of Posix that are
8279 extensions to C, as well as platform extensions not defined by Posix.
8281 @anchor{AC_USE_SYSTEM_EXTENSIONS}
8282 @defmac AC_USE_SYSTEM_EXTENSIONS
8283 @acindex{USE_SYSTEM_EXTENSIONS}
8284 @cvindex _ALL_SOURCE
8285 @cvindex _GNU_SOURCE
8287 @cvindex _POSIX_1_SOURCE
8288 @cvindex _POSIX_PTHREAD_SEMANTICS
8289 @cvindex _POSIX_SOURCE
8290 @cvindex _TANDEM_SOURCE
8291 @cvindex __EXTENSIONS__
8292 This macro was introduced in Autoconf 2.60. If possible, enable
8293 extensions to C or Posix on hosts that normally disable the extensions,
8294 typically due to standards-conformance namespace issues. This should be
8295 called before any macros that run the C compiler. The following
8296 preprocessor macros are defined where appropriate:
8300 Enable extensions on GNU/Linux.
8301 @item __EXTENSIONS__
8302 Enable general extensions on Solaris.
8303 @item _POSIX_PTHREAD_SEMANTICS
8304 Enable threading extensions on Solaris.
8305 @item _TANDEM_SOURCE
8306 Enable extensions for the HP NonStop platform.
8308 Enable extensions for AIX 3, and for Interix.
8310 Enable Posix functions for Minix.
8311 @item _POSIX_1_SOURCE
8312 Enable additional Posix functions for Minix.
8314 Identify Minix platform. This particular preprocessor macro is
8315 obsolescent, and may be removed in a future release of Autoconf.
8320 @node Erlang Libraries
8321 @section Erlang Libraries
8322 @cindex Erlang, Library, checking
8324 The following macros check for an installation of Erlang/OTP, and for the
8325 presence of certain Erlang libraries. All those macros require the
8326 configuration of an Erlang interpreter and an Erlang compiler
8327 (@pxref{Erlang Compiler and Interpreter}).
8329 @defmac AC_ERLANG_SUBST_ERTS_VER
8330 @acindex{ERLANG_SUBST_ERTS_VER}
8331 @ovindex ERLANG_ERTS_VER
8332 Set the output variable @code{ERLANG_ERTS_VER} to the version of the
8333 Erlang runtime system (as returned by Erlang's
8334 @code{erlang:system_info(version)} function). The result of this test
8335 is cached if caching is enabled when running @command{configure}. The
8336 @code{ERLANG_ERTS_VER} variable is not intended to be used for testing
8337 for features of specific ERTS versions, but to be used for substituting
8338 the ERTS version in Erlang/OTP release resource files (@code{.rel}
8339 files), as shown below.
8342 @defmac AC_ERLANG_SUBST_ROOT_DIR
8343 @acindex{ERLANG_SUBST_ROOT_DIR}
8344 @ovindex ERLANG_ROOT_DIR
8345 Set the output variable @code{ERLANG_ROOT_DIR} to the path to the base
8346 directory in which Erlang/OTP is installed (as returned by Erlang's
8347 @code{code:root_dir/0} function). The result of this test is cached if
8348 caching is enabled when running @command{configure}.
8351 @defmac AC_ERLANG_SUBST_LIB_DIR
8352 @acindex{ERLANG_SUBST_LIB_DIR}
8353 @ovindex ERLANG_LIB_DIR
8354 Set the output variable @code{ERLANG_LIB_DIR} to the path of the library
8355 directory of Erlang/OTP (as returned by Erlang's
8356 @code{code:lib_dir/0} function), which subdirectories each contain an installed
8357 Erlang/OTP library. The result of this test is cached if caching is enabled
8358 when running @command{configure}.
8361 @defmac AC_ERLANG_CHECK_LIB (@var{library}, @ovar{action-if-found}, @
8362 @ovar{action-if-not-found})
8363 @acindex{ERLANG_CHECK_LIB}
8364 @ovindex ERLANG_LIB_DIR_@var{library}
8365 @ovindex ERLANG_LIB_VER_@var{library}
8366 Test whether the Erlang/OTP library @var{library} is installed by
8367 calling Erlang's @code{code:lib_dir/1} function. The result of this
8368 test is cached if caching is enabled when running @command{configure}.
8369 @var{action-if-found} is a list of shell commands to run if the library
8370 is installed; @var{action-if-not-found} is a list of shell commands to
8371 run if it is not. Additionally, if the library is installed, the output
8372 variable @samp{ERLANG_LIB_DIR_@var{library}} is set to the path to the
8373 library installation directory, and the output variable
8374 @samp{ERLANG_LIB_VER_@var{library}} is set to the version number that is
8375 part of the subdirectory name, if it is in the standard form
8376 (@code{@var{library}-@var{version}}). If the directory name does not
8377 have a version part, @samp{ERLANG_LIB_VER_@var{library}} is set to the
8378 empty string. If the library is not installed,
8379 @samp{ERLANG_LIB_DIR_@var{library}} and
8380 @samp{ERLANG_LIB_VER_@var{library}} are set to @code{"not found"}. For
8381 example, to check if library @code{stdlib} is installed:
8384 AC_ERLANG_CHECK_LIB([stdlib],
8385 [echo "stdlib version \"$ERLANG_LIB_VER_stdlib\""
8386 echo "is installed in \"$ERLANG_LIB_DIR_stdlib\""],
8387 [AC_MSG_ERROR([stdlib was not found!])])
8390 The @samp{ERLANG_LIB_VER_@var{library}} variables (set by
8391 @code{AC_ERLANG_CHECK_LIB}) and the @code{ERLANG_ERTS_VER} variable (set
8392 by @code{AC_ERLANG_SUBST_ERTS_VER}) are not intended to be used for
8393 testing for features of specific versions of libraries or of the Erlang
8394 runtime system. Those variables are intended to be substituted in
8395 Erlang release resource files (@code{.rel} files). For instance, to
8396 generate a @file{example.rel} file for an application depending on the
8397 @code{stdlib} library, @file{configure.ac} could contain:
8400 AC_ERLANG_SUBST_ERTS_VER
8401 AC_ERLANG_CHECK_LIB([stdlib],
8403 [AC_MSG_ERROR([stdlib was not found!])])
8404 AC_CONFIG_FILES([example.rel])
8408 The @file{example.rel.in} file used to generate @file{example.rel}
8413 @{"@@PACKAGE@@", "@@VERSION@@"@},
8414 @{erts, "@@ERLANG_ERTS_VER@@"@},
8415 [@{stdlib, "@@ERLANG_LIB_VER_stdlib@@"@},
8416 @{@@PACKAGE@@, "@@VERSION@@"@}]@}.
8420 In addition to the above macros, which test installed Erlang libraries, the
8421 following macros determine the paths to the directories into which newly built
8422 Erlang libraries are to be installed:
8424 @defmac AC_ERLANG_SUBST_INSTALL_LIB_DIR
8425 @acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
8426 @ovindex ERLANG_INSTALL_LIB_DIR
8428 Set the @code{ERLANG_INSTALL_LIB_DIR} output variable to the directory into
8429 which every built Erlang library should be installed in a separate
8431 If this variable is not set in the environment when @command{configure} runs,
8432 its default value is @code{$@{libdir@}/erlang/lib}.
8435 @defmac AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR (@var{library}, @var{version})
8436 @acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
8437 @ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
8439 Set the @samp{ERLANG_INSTALL_LIB_DIR_@var{library}} output variable to the
8440 directory into which the built Erlang library @var{library} version
8441 @var{version} should be installed. If this variable is not set in the
8442 environment when @command{configure} runs, its default value is
8443 @samp{$ERLANG_INSTALL_LIB_DIR/@var{library}-@var{version}}, the value of the
8444 @code{ERLANG_INSTALL_LIB_DIR} variable being set by the
8445 @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR} macro.
8452 @c ========================================================= Writing Tests
8455 @chapter Writing Tests
8457 If the existing feature tests don't do something you need, you have to
8458 write new ones. These macros are the building blocks. They provide
8459 ways for other macros to check whether various kinds of features are
8460 available and report the results.
8462 This chapter contains some suggestions and some of the reasons why the
8463 existing tests are written the way they are. You can also learn a lot
8464 about how to write Autoconf tests by looking at the existing ones. If
8465 something goes wrong in one or more of the Autoconf tests, this
8466 information can help you understand the assumptions behind them, which
8467 might help you figure out how to best solve the problem.
8469 These macros check the output of the compiler system of the current
8470 language (@pxref{Language Choice}). They do not cache the results of
8471 their tests for future use (@pxref{Caching Results}), because they don't
8472 know enough about the information they are checking for to generate a
8473 cache variable name. They also do not print any messages, for the same
8474 reason. The checks for particular kinds of features call these macros
8475 and do cache their results and print messages about what they're
8478 When you write a feature test that could be applicable to more than one
8479 software package, the best thing to do is encapsulate it in a new macro.
8480 @xref{Writing Autoconf Macros}, for how to do that.
8483 * Language Choice:: Selecting which language to use for testing
8484 * Writing Test Programs:: Forging source files for compilers
8485 * Running the Preprocessor:: Detecting preprocessor symbols
8486 * Running the Compiler:: Detecting language or header features
8487 * Running the Linker:: Detecting library features
8488 * Runtime:: Testing for runtime features
8489 * Systemology:: A zoology of operating systems
8490 * Multiple Cases:: Tests for several possible values
8493 @node Language Choice
8494 @section Language Choice
8497 Autoconf-generated @command{configure} scripts check for the C compiler and
8498 its features by default. Packages that use other programming languages
8499 (maybe more than one, e.g., C and C++) need to test features of the
8500 compilers for the respective languages. The following macros determine
8501 which programming language is used in the subsequent tests in
8502 @file{configure.ac}.
8505 @defmac AC_LANG (@var{language})
8506 Do compilation tests using the compiler, preprocessor, and file
8507 extensions for the specified @var{language}.
8509 Supported languages are:
8513 Do compilation tests using @code{CC} and @code{CPP} and use extension
8514 @file{.c} for test programs. Use compilation flags: @code{CPPFLAGS} with
8515 @code{CPP}, and both @code{CPPFLAGS} and @code{CFLAGS} with @code{CC}.
8518 Do compilation tests using @code{CXX} and @code{CXXCPP} and use
8519 extension @file{.C} for test programs. Use compilation flags:
8520 @code{CPPFLAGS} with @code{CXXCPP}, and both @code{CPPFLAGS} and
8521 @code{CXXFLAGS} with @code{CXX}.
8524 Do compilation tests using @code{F77} and use extension @file{.f} for
8525 test programs. Use compilation flags: @code{FFLAGS}.
8528 Do compilation tests using @code{FC} and use extension @file{.f} (or
8529 whatever has been set by @code{AC_FC_SRCEXT}) for test programs. Use
8530 compilation flags: @code{FCFLAGS}.
8536 Compile and execute tests using @code{ERLC} and @code{ERL} and use extension
8537 @file{.erl} for test Erlang modules. Use compilation flags: @code{ERLCFLAGS}.
8540 Do compilation tests using @code{OBJC} and @code{OBJCPP} and use
8541 extension @file{.m} for test programs. Use compilation flags:
8542 @code{CPPFLAGS} with @code{OBJCPP}, and both @code{CPPFLAGS} and
8543 @code{OBJCFLAGS} with @code{OBJC}.
8546 Do compilation tests using @code{OBJCXX} and @code{OBJCXXCPP} and use
8547 extension @file{.mm} for test programs. Use compilation flags:
8548 @code{CPPFLAGS} with @code{OBJCXXCPP}, and both @code{CPPFLAGS} and
8549 @code{OBJCXXFLAGS} with @code{OBJCXX}.
8553 @anchor{AC_LANG_PUSH}
8554 @defmac AC_LANG_PUSH (@var{language})
8556 Remember the current language (as set by @code{AC_LANG}) on a stack, and
8557 then select the @var{language}. Use this macro and @code{AC_LANG_POP}
8558 in macros that need to temporarily switch to a particular language.
8561 @defmac AC_LANG_POP (@ovar{language})
8563 Select the language that is saved on the top of the stack, as set by
8564 @code{AC_LANG_PUSH}, and remove it from the stack.
8566 If given, @var{language} specifies the language we just @emph{quit}. It
8567 is a good idea to specify it when it's known (which should be the
8568 case@dots{}), since Autoconf detects inconsistencies.
8571 AC_LANG_PUSH([Fortran 77])
8572 # Perform some tests on Fortran 77.
8574 AC_LANG_POP([Fortran 77])
8578 @defmac AC_LANG_ASSERT (@var{language})
8579 @acindex{LANG_ASSERT} Check statically that the current language is
8580 @var{language}. You should use this in your language specific macros
8581 to avoid that they be called with an inappropriate language.
8583 This macro runs only at @command{autoconf} time, and incurs no cost at
8584 @command{configure} time. Sadly enough and because Autoconf is a two
8585 layer language @footnote{Because M4 is not aware of Sh code,
8586 especially conditionals, some optimizations that look nice statically
8587 may produce incorrect results at runtime.}, the macros
8588 @code{AC_LANG_PUSH} and @code{AC_LANG_POP} cannot be ``optimizing'',
8589 therefore as much as possible you ought to avoid using them to wrap
8590 your code, rather, require from the user to run the macro with a
8591 correct current language, and check it with @code{AC_LANG_ASSERT}.
8592 And anyway, that may help the user understand she is running a Fortran
8593 macro while expecting a result about her Fortran 77 compiler@enddots{}
8597 @defmac AC_REQUIRE_CPP
8598 @acindex{REQUIRE_CPP}
8599 Ensure that whichever preprocessor would currently be used for tests has
8600 been found. Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an
8601 argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP},
8602 depending on which language is current.
8606 @node Writing Test Programs
8607 @section Writing Test Programs
8609 Autoconf tests follow a common scheme: feed some program with some
8610 input, and most of the time, feed a compiler with some source file.
8611 This section is dedicated to these source samples.
8614 * Guidelines:: General rules for writing test programs
8615 * Test Functions:: Avoiding pitfalls in test programs
8616 * Generating Sources:: Source program boilerplate
8620 @subsection Guidelines for Test Programs
8622 The most important rule to follow when writing testing samples is:
8624 @center @emph{Look for realism.}
8626 This motto means that testing samples must be written with the same
8627 strictness as real programs are written. In particular, you should
8628 avoid ``shortcuts'' and simplifications.
8630 Don't just play with the preprocessor if you want to prepare a
8631 compilation. For instance, using @command{cpp} to check whether a header is
8632 functional might let your @command{configure} accept a header which
8633 causes some @emph{compiler} error. Do not hesitate to check a header with
8634 other headers included before, especially required headers.
8636 Make sure the symbols you use are properly defined, i.e., refrain from
8637 simply declaring a function yourself instead of including the proper
8640 Test programs should not write to standard output. They
8641 should exit with status 0 if the test succeeds, and with status 1
8642 otherwise, so that success
8643 can be distinguished easily from a core dump or other failure;
8644 segmentation violations and other failures produce a nonzero exit
8645 status. Unless you arrange for @code{exit} to be declared, test
8646 programs should @code{return}, not @code{exit}, from @code{main},
8647 because on many systems @code{exit} is not declared by default.
8649 Test programs can use @code{#if} or @code{#ifdef} to check the values of
8650 preprocessor macros defined by tests that have already run. For
8651 example, if you call @code{AC_HEADER_STDBOOL}, then later on in
8652 @file{configure.ac} you can have a test program that includes
8653 @file{stdbool.h} conditionally:
8657 #ifdef HAVE_STDBOOL_H
8658 # include <stdbool.h>
8663 Both @code{#if HAVE_STDBOOL_H} and @code{#ifdef HAVE_STDBOOL_H} will
8664 work with any standard C compiler. Some developers prefer @code{#if}
8665 because it is easier to read, while others prefer @code{#ifdef} because
8666 it avoids diagnostics with picky compilers like GCC with the
8667 @option{-Wundef} option.
8669 If a test program needs to use or create a data file, give it a name
8670 that starts with @file{conftest}, such as @file{conftest.data}. The
8671 @command{configure} script cleans up by running @samp{rm -f -r conftest*}
8672 after running test programs and if the script is interrupted.
8674 @node Test Functions
8675 @subsection Test Functions
8677 These days it's safe to assume support for function prototypes
8678 (introduced in C89).
8680 Functions that test programs declare should also be conditionalized for
8681 C++, which requires @samp{extern "C"} prototypes. Make sure to not
8682 include any header files containing clashing prototypes.
8688 void *valloc (size_t);
8691 If a test program calls a function with invalid parameters (just to see
8692 whether it exists), organize the program to ensure that it never invokes
8693 that function. You can do this by calling it in another function that is
8694 never invoked. You can't do it by putting it after a call to
8695 @code{exit}, because GCC version 2 knows that @code{exit}
8697 and optimizes out any code that follows it in the same block.
8699 If you include any header files, be sure to call the functions
8700 relevant to them with the correct number of arguments, even if they are
8701 just 0, to avoid compilation errors due to prototypes. GCC
8703 has internal prototypes for several functions that it automatically
8704 inlines; for example, @code{memcpy}. To avoid errors when checking for
8705 them, either pass them the correct number of arguments or redeclare them
8706 with a different return type (such as @code{char}).
8709 @node Generating Sources
8710 @subsection Generating Sources
8712 Autoconf provides a set of macros that can be used to generate test
8713 source files. They are written to be language generic, i.e., they
8714 actually depend on the current language (@pxref{Language Choice}) to
8715 ``format'' the output properly.
8718 @defmac AC_LANG_CONFTEST (@var{source})
8719 @acindex{LANG_CONFTEST}
8720 Save the @var{source} text in the current test source file:
8721 @file{conftest.@var{extension}} where the @var{extension} depends on the
8722 current language. As of Autoconf 2.63b, the source file also contains
8723 the results of all of the @code{AC_DEFINE} performed so far.
8725 Note that the @var{source} is evaluated exactly once, like regular
8726 Autoconf macro arguments, and therefore (i) you may pass a macro
8727 invocation, (ii) if not, be sure to double quote if needed.
8730 @defmac AC_LANG_SOURCE (@var{source})
8731 @acindex{LANG_SOURCE}
8732 Expands into the @var{source}, with the definition of
8733 all the @code{AC_DEFINE} performed so far.
8736 For instance executing (observe the double quotation!):
8739 @c If you change this example, adjust tests/compile.at:AC_LANG_SOURCE example.
8740 AC_INIT([Hello], [1.0], [bug-hello@@example.org], [],
8741 [http://www.example.org/])
8742 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
8743 [Greetings string.])
8746 [AC_LANG_SOURCE([[const char hw[] = "Hello, World\n";]])])
8747 gcc -E -dD -o - conftest.c
8751 on a system with @command{gcc} installed, results in:
8754 @c If you change this example, adjust tests/compile.at:AC_LANG_SOURCE example.
8758 #define PACKAGE_NAME "Hello"
8759 #define PACKAGE_TARNAME "hello"
8760 #define PACKAGE_VERSION "1.0"
8761 #define PACKAGE_STRING "Hello 1.0"
8762 #define PACKAGE_BUGREPORT "bug-hello@@example.org"
8763 #define PACKAGE_URL "http://www.example.org/"
8764 #define HELLO_WORLD "Hello, World\n"
8766 const char hw[] = "Hello, World\n";
8769 When the test language is Fortran or Erlang, the @code{AC_DEFINE} definitions
8770 are not automatically translated into constants in the source code by this
8773 @defmac AC_LANG_PROGRAM (@var{prologue}, @var{body})
8774 @acindex{LANG_PROGRAM}
8775 Expands into a source file which consists of the @var{prologue}, and
8776 then @var{body} as body of the main function (e.g., @code{main} in
8777 C). Since it uses @code{AC_LANG_SOURCE}, the features of the latter are
8784 @c If you change this example, adjust tests/compile.at:AC_LANG_PROGRAM example.
8785 AC_INIT([Hello], [1.0], [bug-hello@@example.org], [],
8786 [http://www.example.org/])
8787 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
8788 [Greetings string.])
8790 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
8791 [[fputs (hw, stdout);]])])
8792 gcc -E -dD -o - conftest.c
8796 on a system with @command{gcc} installed, results in:
8799 @c If you change this example, adjust tests/compile.at:AC_LANG_PROGRAM example.
8803 #define PACKAGE_NAME "Hello"
8804 #define PACKAGE_TARNAME "hello"
8805 #define PACKAGE_VERSION "1.0"
8806 #define PACKAGE_STRING "Hello 1.0"
8807 #define PACKAGE_BUGREPORT "bug-hello@@example.org"
8808 #define PACKAGE_URL "http://www.example.org/"
8809 #define HELLO_WORLD "Hello, World\n"
8811 const char hw[] = "Hello, World\n";
8821 In Erlang tests, the created source file is that of an Erlang module called
8822 @code{conftest} (@file{conftest.erl}). This module defines and exports
8824 one @code{start/0} function, which is called to perform the test. The
8825 @var{prologue} is optional code that is inserted between the module header and
8826 the @code{start/0} function definition. @var{body} is the body of the
8827 @code{start/0} function without the final period (@pxref{Runtime}, about
8828 constraints on this function's behavior).
8833 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
8836 [AC_LANG_PROGRAM([[-define(HELLO_WORLD, "Hello, world!").]],
8837 [[io:format("~s~n", [?HELLO_WORLD])]])])
8847 -define(HELLO_WORLD, "Hello, world!").
8849 io:format("~s~n", [?HELLO_WORLD])
8853 @defmac AC_LANG_CALL (@var{prologue}, @var{function})
8855 Expands into a source file which consists of the @var{prologue}, and
8856 then a call to the @var{function} as body of the main function (e.g.,
8857 @code{main} in C). Since it uses @code{AC_LANG_PROGRAM}, the feature
8858 of the latter are available.
8860 This function will probably be replaced in the future by a version
8861 which would enable specifying the arguments. The use of this macro is
8862 not encouraged, as it violates strongly the typing system.
8864 This macro cannot be used for Erlang tests.
8867 @defmac AC_LANG_FUNC_LINK_TRY (@var{function})
8868 @acindex{LANG_FUNC_LINK_TRY}
8869 Expands into a source file which uses the @var{function} in the body of
8870 the main function (e.g., @code{main} in C). Since it uses
8871 @code{AC_LANG_PROGRAM}, the features of the latter are available.
8873 As @code{AC_LANG_CALL}, this macro is documented only for completeness.
8874 It is considered to be severely broken, and in the future will be
8875 removed in favor of actual function calls (with properly typed
8878 This macro cannot be used for Erlang tests.
8881 @node Running the Preprocessor
8882 @section Running the Preprocessor
8884 Sometimes one might need to run the preprocessor on some source file.
8885 @emph{Usually it is a bad idea}, as you typically need to @emph{compile}
8886 your project, not merely run the preprocessor on it; therefore you
8887 certainly want to run the compiler, not the preprocessor. Resist the
8888 temptation of following the easiest path.
8890 Nevertheless, if you need to run the preprocessor, then use
8891 @code{AC_PREPROC_IFELSE}.
8893 The macros described in this section cannot be used for tests in Erlang or
8894 Fortran, since those languages require no preprocessor.
8896 @anchor{AC_PREPROC_IFELSE}
8897 @defmac AC_PREPROC_IFELSE (@var{input}, @ovar{action-if-true}, @
8898 @ovar{action-if-false})
8899 @acindex{PREPROC_IFELSE}
8900 Run the preprocessor of the current language (@pxref{Language Choice})
8901 on the @var{input}, run the shell commands @var{action-if-true} on
8902 success, @var{action-if-false} otherwise. The @var{input} can be made
8903 by @code{AC_LANG_PROGRAM} and friends.
8905 This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because
8906 @option{-g}, @option{-O}, etc.@: are not valid options to many C
8909 It is customary to report unexpected failures with
8910 @code{AC_MSG_FAILURE}. If needed, @var{action-if-true} can further access
8911 the preprocessed output in the file @file{conftest.i}.
8917 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
8918 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
8919 [Greetings string.])
8921 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
8922 [[fputs (hw, stdout);]])],
8923 [AC_MSG_RESULT([OK])],
8924 [AC_MSG_FAILURE([unexpected preprocessor failure])])
8931 checking for gcc... gcc
8932 checking for C compiler default output file name... a.out
8933 checking whether the C compiler works... yes
8934 checking whether we are cross compiling... no
8935 checking for suffix of executables...
8936 checking for suffix of object files... o
8937 checking whether we are using the GNU C compiler... yes
8938 checking whether gcc accepts -g... yes
8939 checking for gcc option to accept ISO C89... none needed
8940 checking how to run the C preprocessor... gcc -E
8946 The macro @code{AC_TRY_CPP} (@pxref{Obsolete Macros}) used to play the
8947 role of @code{AC_PREPROC_IFELSE}, but double quotes its argument, making
8948 it impossible to use it to elaborate sources. You are encouraged to
8949 get rid of your old use of the macro @code{AC_TRY_CPP} in favor of
8950 @code{AC_PREPROC_IFELSE}, but, in the first place, are you sure you need
8951 to run the @emph{preprocessor} and not the compiler?
8953 @anchor{AC_EGREP_HEADER}
8954 @defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @
8955 @var{action-if-found}, @ovar{action-if-not-found})
8956 @acindex{EGREP_HEADER}
8957 If the output of running the preprocessor on the system header file
8958 @var{header-file} matches the extended regular expression
8959 @var{pattern}, execute shell commands @var{action-if-found}, otherwise
8960 execute @var{action-if-not-found}.
8963 @anchor{AC_EGREP_CPP}
8964 @defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @
8965 @ovar{action-if-found}, @ovar{action-if-not-found})
8967 @var{program} is the text of a C or C++ program, on which shell
8968 variable, back quote, and backslash substitutions are performed. If the
8969 output of running the preprocessor on @var{program} matches the
8970 extended regular expression @var{pattern}, execute shell commands
8971 @var{action-if-found}, otherwise execute @var{action-if-not-found}.
8976 @node Running the Compiler
8977 @section Running the Compiler
8979 To check for a syntax feature of the current language's (@pxref{Language
8980 Choice}) compiler, such as whether it recognizes a certain keyword, or
8981 simply to try some library feature, use @code{AC_COMPILE_IFELSE} to try
8982 to compile a small program that uses that feature.
8984 @defmac AC_COMPILE_IFELSE (@var{input}, @ovar{action-if-true}, @
8985 @ovar{action-if-false})
8986 @acindex{COMPILE_IFELSE}
8987 Run the compiler and compilation flags of the current language
8988 (@pxref{Language Choice}) on the @var{input}, run the shell commands
8989 @var{action-if-true} on success, @var{action-if-false} otherwise. The
8990 @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
8992 It is customary to report unexpected failures with
8993 @code{AC_MSG_FAILURE}. This macro does not try to link; use
8994 @code{AC_LINK_IFELSE} if you need to do that (@pxref{Running the
8995 Linker}). If needed, @var{action-if-true} can further access the
8996 just-compiled object file @file{conftest.$OBJEXT}.
8998 This macro uses @code{AC_REQUIRE} for the compiler associated with the
8999 current language, which means that if the compiler has not yet been
9000 determined, the compiler determination will be made prior to the body of
9001 the outermust @code{AC_DEFUN} macro that triggered this macro to
9002 expand (@pxref{Expanded Before Required}).
9006 For tests in Erlang, the @var{input} must be the source code of a module named
9007 @code{conftest}. @code{AC_COMPILE_IFELSE} generates a @file{conftest.beam}
9008 file that can be interpreted by the Erlang virtual machine (@code{ERL}). It is
9009 recommended to use @code{AC_LANG_PROGRAM} to specify the test program,
9010 to ensure that the Erlang module has the right name.
9012 @node Running the Linker
9013 @section Running the Linker
9015 To check for a library, a function, or a global variable, Autoconf
9016 @command{configure} scripts try to compile and link a small program that
9017 uses it. This is unlike Metaconfig, which by default uses @code{nm} or
9018 @code{ar} on the C library to try to figure out which functions are
9019 available. Trying to link with the function is usually a more reliable
9020 approach because it avoids dealing with the variations in the options
9021 and output formats of @code{nm} and @code{ar} and in the location of the
9022 standard libraries. It also allows configuring for cross-compilation or
9023 checking a function's runtime behavior if needed. On the other hand,
9024 it can be slower than scanning the libraries once, but accuracy is more
9025 important than speed.
9027 @code{AC_LINK_IFELSE} is used to compile test programs to test for
9028 functions and global variables. It is also used by @code{AC_CHECK_LIB}
9029 to check for libraries (@pxref{Libraries}), by adding the library being
9030 checked for to @code{LIBS} temporarily and trying to link a small
9033 @anchor{AC_LINK_IFELSE}
9034 @defmac AC_LINK_IFELSE (@var{input}, @ovar{action-if-true}, @
9035 @ovar{action-if-false})
9036 @acindex{LINK_IFELSE}
9037 Run the compiler (and compilation flags) and the linker of the current
9038 language (@pxref{Language Choice}) on the @var{input}, run the shell
9039 commands @var{action-if-true} on success, @var{action-if-false}
9040 otherwise. The @var{input} can be made by @code{AC_LANG_PROGRAM} and
9041 friends. If needed, @var{action-if-true} can further access the
9042 just-linked program file @file{conftest$EXEEXT}.
9044 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
9045 current compilation flags.
9047 It is customary to report unexpected failures with
9048 @code{AC_MSG_FAILURE}. This macro does not try to execute the program;
9049 use @code{AC_RUN_IFELSE} if you need to do that (@pxref{Runtime}).
9052 The @code{AC_LINK_IFELSE} macro cannot be used for Erlang tests, since Erlang
9053 programs are interpreted and do not require linking.
9058 @section Checking Runtime Behavior
9060 Sometimes you need to find out how a system performs at runtime, such
9061 as whether a given function has a certain capability or bug. If you
9062 can, make such checks when your program runs instead of when it is
9063 configured. You can check for things like the machine's endianness when
9064 your program initializes itself.
9066 If you really need to test for a runtime behavior while configuring,
9067 you can write a test program to determine the result, and compile and
9068 run it using @code{AC_RUN_IFELSE}. Avoid running test programs if
9069 possible, because this prevents people from configuring your package for
9072 @anchor{AC_RUN_IFELSE}
9073 @defmac AC_RUN_IFELSE (@var{input}, @ovar{action-if-true}, @
9074 @ovar{action-if-false}, @ovar{action-if-cross-compiling})
9075 @acindex{RUN_IFELSE}
9076 If @var{program} compiles and links successfully and returns an exit
9077 status of 0 when executed, run shell commands @var{action-if-true}.
9078 Otherwise, run shell commands @var{action-if-false}.
9080 The @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
9081 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
9082 compilation flags of the current language (@pxref{Language Choice}).
9083 Additionally, @var{action-if-true} can run @command{./conftest$EXEEXT}
9084 for further testing.
9086 If the compiler being used does not produce executables that run on the
9087 system where @command{configure} is being run, then the test program is
9088 not run. If the optional shell commands @var{action-if-cross-compiling}
9089 are given, they are run instead. Otherwise, @command{configure} prints
9090 an error message and exits.
9092 In the @var{action-if-false} section, the failing exit status is
9093 available in the shell variable @samp{$?}. This exit status might be
9094 that of a failed compilation, or it might be that of a failed program
9097 It is customary to report unexpected failures with
9098 @code{AC_MSG_FAILURE}.
9101 Try to provide a pessimistic default value to use when cross-compiling
9102 makes runtime tests impossible. You do this by passing the optional
9103 last argument to @code{AC_RUN_IFELSE}. @command{autoconf} prints a
9104 warning message when creating @command{configure} each time it
9105 encounters a call to @code{AC_RUN_IFELSE} with no
9106 @var{action-if-cross-compiling} argument given. You may ignore the
9107 warning, though users cannot configure your package for
9108 cross-compiling. A few of the macros distributed with Autoconf produce
9109 this warning message.
9111 To configure for cross-compiling you can also choose a value for those
9112 parameters based on the canonical system name (@pxref{Manual
9113 Configuration}). Alternatively, set up a test results cache file with
9114 the correct values for the host system (@pxref{Caching Results}).
9116 @ovindex cross_compiling
9117 To provide a default for calls of @code{AC_RUN_IFELSE} that are embedded
9118 in other macros, including a few of the ones that come with Autoconf,
9119 you can test whether the shell variable @code{cross_compiling} is set to
9120 @samp{yes}, and then use an alternate method to get the results instead
9121 of calling the macros.
9123 It is also permissible to temporarily assign to @code{cross_compiling}
9124 in order to force tests to behave as though they are in a
9125 cross-compilation environment, particularly since this provides a way to
9126 test your @var{action-if-cross-compiling} even when you are not using a
9130 # We temporarily set cross-compile mode to force AC_COMPUTE_INT
9131 # to use the slow link-only method
9132 save_cross_compiling=$cross_compiling
9134 AC_COMPUTE_INT([@dots{}])
9135 cross_compiling=$save_cross_compiling
9138 A C or C++ runtime test should be portable.
9139 @xref{Portable C and C++}.
9141 Erlang tests must exit themselves the Erlang VM by calling the @code{halt/1}
9142 function: the given status code is used to determine the success of the test
9143 (status is @code{0}) or its failure (status is different than @code{0}), as
9144 explained above. It must be noted that data output through the standard output
9145 (e.g., using @code{io:format/2}) may be truncated when halting the VM.
9146 Therefore, if a test must output configuration information, it is recommended
9147 to create and to output data into the temporary file named @file{conftest.out},
9148 using the functions of module @code{file}. The @code{conftest.out} file is
9149 automatically deleted by the @code{AC_RUN_IFELSE} macro. For instance, a
9150 simplified implementation of Autoconf's @code{AC_ERLANG_SUBST_LIB_DIR}
9154 AC_INIT([LibdirTest], [1.0], [bug-libdirtest@@example.org])
9158 [AC_LANG_PROGRAM([], [dnl
9159 file:write_file("conftest.out", code:lib_dir()),
9161 [echo "code:lib_dir() returned: `cat conftest.out`"],
9162 [AC_MSG_FAILURE([test Erlang program execution failed])])
9167 @section Systemology
9170 This section aims at presenting some systems and pointers to
9171 documentation. It may help you addressing particular problems reported
9174 @uref{http://@/www.opengroup.org/@/susv3, Posix-conforming systems} are
9175 derived from the @uref{http://@/www.bell-labs.com/@/history/@/unix/, Unix
9178 The @uref{http://@/bhami.com/@/rosetta.html, Rosetta Stone for Unix}
9179 contains a table correlating the features of various Posix-conforming
9180 systems. @uref{http://@/www.levenez.com/@/unix/, Unix History} is a
9181 simplified diagram of how many Unix systems were derived from each
9184 @uref{http://@/heirloom.sourceforge.net/, The Heirloom Project}
9185 provides some variants of traditional implementations of Unix utilities.
9190 Darwin is also known as Mac OS X@. Beware that the file system @emph{can} be
9191 case-preserving, but case insensitive. This can cause nasty problems,
9192 since for instance the installation attempt for a package having an
9193 @file{INSTALL} file can result in @samp{make install} report that
9194 nothing was to be done!
9196 That's all dependent on whether the file system is a UFS (case
9197 sensitive) or HFS+ (case preserving). By default Apple wants you to
9198 install the OS on HFS+. Unfortunately, there are some pieces of
9199 software which really need to be built on UFS@. We may want to rebuild
9200 Darwin to have both UFS and HFS+ available (and put the /local/build
9205 @c FIXME: Please, if you feel like writing something more precise,
9206 @c it'd be great. In particular, I can't understand the difference with
9208 QNX is a realtime operating system running on Intel architecture
9209 meant to be scalable from the small embedded systems to the hundred
9210 processor super-computer. It claims to be Posix certified. More
9211 information is available on the
9212 @uref{http://@/www.qnx.com/, QNX home page}.
9216 @uref{http://@/h30097.www3.hp.com/@/docs/,
9217 Documentation of several versions of Tru64} is available in different
9220 @item Unix version 7
9221 @cindex Unix version 7
9223 Officially this was called the ``Seventh Edition'' of ``the UNIX
9224 time-sharing system'' but we use the more-common name ``Unix version 7''.
9225 Documentation is available in the
9226 @uref{http://@/plan9.bell-labs.com/@/7thEdMan/, Unix Seventh Edition Manual}.
9227 Previous versions of Unix are called ``Unix version 6'', etc., but
9228 they were not as widely used.
9232 @node Multiple Cases
9233 @section Multiple Cases
9235 Some operations are accomplished in several possible ways, depending on
9236 the OS variant. Checking for them essentially requires a ``case
9237 statement''. Autoconf does not directly provide one; however, it is
9238 easy to simulate by using a shell variable to keep track of whether a
9239 way to perform the operation has been found yet.
9241 Here is an example that uses the shell variable @code{fstype} to keep
9242 track of whether the remaining cases need to be checked. Note that
9243 since the value of @code{fstype} is under our control, we don't have to
9244 use the longer @samp{test "x$fstype" = xno}.
9248 AC_MSG_CHECKING([how to get file system type])
9250 # The order of these tests is important.
9251 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statvfs.h>
9252 #include <sys/fstyp.h>]])],
9253 [AC_DEFINE([FSTYPE_STATVFS], [1],
9254 [Define if statvfs exists.])
9256 if test $fstype = no; then
9257 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
9258 #include <sys/fstyp.h>]])],
9259 [AC_DEFINE([FSTYPE_USG_STATFS], [1],
9260 [Define if USG statfs.])
9263 if test $fstype = no; then
9264 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
9265 #include <sys/vmount.h>]])]),
9266 [AC_DEFINE([FSTYPE_AIX_STATFS], [1],
9267 [Define if AIX statfs.])
9270 # (more cases omitted here)
9271 AC_MSG_RESULT([$fstype])
9275 @c ====================================================== Results of Tests.
9278 @chapter Results of Tests
9280 Once @command{configure} has determined whether a feature exists, what can
9281 it do to record that information? There are four sorts of things it can
9282 do: define a C preprocessor symbol, set a variable in the output files,
9283 save the result in a cache file for future @command{configure} runs, and
9284 print a message letting the user know the result of the test.
9287 * Defining Symbols:: Defining C preprocessor symbols
9288 * Setting Output Variables:: Replacing variables in output files
9289 * Special Chars in Variables:: Characters to beware of in variables
9290 * Caching Results:: Speeding up subsequent @command{configure} runs
9291 * Printing Messages:: Notifying @command{configure} users
9294 @node Defining Symbols
9295 @section Defining C Preprocessor Symbols
9297 A common action to take in response to a feature test is to define a C
9298 preprocessor symbol indicating the results of the test. That is done by
9299 calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}.
9301 By default, @code{AC_OUTPUT} places the symbols defined by these macros
9302 into the output variable @code{DEFS}, which contains an option
9303 @option{-D@var{symbol}=@var{value}} for each symbol defined. Unlike in
9304 Autoconf version 1, there is no variable @code{DEFS} defined while
9305 @command{configure} is running. To check whether Autoconf macros have
9306 already defined a certain C preprocessor symbol, test the value of the
9307 appropriate cache variable, as in this example:
9310 AC_CHECK_FUNC([vprintf], [AC_DEFINE([HAVE_VPRINTF], [1],
9311 [Define if vprintf exists.])])
9312 if test "x$ac_cv_func_vprintf" != xyes; then
9313 AC_CHECK_FUNC([_doprnt], [AC_DEFINE([HAVE_DOPRNT], [1],
9314 [Define if _doprnt exists.])])
9318 If @code{AC_CONFIG_HEADERS} has been called, then instead of creating
9319 @code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the
9320 correct values into @code{#define} statements in a template file.
9321 @xref{Configuration Headers}, for more information about this kind of
9324 @defmac AC_DEFINE (@var{variable}, @var{value}, @ovar{description})
9325 @defmacx AC_DEFINE (@var{variable})
9326 @cvindex @var{variable}
9328 Define @var{variable} to @var{value} (verbatim), by defining a C
9329 preprocessor macro for @var{variable}. @var{variable} should be a C
9330 identifier, optionally suffixed by a parenthesized argument list to
9331 define a C preprocessor macro with arguments. The macro argument list,
9332 if present, should be a comma-separated list of C identifiers, possibly
9333 terminated by an ellipsis @samp{...} if C99 syntax is employed.
9334 @var{variable} should not contain comments, white space, trigraphs,
9335 backslash-newlines, universal character names, or non-ASCII
9338 @var{value} may contain backslash-escaped newlines, which will be
9339 preserved if you use @code{AC_CONFIG_HEADERS} but flattened if passed
9340 via @code{@@DEFS@@} (with no effect on the compilation, since the
9341 preprocessor sees only one line in the first place). @var{value} should
9342 not contain raw newlines. If you are not using
9343 @code{AC_CONFIG_HEADERS}, @var{value} should not contain any @samp{#}
9344 characters, as @command{make} tends to eat them. To use a shell
9345 variable, use @code{AC_DEFINE_UNQUOTED} instead.
9347 @var{description} is only useful if you are using
9348 @code{AC_CONFIG_HEADERS}. In this case, @var{description} is put into
9349 the generated @file{config.h.in} as the comment before the macro define.
9350 The following example defines the C preprocessor variable
9351 @code{EQUATION} to be the string constant @samp{"$a > $b"}:
9354 AC_DEFINE([EQUATION], ["$a > $b"],
9358 If neither @var{value} nor @var{description} are given, then
9359 @var{value} defaults to 1 instead of to the empty string. This is for
9360 backwards compatibility with older versions of Autoconf, but this usage
9361 is obsolescent and may be withdrawn in future versions of Autoconf.
9363 If the @var{variable} is a literal string, it is passed to
9364 @code{m4_pattern_allow} (@pxref{Forbidden Patterns}).
9366 If multiple @code{AC_DEFINE} statements are executed for the same
9367 @var{variable} name (not counting any parenthesized argument list),
9371 @defmac AC_DEFINE_UNQUOTED (@var{variable}, @var{value}, @ovar{description})
9372 @defmacx AC_DEFINE_UNQUOTED (@var{variable})
9373 @acindex{DEFINE_UNQUOTED}
9374 @cvindex @var{variable}
9375 Like @code{AC_DEFINE}, but three shell expansions are
9376 performed---once---on @var{variable} and @var{value}: variable expansion
9377 (@samp{$}), command substitution (@samp{`}), and backslash escaping
9378 (@samp{\}), as if in an unquoted here-document. Single and double quote
9379 characters in the value have no
9380 special meaning. Use this macro instead of @code{AC_DEFINE} when
9381 @var{variable} or @var{value} is a shell variable. Examples:
9384 AC_DEFINE_UNQUOTED([config_machfile], ["$machfile"],
9385 [Configuration machine file.])
9386 AC_DEFINE_UNQUOTED([GETGROUPS_T], [$ac_cv_type_getgroups],
9387 [getgroups return type.])
9388 AC_DEFINE_UNQUOTED([$ac_tr_hdr], [1],
9389 [Translated header name.])
9393 Due to a syntactical bizarreness of the Bourne shell, do not use
9394 semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}
9395 calls from other macro calls or shell code; that can cause syntax errors
9396 in the resulting @command{configure} script. Use either blanks or
9397 newlines. That is, do this:
9400 AC_CHECK_HEADER([elf.h],
9401 [AC_DEFINE([SVR4], [1], [System V Release 4]) LIBS="-lelf $LIBS"])
9408 AC_CHECK_HEADER([elf.h],
9409 [AC_DEFINE([SVR4], [1], [System V Release 4])
9410 LIBS="-lelf $LIBS"])
9417 AC_CHECK_HEADER([elf.h],
9418 [AC_DEFINE([SVR4], [1], [System V Release 4]); LIBS="-lelf $LIBS"])
9421 @node Setting Output Variables
9422 @section Setting Output Variables
9423 @cindex Output variables
9425 Another way to record the results of tests is to set @dfn{output
9426 variables}, which are shell variables whose values are substituted into
9427 files that @command{configure} outputs. The two macros below create new
9428 output variables. @xref{Preset Output Variables}, for a list of output
9429 variables that are always available.
9431 @defmac AC_SUBST (@var{variable}, @ovar{value})
9433 Create an output variable from a shell variable. Make @code{AC_OUTPUT}
9434 substitute the variable @var{variable} into output files (typically one
9435 or more makefiles). This means that @code{AC_OUTPUT}
9436 replaces instances of @samp{@@@var{variable}@@} in input files with the
9437 value that the shell variable @var{variable} has when @code{AC_OUTPUT}
9438 is called. The value can contain any non-@code{NUL} character, including
9439 newline. If you are using Automake 1.11 or newer, for newlines in values
9440 you might want to consider using @code{AM_SUBST_NOTMAKE} to prevent
9441 @command{automake} from adding a line @code{@var{variable} =
9442 @@@var{variable}@@} to the @file{Makefile.in} files (@pxref{Optional, ,
9443 Automake, automake, Other things Automake recognizes}).
9445 Variable occurrences should not overlap: e.g., an input file should
9446 not contain @samp{@@@var{var1}@@@var{var2}@@} if @var{var1} and @var{var2}
9448 The substituted value is not rescanned for more output variables;
9449 occurrences of @samp{@@@var{variable}@@} in the value are inserted
9450 literally into the output file. (The algorithm uses the special marker
9451 @code{|#_!!_#|} internally, so neither the substituted value nor the
9452 output file may contain @code{|#_!!_#|}.)
9454 If @var{value} is given, in addition assign it to @var{variable}.
9456 The string @var{variable} is passed to @code{m4_pattern_allow}
9457 (@pxref{Forbidden Patterns}).
9460 @defmac AC_SUBST_FILE (@var{variable})
9461 @acindex{SUBST_FILE}
9462 Another way to create an output variable from a shell variable. Make
9463 @code{AC_OUTPUT} insert (without substitutions) the contents of the file
9464 named by shell variable @var{variable} into output files. This means
9465 that @code{AC_OUTPUT} replaces instances of
9466 @samp{@@@var{variable}@@} in output files (such as @file{Makefile.in})
9467 with the contents of the file that the shell variable @var{variable}
9468 names when @code{AC_OUTPUT} is called. Set the variable to
9469 @file{/dev/null} for cases that do not have a file to insert.
9470 This substitution occurs only when the @samp{@@@var{variable}@@} is on a
9471 line by itself, optionally surrounded by spaces and tabs. The
9472 substitution replaces the whole line, including the spaces, tabs, and
9473 the terminating newline.
9475 This macro is useful for inserting makefile fragments containing
9476 special dependencies or other @command{make} directives for particular host
9477 or target types into makefiles. For example, @file{configure.ac}
9481 AC_SUBST_FILE([host_frag])
9482 host_frag=$srcdir/conf/sun4.mh
9486 and then a @file{Makefile.in} could contain:
9492 The string @var{variable} is passed to @code{m4_pattern_allow}
9493 (@pxref{Forbidden Patterns}).
9496 @cindex Precious Variable
9497 @cindex Variable, Precious
9498 Running @command{configure} in varying environments can be extremely
9499 dangerous. If for instance the user runs @samp{CC=bizarre-cc
9500 ./configure}, then the cache, @file{config.h}, and many other output
9501 files depend upon @command{bizarre-cc} being the C compiler. If
9502 for some reason the user runs @command{./configure} again, or if it is
9503 run via @samp{./config.status --recheck}, (@xref{Automatic Remaking},
9504 and @pxref{config.status Invocation}), then the configuration can be
9505 inconsistent, composed of results depending upon two different
9508 Environment variables that affect this situation, such as @samp{CC}
9509 above, are called @dfn{precious variables}, and can be declared as such
9510 by @code{AC_ARG_VAR}.
9512 @defmac AC_ARG_VAR (@var{variable}, @var{description})
9514 Declare @var{variable} is a precious variable, and include its
9515 @var{description} in the variable section of @samp{./configure --help}.
9517 Being precious means that
9520 @var{variable} is substituted via @code{AC_SUBST}.
9523 The value of @var{variable} when @command{configure} was launched is
9524 saved in the cache, including if it was not specified on the command
9525 line but via the environment. Indeed, while @command{configure} can
9526 notice the definition of @code{CC} in @samp{./configure CC=bizarre-cc},
9527 it is impossible to notice it in @samp{CC=bizarre-cc ./configure},
9528 which, unfortunately, is what most users do.
9530 We emphasize that it is the @emph{initial} value of @var{variable} which
9531 is saved, not that found during the execution of @command{configure}.
9532 Indeed, specifying @samp{./configure FOO=foo} and letting
9533 @samp{./configure} guess that @code{FOO} is @code{foo} can be two
9537 @var{variable} is checked for consistency between two
9538 @command{configure} runs. For instance:
9541 $ @kbd{./configure --silent --config-cache}
9542 $ @kbd{CC=cc ./configure --silent --config-cache}
9543 configure: error: `CC' was not set in the previous run
9544 configure: error: changes in the environment can compromise \
9546 configure: error: run `make distclean' and/or \
9547 `rm config.cache' and start over
9551 and similarly if the variable is unset, or if its content is changed.
9552 If the content has white space changes only, then the error is degraded
9553 to a warning only, but the old value is reused.
9556 @var{variable} is kept during automatic reconfiguration
9557 (@pxref{config.status Invocation}) as if it had been passed as a command
9558 line argument, including when no cache is used:
9561 $ @kbd{CC=/usr/bin/cc ./configure var=raboof --silent}
9562 $ @kbd{./config.status --recheck}
9563 running CONFIG_SHELL=/bin/sh /bin/sh ./configure var=raboof \
9564 CC=/usr/bin/cc --no-create --no-recursion
9569 @node Special Chars in Variables
9570 @section Special Characters in Output Variables
9571 @cindex Output variables, special characters in
9573 Many output variables are intended to be evaluated both by
9574 @command{make} and by the shell. Some characters are expanded
9575 differently in these two contexts, so to avoid confusion these
9576 variables' values should not contain any of the following characters:
9579 " # $ & ' ( ) * ; < > ? [ \ ^ ` |
9582 Also, these variables' values should neither contain newlines, nor start
9583 with @samp{~}, nor contain white space or @samp{:} immediately followed
9584 by @samp{~}. The values can contain nonempty sequences of white space
9585 characters like tabs and spaces, but each such sequence might
9586 arbitrarily be replaced by a single space during substitution.
9588 These restrictions apply both to the values that @command{configure}
9589 computes, and to the values set directly by the user. For example, the
9590 following invocations of @command{configure} are problematic, since they
9591 attempt to use special characters within @code{CPPFLAGS} and white space
9592 within @code{$(srcdir)}:
9595 CPPFLAGS='-DOUCH="&\"#$*?"' '../My Source/ouch-1.0/configure'
9597 '../My Source/ouch-1.0/configure' CPPFLAGS='-DOUCH="&\"#$*?"'
9600 @node Caching Results
9601 @section Caching Results
9604 To avoid checking for the same features repeatedly in various
9605 @command{configure} scripts (or in repeated runs of one script),
9606 @command{configure} can optionally save the results of many checks in a
9607 @dfn{cache file} (@pxref{Cache Files}). If a @command{configure} script
9608 runs with caching enabled and finds a cache file, it reads the results
9609 of previous runs from the cache and avoids rerunning those checks. As a
9610 result, @command{configure} can then run much faster than if it had to
9611 perform all of the checks every time.
9613 @defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it})
9615 Ensure that the results of the check identified by @var{cache-id} are
9616 available. If the results of the check were in the cache file that was
9617 read, and @command{configure} was not given the @option{--quiet} or
9618 @option{--silent} option, print a message saying that the result was
9619 cached; otherwise, run the shell commands @var{commands-to-set-it}. If
9620 the shell commands are run to determine the value, the value is
9621 saved in the cache file just before @command{configure} creates its output
9622 files. @xref{Cache Variable Names}, for how to choose the name of the
9623 @var{cache-id} variable.
9625 The @var{commands-to-set-it} @emph{must have no side effects} except for
9626 setting the variable @var{cache-id}, see below.
9629 @defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @
9630 @var{commands-to-set-it})
9631 @acindex{CACHE_CHECK}
9632 A wrapper for @code{AC_CACHE_VAL} that takes care of printing the
9633 messages. This macro provides a convenient shorthand for the most
9634 common way to use these macros. It calls @code{AC_MSG_CHECKING} for
9635 @var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and
9636 @var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}.
9638 The @var{commands-to-set-it} @emph{must have no side effects} except for
9639 setting the variable @var{cache-id}, see below.
9642 It is common to find buggy macros using @code{AC_CACHE_VAL} or
9643 @code{AC_CACHE_CHECK}, because people are tempted to call
9644 @code{AC_DEFINE} in the @var{commands-to-set-it}. Instead, the code that
9645 @emph{follows} the call to @code{AC_CACHE_VAL} should call
9646 @code{AC_DEFINE}, by examining the value of the cache variable. For
9647 instance, the following macro is broken:
9650 @c If you change this example, adjust tests/base.at:AC_CACHE_CHECK.
9652 AC_DEFUN([AC_SHELL_TRUE],
9653 [AC_CACHE_CHECK([whether true(1) works], [my_cv_shell_true_works],
9654 [my_cv_shell_true_works=no
9655 (true) 2>/dev/null && my_cv_shell_true_works=yes
9656 if test "x$my_cv_shell_true_works" = xyes; then
9657 AC_DEFINE([TRUE_WORKS], [1],
9658 [Define if `true(1)' works properly.])
9665 This fails if the cache is enabled: the second time this macro is run,
9666 @code{TRUE_WORKS} @emph{will not be defined}. The proper implementation
9670 @c If you change this example, adjust tests/base.at:AC_CACHE_CHECK.
9672 AC_DEFUN([AC_SHELL_TRUE],
9673 [AC_CACHE_CHECK([whether true(1) works], [my_cv_shell_true_works],
9674 [my_cv_shell_true_works=no
9675 (true) 2>/dev/null && my_cv_shell_true_works=yes])
9676 if test "x$my_cv_shell_true_works" = xyes; then
9677 AC_DEFINE([TRUE_WORKS], [1],
9678 [Define if `true(1)' works properly.])
9684 Also, @var{commands-to-set-it} should not print any messages, for
9685 example with @code{AC_MSG_CHECKING}; do that before calling
9686 @code{AC_CACHE_VAL}, so the messages are printed regardless of whether
9687 the results of the check are retrieved from the cache or determined by
9688 running the shell commands.
9691 * Cache Variable Names:: Shell variables used in caches
9692 * Cache Files:: Files @command{configure} uses for caching
9693 * Cache Checkpointing:: Loading and saving the cache file
9696 @node Cache Variable Names
9697 @subsection Cache Variable Names
9698 @cindex Cache variable
9700 The names of cache variables should have the following format:
9703 @var{package-prefix}_cv_@var{value-type}_@var{specific-value}_@ovar{additional-options}
9707 for example, @samp{ac_cv_header_stat_broken} or
9708 @samp{ac_cv_prog_gcc_traditional}. The parts of the variable name are:
9711 @item @var{package-prefix}
9712 An abbreviation for your package or organization; the same prefix you
9713 begin local Autoconf macros with, except lowercase by convention.
9714 For cache values used by the distributed Autoconf macros, this value is
9718 Indicates that this shell variable is a cache value. This string
9719 @emph{must} be present in the variable name, including the leading
9722 @item @var{value-type}
9723 A convention for classifying cache values, to produce a rational naming
9724 system. The values used in Autoconf are listed in @ref{Macro Names}.
9726 @item @var{specific-value}
9727 Which member of the class of cache values this test applies to.
9728 For example, which function (@samp{alloca}), program (@samp{gcc}), or
9729 output variable (@samp{INSTALL}).
9731 @item @var{additional-options}
9732 Any particular behavior of the specific member that this test applies to.
9733 For example, @samp{broken} or @samp{set}. This part of the name may
9734 be omitted if it does not apply.
9737 The values assigned to cache variables may not contain newlines.
9738 Usually, their values are Boolean (@samp{yes} or @samp{no}) or the
9739 names of files or functions; so this is not an important restriction.
9740 @ref{Cache Variable Index} for an index of cache variables with
9741 documented semantics.
9745 @subsection Cache Files
9747 A cache file is a shell script that caches the results of configure
9748 tests run on one system so they can be shared between configure scripts
9749 and configure runs. It is not useful on other systems. If its contents
9750 are invalid for some reason, the user may delete or edit it, or override
9751 documented cache variables on the @command{configure} command line.
9753 By default, @command{configure} uses no cache file,
9754 to avoid problems caused by accidental
9755 use of stale cache files.
9757 To enable caching, @command{configure} accepts @option{--config-cache} (or
9758 @option{-C}) to cache results in the file @file{config.cache}.
9759 Alternatively, @option{--cache-file=@var{file}} specifies that
9760 @var{file} be the cache file. The cache file is created if it does not
9761 exist already. When @command{configure} calls @command{configure} scripts in
9762 subdirectories, it uses the @option{--cache-file} argument so that they
9763 share the same cache. @xref{Subdirectories}, for information on
9764 configuring subdirectories with the @code{AC_CONFIG_SUBDIRS} macro.
9766 @file{config.status} only pays attention to the cache file if it is
9767 given the @option{--recheck} option, which makes it rerun
9768 @command{configure}.
9770 It is wrong to try to distribute cache files for particular system types.
9771 There is too much room for error in doing that, and too much
9772 administrative overhead in maintaining them. For any features that
9773 can't be guessed automatically, use the standard method of the canonical
9774 system type and linking files (@pxref{Manual Configuration}).
9776 The site initialization script can specify a site-wide cache file to
9777 use, instead of the usual per-program cache. In this case, the cache
9778 file gradually accumulates information whenever someone runs a new
9779 @command{configure} script. (Running @command{configure} merges the new cache
9780 results with the existing cache file.) This may cause problems,
9781 however, if the system configuration (e.g., the installed libraries or
9782 compilers) changes and the stale cache file is not deleted.
9784 @node Cache Checkpointing
9785 @subsection Cache Checkpointing
9787 If your configure script, or a macro called from @file{configure.ac}, happens
9788 to abort the configure process, it may be useful to checkpoint the cache
9789 a few times at key points using @code{AC_CACHE_SAVE}. Doing so
9790 reduces the amount of time it takes to rerun the configure script with
9791 (hopefully) the error that caused the previous abort corrected.
9793 @c FIXME: Do we really want to document this guy?
9794 @defmac AC_CACHE_LOAD
9795 @acindex{CACHE_LOAD}
9796 Loads values from existing cache file, or creates a new cache file if a
9797 cache file is not found. Called automatically from @code{AC_INIT}.
9800 @defmac AC_CACHE_SAVE
9801 @acindex{CACHE_SAVE}
9802 Flushes all cached values to the cache file. Called automatically from
9803 @code{AC_OUTPUT}, but it can be quite useful to call
9804 @code{AC_CACHE_SAVE} at key points in @file{configure.ac}.
9810 @r{ @dots{} AC_INIT, etc. @dots{}}
9812 # Checks for programs.
9815 @r{ @dots{} more program checks @dots{}}
9820 # Checks for libraries.
9821 AC_CHECK_LIB([nsl], [gethostbyname])
9822 AC_CHECK_LIB([socket], [connect])
9823 @r{ @dots{} more lib checks @dots{}}
9828 # Might abort@dots{}
9829 AM_PATH_GTK([1.0.2], [], [AC_MSG_ERROR([GTK not in path])])
9830 AM_PATH_GTKMM([0.9.5], [], [AC_MSG_ERROR([GTK not in path])])
9832 @r{ @dots{} AC_OUTPUT, etc. @dots{}}
9835 @node Printing Messages
9836 @section Printing Messages
9837 @cindex Messages, from @command{configure}
9839 @command{configure} scripts need to give users running them several kinds
9840 of information. The following macros print messages in ways appropriate
9841 for each kind. The arguments to all of them get enclosed in shell
9842 double quotes, so the shell performs variable and back-quote
9843 substitution on them.
9845 These macros are all wrappers around the @command{echo} shell command.
9846 They direct output to the appropriate file descriptor (@pxref{File
9847 Descriptor Macros}).
9848 @command{configure} scripts should rarely need to run @command{echo} directly
9849 to print messages for the user. Using these macros makes it easy to
9850 change how and when each kind of message is printed; such changes need
9851 only be made to the macro definitions and all the callers change
9854 To diagnose static issues, i.e., when @command{autoconf} is run, see
9855 @ref{Diagnostic Macros}.
9857 @defmac AC_MSG_CHECKING (@var{feature-description})
9858 @acindex{MSG_CHECKING}
9859 Notify the user that @command{configure} is checking for a particular
9860 feature. This macro prints a message that starts with @samp{checking }
9861 and ends with @samp{...} and no newline. It must be followed by a call
9862 to @code{AC_MSG_RESULT} to print the result of the check and the
9863 newline. The @var{feature-description} should be something like
9864 @samp{whether the Fortran compiler accepts C++ comments} or @samp{for
9867 This macro prints nothing if @command{configure} is run with the
9868 @option{--quiet} or @option{--silent} option.
9871 @anchor{AC_MSG_RESULT}
9872 @defmac AC_MSG_RESULT (@var{result-description})
9873 @acindex{MSG_RESULT}
9874 Notify the user of the results of a check. @var{result-description} is
9875 almost always the value of the cache variable for the check, typically
9876 @samp{yes}, @samp{no}, or a file name. This macro should follow a call
9877 to @code{AC_MSG_CHECKING}, and the @var{result-description} should be
9878 the completion of the message printed by the call to
9879 @code{AC_MSG_CHECKING}.
9881 This macro prints nothing if @command{configure} is run with the
9882 @option{--quiet} or @option{--silent} option.
9885 @anchor{AC_MSG_NOTICE}
9886 @defmac AC_MSG_NOTICE (@var{message})
9887 @acindex{MSG_NOTICE}
9888 Deliver the @var{message} to the user. It is useful mainly to print a
9889 general description of the overall purpose of a group of feature checks,
9893 AC_MSG_NOTICE([checking if stack overflow is detectable])
9896 This macro prints nothing if @command{configure} is run with the
9897 @option{--quiet} or @option{--silent} option.
9900 @anchor{AC_MSG_ERROR}
9901 @defmac AC_MSG_ERROR (@var{error-description}, @dvar{exit-status, $?/1})
9903 Notify the user of an error that prevents @command{configure} from
9904 completing. This macro prints an error message to the standard error
9905 output and exits @command{configure} with @var{exit-status} (@samp{$?}
9906 by default, except that @samp{0} is converted to @samp{1}).
9907 @var{error-description} should be something like @samp{invalid value
9910 The @var{error-description} should start with a lower-case letter, and
9911 ``cannot'' is preferred to ``can't''.
9914 @defmac AC_MSG_FAILURE (@var{error-description}, @ovar{exit-status})
9915 @acindex{MSG_FAILURE}
9916 This @code{AC_MSG_ERROR} wrapper notifies the user of an error that
9917 prevents @command{configure} from completing @emph{and} that additional
9918 details are provided in @file{config.log}. This is typically used when
9919 abnormal results are found during a compilation.
9922 @anchor{AC_MSG_WARN}
9923 @defmac AC_MSG_WARN (@var{problem-description})
9925 Notify the @command{configure} user of a possible problem. This macro
9926 prints the message to the standard error output; @command{configure}
9927 continues running afterward, so macros that call @code{AC_MSG_WARN} should
9928 provide a default (back-up) behavior for the situations they warn about.
9929 @var{problem-description} should be something like @samp{ln -s seems to
9935 @c ====================================================== Programming in M4.
9937 @node Programming in M4
9938 @chapter Programming in M4
9941 Autoconf is written on top of two layers: @dfn{M4sugar}, which provides
9942 convenient macros for pure M4 programming, and @dfn{M4sh}, which
9943 provides macros dedicated to shell script generation.
9945 As of this version of Autoconf, these two layers still contain
9946 experimental macros, whose interface might change in the future. As a
9947 matter of fact, @emph{anything that is not documented must not be used}.
9950 * M4 Quotation:: Protecting macros from unwanted expansion
9951 * Using autom4te:: The Autoconf executables backbone
9952 * Programming in M4sugar:: Convenient pure M4 macros
9953 * Debugging via autom4te:: Figuring out what M4 was doing
9957 @section M4 Quotation
9958 @cindex M4 quotation
9961 The most common problem with existing macros is an improper quotation.
9962 This section, which users of Autoconf can skip, but which macro writers
9963 @emph{must} read, first justifies the quotation scheme that was chosen
9964 for Autoconf and then ends with a rule of thumb. Understanding the
9965 former helps one to follow the latter.
9968 * Active Characters:: Characters that change the behavior of M4
9969 * One Macro Call:: Quotation and one macro call
9970 * Quoting and Parameters:: M4 vs. shell parameters
9971 * Quotation and Nested Macros:: Macros calling macros
9972 * Changequote is Evil:: Worse than INTERCAL: M4 + changequote
9973 * Quadrigraphs:: Another way to escape special characters
9974 * Balancing Parentheses:: Dealing with unbalanced parentheses
9975 * Quotation Rule Of Thumb:: One parenthesis, one quote
9978 @node Active Characters
9979 @subsection Active Characters
9981 To fully understand where proper quotation is important, you first need
9982 to know what the special characters are in Autoconf: @samp{#} introduces
9983 a comment inside which no macro expansion is performed, @samp{,}
9984 separates arguments, @samp{[} and @samp{]} are the quotes
9985 themselves@footnote{By itself, M4 uses @samp{`} and @samp{'}; it is the
9986 M4sugar layer that sets up the preferred quotes of @samp{[} and @samp{]}.},
9987 @samp{(} and @samp{)} (which M4 tries to match by pairs), and finally
9988 @samp{$} inside a macro definition.
9990 In order to understand the delicate case of macro calls, we first have
9991 to present some obvious failures. Below they are ``obvious-ified'',
9992 but when you find them in real life, they are usually in disguise.
9994 Comments, introduced by a hash and running up to the newline, are opaque
9995 tokens to the top level: active characters are turned off, and there is
9999 # define([def], ine)
10000 @result{}# define([def], ine)
10003 Each time there can be a macro expansion, there is a quotation
10004 expansion, i.e., one level of quotes is stripped:
10008 @result{}int tab10;
10010 @result{}int tab[10];
10013 Without this in mind, the reader might try hopelessly to use her macro
10017 define([array], [int tab[10];])
10019 @result{}int tab10;
10025 How can you correctly output the intended results@footnote{Using
10029 @node One Macro Call
10030 @subsection One Macro Call
10032 Let's proceed on the interaction between active characters and macros
10033 with this small macro, which just returns its first argument:
10036 define([car], [$1])
10040 The two pairs of quotes above are not part of the arguments of
10041 @code{define}; rather, they are understood by the top level when it
10042 tries to find the arguments of @code{define}. Therefore, assuming
10043 @code{car} is not already defined, it is equivalent to write:
10050 But, while it is acceptable for a @file{configure.ac} to avoid unnecessary
10051 quotes, it is bad practice for Autoconf macros which must both be more
10052 robust and also advocate perfect style.
10054 At the top level, there are only two possibilities: either you
10055 quote or you don't:
10060 [car(foo, bar, baz)]
10061 @result{}car(foo, bar, baz)
10064 Let's pay attention to the special characters:
10068 @error{}EOF in argument list
10071 The closing parenthesis is hidden in the comment; with a hypothetical
10072 quoting, the top level understood it this way:
10079 Proper quotation, of course, fixes the problem:
10086 Here are more examples:
10094 @result{}(foo, bar)
10095 car([(foo], [bar)])
10109 @node Quoting and Parameters
10110 @subsection Quoting and Parameters
10112 When M4 encounters @samp{$} within a macro definition, followed
10113 immediately by a character it recognizes (@samp{0}@dots{}@samp{9},
10114 @samp{#}, @samp{@@}, or @samp{*}), it will perform M4 parameter
10115 expansion. This happens regardless of how many layers of quotes the
10116 parameter expansion is nested within, or even if it occurs in text that
10117 will be rescanned as a comment.
10120 define([none], [$1])
10122 define([one], [[$1]])
10124 define([two], [[[$1]]])
10126 define([comment], [# $1])
10128 define([active], [ACTIVE])
10140 On the other hand, since autoconf generates shell code, you often want
10141 to output shell variable expansion, rather than performing M4 parameter
10142 expansion. To do this, you must use M4 quoting to separate the @samp{$}
10143 from the next character in the definition of your macro. If the macro
10144 definition occurs in single-quoted text, then insert another level of
10145 quoting; if the usage is already inside a double-quoted string, then
10146 split it into concatenated strings.
10149 define([single], [a single-quoted $[]1 definition])
10151 define([double], [[a double-quoted $][1 definition]])
10154 @result{}a single-quoted $1 definition
10156 @result{}a double-quoted $1 definition
10159 Posix states that M4 implementations are free to provide implementation
10160 extensions when @samp{$@{} is encountered in a macro definition.
10161 Autoconf reserves the longer sequence @samp{$@{@{} for use with planned
10162 extensions that will be available in the future GNU M4 2.0,
10163 but guarantees that all other instances of @samp{$@{} will be output
10164 literally. Therefore, this idiom can also be used to output shell code
10165 parameter references:
10168 define([first], [$@{1@}])first
10172 Posix also states that @samp{$11} should expand to the first parameter
10173 concatenated with a literal @samp{1}, although some versions of
10174 GNU M4 expand the eleventh parameter instead. For
10175 portability, you should only use single-digit M4 parameter expansion.
10177 With this in mind, we can explore the cases where macros invoke
10180 @node Quotation and Nested Macros
10181 @subsection Quotation and Nested Macros
10183 The examples below use the following macros:
10186 define([car], [$1])
10187 define([active], [ACT, IVE])
10188 define([array], [int tab[10]])
10191 Each additional embedded macro call introduces other possible
10192 interesting quotations:
10203 In the first case, the top level looks for the arguments of @code{car},
10204 and finds @samp{active}. Because M4 evaluates its arguments
10205 before applying the macro, @samp{active} is expanded, which results in:
10213 In the second case, the top level gives @samp{active} as first and only
10214 argument of @code{car}, which results in:
10222 i.e., the argument is evaluated @emph{after} the macro that invokes it.
10223 In the third case, @code{car} receives @samp{[active]}, which results in:
10231 exactly as we already saw above.
10233 The example above, applied to a more realistic example, gives:
10237 @result{}int tab10;
10238 car([int tab[10];])
10239 @result{}int tab10;
10240 car([[int tab[10];]])
10241 @result{}int tab[10];
10245 Huh? The first case is easily understood, but why is the second wrong,
10246 and the third right? To understand that, you must know that after
10247 M4 expands a macro, the resulting text is immediately subjected
10248 to macro expansion and quote removal. This means that the quote removal
10249 occurs twice---first before the argument is passed to the @code{car}
10250 macro, and second after the @code{car} macro expands to the first
10253 As the author of the Autoconf macro @code{car}, you then consider it to
10254 be incorrect that your users have to double-quote the arguments of
10255 @code{car}, so you ``fix'' your macro. Let's call it @code{qar} for
10259 define([qar], [[$1]])
10263 and check that @code{qar} is properly fixed:
10266 qar([int tab[10];])
10267 @result{}int tab[10];
10271 Ahhh! That's much better.
10273 But note what you've done: now that the result of @code{qar} is always
10274 a literal string, the only time a user can use nested macros is if she
10275 relies on an @emph{unquoted} macro call:
10285 leaving no way for her to reproduce what she used to do with @code{car}:
10293 Worse yet: she wants to use a macro that produces a set of @code{cpp}
10297 define([my_includes], [#include <stdio.h>])
10299 @result{}#include <stdio.h>
10301 @error{}EOF in argument list
10304 This macro, @code{qar}, because it double quotes its arguments, forces
10305 its users to leave their macro calls unquoted, which is dangerous.
10306 Commas and other active symbols are interpreted by M4 before
10307 they are given to the macro, often not in the way the users expect.
10308 Also, because @code{qar} behaves differently from the other macros,
10309 it's an exception that should be avoided in Autoconf.
10311 @node Changequote is Evil
10312 @subsection @code{changequote} is Evil
10313 @cindex @code{changequote}
10315 The temptation is often high to bypass proper quotation, in particular
10316 when it's late at night. Then, many experienced Autoconf hackers
10317 finally surrender to the dark side of the force and use the ultimate
10318 weapon: @code{changequote}.
10320 The M4 builtin @code{changequote} belongs to a set of primitives that
10321 allow one to adjust the syntax of the language to adjust it to one's
10322 needs. For instance, by default M4 uses @samp{`} and @samp{'} as
10323 quotes, but in the context of shell programming (and actually of most
10324 programming languages), that's about the worst choice one can make:
10325 because of strings and back-quoted expressions in shell code (such as
10326 @samp{'this'} and @samp{`that`}), and because of literal characters in usual
10327 programming languages (as in @samp{'0'}), there are many unbalanced
10328 @samp{`} and @samp{'}. Proper M4 quotation then becomes a nightmare, if
10329 not impossible. In order to make M4 useful in such a context, its
10330 designers have equipped it with @code{changequote}, which makes it
10331 possible to choose another pair of quotes. M4sugar, M4sh, Autoconf, and
10332 Autotest all have chosen to use @samp{[} and @samp{]}. Not especially
10333 because they are unlikely characters, but @emph{because they are
10334 characters unlikely to be unbalanced}.
10336 There are other magic primitives, such as @code{changecom} to specify
10337 what syntactic forms are comments (it is common to see
10338 @samp{changecom(<!--, -->)} when M4 is used to produce HTML pages),
10339 @code{changeword} and @code{changesyntax} to change other syntactic
10340 details (such as the character to denote the @var{n}th argument, @samp{$} by
10341 default, the parentheses around arguments, etc.).
10343 These primitives are really meant to make M4 more useful for specific
10344 domains: they should be considered like command line options:
10345 @option{--quotes}, @option{--comments}, @option{--words}, and
10346 @option{--syntax}. Nevertheless, they are implemented as M4 builtins, as
10347 it makes M4 libraries self contained (no need for additional options).
10349 There lies the problem@enddots{}
10353 The problem is that it is then tempting to use them in the middle of an
10354 M4 script, as opposed to its initialization. This, if not carefully
10355 thought out, can lead to disastrous effects: @emph{you are changing the
10356 language in the middle of the execution}. Changing and restoring the
10357 syntax is often not enough: if you happened to invoke macros in between,
10358 these macros are lost, as the current syntax is probably not
10359 the one they were implemented with.
10361 @c FIXME: I've been looking for a short, real case example, but I
10362 @c lost them all :(
10366 @subsection Quadrigraphs
10367 @cindex quadrigraphs
10368 @cindex @samp{@@S|@@}
10369 @cindex @samp{@@&t@@}
10370 @c Info cannot handle `:' in index entries.
10372 @cindex @samp{@@<:@@}
10373 @cindex @samp{@@:>@@}
10374 @cindex @samp{@@%:@@}
10375 @cindex @samp{@@@{:@@}
10376 @cindex @samp{@@:@}@@}
10379 When writing an Autoconf macro you may occasionally need to generate
10380 special characters that are difficult to express with the standard
10381 Autoconf quoting rules. For example, you may need to output the regular
10382 expression @samp{[^[]}, which matches any character other than @samp{[}.
10383 This expression contains unbalanced brackets so it cannot be put easily
10386 Additionally, there are a few m4sugar macros (such as @code{m4_split}
10387 and @code{m4_expand}) which internally use special markers in addition
10388 to the regular quoting characters. If the arguments to these macros
10389 contain the literal strings @samp{-=<@{(} or @samp{)@}>=-}, the macros
10390 might behave incorrectly.
10392 You can work around these problems by using one of the following
10393 @dfn{quadrigraphs}:
10409 Expands to nothing.
10412 Quadrigraphs are replaced at a late stage of the translation process,
10413 after @command{m4} is run, so they do not get in the way of M4 quoting.
10414 For example, the string @samp{^@@<:@@}, independently of its quotation,
10415 appears as @samp{^[} in the output.
10417 The empty quadrigraph can be used:
10420 @item to mark trailing spaces explicitly
10422 Trailing spaces are smashed by @command{autom4te}. This is a feature.
10424 @item to produce quadrigraphs and other strings reserved by m4sugar
10426 For instance @samp{@@<@@&t@@:@@} produces @samp{@@<:@@}. For a more
10430 m4_define([a], [A])m4_define([b], [B])m4_define([c], [C])dnl
10431 m4_split([a )@}>=- b -=<@{( c])
10432 @result{}[a], [], [B], [], [c]
10433 m4_split([a )@}@@&t@@>=- b -=<@@&t@@@{( c])
10434 @result{}[a], [)@}>=-], [b], [-=<@{(], [c]
10437 @item to escape @emph{occurrences} of forbidden patterns
10439 For instance you might want to mention @code{AC_FOO} in a comment, while
10440 still being sure that @command{autom4te} still catches unexpanded
10441 @samp{AC_*}. Then write @samp{AC@@&t@@_FOO}.
10444 The name @samp{@@&t@@} was suggested by Paul Eggert:
10447 I should give some credit to the @samp{@@&t@@} pun. The @samp{&} is my
10448 own invention, but the @samp{t} came from the source code of the
10449 ALGOL68C compiler, written by Steve Bourne (of Bourne shell fame),
10450 and which used @samp{mt} to denote the empty string. In C, it would
10451 have looked like something like:
10454 char const mt[] = "";
10458 but of course the source code was written in Algol 68.
10460 I don't know where he got @samp{mt} from: it could have been his own
10461 invention, and I suppose it could have been a common pun around the
10462 Cambridge University computer lab at the time.
10466 @node Balancing Parentheses
10467 @subsection Dealing with unbalanced parentheses
10468 @cindex balancing parentheses
10469 @cindex parentheses, balancing
10470 @cindex unbalanced parentheses, managing
10472 One of the pitfalls of portable shell programming is that @command{case}
10473 statements require unbalanced parentheses (@pxref{case, , Limitations of
10474 Shell Builtins}). With syntax highlighting
10475 editors, the presence of unbalanced @samp{)} can interfere with editors
10476 that perform syntax highlighting of macro contents based on finding the
10477 matching @samp{(}. Another concern is how much editing must be done
10478 when transferring code snippets between shell scripts and macro
10479 definitions. But most importantly, the presence of unbalanced
10480 parentheses can introduce expansion bugs.
10482 For an example, here is an underquoted attempt to use the macro
10483 @code{my_case}, which happens to expand to a portable @command{case}
10487 AC_DEFUN([my_case],
10488 [case $file_name in
10489 *.c) echo "C source code";;
10495 In the above example, the @code{AS_IF} call underquotes its arguments.
10496 As a result, the unbalanced @samp{)} generated by the premature
10497 expansion of @code{my_case} results in expanding @code{AS_IF} with a
10498 truncated parameter, and the expansion is syntactically invalid:
10504 fi echo "C source code";;
10508 If nothing else, this should emphasize the importance of the quoting
10509 arguments to macro calls. On the other hand, there are several
10510 variations for defining @code{my_case} to be more robust, even when used
10511 without proper quoting, each with some benefits and some drawbacks.
10514 @item Creative literal shell comment
10516 AC_DEFUN([my_case],
10517 [case $file_name in #(
10518 *.c) echo "C source code";;
10522 This version provides balanced parentheses to several editors, and can
10523 be copied and pasted into a terminal as is. Unfortunately, it is still
10524 unbalanced as an Autoconf argument, since @samp{#(} is an M4 comment
10525 that masks the normal properties of @samp{(}.
10527 @item Quadrigraph shell comment
10529 AC_DEFUN([my_case],
10530 [case $file_name in @@%:@@(
10531 *.c) echo "C source code";;
10535 This version provides balanced parentheses to even more editors, and can
10536 be used as a balanced Autoconf argument. Unfortunately, it requires
10537 some editing before it can be copied and pasted into a terminal, and the
10538 use of the quadrigraph @samp{@@%:@@} for @samp{#} reduces readability.
10540 @item Quoting just the parenthesis
10542 AC_DEFUN([my_case],
10543 [case $file_name in
10544 *.c[)] echo "C source code";;
10548 This version quotes the @samp{)}, so that it can be used as a balanced
10549 Autoconf argument. As written, this is not balanced to an editor, but
10550 it can be coupled with @samp{[#(]} to meet that need, too. However, it
10551 still requires some edits before it can be copied and pasted into a
10554 @item Double-quoting the entire statement
10556 AC_DEFUN([my_case],
10557 [[case $file_name in #(
10558 *.c) echo "C source code";;
10562 Since the entire macro is double-quoted, there is no problem with using
10563 this as an Autoconf argument; and since the double-quoting is over the
10564 entire statement, this code can be easily copied and pasted into a
10565 terminal. However, the double quoting prevents the expansion of any
10566 macros inside the case statement, which may cause its own set of
10569 @item Using @code{AS_CASE}
10571 AC_DEFUN([my_case],
10572 [AS_CASE([$file_name],
10573 [*.c], [echo "C source code"])])
10576 This version avoids the balancing issue altogether, by relying on
10577 @code{AS_CASE} (@pxref{Common Shell Constructs}); it also allows for the
10578 expansion of @code{AC_REQUIRE} to occur prior to the entire case
10579 statement, rather than within a branch of the case statement that might
10580 not be taken. However, the abstraction comes with a penalty that it is
10581 no longer a quick copy, paste, and edit to get back to shell code.
10585 @node Quotation Rule Of Thumb
10586 @subsection Quotation Rule Of Thumb
10588 To conclude, the quotation rule of thumb is:
10590 @center @emph{One pair of quotes per pair of parentheses.}
10592 Never over-quote, never under-quote, in particular in the definition of
10593 macros. In the few places where the macros need to use brackets
10594 (usually in C program text or regular expressions), properly quote
10595 @emph{the arguments}!
10597 It is common to read Autoconf programs with snippets like:
10601 changequote(<<, >>)dnl
10602 <<#include <time.h>
10603 #ifndef tzname /* For SGI. */
10604 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
10606 changequote([, ])dnl
10607 [atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
10611 which is incredibly useless since @code{AC_TRY_LINK} is @emph{already}
10612 double quoting, so you just need:
10617 #ifndef tzname /* For SGI. */
10618 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
10621 [ac_cv_var_tzname=yes],
10622 [ac_cv_var_tzname=no])
10626 The M4-fluent reader might note that these two examples are rigorously
10627 equivalent, since M4 swallows both the @samp{changequote(<<, >>)}
10628 and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these
10629 quotes are not part of the arguments!
10631 Simplified, the example above is just doing this:
10634 changequote(<<, >>)dnl
10636 changequote([, ])dnl
10646 With macros that do not double quote their arguments (which is the
10647 rule), double-quote the (risky) literals:
10650 AC_LINK_IFELSE([AC_LANG_PROGRAM(
10651 [[#include <time.h>
10652 #ifndef tzname /* For SGI. */
10653 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
10655 [atoi (*tzname);])],
10656 [ac_cv_var_tzname=yes],
10657 [ac_cv_var_tzname=no])
10660 Please note that the macro @code{AC_TRY_LINK} is obsolete, so you really
10661 should be using @code{AC_LINK_IFELSE} instead.
10663 @xref{Quadrigraphs}, for what to do if you run into a hopeless case
10664 where quoting does not suffice.
10666 When you create a @command{configure} script using newly written macros,
10667 examine it carefully to check whether you need to add more quotes in
10668 your macros. If one or more words have disappeared in the M4
10669 output, you need more quotes. When in doubt, quote.
10671 However, it's also possible to put on too many layers of quotes. If
10672 this happens, the resulting @command{configure} script may contain
10673 unexpanded macros. The @command{autoconf} program checks for this problem
10674 by looking for the string @samp{AC_} in @file{configure}. However, this
10675 heuristic does not work in general: for example, it does not catch
10676 overquoting in @code{AC_DEFINE} descriptions.
10679 @c ---------------------------------------- Using autom4te
10681 @node Using autom4te
10682 @section Using @command{autom4te}
10684 The Autoconf suite, including M4sugar, M4sh, and Autotest, in addition
10685 to Autoconf per se, heavily rely on M4. All these different uses
10686 revealed common needs factored into a layer over M4:
10687 @command{autom4te}@footnote{
10689 Yet another great name from Lars J. Aas.
10693 @command{autom4te} is a preprocessor that is like @command{m4}.
10694 It supports M4 extensions designed for use in tools like Autoconf.
10697 * autom4te Invocation:: A GNU M4 wrapper
10698 * Customizing autom4te:: Customizing the Autoconf package
10701 @node autom4te Invocation
10702 @subsection Invoking @command{autom4te}
10704 The command line arguments are modeled after M4's:
10707 autom4te @var{options} @var{files}
10712 where the @var{files} are directly passed to @command{m4}. By default,
10713 GNU M4 is found during configuration, but the environment
10715 @env{M4} can be set to tell @command{autom4te} where to look. In addition
10716 to the regular expansion, it handles the replacement of the quadrigraphs
10717 (@pxref{Quadrigraphs}), and of @samp{__oline__}, the current line in the
10718 output. It supports an extended syntax for the @var{files}:
10721 @item @var{file}.m4f
10722 This file is an M4 frozen file. Note that @emph{all the previous files
10723 are ignored}. See the option @option{--melt} for the rationale.
10726 If found in the library path, the @var{file} is included for expansion,
10727 otherwise it is ignored instead of triggering a failure.
10732 Of course, it supports the Autoconf common subset of options:
10737 Print a summary of the command line options and exit.
10741 Print the version number of Autoconf and exit.
10745 Report processing steps.
10749 Don't remove the temporary files and be even more verbose.
10751 @item --include=@var{dir}
10752 @itemx -I @var{dir}
10753 Also look for input files in @var{dir}. Multiple invocations
10756 @item --output=@var{file}
10757 @itemx -o @var{file}
10758 Save output (script or trace) to @var{file}. The file @option{-} stands
10759 for the standard output.
10764 As an extension of @command{m4}, it includes the following options:
10767 @item --warnings=@var{category}
10768 @itemx -W @var{category}
10770 @c FIXME: Point to the M4sugar macros, not Autoconf's.
10771 Report the warnings related to @var{category} (which can actually be a
10772 comma separated list). @xref{Reporting Messages}, macro
10773 @code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
10778 report all the warnings
10784 treats warnings as errors
10786 @item no-@var{category}
10787 disable warnings falling into @var{category}
10790 Warnings about @samp{syntax} are enabled by default, and the environment
10791 variable @env{WARNINGS}, a comma separated list of categories, is
10792 honored. @samp{autom4te -W @var{category}} actually
10793 behaves as if you had run:
10796 autom4te --warnings=syntax,$WARNINGS,@var{category}
10800 For example, if you want to disable defaults and @env{WARNINGS}
10801 of @command{autom4te}, but enable the warnings about obsolete
10802 constructs, you would use @option{-W none,obsolete}.
10805 @cindex Macro invocation stack
10806 @command{autom4te} displays a back trace for errors, but not for
10807 warnings; if you want them, just pass @option{-W error}.
10811 Do not use frozen files. Any argument @code{@var{file}.m4f} is
10812 replaced by @code{@var{file}.m4}. This helps tracing the macros which
10813 are executed only when the files are frozen, typically
10814 @code{m4_define}. For instance, running:
10817 autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4
10821 is roughly equivalent to running:
10824 m4 1.m4 2.m4 3.m4 4.m4 input.m4
10831 autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4
10838 m4 --reload-state=4.m4f input.m4
10843 Produce a frozen state file. @command{autom4te} freezing is stricter
10844 than M4's: it must produce no warnings, and no output other than empty
10845 lines (a line with white space is @emph{not} empty) and comments
10846 (starting with @samp{#}). Unlike @command{m4}'s similarly-named option,
10847 this option takes no argument:
10850 autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f
10857 m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f
10860 @item --mode=@var{octal-mode}
10861 @itemx -m @var{octal-mode}
10862 Set the mode of the non-traces output to @var{octal-mode}; by default
10868 @cindex @file{autom4te.cache}
10869 As another additional feature over @command{m4}, @command{autom4te}
10870 caches its results. GNU M4 is able to produce a regular
10871 output and traces at the same time. Traces are heavily used in the
10872 GNU Build System: @command{autoheader} uses them to build
10873 @file{config.h.in}, @command{autoreconf} to determine what
10874 GNU Build System components are used, @command{automake} to
10875 ``parse'' @file{configure.ac} etc. To avoid recomputation,
10876 traces are cached while performing regular expansion,
10877 and conversely. This cache is (actually, the caches are) stored in
10878 the directory @file{autom4te.cache}. @emph{It can safely be removed}
10879 at any moment (especially if for some reason @command{autom4te}
10880 considers it trashed).
10883 @item --cache=@var{directory}
10884 @itemx -C @var{directory}
10885 Specify the name of the directory where the result should be cached.
10886 Passing an empty value disables caching. Be sure to pass a relative
10887 file name, as for the time being, global caches are not supported.
10890 Don't cache the results.
10894 If a cache is used, consider it obsolete (but update it anyway).
10899 Because traces are so important to the GNU Build System,
10900 @command{autom4te} provides high level tracing features as compared to
10901 M4, and helps exploiting the cache:
10904 @item --trace=@var{macro}[:@var{format}]
10905 @itemx -t @var{macro}[:@var{format}]
10906 Trace the invocations of @var{macro} according to the @var{format}.
10907 Multiple @option{--trace} arguments can be used to list several macros.
10908 Multiple @option{--trace} arguments for a single macro are not
10909 cumulative; instead, you should just make @var{format} as long as
10912 The @var{format} is a regular string, with newlines if desired, and
10913 several special escape codes. It defaults to @samp{$f:$l:$n:$%}. It can
10914 use the following special escapes:
10918 @c $$ restore font-lock
10919 The character @samp{$}.
10922 The file name from which @var{macro} is called.
10925 The line number from which @var{macro} is called.
10928 The depth of the @var{macro} call. This is an M4 technical detail that
10929 you probably don't want to know about.
10932 The name of the @var{macro}.
10935 The @var{num}th argument of the call to @var{macro}.
10938 @itemx $@var{sep}@@
10939 @itemx $@{@var{separator}@}@@
10940 All the arguments passed to @var{macro}, separated by the character
10941 @var{sep} or the string @var{separator} (@samp{,} by default). Each
10942 argument is quoted, i.e., enclosed in a pair of square brackets.
10946 @itemx $@{@var{separator}@}*
10947 As above, but the arguments are not quoted.
10951 @itemx $@{@var{separator}@}%
10952 As above, but the arguments are not quoted, all new line characters in
10953 the arguments are smashed, and the default separator is @samp{:}.
10955 The escape @samp{$%} produces single-line trace outputs (unless you put
10956 newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do
10960 @xref{autoconf Invocation}, for examples of trace uses.
10962 @item --preselect=@var{macro}
10963 @itemx -p @var{macro}
10964 Cache the traces of @var{macro}, but do not enable traces. This is
10965 especially important to save CPU cycles in the future. For instance,
10966 when invoked, @command{autoconf} preselects all the macros that
10967 @command{autoheader}, @command{automake}, @command{autoreconf}, etc.,
10968 trace, so that running @command{m4} is not needed to trace them: the
10969 cache suffices. This results in a huge speed-up.
10974 @cindex Autom4te Library
10975 Finally, @command{autom4te} introduces the concept of @dfn{Autom4te
10976 libraries}. They consists in a powerful yet extremely simple feature:
10977 sets of combined command line arguments:
10980 @item --language=@var{language}
10981 @itemx -l @var{language}
10982 Use the @var{language} Autom4te library. Current languages include:
10986 create M4sugar output.
10989 create M4sh executable shell scripts.
10992 create Autotest executable test suites.
10994 @item Autoconf-without-aclocal-m4
10995 create Autoconf executable configure scripts without
10996 reading @file{aclocal.m4}.
10999 create Autoconf executable configure scripts. This language inherits
11000 all the characteristics of @code{Autoconf-without-aclocal-m4} and
11001 additionally reads @file{aclocal.m4}.
11004 @item --prepend-include=@var{dir}
11005 @itemx -B @var{dir}
11006 Prepend directory @var{dir} to the search path. This is used to include
11007 the language-specific files before any third-party macros.
11011 @cindex @file{autom4te.cfg}
11012 As an example, if Autoconf is installed in its default location,
11013 @file{/usr/local}, the command @samp{autom4te -l m4sugar foo.m4} is
11014 strictly equivalent to the command:
11017 autom4te --prepend-include /usr/local/share/autoconf \
11018 m4sugar/m4sugar.m4f --warnings syntax foo.m4
11022 Recursive expansion applies here: the command @samp{autom4te -l m4sh foo.m4}
11023 is the same as @samp{autom4te --language M4sugar m4sugar/m4sh.m4f
11027 autom4te --prepend-include /usr/local/share/autoconf \
11028 m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4
11032 The definition of the languages is stored in @file{autom4te.cfg}.
11034 @node Customizing autom4te
11035 @subsection Customizing @command{autom4te}
11037 One can customize @command{autom4te} via @file{~/.autom4te.cfg} (i.e.,
11038 as found in the user home directory), and @file{./.autom4te.cfg} (i.e.,
11039 as found in the directory from which @command{autom4te} is run). The
11040 order is first reading @file{autom4te.cfg}, then @file{~/.autom4te.cfg},
11041 then @file{./.autom4te.cfg}, and finally the command line arguments.
11043 In these text files, comments are introduced with @code{#}, and empty
11044 lines are ignored. Customization is performed on a per-language basis,
11045 wrapped in between a @samp{begin-language: "@var{language}"},
11046 @samp{end-language: "@var{language}"} pair.
11048 Customizing a language stands for appending options (@pxref{autom4te
11049 Invocation}) to the current definition of the language. Options, and
11050 more generally arguments, are introduced by @samp{args:
11051 @var{arguments}}. You may use the traditional shell syntax to quote the
11054 As an example, to disable Autoconf caches (@file{autom4te.cache})
11055 globally, include the following lines in @file{~/.autom4te.cfg}:
11058 ## ------------------ ##
11059 ## User Preferences. ##
11060 ## ------------------ ##
11062 begin-language: "Autoconf-without-aclocal-m4"
11064 end-language: "Autoconf-without-aclocal-m4"
11068 @node Programming in M4sugar
11069 @section Programming in M4sugar
11072 M4 by itself provides only a small, but sufficient, set of all-purpose
11073 macros. M4sugar introduces additional generic macros. Its name was
11074 coined by Lars J. Aas: ``Readability And Greater Understanding Stands 4
11077 M4sugar reserves the macro namespace @samp{^_m4_} for internal use, and
11078 the macro namespace @samp{^m4_} for M4sugar macros. You should not
11079 define your own macros into these namespaces.
11082 * Redefined M4 Macros:: M4 builtins changed in M4sugar
11083 * Diagnostic Macros:: Diagnostic messages from M4sugar
11084 * Diversion support:: Diversions in M4sugar
11085 * Conditional constructs:: Conditions in M4
11086 * Looping constructs:: Iteration in M4
11087 * Evaluation Macros:: More quotation and evaluation control
11088 * Text processing Macros:: String manipulation in M4
11089 * Number processing Macros:: Arithmetic computation in M4
11090 * Set manipulation Macros:: Set manipulation in M4
11091 * Forbidden Patterns:: Catching unexpanded macros
11094 @node Redefined M4 Macros
11095 @subsection Redefined M4 Macros
11098 @msindex{changecom}
11099 @msindex{changequote}
11100 @msindex{debugfile}
11101 @msindex{debugmode}
11122 With a few exceptions, all the M4 native macros are moved in the
11123 @samp{m4_} pseudo-namespace, e.g., M4sugar renames @code{define} as
11124 @code{m4_define} etc.
11126 The list of macros unchanged from M4, except for their name, is:
11130 @item m4_changequote
11155 Some M4 macros are redefined, and are slightly incompatible with their
11162 All M4 macros starting with @samp{__} retain their original name: for
11163 example, no @code{m4__file__} is defined.
11168 This is not technically a macro, but a feature of Autom4te. The
11169 sequence @code{__oline__} can be used similarly to the other m4sugar
11170 location macros, but rather than expanding to the location of the input
11171 file, it is translated to the line number where it appears in the output
11172 file after all other M4 expansions.
11177 This macro kept its original name: no @code{m4_dnl} is defined.
11180 @defmac m4_bpatsubst (@var{string}, @var{regexp}, @ovar{replacement})
11181 @msindex{bpatsubst}
11182 This macro corresponds to @code{patsubst}. The name @code{m4_patsubst}
11183 is kept for future versions of M4sugar, once GNU M4 2.0 is
11184 released and supports extended regular expression syntax.
11187 @defmac m4_bregexp (@var{string}, @var{regexp}, @ovar{replacement})
11189 This macro corresponds to @code{regexp}. The name @code{m4_regexp}
11190 is kept for future versions of M4sugar, once GNU M4 2.0 is
11191 released and supports extended regular expression syntax.
11194 @defmac m4_copy (@var{source}, @var{dest})
11195 @defmacx m4_copy_force (@var{source}, @var{dest})
11196 @defmacx m4_rename (@var{source}, @var{dest})
11197 @defmacx m4_rename_force (@var{source}, @var{dest})
11199 @msindex{copy_force}
11201 @msindex{rename_force}
11202 These macros aren't directly builtins, but are closely related to
11203 @code{m4_pushdef} and @code{m4_defn}. @code{m4_copy} and
11204 @code{m4_rename} ensure that @var{dest} is undefined, while
11205 @code{m4_copy_force} and @code{m4_rename_force} overwrite any existing
11206 definition. All four macros then proceed to copy the entire pushdef
11207 stack of definitions of @var{source} over to @var{dest}. @code{m4_copy}
11208 and @code{m4_copy_force} preserve the source (including in the special
11209 case where @var{source} is undefined), while @code{m4_rename} and
11210 @code{m4_rename_force} undefine the original macro name (making it an
11211 error to rename an undefined @var{source}).
11213 Note that attempting to invoke a renamed macro might not work, since the
11214 macro may have a dependence on helper macros accessed via composition of
11215 @samp{$0} but that were not also renamed; likewise, other macros may
11216 have a hard-coded dependence on @var{source} and could break if
11217 @var{source} has been deleted. On the other hand, it is always safe to
11218 rename a macro to temporarily move it out of the way, then rename it
11219 back later to restore original semantics.
11222 @defmac m4_defn (@var{macro}@dots{})
11224 This macro fails if @var{macro} is not defined, even when using older
11225 versions of M4 that did not warn. See @code{m4_undefine}.
11226 Unfortunately, in order to support these older versions of M4, there are
11227 some situations involving unbalanced quotes where concatenating multiple
11228 macros together will work in newer M4 but not in m4sugar; use
11229 quadrigraphs to work around this.
11232 @defmac m4_divert (@var{diversion})
11234 M4sugar relies heavily on diversions, so rather than behaving as a
11235 primitive, @code{m4_divert} behaves like:
11237 m4_divert_pop()m4_divert_push([@var{diversion}])
11240 @xref{Diversion support}, for more details about the use of the
11241 diversion stack. In particular, this implies that @var{diversion}
11242 should be a named diversion rather than a raw number. But be aware that
11243 it is seldom necessary to explicitly change the diversion stack, and
11244 that when done incorrectly, it can lead to syntactically invalid
11248 @defmac m4_dumpdef (@var{name}@dots{})
11249 @defmacx m4_dumpdefs (@var{name}@dots{})
11252 @code{m4_dumpdef} is like the M4 builtin, except that this version
11253 requires at least one argument, output always goes to standard error
11254 rather than the current debug file, no sorting is done on multiple
11255 arguments, and an error is issued if any
11256 @var{name} is undefined. @code{m4_dumpdefs} is a convenience macro that
11257 calls @code{m4_dumpdef} for all of the
11258 @code{m4_pushdef} stack of definitions, starting with the current, and
11259 silently does nothing if @var{name} is undefined.
11261 Unfortunately, due to a limitation in M4 1.4.x, any macro defined as a
11262 builtin is output as the empty string. This behavior is rectified by
11263 using M4 1.6 or newer. However, this behavior difference means that
11264 @code{m4_dumpdef} should only be used while developing m4sugar macros,
11265 and never in the final published form of a macro.
11268 @defmac m4_esyscmd_s (@var{command})
11269 @msindex{esyscmd_s}
11270 Like @code{m4_esyscmd}, this macro expands to the result of running
11271 @var{command} in a shell. The difference is that any trailing newlines
11272 are removed, so that the output behaves more like shell command
11276 @defmac m4_exit (@var{exit-status})
11278 This macro corresponds to @code{m4exit}.
11281 @defmac m4_if (@var{comment})
11282 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @ovar{not-equal})
11283 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal-1}, @
11284 @var{string-3}, @var{string-4}, @var{equal-2}, @dots{}, @ovar{not-equal})
11286 This macro corresponds to @code{ifelse}. @var{string-1} and
11287 @var{string-2} are compared literally, so usually one of the two
11288 arguments is passed unquoted. @xref{Conditional constructs}, for more
11289 conditional idioms.
11292 @defmac m4_include (@var{file})
11293 @defmacx m4_sinclude (@var{file})
11296 Like the M4 builtins, but warn against multiple inclusions of @var{file}.
11299 @defmac m4_mkstemp (@var{template})
11300 @defmacx m4_maketemp (@var{template})
11303 Posix requires @code{maketemp} to replace the trailing @samp{X}
11304 characters in @var{template} with the process id, without regards to the
11305 existence of a file by that name, but this a security hole. When this
11306 was pointed out to the Posix folks, they agreed to invent a new macro
11307 @code{mkstemp} that always creates a uniquely named file, but not all
11308 versions of GNU M4 support the new macro. In M4sugar,
11309 @code{m4_maketemp} and @code{m4_mkstemp} are synonyms for each other,
11310 and both have the secure semantics regardless of which macro the
11311 underlying M4 provides.
11314 @defmac m4_popdef (@var{macro}@dots{})
11316 This macro fails if @var{macro} is not defined, even when using older
11317 versions of M4 that did not warn. See @code{m4_undefine}.
11320 @defmac m4_undefine (@var{macro}@dots{})
11322 This macro fails if @var{macro} is not defined, even when using older
11323 versions of M4 that did not warn. Use
11326 m4_ifdef([@var{macro}], [m4_undefine([@var{macro}])])
11330 if you are not sure whether @var{macro} is defined.
11333 @defmac m4_undivert (@var{diversion}@dots{})
11335 Unlike the M4 builtin, at least one @var{diversion} must be specified.
11336 Also, since the M4sugar diversion stack prefers named
11337 diversions, the use of @code{m4_undivert} to include files is risky.
11338 @xref{Diversion support}, for more details about the use of the
11339 diversion stack. But be aware that it is seldom necessary to explicitly
11340 change the diversion stack, and that when done incorrectly, it can lead
11341 to syntactically invalid scripts.
11344 @defmac m4_wrap (@var{text})
11345 @defmacx m4_wrap_lifo (@var{text})
11347 @msindex{wrap_lifo}
11348 These macros correspond to @code{m4wrap}. Posix requires arguments of
11349 multiple wrap calls to be reprocessed at EOF in the same order
11350 as the original calls (first-in, first-out). GNU M4 versions
11351 through 1.4.10, however, reprocess them in reverse order (last-in,
11352 first-out). Both orders are useful, therefore, you can rely on
11353 @code{m4_wrap} to provide FIFO semantics and @code{m4_wrap_lifo} for
11354 LIFO semantics, regardless of the underlying GNU M4 version.
11356 Unlike the GNU M4 builtin, these macros only recognize one
11357 argument, and avoid token pasting between consecutive invocations. On
11358 the other hand, nested calls to @code{m4_wrap} from within wrapped text
11359 work just as in the builtin.
11363 @node Diagnostic Macros
11364 @subsection Diagnostic messages from M4sugar
11365 @cindex Messages, from @command{M4sugar}
11367 When macros statically diagnose abnormal situations, benign or fatal,
11368 they should report them using these macros. For issuing dynamic issues,
11369 i.e., when @command{configure} is run, see @ref{Printing Messages}.
11371 @defmac m4_assert (@var{expression}, @dvar{exit-status, 1})
11373 Assert that the arithmetic @var{expression} evaluates to non-zero.
11374 Otherwise, issue a fatal error, and exit @command{autom4te} with
11378 @defmac m4_errprintn (@var{message})
11379 @msindex{errprintn}
11380 Similar to the builtin @code{m4_errprint}, except that a newline is
11381 guaranteed after @var{message}.
11385 @defmac m4_fatal (@var{message})
11387 Report a severe error @var{message} prefixed with the current location,
11388 and have @command{autom4te} die.
11391 @defmac m4_location
11393 Useful as a prefix in a message line. Short for:
11400 @defmac m4_warn (@var{category}, @var{message})
11402 Report @var{message} as a warning (or as an error if requested by the
11403 user) if warnings of the @var{category} are turned on. If the message
11404 is emitted, it is prefixed with the current location, and followed by a
11405 call trace of all macros defined via @code{AC_DEFUN} used to get to the
11406 current expansion. You are encouraged to use standard categories, which
11411 messages that don't fall into one of the following categories. Use of an
11412 empty @var{category} is equivalent.
11415 related to cross compilation issues.
11418 use of an obsolete construct.
11421 dubious syntactic constructs, incorrectly ordered macro calls.
11426 @node Diversion support
11427 @subsection Diversion support
11429 M4sugar makes heavy use of diversions under the hood, because it is
11430 often the case that
11431 text that must appear early in the output is not discovered until late
11432 in the input. Additionally, some of the topological sorting algorithms
11433 used in resolving macro dependencies use diversions. However, most
11434 macros should not need to change diversions directly, but rather rely on
11435 higher-level M4sugar macros to manage diversions transparently. If you
11436 change diversions improperly, you risk generating a syntactically
11437 invalid script, because an incorrect diversion will violate assumptions
11438 made by many macros about whether prerequisite text has been previously
11439 output. In short, if you manually change the diversion, you should not
11440 expect any macros provided by the Autoconf package to work until you
11441 have restored the diversion stack back to its original state.
11443 In the rare case that it is necessary to write a macro that explicitly
11444 outputs text to a different diversion, it is important to be aware of an
11445 M4 limitation regarding diversions: text only goes to a diversion if it
11446 is not part of argument collection. Therefore, any macro that changes
11447 the current diversion cannot be used as an unquoted argument to another
11448 macro, but must be expanded at the top level. The macro
11449 @code{m4_expand} will diagnose any attempt to change diversions, since
11450 it is generally useful only as an argument to another macro. The
11451 following example shows what happens when diversion manipulation is
11452 attempted within macro arguments:
11455 m4_do([normal text]
11456 m4_divert_push([KILL])unwanted[]m4_divert_pop([KILL])
11457 [m4_divert_push([KILL])discarded[]m4_divert_pop([KILL])])dnl
11458 @result{}normal text
11463 Notice that the unquoted text @code{unwanted} is output, even though it
11464 was processed while the current diversion was @code{KILL}, because it
11465 was collected as part of the argument to @code{m4_do}. However, the
11466 text @code{discarded} disappeared as desired, because the diversion
11467 changes were single-quoted, and were not expanded until the top-level
11468 rescan of the output of @code{m4_do}.
11470 To make diversion management easier, M4sugar uses the concept of named
11471 diversions. Rather than using diversion numbers directly, it is nicer
11472 to associate a name with each diversion. The diversion number associated
11473 with a particular diversion name is an implementation detail, and a
11474 syntax warning is issued if a diversion number is used instead of a
11475 name. In general, you should not output text
11476 to a named diversion until after calling the appropriate initialization
11477 routine for your language (@code{m4_init}, @code{AS_INIT},
11478 @code{AT_INIT}, @dots{}), although there are some exceptions documented
11481 M4sugar defines two named diversions.
11484 Text written to this diversion is discarded. This is the default
11485 diversion once M4sugar is initialized.
11487 This diversion is used behind the scenes by topological sorting macros,
11488 such as @code{AC_REQUIRE}.
11491 M4sh adds several more named diversions.
11494 This diversion is reserved for the @samp{#!} interpreter line.
11495 @item HEADER-REVISION
11496 This diversion holds text from @code{AC_REVISION}.
11497 @item HEADER-COMMENT
11498 This diversion holds comments about the purpose of a file.
11499 @item HEADER-COPYRIGHT
11500 This diversion is managed by @code{AC_COPYRIGHT}.
11501 @item M4SH-SANITIZE
11502 This diversion contains M4sh sanitization code, used to ensure M4sh is
11503 executing in a reasonable shell environment.
11505 This diversion contains M4sh initialization code, initializing variables
11506 that are required by other M4sh macros.
11508 This diversion contains the body of the shell code, and is the default
11509 diversion once M4sh is initialized.
11512 Autotest inherits diversions from M4sh, and changes the default
11513 diversion from @code{BODY} back to @code{KILL}. It also adds several
11514 more named diversions, with the following subset designed for developer
11517 @item PREPARE_TESTS
11518 This diversion contains initialization sequences which are executed
11519 after @file{atconfig} and @file{atlocal}, and after all command line
11520 arguments have been parsed, but prior to running any tests. It can be
11521 used to set up state that is required across all tests. This diversion
11522 will work even before @code{AT_INIT}.
11525 Autoconf inherits diversions from M4sh, and adds the following named
11526 diversions which developers can utilize.
11529 This diversion contains shell variable assignments to set defaults that
11530 must be in place before arguments are parsed. This diversion is placed
11531 early enough in @file{configure} that it is unsafe to expand any
11532 autoconf macros into this diversion.
11534 If @code{AC_PRESERVE_HELP_ORDER} was used, then text placed in this
11535 diversion will be included as part of a quoted here-doc providing all of
11536 the @option{--help} output of @file{configure} related to options
11537 created by @code{AC_ARG_WITH} and @code{AC_ARG_ENABLE}.
11539 This diversion occurs after all command line options have been parsed,
11540 but prior to the main body of the @file{configure} script. This
11541 diversion is the last chance to insert shell code such as variable
11542 assignments or shell function declarations that will used by the
11543 expansion of other macros.
11546 For now, the remaining named diversions of Autoconf, Autoheader, and
11547 Autotest are not documented. In other words,
11548 intentionally outputting text into an undocumented diversion is subject
11549 to breakage in a future release of Autoconf.
11551 @defmac m4_cleardivert (@var{diversion}@dots{})
11552 @msindex{cleardivert}
11553 Permanently discard any text that has been diverted into
11557 @defmac m4_divert_once (@var{diversion}, @ovar{content})
11558 @msindex{divert_once}
11559 Similar to @code{m4_divert_text}, except that @var{content} is only
11560 output to @var{diversion} if this is the first time that
11561 @code{m4_divert_once} has been called with its particular arguments.
11564 @defmac m4_divert_pop (@ovar{diversion})
11565 @msindex{divert_pop}
11566 If provided, check that the current diversion is indeed @var{diversion}.
11567 Then change to the diversion located earlier on the stack, giving an
11568 error if an attempt is made to pop beyond the initial m4sugar diversion
11572 @defmac m4_divert_push (@var{diversion})
11573 @msindex{divert_push}
11574 Remember the former diversion on the diversion stack, and output
11575 subsequent text into @var{diversion}. M4sugar maintains a diversion
11576 stack, and issues an error if there is not a matching pop for every
11580 @defmac m4_divert_text (@var{diversion}, @ovar{content})
11581 @msindex{divert_text}
11582 Output @var{content} and a newline into @var{diversion}, without
11583 affecting the current diversion. Shorthand for:
11585 m4_divert_push([@var{diversion}])@var{content}
11586 m4_divert_pop([@var{diversion}])dnl
11589 One use of @code{m4_divert_text} is to develop two related macros, where
11590 macro @samp{MY_A} does the work, but adjusts what work is performed
11591 based on whether the optional macro @samp{MY_B} has also been expanded.
11592 Of course, it is possible to use @code{AC_BEFORE} within @code{MY_A} to
11593 require that @samp{MY_B} occurs first, if it occurs at all. But this
11594 imposes an ordering restriction on the user; it would be nicer if macros
11595 @samp{MY_A} and @samp{MY_B} can be invoked in either order. The trick
11596 is to let @samp{MY_B} leave a breadcrumb in an early diversion, which
11597 @samp{MY_A} can then use to determine whether @samp{MY_B} has been
11603 if test -n "$b_was_used"; then
11607 [AC_REQUIRE([MY_A])dnl
11608 m4_divert_text([INIT_PREPARE], [b_was_used=true])])
11615 Initialize the M4sugar environment, setting up the default named
11616 diversion to be @code{KILL}.
11619 @node Conditional constructs
11620 @subsection Conditional constructs
11622 The following macros provide additional conditional constructs as
11623 convenience wrappers around @code{m4_if}.
11625 @defmac m4_bmatch (@var{string}, @var{regex-1}, @var{value-1}, @
11626 @ovar{regex-2}, @ovar{value-2}, @dots{}, @ovar{default})
11628 The string @var{string} is repeatedly compared against a series of
11629 @var{regex} arguments; if a match is found, the expansion is the
11630 corresponding @var{value}, otherwise, the macro moves on to the next
11631 @var{regex}. If no @var{regex} match, then the result is the optional
11632 @var{default}, or nothing.
11635 @defmac m4_bpatsubsts (@var{string}, @var{regex-1}, @var{subst-1}, @
11636 @ovar{regex-2}, @ovar{subst-2}, @dots{})
11637 @msindex{bpatsubsts}
11638 The string @var{string} is altered by @var{regex-1} and @var{subst-1},
11641 m4_bpatsubst([[@var{string}]], [@var{regex}], [@var{subst}])
11645 The result of the substitution is then passed through the next set of
11646 @var{regex} and @var{subst}, and so forth. An empty @var{subst} implies
11647 deletion of any matched portions in the current string. Note that this
11648 macro over-quotes @var{string}; this behavior is intentional, so that
11649 the result of each step of the recursion remains as a quoted string.
11650 However, it means that anchors (@samp{^} and @samp{$} in the @var{regex}
11651 will line up with the extra quotations, and not the characters of the
11652 original string. The overquoting is removed after the final
11656 @defmac m4_case (@var{string}, @var{value-1}, @var{if-value-1}, @
11657 @ovar{value-2}, @ovar{if-value-2}, @dots{}, @ovar{default})
11659 Test @var{string} against multiple @var{value} possibilities, resulting
11660 in the first @var{if-value} for a match, or in the optional
11661 @var{default}. This is shorthand for:
11663 m4_if([@var{string}], [@var{value-1}], [@var{if-value-1}],
11664 [@var{string}], [@var{value-2}], [@var{if-value-2}], @dots{},
11669 @defmac m4_cond (@var{test-1}, @var{value-1}, @var{if-value-1}, @
11670 @ovar{test-2}, @ovar{value-2}, @ovar{if-value-2}, @dots{}, @ovar{default})
11672 This macro was introduced in Autoconf 2.62. Similar to @code{m4_if},
11673 except that each @var{test} is expanded only when it is encountered.
11674 This is useful for short-circuiting expensive tests; while @code{m4_if}
11675 requires all its strings to be expanded up front before doing
11676 comparisons, @code{m4_cond} only expands a @var{test} when all earlier
11679 For an example, these two sequences give the same result, but in the
11680 case where @samp{$1} does not contain a backslash, the @code{m4_cond}
11681 version only expands @code{m4_index} once, instead of five times, for
11682 faster computation if this is a common case for @samp{$1}. Notice that
11683 every third argument is unquoted for @code{m4_if}, and quoted for
11687 m4_if(m4_index([$1], [\]), [-1], [$2],
11688 m4_eval(m4_index([$1], [\\]) >= 0), [1], [$2],
11689 m4_eval(m4_index([$1], [\$]) >= 0), [1], [$2],
11690 m4_eval(m4_index([$1], [\`]) >= 0), [1], [$3],
11691 m4_eval(m4_index([$1], [\"]) >= 0), [1], [$3],
11693 m4_cond([m4_index([$1], [\])], [-1], [$2],
11694 [m4_eval(m4_index([$1], [\\]) >= 0)], [1], [$2],
11695 [m4_eval(m4_index([$1], [\$]) >= 0)], [1], [$2],
11696 [m4_eval(m4_index([$1], [\`]) >= 0)], [1], [$3],
11697 [m4_eval(m4_index([$1], [\"]) >= 0)], [1], [$3],
11702 @defmac m4_default (@var{expr-1}, @var{expr-2})
11703 @defmacx m4_default_quoted (@var{expr-1}, @var{expr-2})
11704 @defmacx m4_default_nblank (@var{expr-1}, @ovar{expr-2})
11705 @defmacx m4_default_nblank_quoted (@var{expr-1}, @ovar{expr-2})
11707 @msindex{default_quoted}
11708 @msindex{default_nblank}
11709 @msindex{default_nblank_quoted}
11710 If @var{expr-1} contains text, use it. Otherwise, select @var{expr-2}.
11711 @code{m4_default} expands the result, while @code{m4_default_quoted}
11712 does not. Useful for providing a fixed default if the expression that
11713 results in @var{expr-1} would otherwise be empty. The difference
11714 between @code{m4_default} and @code{m4_default_nblank} is whether an
11715 argument consisting of just blanks (space, tab, newline) is
11716 significant. When using the expanding versions, note that an argument
11717 may contain text but still expand to an empty string.
11720 m4_define([active], [ACTIVE])dnl
11721 m4_define([empty], [])dnl
11722 m4_define([demo1], [m4_default([$1], [$2])])dnl
11723 m4_define([demo2], [m4_default_quoted([$1], [$2])])dnl
11724 m4_define([demo3], [m4_default_nblank([$1], [$2])])dnl
11725 m4_define([demo4], [m4_default_nblank_quoted([$1], [$2])])dnl
11726 demo1([active], [default])
11728 demo1([], [active])
11730 demo1([empty], [text])
11732 -demo1([ ], [active])-
11734 demo2([active], [default])
11736 demo2([], [active])
11738 demo2([empty], [text])
11740 -demo2([ ], [active])-
11742 demo3([active], [default])
11744 demo3([], [active])
11746 demo3([empty], [text])
11748 -demo3([ ], [active])-
11750 demo4([active], [default])
11752 demo4([], [active])
11754 demo4([empty], [text])
11756 -demo4([ ], [active])-
11761 @defmac m4_ifblank (@var{cond}, @ovar{if-blank}, @ovar{if-text})
11762 @defmacx m4_ifnblank (@var{cond}, @ovar{if-text}, @ovar{if-blank})
11765 If @var{cond} is empty or consists only of blanks (space, tab, newline),
11766 then expand @var{if-blank}; otherwise, expand @var{if-text}. Two
11767 variants exist, in order to make it easier to select the correct logical
11768 sense when using only two parameters. Note that this is more efficient
11769 than the equivalent behavior of:
11771 m4_ifval(m4_normalize([@var{cond}]), @var{if-text}, @var{if-blank})
11775 @defmac m4_ifndef (@var{macro}, @var{if-not-defined}, @ovar{if-defined})
11777 This is shorthand for:
11779 m4_ifdef([@var{macro}], [@var{if-defined}], [@var{if-not-defined}])
11783 @defmac m4_ifset (@var{macro}, @ovar{if-true}, @ovar{if-false})
11785 If @var{macro} is undefined, or is defined as the empty string, expand
11786 to @var{if-false}. Otherwise, expands to @var{if-true}. Similar to:
11788 m4_ifval(m4_defn([@var{macro}]), [@var{if-true}], [@var{if-false}])
11791 except that it is not an error if @var{macro} is undefined.
11794 @defmac m4_ifval (@var{cond}, @ovar{if-true}, @ovar{if-false})
11796 Expands to @var{if-true} if @var{cond} is not empty, otherwise to
11797 @var{if-false}. This is shorthand for:
11799 m4_if([@var{cond}], [], [@var{if-true}], [@var{if-false}])
11803 @defmac m4_ifvaln (@var{cond}, @ovar{if-true}, @ovar{if-false})
11805 Similar to @code{m4_ifval}, except guarantee that a newline is present
11806 after any non-empty expansion. Often followed by @code{dnl}.
11809 @defmac m4_n (@var{text})
11811 Expand to @var{text}, and add a newline if @var{text} is not empty.
11812 Often followed by @code{dnl}.
11816 @node Looping constructs
11817 @subsection Looping constructs
11819 The following macros are useful in implementing recursive algorithms in
11820 M4, including loop operations. An M4 list is formed by quoting a list
11821 of quoted elements; generally the lists are comma-separated, although
11822 @code{m4_foreach_w} is whitespace-separated. For example, the list
11823 @samp{[[a], [b,c]]} contains two elements: @samp{[a]} and @samp{[b,c]}.
11824 It is common to see lists with unquoted elements when those elements are
11825 not likely to be macro names, as in @samp{[fputc_unlocked,
11828 Although not generally recommended, it is possible for quoted lists to
11829 have side effects; all side effects are expanded only once, and prior to
11830 visiting any list element. On the other hand, the fact that unquoted
11831 macros are expanded exactly once means that macros without side effects
11832 can be used to generate lists. For example,
11835 m4_foreach([i], [[1], [2], [3]m4_errprintn([hi])], [i])
11838 m4_define([list], [[1], [2], [3]])
11840 m4_foreach([i], [list], [i])
11844 @defmac m4_argn (@var{n}, @ovar{arg}@dots{})
11846 Extracts argument @var{n} (larger than 0) from the remaining arguments.
11847 If there are too few arguments, the empty string is used. For any
11848 @var{n} besides 1, this is more efficient than the similar
11849 @samp{m4_car(m4_shiftn([@var{n}], [], [@var{arg}@dots{}]))}.
11852 @defmac m4_car (@var{arg}@dots{})
11854 Expands to the quoted first @var{arg}. Can be used with @code{m4_cdr}
11855 to recursively iterate
11856 through a list. Generally, when using quoted lists of quoted elements,
11857 @code{m4_car} should be called without any extra quotes.
11860 @defmac m4_cdr (@var{arg}@dots{})
11862 Expands to a quoted list of all but the first @var{arg}, or the empty
11863 string if there was only one argument. Generally, when using quoted
11864 lists of quoted elements, @code{m4_cdr} should be called without any
11867 For example, this is a simple implementation of @code{m4_map}; note how
11868 each iteration checks for the end of recursion, then merely applies the
11869 first argument to the first element of the list, then repeats with the
11870 rest of the list. (The actual implementation in M4sugar is a bit more
11871 involved, to gain some speed and share code with @code{m4_map_sep}, and
11872 also to avoid expanding side effects in @samp{$2} twice).
11874 m4_define([m4_map], [m4_ifval([$2],
11875 [m4_apply([$1], m4_car($2))[]$0([$1], m4_cdr($2))])])dnl
11876 m4_map([ m4_eval], [[[1]], [[1+1]], [[10],[16]]])
11881 @defmac m4_for (@var{var}, @var{first}, @var{last}, @ovar{step}, @
11884 Loop over the numeric values between @var{first} and @var{last}
11885 including bounds by increments of @var{step}. For each iteration,
11886 expand @var{expression} with the numeric value assigned to @var{var}.
11887 If @var{step} is omitted, it defaults to @samp{1} or @samp{-1} depending
11888 on the order of the limits. If given, @var{step} has to match this
11889 order. The number of iterations is determined independently from
11890 definition of @var{var}; iteration cannot be short-circuited or
11891 lengthened by modifying @var{var} from within @var{expression}.
11894 @defmac m4_foreach (@var{var}, @var{list}, @var{expression})
11896 Loop over the comma-separated M4 list @var{list}, assigning each value
11897 to @var{var}, and expand @var{expression}. The following example
11901 m4_foreach([myvar], [[foo], [bar, baz]],
11905 @result{}echo bar, baz
11908 Note that for some forms of @var{expression}, it may be faster to use
11909 @code{m4_map_args}.
11912 @anchor{m4_foreach_w}
11913 @defmac m4_foreach_w (@var{var}, @var{list}, @var{expression})
11914 @msindex{foreach_w}
11915 Loop over the white-space-separated list @var{list}, assigning each value
11916 to @var{var}, and expand @var{expression}. If @var{var} is only
11917 referenced once in @var{expression}, it is more efficient to use
11918 @code{m4_map_args_w}.
11920 The deprecated macro @code{AC_FOREACH} is an alias of
11921 @code{m4_foreach_w}.
11924 @defmac m4_map (@var{macro}, @var{list})
11925 @defmacx m4_mapall (@var{macro}, @var{list})
11926 @defmacx m4_map_sep (@var{macro}, @var{separator}, @var{list})
11927 @defmacx m4_mapall_sep (@var{macro}, @var{separator}, @var{list})
11931 @msindex{mapall_sep}
11932 Loop over the comma separated quoted list of argument descriptions in
11933 @var{list}, and invoke @var{macro} with the arguments. An argument
11934 description is in turn a comma-separated quoted list of quoted elements,
11935 suitable for @code{m4_apply}. The macros @code{m4_map} and
11936 @code{m4_map_sep} ignore empty argument descriptions, while
11937 @code{m4_mapall} and @code{m4_mapall_sep} invoke @var{macro} with no
11938 arguments. The macros @code{m4_map_sep} and @code{m4_mapall_sep}
11939 additionally expand @var{separator} between invocations of @var{macro}.
11941 Note that @var{separator} is expanded, unlike in @code{m4_join}. When
11942 separating output with commas, this means that the map result can be
11943 used as a series of arguments, by using a single-quoted comma as
11944 @var{separator}, or as a single string, by using a double-quoted comma.
11947 m4_map([m4_count], [])
11949 m4_map([ m4_count], [[],
11953 m4_mapall([ m4_count], [[],
11957 m4_map_sep([m4_eval], [,], [[[1+2]],
11960 m4_map_sep([m4_echo], [,], [[[a]], [[b]]])
11962 m4_count(m4_map_sep([m4_echo], [,], [[[a]], [[b]]]))
11964 m4_map_sep([m4_echo], [[,]], [[[a]], [[b]]])
11966 m4_count(m4_map_sep([m4_echo], [[,]], [[[a]], [[b]]]))
11971 @defmac m4_map_args (@var{macro}, @var{arg}@dots{})
11973 Repeatedly invoke @var{macro} with each successive @var{arg} as its only
11974 argument. In the following example, three solutions are presented with
11975 the same expansion; the solution using @code{m4_map_args} is the most
11978 m4_define([active], [ACTIVE])dnl
11979 m4_foreach([var], [[plain], [active]], [ m4_echo(m4_defn([var]))])
11980 @result{} plain active
11981 m4_map([ m4_echo], [[[plain]], [[active]]])
11982 @result{} plain active
11983 m4_map_args([ m4_echo], [plain], [active])
11984 @result{} plain active
11987 In cases where it is useful to operate on additional parameters besides
11988 the list elements, the macro @code{m4_curry} can be used in @var{macro}
11989 to supply the argument currying necessary to generate the desired
11990 argument list. In the following example, @code{list_add_n} is more
11991 efficient than @code{list_add_x}. On the other hand, using
11992 @code{m4_map_args_sep} can be even more efficient.
11995 m4_define([list], [[1], [2], [3]])dnl
11996 m4_define([add], [m4_eval(([$1]) + ([$2]))])dnl
11997 dnl list_add_n(N, ARG...)
11998 dnl Output a list consisting of each ARG added to N
11999 m4_define([list_add_n],
12000 [m4_shift(m4_map_args([,m4_curry([add], [$1])], m4_shift($@@)))])dnl
12001 list_add_n([1], list)
12003 list_add_n([2], list)
12005 m4_define([list_add_x],
12006 [m4_shift(m4_foreach([var], m4_dquote(m4_shift($@@)),
12007 [,add([$1],m4_defn([var]))]))])dnl
12008 list_add_x([1], list)
12013 @defmac m4_map_args_pair (@var{macro}, @dvar{macro-end, macro}, @
12015 @msindex{map_args_pair}
12016 For every pair of arguments @var{arg}, invoke @var{macro} with two
12017 arguments. If there is an odd number of arguments, invoke
12018 @var{macro-end}, which defaults to @var{macro}, with the remaining
12022 m4_map_args_pair([, m4_reverse], [], [1], [2], [3])
12024 m4_map_args_pair([, m4_reverse], [, m4_dquote], [1], [2], [3])
12025 @result{}, 2, 1, [3]
12026 m4_map_args_pair([, m4_reverse], [, m4_dquote], [1], [2], [3], [4])
12027 @result{}, 2, 1, 4, 3
12031 @defmac m4_map_args_sep (@ovar{pre}, @ovar{post}, @ovar{sep}, @var{arg}@dots{})
12032 @msindex{map_args_sep}
12033 Expand the sequence @code{@var{pre}[@var{arg}]@var{post}} for each
12034 argument, additionally expanding @var{sep} between arguments. One
12035 common use of this macro is constructing a macro call, where the opening
12036 and closing parentheses are split between @var{pre} and @var{post}; in
12037 particular, @code{m4_map_args([@var{macro}], [@var{arg}])} is equivalent
12038 to @code{m4_map_args_sep([@var{macro}(], [)], [], [@var{arg}])}. This
12039 macro provides the most efficient means for iterating over an arbitrary
12040 list of arguments, particularly when repeatedly constructing a macro
12041 call with more arguments than @var{arg}.
12044 @defmac m4_map_args_w (@var{string}, @ovar{pre}, @ovar{post}, @ovar{sep})
12045 @msindex{map_args_w}
12046 Expand the sequence @code{@var{pre}[word]@var{post}} for each word in
12047 the whitespace-separated @var{string}, additionally expanding @var{sep}
12048 between words. This macro provides the most efficient means for
12049 iterating over a whitespace-separated string. In particular,
12050 @code{m4_map_args_w([@var{string}], [@var{action}(], [)])} is more
12051 efficient than @code{m4_foreach_w([var], [@var{string}],
12052 [@var{action}(m4_defn([var]))])}.
12055 @defmac m4_shiftn (@var{count}, @dots{})
12056 @defmacx m4_shift2 (@dots{})
12057 @defmacx m4_shift3 (@dots{})
12061 @code{m4_shiftn} performs @var{count} iterations of @code{m4_shift},
12062 along with validation that enough arguments were passed in to match the
12063 shift count, and that the count is positive. @code{m4_shift2} and
12064 @code{m4_shift3} are specializations
12065 of @code{m4_shiftn}, introduced in Autoconf 2.62, and are more efficient
12066 for two and three shifts, respectively.
12069 @defmac m4_stack_foreach (@var{macro}, @var{action})
12070 @defmacx m4_stack_foreach_lifo (@var{macro}, @var{action})
12071 @msindex{stack_foreach}
12072 @msindex{stack_foreach_lifo}
12073 For each of the @code{m4_pushdef} definitions of @var{macro}, expand
12074 @var{action} with the single argument of a definition of @var{macro}.
12075 @code{m4_stack_foreach} starts with the oldest definition, while
12076 @code{m4_stack_foreach_lifo} starts with the current definition.
12077 @var{action} should not push or pop definitions of @var{macro}, nor is
12078 there any guarantee that the current definition of @var{macro} matches
12079 the argument that was passed to @var{action}. The macro @code{m4_curry}
12080 can be used if @var{action} needs more than one argument, although in
12081 that case it is more efficient to use @var{m4_stack_foreach_sep}.
12083 Due to technical limitations, there are a few low-level m4sugar
12084 functions, such as @code{m4_pushdef}, that cannot be used as the
12085 @var{macro} argument.
12088 m4_pushdef([a], [1])m4_pushdef([a], [2])dnl
12089 m4_stack_foreach([a], [ m4_incr])
12091 m4_stack_foreach_lifo([a], [ m4_curry([m4_substr], [abcd])])
12096 @defmac m4_stack_foreach_sep (@var{macro}, @ovar{pre}, @ovar{post}, @ovar{sep})
12097 @defmacx m4_stack_foreach_sep_lifo (@var{macro}, @ovar{pre}, @ovar{post}, @
12099 @msindex{stack_foreach_sep}
12100 @msindex{stack_foreach_sep_lifo}
12101 Expand the sequence @code{@var{pre}[definition]@var{post}} for each
12102 @code{m4_pushdef} definition of @var{macro}, additionally expanding
12103 @var{sep} between definitions. @code{m4_stack_foreach_sep} visits the
12104 oldest definition first, while @code{m4_stack_foreach_sep_lifo} visits
12105 the current definition first. This macro provides the most efficient
12106 means for iterating over a pushdef stack. In particular,
12107 @code{m4_stack_foreach([@var{macro}], [@var{action}])} is short for
12108 @code{m4_stack_foreach_sep([@var{macro}], [@var{action}(], [)])}.
12111 @node Evaluation Macros
12112 @subsection Evaluation Macros
12114 The following macros give some control over the order of the evaluation
12115 by adding or removing levels of quotes.
12117 @defmac m4_apply (@var{macro}, @var{list})
12119 Apply the elements of the quoted, comma-separated @var{list} as the
12120 arguments to @var{macro}. If @var{list} is empty, invoke @var{macro}
12121 without arguments. Note the difference between @code{m4_indir}, which
12122 expects its first argument to be a macro name but can use names that are
12123 otherwise invalid, and @code{m4_apply}, where @var{macro} can contain
12124 other text, but must end in a valid macro name.
12126 m4_apply([m4_count], [])
12128 m4_apply([m4_count], [[]])
12130 m4_apply([m4_count], [[1], [2]])
12132 m4_apply([m4_join], [[|], [1], [2]])
12137 @defmac m4_count (@var{arg}, @dots{})
12139 This macro returns the decimal count of the number of arguments it was
12143 @defmac m4_curry (@var{macro}, @var{arg}@dots{})
12145 This macro performs argument currying. The expansion of this macro is
12146 another macro name that expects exactly one argument; that argument is
12147 then appended to the @var{arg} list, and then @var{macro} is expanded
12148 with the resulting argument list.
12151 m4_curry([m4_curry], [m4_reverse], [1])([2])([3])
12155 Unfortunately, due to a limitation in M4 1.4.x, it is not possible to
12156 pass the definition of a builtin macro as the argument to the output of
12157 @code{m4_curry}; the empty string is used instead of the builtin token.
12158 This behavior is rectified by using M4 1.6 or newer.
12161 @defmac m4_do (@var{arg}, @dots{})
12163 This macro loops over its arguments and expands each @var{arg} in
12164 sequence. Its main use is for readability; it allows the use of
12165 indentation and fewer @code{dnl} to result in the same expansion. This
12166 macro guarantees that no expansion will be concatenated with subsequent
12167 text; to achieve full concatenation, use @code{m4_unquote(m4_join([],
12168 @var{arg@dots{}}))}.
12171 m4_define([ab],[1])m4_define([bc],[2])m4_define([abc],[3])dnl
12174 m4_unquote(m4_join([],[a],[b]))c
12176 m4_define([a],[A])m4_define([b],[B])m4_define([c],[C])dnl
12177 m4_define([AB],[4])m4_define([BC],[5])m4_define([ABC],[6])dnl
12180 m4_unquote(m4_join([],[a],[b]))c
12185 @defmac m4_dquote (@var{arg}, @dots{})
12187 Return the arguments as a quoted list of quoted arguments.
12188 Conveniently, if there is just one @var{arg}, this effectively adds a
12192 @defmac m4_dquote_elt (@var{arg}, @dots{})
12193 @msindex{dquote_elt}
12194 Return the arguments as a series of double-quoted arguments. Whereas
12195 @code{m4_dquote} returns a single argument, @code{m4_dquote_elt} returns
12196 as many arguments as it was passed.
12199 @defmac m4_echo (@var{arg}, @dots{})
12201 Return the arguments, with the same level of quoting. Other than
12202 discarding whitespace after unquoted commas, this macro is a no-op.
12205 @defmac m4_expand (@var{arg})
12207 Return the expansion of @var{arg} as a quoted string. Whereas
12208 @code{m4_quote} is designed to collect expanded text into a single
12209 argument, @code{m4_expand} is designed to perform one level of expansion
12210 on quoted text. One distinction is in the treatment of whitespace
12211 following a comma in the original @var{arg}. Any time multiple
12212 arguments are collected into one with @code{m4_quote}, the M4 argument
12213 collection rules discard the whitespace. However, with @code{m4_expand},
12214 whitespace is preserved, even after the expansion of macros contained in
12215 @var{arg}. Additionally, @code{m4_expand} is able to expand text that
12216 would involve an unterminated comment, whereas expanding that same text
12217 as the argument to @code{m4_quote} runs into difficulty in finding the
12218 end of the argument. Since manipulating diversions during argument
12219 collection is inherently unsafe, @code{m4_expand} issues an error if
12220 @var{arg} attempts to change the current diversion (@pxref{Diversion
12224 m4_define([active], [ACT, IVE])dnl
12225 m4_define([active2], [[ACT, IVE]])dnl
12226 m4_quote(active, active)
12227 @result{}ACT,IVE,ACT,IVE
12228 m4_expand([active, active])
12229 @result{}ACT, IVE, ACT, IVE
12230 m4_quote(active2, active2)
12231 @result{}ACT, IVE,ACT, IVE
12232 m4_expand([active2, active2])
12233 @result{}ACT, IVE, ACT, IVE
12234 m4_expand([# m4_echo])
12236 m4_quote(# m4_echo)
12238 @result{}# m4_echo)
12242 Note that @code{m4_expand} cannot handle an @var{arg} that expands to
12243 literal unbalanced quotes, but that quadrigraphs can be used when
12244 unbalanced output is necessary. Likewise, unbalanced parentheses should
12245 be supplied with double quoting or a quadrigraph.
12248 m4_define([pattern], [[!@@<:@@]])dnl
12249 m4_define([bar], [BAR])dnl
12250 m4_expand([case $foo in
12251 m4_defn([pattern])@@:@}@@ bar ;;
12254 @result{}case $foo in
12255 @result{} [![]) BAR ;;
12256 @result{} *) blah ;;
12261 @defmac m4_ignore (@dots{})
12263 This macro was introduced in Autoconf 2.62. Expands to nothing,
12264 ignoring all of its arguments. By itself, this isn't very useful.
12265 However, it can be used to conditionally ignore an arbitrary number of
12266 arguments, by deciding which macro name to apply to a list of arguments.
12268 dnl foo outputs a message only if [debug] is defined.
12270 [m4_ifdef([debug],[AC_MSG_NOTICE],[m4_ignore])([debug message])])
12273 Note that for earlier versions of Autoconf, the macro @code{__gnu__} can
12274 serve the same purpose, although it is less readable.
12277 @defmac m4_make_list (@var{arg}, @dots{})
12278 @msindex{make_list}
12279 This macro exists to aid debugging of M4sugar algorithms. Its net
12280 effect is similar to @code{m4_dquote}---it produces a quoted list of
12281 quoted arguments, for each @var{arg}. The difference is that this
12282 version uses a comma-newline separator instead of just comma, to improve
12283 readability of the list; with the result that it is less efficient than
12286 m4_define([zero],[0])m4_define([one],[1])m4_define([two],[2])dnl
12287 m4_dquote(zero, [one], [[two]])
12288 @result{}[0],[one],[[two]]
12289 m4_make_list(zero, [one], [[two]])
12293 m4_foreach([number], m4_dquote(zero, [one], [[two]]), [ number])
12295 m4_foreach([number], m4_make_list(zero, [one], [[two]]), [ number])
12300 @c m4_noquote is too dangerous to document - it invokes macros that
12301 @c probably rely on @samp{[]} nested quoting for proper operation. The
12302 @c user should generally prefer m4_unquote instead.
12304 @defmac m4_quote (@var{arg}, @dots{})
12306 Return the arguments as a single entity, i.e., wrap them into a pair of
12307 quotes. This effectively collapses multiple arguments into one,
12308 although it loses whitespace after unquoted commas in the process.
12311 @defmac m4_reverse (@var{arg}, @dots{})
12313 Outputs each argument with the same level of quoting, but in reverse
12314 order, and with space following each comma for readability.
12317 m4_define([active], [ACT,IVE])
12319 m4_reverse(active, [active])
12320 @result{}active, IVE, ACT
12324 @defmac m4_unquote (@var{arg}, @dots{})
12326 This macro was introduced in Autoconf 2.62. Expand each argument,
12327 separated by commas. For a single @var{arg}, this effectively removes a
12328 layer of quoting, and @code{m4_unquote([@var{arg}])} is more efficient
12329 than the equivalent @code{m4_do([@var{arg}])}. For multiple arguments,
12330 this results in an unquoted list of expansions. This is commonly used
12331 with @code{m4_split}, in order to convert a single quoted list into a
12332 series of quoted elements.
12335 The following example aims at emphasizing the difference between several
12336 scenarios: not using these macros, using @code{m4_defn}, using
12337 @code{m4_quote}, using @code{m4_dquote}, and using @code{m4_expand}.
12340 $ @kbd{cat example.m4}
12341 dnl Overquote, so that quotes are visible.
12342 m4_define([show], [$[]1 = [$1], $[]@@ = [$@@]])
12343 m4_define([a], [A])
12344 m4_define([mkargs], [1, 2[,] 3])
12345 m4_define([arg1], [[$1]])
12349 show(m4_quote(a, b))
12350 show(m4_dquote(a, b))
12351 show(m4_expand([a, b]))
12355 arg1(m4_defn([mkargs]))
12356 arg1(m4_quote(mkargs))
12357 arg1(m4_dquote(mkargs))
12358 arg1(m4_expand([mkargs]))
12359 $ @kbd{autom4te -l m4sugar example.m4}
12360 $1 = A, $@@ = [A],[b]
12361 $1 = a, b, $@@ = [a, b]
12362 $1 = A,b, $@@ = [A,b]
12363 $1 = [A],[b], $@@ = [[A],[b]]
12364 $1 = A, b, $@@ = [A, b]
12375 @node Text processing Macros
12376 @subsection String manipulation in M4
12378 The following macros may be used to manipulate strings in M4. Many of
12379 the macros in this section intentionally result in quoted strings as
12380 output, rather than subjecting the arguments to further expansions. As
12381 a result, if you are manipulating text that contains active M4
12382 characters, the arguments are passed with single quoting rather than
12385 @defmac m4_append (@var{macro-name}, @var{string}, @ovar{separator})
12386 @defmacx m4_append_uniq (@var{macro-name}, @var{string}, @ovar{separator} @
12387 @ovar{if-uniq}, @ovar{if-duplicate})
12389 @msindex{append_uniq}
12390 Redefine @var{macro-name} to its former contents with @var{separator}
12391 and @var{string} added at the end. If @var{macro-name} was undefined
12392 before (but not if it was defined but empty), then no @var{separator} is
12393 added. As of Autoconf 2.62, neither @var{string} nor @var{separator}
12394 are expanded during this macro; instead, they are expanded when
12395 @var{macro-name} is invoked.
12397 @code{m4_append} can be used to grow strings, and @code{m4_append_uniq}
12398 to grow strings without duplicating substrings. Additionally,
12399 @code{m4_append_uniq} takes two optional parameters as of Autoconf 2.62;
12400 @var{if-uniq} is expanded if @var{string} was appended, and
12401 @var{if-duplicate} is expanded if @var{string} was already present.
12402 Also, @code{m4_append_uniq} warns if @var{separator} is not empty, but
12403 occurs within @var{string}, since that can lead to duplicates.
12405 Note that @code{m4_append} can scale linearly in the length of the final
12406 string, depending on the quality of the underlying M4 implementation,
12407 while @code{m4_append_uniq} has an inherent quadratic scaling factor.
12408 If an algorithm can tolerate duplicates in the final string, use the
12409 former for speed. If duplicates must be avoided, consider using
12410 @code{m4_set_add} instead (@pxref{Set manipulation Macros}).
12413 m4_define([active], [ACTIVE])dnl
12414 m4_append([sentence], [This is an])dnl
12415 m4_append([sentence], [ active ])dnl
12416 m4_append([sentence], [symbol.])dnl
12418 @result{}This is an ACTIVE symbol.
12419 m4_undefine([active])dnl
12420 @result{}This is an active symbol.
12421 m4_append_uniq([list], [one], [, ], [new], [existing])
12423 m4_append_uniq([list], [one], [, ], [new], [existing])
12425 m4_append_uniq([list], [two], [, ], [new], [existing])
12427 m4_append_uniq([list], [three], [, ], [new], [existing])
12429 m4_append_uniq([list], [two], [, ], [new], [existing])
12432 @result{}one, two, three
12434 @result{}[one],[two],[three]
12435 m4_append([list2], [one], [[, ]])dnl
12436 m4_append_uniq([list2], [two], [[, ]])dnl
12437 m4_append([list2], [three], [[, ]])dnl
12439 @result{}one, two, three
12441 @result{}[one, two, three]
12445 @defmac m4_append_uniq_w (@var{macro-name}, @var{strings})
12446 @msindex{append_uniq_w}
12447 This macro was introduced in Autoconf 2.62. It is similar to
12448 @code{m4_append_uniq}, but treats @var{strings} as a whitespace
12449 separated list of words to append, and only appends unique words.
12450 @var{macro-name} is updated with a single space between new words.
12452 m4_append_uniq_w([numbers], [1 1 2])dnl
12453 m4_append_uniq_w([numbers], [ 2 3 ])dnl
12459 @defmac m4_chomp (@var{string})
12460 @defmacx m4_chomp_all (@var{string})
12462 @msindex{chomp_all}
12463 Output @var{string} in quotes, but without a trailing newline. The
12464 macro @code{m4_chomp} is slightly faster, and removes at most one
12465 newline; the macro @code{m4_chomp_all} removes all consecutive trailing
12466 newlines. Unlike @code{m4_flatten}, embedded newlines are left intact,
12467 and backslash does not influence the result.
12470 @defmac m4_combine (@ovar{separator}, @var{prefix-list}, @ovar{infix}, @
12471 @var{suffix-1}, @ovar{suffix-2}, @dots{})
12473 This macro produces a quoted string containing the pairwise combination
12474 of every element of the quoted, comma-separated @var{prefix-list}, and
12475 every element from the @var{suffix} arguments. Each pairwise
12476 combination is joined with @var{infix} in the middle, and successive
12477 pairs are joined by @var{separator}. No expansion occurs on any of the
12478 arguments. No output occurs if either the @var{prefix} or @var{suffix}
12479 list is empty, but the lists can contain empty elements.
12481 m4_define([a], [oops])dnl
12482 m4_combine([, ], [[a], [b], [c]], [-], [1], [2], [3])
12483 @result{}a-1, a-2, a-3, b-1, b-2, b-3, c-1, c-2, c-3
12484 m4_combine([, ], [[a], [b]], [-])
12486 m4_combine([, ], [[a], [b]], [-], [])
12488 m4_combine([, ], [], [-], [1], [2])
12490 m4_combine([, ], [[]], [-], [1], [2])
12495 @defmac m4_escape (@var{string})
12497 Convert all instances of @samp{[}, @samp{]}, @samp{#}, and @samp{$}
12498 within @var{string} into their respective quadrigraphs. The result is
12499 still a quoted string.
12502 @defmac m4_flatten (@var{string})
12504 Flatten @var{string} into a single line. Delete all backslash-newline
12505 pairs, and replace all remaining newlines with a space. The result is
12506 still a quoted string.
12509 @defmac m4_join (@ovar{separator}, @var{args}@dots{})
12510 @defmacx m4_joinall (@ovar{separator}, @var{args}@dots{})
12513 Concatenate each @var{arg}, separated by @var{separator}.
12514 @code{joinall} uses every argument, while @code{join} omits empty
12515 arguments so that there are no back-to-back separators in the output.
12516 The result is a quoted string.
12518 m4_define([active], [ACTIVE])dnl
12519 m4_join([|], [one], [], [active], [two])
12520 @result{}one|active|two
12521 m4_joinall([|], [one], [], [active], [two])
12522 @result{}one||active|two
12525 Note that if all you intend to do is join @var{args} with commas between
12526 them, to form a quoted list suitable for @code{m4_foreach}, it is more
12527 efficient to use @code{m4_dquote}.
12530 @defmac m4_newline (@ovar{text})
12532 This macro was introduced in Autoconf 2.62, and expands to a newline,
12533 followed by any @var{text}.
12534 It is primarily useful for maintaining macro formatting, and ensuring
12535 that M4 does not discard leading whitespace during argument collection.
12538 @defmac m4_normalize (@var{string})
12539 @msindex{normalize}
12540 Remove leading and trailing spaces and tabs, sequences of
12541 backslash-then-newline, and replace multiple spaces, tabs, and newlines
12542 with a single space. This is a combination of @code{m4_flatten} and
12543 @code{m4_strip}. To determine if @var{string} consists only of bytes
12544 that would be removed by @code{m4_normalize}, you can use
12548 @defmac m4_re_escape (@var{string})
12549 @msindex{re_escape}
12550 Backslash-escape all characters in @var{string} that are active in
12554 @c We cannot use @dvar because the macro expansion mistreats backslashes.
12555 @defmac m4_split (@var{string}, @r{[}@var{regexp} = @samp{[\t ]+}@r{]})
12557 Split @var{string} into an M4 list of elements quoted by @samp{[} and
12558 @samp{]}, while keeping white space at the beginning and at the end.
12559 If @var{regexp} is given, use it instead of @samp{[\t ]+} for splitting.
12560 If @var{string} is empty, the result is an empty list.
12563 @defmac m4_strip (@var{string})
12565 Strip whitespace from @var{string}. Sequences of spaces and tabs are
12566 reduced to a single space, then leading and trailing spaces are removed.
12567 The result is still a quoted string. Note that this does not interfere
12568 with newlines; if you want newlines stripped as well, consider
12569 @code{m4_flatten}, or do it all at once with @code{m4_normalize}. To
12570 quickly test if @var{string} has only whitespace, use @code{m4_ifblank}.
12573 @defmac m4_text_box (@var{message}, @dvar{frame, -})
12575 Add a text box around @var{message}, using @var{frame} as the border
12576 character above and below the message. The @var{frame} argument must be
12577 a single byte, and does not support quadrigraphs.
12578 The frame correctly accounts for
12579 the subsequent expansion of @var{message}. For example:
12581 m4_define([macro], [abc])dnl
12582 m4_text_box([macro])
12588 The @var{message} must contain balanced quotes and parentheses, although
12589 quadrigraphs can be used to work around this.
12592 @defmac m4_text_wrap (@var{string}, @ovar{prefix}, @
12593 @dvar{prefix1, @var{prefix}}, @dvar{width, 79})
12594 @msindex{text_wrap}
12595 Break @var{string} into a series of whitespace-separated words, then
12596 output those words separated by spaces, and wrapping lines any time the
12597 output would exceed @var{width} columns. If given, @var{prefix1} begins
12598 the first line, and @var{prefix} begins all wrapped lines. If
12599 @var{prefix1} is longer than @var{prefix}, then the first line consists
12600 of just @var{prefix1}. If @var{prefix} is longer than @var{prefix1},
12601 padding is inserted so that the first word of @var{string} begins at the
12602 same indentation as all wrapped lines. Note that using literal tab
12603 characters in any of the arguments will interfere with the calculation
12604 of width. No expansions occur on @var{prefix}, @var{prefix1}, or the
12605 words of @var{string}, although quadrigraphs are recognized.
12609 m4_text_wrap([Short string */], [ ], [/* ], [20])
12610 @result{}/* Short string */
12611 m4_text_wrap([Much longer string */], [ ], [/* ], [20])
12612 @result{}/* Much longer
12613 @result{} string */
12614 m4_text_wrap([Short doc.], [ ], [ --short ], [30])
12615 @result{} --short Short doc.
12616 m4_text_wrap([Short doc.], [ ], [ --too-wide ], [30])
12617 @result{} --too-wide
12618 @result{} Short doc.
12619 m4_text_wrap([Super long documentation.], [ ],
12620 [ --too-wide ], 30)
12621 @result{} --too-wide
12622 @result{} Super long
12623 @result{} documentation.
12627 @defmac m4_tolower (@var{string})
12628 @defmacx m4_toupper (@var{string})
12631 Return @var{string} with letters converted to upper or lower case,
12635 @node Number processing Macros
12636 @subsection Arithmetic computation in M4
12638 The following macros facilitate integer arithmetic operations.
12639 Where a parameter is documented as taking an arithmetic expression, you
12640 can use anything that can be parsed by @code{m4_eval}.
12642 @defmac m4_cmp (@var{expr-1}, @var{expr-2})
12644 Compare the arithmetic expressions @var{expr-1} and @var{expr-2}, and
12645 expand to @samp{-1} if @var{expr-1} is smaller, @samp{0} if they are
12646 equal, and @samp{1} if @var{expr-1} is larger.
12649 @defmac m4_list_cmp (@var{list-1}, @var{list-2})
12651 Compare the two M4 lists consisting of comma-separated arithmetic
12652 expressions, left to right. Expand to @samp{-1} for the first element
12653 pairing where the value from @var{list-1} is smaller, @samp{1} where the
12654 value from @var{list-2} is smaller, or @samp{0} if both lists have the
12655 same values. If one list is shorter than the other, the remaining
12656 elements of the longer list are compared against zero.
12658 m4_list_cmp([1, 0], [1])
12660 m4_list_cmp([1, [1 * 0]], [1, 0])
12662 m4_list_cmp([1, 2], [1, 0])
12664 m4_list_cmp([1, [1+1], 3],[1, 2])
12666 m4_list_cmp([1, 2, -3], [1, 2])
12668 m4_list_cmp([1, 0], [1, 2])
12670 m4_list_cmp([1], [1, 2])
12675 @defmac m4_max (@var{arg}, @dots{})
12677 This macro was introduced in Autoconf 2.62. Expand to the decimal value
12678 of the maximum arithmetic expression among all the arguments.
12681 @defmac m4_min (@var{arg}, @dots{})
12683 This macro was introduced in Autoconf 2.62. Expand to the decimal value
12684 of the minimum arithmetic expression among all the arguments.
12687 @defmac m4_sign (@var{expr})
12689 Expand to @samp{-1} if the arithmetic expression @var{expr} is negative,
12690 @samp{1} if it is positive, and @samp{0} if it is zero.
12693 @anchor{m4_version_compare}
12694 @defmac m4_version_compare (@var{version-1}, @var{version-2})
12695 @msindex{version_compare}
12696 This macro was introduced in Autoconf 2.53, but had a number of
12697 usability limitations that were not lifted until Autoconf 2.62. Compare
12698 the version strings @var{version-1} and @var{version-2}, and expand to
12699 @samp{-1} if @var{version-1} is smaller, @samp{0} if they are the same,
12700 or @samp{1} @var{version-2} is smaller. Version strings must be a list
12701 of elements separated by @samp{.}, @samp{,} or @samp{-}, where each
12702 element is a number along with optional case-insensitive letters
12703 designating beta releases. The comparison stops at the leftmost element
12704 that contains a difference, although a 0 element compares equal to a
12707 It is permissible to include commit identifiers in @var{version}, such
12708 as an abbreviated SHA1 of the commit, provided there is still a
12709 monotonically increasing prefix to allow for accurate version-based
12710 comparisons. For example, this paragraph was written when the
12711 development snapshot of autoconf claimed to be at version
12712 @samp{2.61a-248-dc51}, or 248 commits after the 2.61a release, with an
12713 abbreviated commit identification of @samp{dc51}.
12716 m4_version_compare([1.1], [2.0])
12718 m4_version_compare([2.0b], [2.0a])
12720 m4_version_compare([1.1.1], [1.1.1a])
12722 m4_version_compare([1.2], [1.1.1a])
12724 m4_version_compare([1.0], [1])
12726 m4_version_compare([1.1pre], [1.1PRE])
12728 m4_version_compare([1.1a], [1,10])
12730 m4_version_compare([2.61a], [2.61a-248-dc51])
12732 m4_version_compare([2.61b], [2.61a-248-dc51])
12737 @defmac m4_version_prereq (@var{version}, @ovar{if-new-enough}, @
12738 @dvar{if-old, m4_fatal})
12739 @msindex{version_prereq}
12740 Compares @var{version} against the version of Autoconf currently
12741 running. If the running version is at @var{version} or newer, expand
12742 @var{if-new-enough}, but if @var{version} is larger than the version
12743 currently executing, expand @var{if-old}, which defaults to printing an
12744 error message and exiting m4sugar with status 63. When given only one
12745 argument, this behaves like @code{AC_PREREQ} (@pxref{Versioning}).
12746 Remember that the autoconf philosophy favors feature checks over version
12750 @node Set manipulation Macros
12751 @subsection Set manipulation in M4
12752 @cindex Set manipulation
12753 @cindex Data structure, set
12754 @cindex Unordered set manipulation
12756 Sometimes, it is necessary to track a set of data, where the order does
12757 not matter and where there are no duplicates in the set. The following
12758 macros facilitate set manipulations. Each set is an opaque object,
12759 which can only be accessed via these basic operations. The underlying
12760 implementation guarantees linear scaling for set creation, which is more
12761 efficient than using the quadratic @code{m4_append_uniq}. Both set
12762 names and values can be arbitrary strings, except for unbalanced quotes.
12763 This implementation ties up memory for removed elements until the next
12764 operation that must traverse all the elements of a set; and although
12765 that may slow down some operations until the memory for removed elements
12766 is pruned, it still guarantees linear performance.
12768 @defmac m4_set_add (@var{set}, @var{value}, @ovar{if-uniq}, @ovar{if-dup})
12770 Adds the string @var{value} as a member of set @var{set}. Expand
12771 @var{if-uniq} if the element was added, or @var{if-dup} if it was
12772 previously in the set. Operates in amortized constant time, so that set
12773 creation scales linearly.
12776 @defmac m4_set_add_all (@var{set}, @var{value}@dots{})
12777 @msindex{set_add_all}
12778 Adds each @var{value} to the set @var{set}. This is slightly more
12779 efficient than repeatedly invoking @code{m4_set_add}.
12782 @defmac m4_set_contains (@var{set}, @var{value}, @ovar{if-present}, @
12784 @msindex{set_contains}
12785 Expands @var{if-present} if the string @var{value} is a member of
12786 @var{set}, otherwise @var{if-absent}.
12789 m4_set_contains([a], [1], [yes], [no])
12791 m4_set_add([a], [1], [added], [dup])
12793 m4_set_add([a], [1], [added], [dup])
12795 m4_set_contains([a], [1], [yes], [no])
12797 m4_set_remove([a], [1], [removed], [missing])
12799 m4_set_contains([a], [1], [yes], [no])
12801 m4_set_remove([a], [1], [removed], [missing])
12806 @defmac m4_set_contents (@var{set}, @ovar{sep})
12807 @defmacx m4_set_dump (@var{set}, @ovar{sep})
12808 @msindex{set_contents}
12810 Expands to a single string consisting of all the members of the set
12811 @var{set}, each separated by @var{sep}, which is not expanded.
12812 @code{m4_set_contents} leaves the elements in @var{set} but reclaims any
12813 memory occupied by removed elements, while @code{m4_set_dump} is a
12814 faster one-shot action that also deletes the set. No provision is made
12815 for disambiguating members that contain a non-empty @var{sep} as a
12816 substring; use @code{m4_set_empty} to distinguish between an empty set
12817 and the set containing only the empty string. The order of the output
12818 is unspecified; in the current implementation, part of the speed of
12819 @code{m4_set_dump} results from using a different output order than
12820 @code{m4_set_contents}. These macros scale linearly in the size of the
12821 set before memory pruning, and @code{m4_set_contents([@var{set}],
12822 [@var{sep}])} is faster than
12823 @code{m4_joinall([@var{sep}]m4_set_listc([@var{set}]))}.
12826 m4_set_add_all([a], [1], [2], [3])
12828 m4_set_contents([a], [-])
12830 m4_joinall([-]m4_set_listc([a]))
12832 m4_set_dump([a], [-])
12834 m4_set_contents([a])
12836 m4_set_add([a], [])
12838 m4_set_contents([a], [-])
12843 @defmac m4_set_delete (@var{set})
12844 @msindex{set_delete}
12845 Delete all elements and memory associated with @var{set}. This is
12846 linear in the set size, and faster than removing one element at a time.
12849 @defmac m4_set_difference (@var{seta}, @var{setb})
12850 @defmacx m4_set_intersection (@var{seta}, @var{setb})
12851 @defmacx m4_set_union (@var{seta}, @var{setb})
12852 @msindex{set_difference}
12853 @msindex{set_intersection}
12854 @msindex{set_union}
12855 Compute the relation between @var{seta} and @var{setb}, and output the
12856 result as a list of quoted arguments without duplicates and with a
12857 leading comma. Set difference selects the elements in @var{seta} but
12858 not @var{setb}, intersection selects only elements in both sets, and
12859 union selects elements in either set. These actions are linear in the
12860 sum of the set sizes. The leading comma is necessary to distinguish
12861 between no elements and the empty string as the only element.
12864 m4_set_add_all([a], [1], [2], [3])
12866 m4_set_add_all([b], [3], [], [4])
12868 m4_set_difference([a], [b])
12870 m4_set_difference([b], [a])
12872 m4_set_intersection([a], [b])
12874 m4_set_union([a], [b])
12879 @defmac m4_set_empty (@var{set}, @ovar{if-empty}, @ovar{if-elements})
12880 @msindex{set_empty}
12881 Expand @var{if-empty} if the set @var{set} has no elements, otherwise
12882 expand @var{if-elements}. This macro operates in constant time. Using
12883 this macro can help disambiguate output from @code{m4_set_contents} or
12884 @code{m4_set_list}.
12887 @defmac m4_set_foreach (@var{set}, @var{variable}, @var{action})
12888 @msindex{set_foreach}
12889 For each element in the set @var{set}, expand @var{action} with the
12890 macro @var{variable} defined as the set element. Behavior is
12891 unspecified if @var{action} recursively lists the contents of @var{set}
12892 (although listing other sets is acceptable), or if it modifies the set
12893 in any way other than removing the element currently contained in
12894 @var{variable}. This macro is faster than the corresponding
12895 @code{m4_foreach([@var{variable}],
12896 m4_indir([m4_dquote]m4_set_listc([@var{set}])), [@var{action}])},
12897 although @code{m4_set_map} might be faster still.
12900 m4_set_add_all([a]m4_for([i], [1], [5], [], [,i]))
12902 m4_set_contents([a])
12904 m4_set_foreach([a], [i],
12905 [m4_if(m4_eval(i&1), [0], [m4_set_remove([a], i, [i])])])
12907 m4_set_contents([a])
12912 @defmac m4_set_list (@var{set})
12913 @defmacx m4_set_listc (@var{set})
12915 @msindex{set_listc}
12916 Produce a list of arguments, where each argument is a quoted element
12917 from the set @var{set}. The variant @code{m4_set_listc} is unambiguous,
12918 by adding a leading comma if there are any set elements, whereas the
12919 variant @code{m4_set_list} cannot distinguish between an empty set and a
12920 set containing only the empty string. These can be directly used in
12921 macros that take multiple arguments, such as @code{m4_join} or
12922 @code{m4_set_add_all}, or wrapped by @code{m4_dquote} for macros that
12923 take a quoted list, such as @code{m4_map} or @code{m4_foreach}. Any
12924 memory occupied by removed elements is reclaimed during these macros.
12927 m4_set_add_all([a], [1], [2], [3])
12935 m4_count(m4_set_list([b]))
12937 m4_set_empty([b], [0], [m4_count(m4_set_list([b]))])
12939 m4_set_add([b], [])
12945 m4_count(m4_set_list([b]))
12947 m4_set_empty([b], [0], [m4_count(m4_set_list([b]))])
12952 @defmac m4_set_map (@var{set}, @var{action})
12954 For each element in the set @var{set}, expand @var{action} with a single
12955 argument of the set element. Behavior is unspecified if @var{action}
12956 recursively lists the contents of @var{set} (although listing other sets
12957 is acceptable), or if it modifies the set in any way other than removing
12958 the element passed as an argument. This macro is faster than either
12959 corresponding counterpart of
12960 @code{m4_map_args([@var{action}]m4_set_listc([@var{set}]))} or
12961 @code{m4_set_foreach([@var{set}], [var],
12962 [@var{action}(m4_defn([var]))])}. It is possible to use @code{m4_curry}
12963 if more than one argument is needed for @var{action}, although it is
12964 more efficient to use @code{m4_set_map_sep} in that case.
12967 @defmac m4_set_map_sep (@var{set}, @ovar{pre}, @ovar{post}, @ovar{sep})
12968 @msindex{set_map_sep}
12969 For each element in the set @var{set}, expand
12970 @code{@var{pre}[element]@var{post}}, additionally expanding @var{sep}
12971 between elements. Behavior is unspecified if the expansion recursively
12972 lists the contents of @var{set} (although listing other sets
12973 is acceptable), or if it modifies the set in any way other than removing
12974 the element visited by the expansion. This macro provides the most
12975 efficient means for non-destructively visiting the elements of a set; in
12976 particular, @code{m4_set_map([@var{set}], [@var{action}])} is equivalent
12977 to @code{m4_set_map_sep([@var{set}], [@var{action}(], [)])}.
12980 @defmac m4_set_remove (@var{set}, @var{value}, @ovar{if-present}, @
12982 @msindex{set_remove}
12983 If @var{value} is an element in the set @var{set}, then remove it and
12984 expand @var{if-present}. Otherwise expand @var{if-absent}. This macro
12985 operates in constant time so that multiple removals will scale linearly
12986 rather than quadratically; but when used outside of
12987 @code{m4_set_foreach} or @code{m4_set_map}, it leaves memory occupied
12988 until the set is later
12989 compacted by @code{m4_set_contents} or @code{m4_set_list}. Several
12990 other set operations are then less efficient between the time of element
12991 removal and subsequent memory compaction, but still maintain their
12992 guaranteed scaling performance.
12995 @defmac m4_set_size (@var{set})
12997 Expand to the size of the set @var{set}. This implementation operates
12998 in constant time, and is thus more efficient than
12999 @code{m4_eval(m4_count(m4_set_listc([set])) - 1)}.
13003 @node Forbidden Patterns
13004 @subsection Forbidden Patterns
13005 @cindex Forbidden patterns
13006 @cindex Patterns, forbidden
13008 M4sugar provides a means to define suspicious patterns, patterns
13009 describing tokens which should not be found in the output. For
13010 instance, if an Autoconf @file{configure} script includes tokens such as
13011 @samp{AC_DEFINE}, or @samp{dnl}, then most probably something went
13012 wrong (typically a macro was not evaluated because of overquotation).
13014 M4sugar forbids all the tokens matching @samp{^_?m4_} and @samp{^dnl$}.
13015 Additional layers, such as M4sh and Autoconf, add additional forbidden
13016 patterns to the list.
13018 @defmac m4_pattern_forbid (@var{pattern})
13019 @msindex{pattern_forbid}
13020 Declare that no token matching @var{pattern} must be found in the output.
13021 Comments are not checked; this can be a problem if, for instance, you
13022 have some macro left unexpanded after an @samp{#include}. No consensus
13023 is currently found in the Autoconf community, as some people consider it
13024 should be valid to name macros in comments (which doesn't make sense to
13025 the authors of this documentation: input, such as macros, should be
13026 documented by @samp{dnl} comments; reserving @samp{#}-comments to
13027 document the output).
13030 Of course, you might encounter exceptions to these generic rules, for
13031 instance you might have to refer to @samp{$m4_flags}.
13033 @defmac m4_pattern_allow (@var{pattern})
13034 @msindex{pattern_allow}
13035 Any token matching @var{pattern} is allowed, including if it matches an
13036 @code{m4_pattern_forbid} pattern.
13039 @node Debugging via autom4te
13040 @section Debugging via autom4te
13041 @cindex debugging tips
13042 @cindex autom4te debugging tips
13043 @cindex m4sugar debugging tips
13044 At times, it is desirable to see what was happening inside m4, to see
13045 why output was not matching expectations. However, post-processing done
13046 by @command{autom4te} means that directly using the m4 builtin
13047 @code{m4_traceon} is likely to interfere with operation. Also, frequent
13048 diversion changes and the concept of forbidden tokens make it difficult
13049 to use @code{m4_defn} to generate inline comments in the final output.
13051 There are a couple of tools to help with this. One is the use of the
13052 @option{--trace} option provided by @command{autom4te} (as well as each
13053 of the programs that wrap @command{autom4te}, such as
13054 @command{autoconf}), in order to inspect when a macro is called and with
13055 which arguments. For example, when this paragraph was written, the
13056 autoconf version could be found by:
13059 $ @kbd{autoconf --trace=AC_INIT}
13060 configure.ac:23:AC_INIT:GNU Autoconf:2.63b.95-3963:bug-autoconf@@gnu.org
13061 $ @kbd{autoconf --trace='AC_INIT:version is $2'}
13062 version is 2.63b.95-3963
13065 Another trick is to print out the expansion of various m4 expressions to
13066 standard error or to an independent file, with no further m4 expansion,
13067 and without interfering with diversion changes or the post-processing
13068 done to standard output. @code{m4_errprintn} shows a given expression
13069 on standard error. For example, if you want to see the expansion of an
13070 autoconf primitive or of one of your autoconf macros, you can do it like
13074 $ @kbd{cat <<\EOF > configure.ac}
13076 m4_errprintn([The definition of AC_DEFINE_UNQUOTED:])
13077 m4_errprintn(m4_defn([AC_DEFINE_UNQUOTED]))
13081 @error{}The definition of AC_DEFINE_UNQUOTED:
13082 @error{}_AC_DEFINE_Q([], $@@)
13085 @node Programming in M4sh
13086 @chapter Programming in M4sh
13088 M4sh, pronounced ``mash'', is aiming at producing portable Bourne shell
13089 scripts. This name was coined by Lars J. Aas, who notes that,
13090 according to the Webster's Revised Unabridged Dictionary (1913):
13093 Mash \Mash\, n. [Akin to G. meisch, maisch, meische, maische, mash,
13094 wash, and prob.@: to AS. miscian to mix. See ``Mix''.]
13098 A mass of mixed ingredients reduced to a soft pulpy state by beating or
13102 A mixture of meal or bran and water fed to animals.
13105 A mess; trouble. [Obs.] --Beau.@: & Fl.
13109 M4sh reserves the M4 macro namespace @samp{^_AS_} for internal use, and
13110 the namespace @samp{^AS_} for M4sh macros. It also reserves the shell
13111 and environment variable namespace @samp{^as_}, and the here-document
13112 delimiter namespace @samp{^_AS[A-Z]} in the output file. You should not
13113 define your own macros or output shell code that conflicts with these
13117 * Common Shell Constructs:: Portability layer for common shell constructs
13118 * Polymorphic Variables:: Support for indirect variable names
13119 * Initialization Macros:: Macros to establish a sane shell environment
13120 * File Descriptor Macros:: File descriptor macros for input and output
13123 @node Common Shell Constructs
13124 @section Common Shell Constructs
13126 M4sh provides portable alternatives for some common shell constructs
13127 that unfortunately are not portable in practice.
13129 @c Deprecated, to be replaced by a better API
13131 @defmac AS_BASENAME (@var{file-name})
13133 Output the non-directory portion of @var{file-name}. For example,
13134 if @code{$file} is @samp{/one/two/three}, the command
13135 @code{base=`AS_BASENAME(["$file"])`} sets @code{base} to @samp{three}.
13139 @defmac AS_BOX (@var{text}, @dvar{char, -})
13141 Expand into shell code that will output @var{text} surrounded by a box
13142 with @var{char} in the top and bottom border. @var{text} should not
13143 contain a newline, but may contain shell expansions valid for unquoted
13144 here-documents. @var{char} defaults to @samp{-}, but can be any
13145 character except @samp{/}, @samp{'}, @samp{"}, @samp{\},
13146 @samp{&}, or @samp{`}. This is useful for outputting a comment box into
13147 log files to separate distinct phases of script operation.
13150 @defmac AS_CASE (@var{word}, @ovar{pattern1}, @ovar{if-matched1}, @
13151 @dots{}, @ovar{default})
13153 Expand into a shell @samp{case} statement, where @var{word} is matched
13154 against one or more patterns. @var{if-matched} is run if the
13155 corresponding pattern matched @var{word}, else @var{default} is run.
13156 Avoids several portability issues (@pxref{case, , Limitations of Shell
13160 @c Deprecated, to be replaced by a better API
13161 @defmac AS_DIRNAME (@var{file-name})
13163 Output the directory portion of @var{file-name}. For example,
13164 if @code{$file} is @samp{/one/two/three}, the command
13165 @code{dir=`AS_DIRNAME(["$file"])`} sets @code{dir} to @samp{/one/two}.
13167 This interface may be improved in the future to avoid forks and losing
13171 @defmac AS_ECHO (@var{word})
13173 Emits @var{word} to the standard output, followed by a newline. @var{word}
13174 must be a single shell word (typically a quoted string). The bytes of
13175 @var{word} are output as-is, even if it starts with "-" or contains "\".
13176 Redirections can be placed outside the macro invocation. This is much
13177 more portable than using @command{echo} (@pxref{echo, , Limitations of
13181 @defmac AS_ECHO_N (@var{word})
13183 Emits @var{word} to the standard output, without a following newline.
13184 @var{word} must be a single shell word (typically a quoted string) and,
13185 for portability, should not include more than one newline. The bytes of
13186 @var{word} are output as-is, even if it starts with "-" or contains "\".
13187 Redirections can be placed outside the macro invocation.
13190 @c We cannot use @dvar because the macro expansion mistreats backslashes.
13191 @defmac AS_ESCAPE (@var{string}, @r{[}@var{chars} = @samp{`\"$}@r{]})
13193 Expands to @var{string}, with any characters in @var{chars} escaped with
13194 a backslash (@samp{\}). @var{chars} should be at most four bytes long,
13195 and only contain characters from the set @samp{`\"$}; however,
13196 characters may be safely listed more than once in @var{chars} for the
13197 sake of syntax highlighting editors. The current implementation expands
13198 @var{string} after adding escapes; if @var{string} contains macro calls
13199 that in turn expand to text needing shell quoting, you can use
13200 @code{AS_ESCAPE(m4_dquote(m4_expand([string])))}.
13202 The default for @var{chars} (@samp{\"$`}) is the set of characters
13203 needing escapes when @var{string} will be used literally within double
13204 quotes. One common variant is the set of characters to protect when
13205 @var{string} will be used literally within back-ticks or an unquoted
13206 here-document (@samp{\$`}). Another common variant is @samp{""}, which can
13207 be used to form a double-quoted string containing the same expansions
13208 that would have occurred if @var{string} were expanded in an unquoted
13209 here-document; however, when using this variant, care must be taken that
13210 @var{string} does not use double quotes within complex variable
13211 expansions (such as @samp{$@{foo-`echo "hi"`@}}) that would be broken
13212 with improper escapes.
13214 This macro is often used with @code{AS_ECHO}. For an example, observe
13215 the output generated by the shell code generated from this snippet:
13219 AS_ECHO(["AS_ESCAPE(["$foo" = ])AS_ESCAPE(["$foo"], [""])"])
13220 @result{}"$foo" = "bar"
13221 m4_define([macro], [a, [\b]])
13222 AS_ECHO(["AS_ESCAPE([[macro]])"])
13224 AS_ECHO(["AS_ESCAPE([macro])"])
13226 AS_ECHO(["AS_ESCAPE(m4_dquote(m4_expand([macro])))"])
13230 @comment Should we add AS_ESCAPE_SINGLE? If we do, we can optimize in
13231 @comment the case of @var{string} that does not contain '.
13232 To escape a string that will be placed within single quotes, use:
13235 m4_bpatsubst([[@var{string}]], ['], ['\\''])
13239 @defmac AS_EXIT (@dvar{status, $?})
13241 Emit code to exit the shell with @var{status}, defaulting to @samp{$?}.
13243 works around shells that see the exit status of the command prior to
13244 @code{exit} inside a @samp{trap 0} handler (@pxref{trap, , Limitations
13245 of Shell Builtins}).
13248 @defmac AS_IF (@var{test1}, @ovar{run-if-true1}, @dots{}, @ovar{run-if-false})
13250 Run shell code @var{test1}. If @var{test1} exits with a zero status then
13251 run shell code @var{run-if-true1}, else examine further tests. If no test
13252 exits with a zero status, run shell code @var{run-if-false}, with
13253 simplifications if either @var{run-if-true1} or @var{run-if-false}
13254 is empty. For example,
13257 AS_IF([test "x$foo" = xyes], [HANDLE_FOO([yes])],
13258 [test "x$foo" != xno], [HANDLE_FOO([maybe])],
13259 [echo foo not specified])
13263 ensures any required macros of @code{HANDLE_FOO}
13264 are expanded before the first test.
13267 @defmac AS_MKDIR_P (@var{file-name})
13269 Make the directory @var{file-name}, including intervening directories
13270 as necessary. This is equivalent to @samp{mkdir -p -- @var{file-name}},
13271 except that it is portable to older versions of @command{mkdir} that
13272 lack support for the @option{-p} option or for the @option{--}
13273 delimiter (@pxref{mkdir, , Limitations of Usual Tools}). Also,
13275 succeeds if @var{file-name} is a symbolic link to an existing directory,
13276 even though Posix is unclear whether @samp{mkdir -p} should
13277 succeed in that case. If creation of @var{file-name} fails, exit the
13280 Also see the @code{AC_PROG_MKDIR_P} macro (@pxref{Particular Programs}).
13283 @defmac AS_SET_STATUS (@var{status})
13284 @asindex{SET_STATUS}
13285 Emit shell code to set the value of @samp{$?} to @var{status}, as
13286 efficiently as possible. However, this is not guaranteed to abort a
13287 shell running with @code{set -e} (@pxref{set, , Limitations of Shell
13288 Builtins}). This should also be used at the end of a complex shell
13289 function instead of @samp{return} (@pxref{Shell Functions}) to avoid
13293 @defmac AS_TR_CPP (@var{expression})
13295 Transform @var{expression} into a valid right-hand side for a C @code{#define}.
13299 # This outputs "#define HAVE_CHAR_P 1".
13300 # Notice the m4 quoting around #, to prevent an m4 comment
13302 echo "[#]define AS_TR_CPP([HAVE_$type]) 1"
13306 @defmac AS_TR_SH (@var{expression})
13308 Transform @var{expression} into shell code that generates a valid shell
13309 variable name. The result is literal when possible at m4 time, but must
13310 be used with @code{eval} if @var{expression} causes shell indirections.
13314 # This outputs "Have it!".
13315 header="sys/some file.h"
13316 eval AS_TR_SH([HAVE_$header])=yes
13317 if test "x$HAVE_sys_some_file_h" = xyes; then echo "Have it!"; fi
13321 @defmac AS_SET_CATFILE (@var{var}, @var{dir}, @var{file})
13322 @asindex{SET_CATFILE}
13323 Set the polymorphic shell variable @var{var} to @var{dir}/@var{file},
13324 but optimizing the common cases (@var{dir} or @var{file} is @samp{.},
13325 @var{file} is absolute, etc.).
13328 @defmac AS_UNSET (@var{var})
13330 Unsets the shell variable @var{var}, working around bugs in older
13331 shells (@pxref{unset, , Limitations of Shell
13332 Builtins}). @var{var} can be a literal or indirect variable name.
13335 @defmac AS_VERSION_COMPARE (@var{version-1}, @var{version-2}, @
13336 @ovar{action-if-less}, @ovar{action-if-equal}, @ovar{action-if-greater})
13337 @asindex{VERSION_COMPARE}
13338 Compare two strings @var{version-1} and @var{version-2}, possibly
13339 containing shell variables, as version strings, and expand
13340 @var{action-if-less}, @var{action-if-equal}, or @var{action-if-greater}
13341 depending upon the result.
13342 The algorithm to compare is similar to the one used by strverscmp in
13343 glibc (@pxref{String/Array Comparison, , String/Array Comparison, libc,
13344 The GNU C Library}).
13347 @node Polymorphic Variables
13348 @section Support for indirect variable names
13349 @cindex variable name indirection
13350 @cindex polymorphic variable name
13351 @cindex indirection, variable name
13353 Often, it is convenient to write a macro that will emit shell code
13354 operating on a shell variable. The simplest case is when the variable
13355 name is known. But a more powerful idiom is writing shell code that can
13356 work through an indirection, where another variable or command
13357 substitution produces the name of the variable to actually manipulate.
13358 M4sh supports the notion of polymorphic shell variables, making it easy
13359 to write a macro that can deal with either literal or indirect variable
13360 names and output shell code appropriate for both use cases. Behavior is
13361 undefined if expansion of an indirect variable does not result in a
13362 literal variable name.
13364 @defmac AS_LITERAL_IF (@var{expression}, @ovar{if-literal}, @ovar{if-not}, @
13365 @dvar{if-simple-ref, @var{if-not}})
13366 @defmacx AS_LITERAL_WORD_IF (@var{expression}, @ovar{if-literal}, @
13367 @ovar{if-not}, @dvar{if-simple-ref, @var{if-not}})
13368 @asindex{LITERAL_IF}
13369 @asindex{LITERAL_WORD_IF}
13370 If the expansion of @var{expression} is definitely a shell literal,
13371 expand @var{if-literal}. If the expansion of @var{expression} looks
13372 like it might contain shell indirections (such as @code{$var} or
13373 @code{`expr`}), then @var{if-not} is expanded. Sometimes, it is
13374 possible to output optimized code if @var{expression} consists only of
13375 shell variable expansions (such as @code{$@{var@}}), in which case
13376 @var{if-simple-ref} can be provided; but defaulting to @var{if-not}
13377 should always be safe. @code{AS_LITERAL_WORD_IF} only expands
13378 @var{if-literal} if @var{expression} looks like a single shell word,
13379 containing no whitespace; while @code{AS_LITERAL_IF} allows whitespace
13380 in @var{expression}.
13382 In order to reduce the time spent recognizing whether an
13383 @var{expression} qualifies as a literal or a simple indirection, the
13384 implementation is somewhat conservative: @var{expression} must be a
13385 single shell word (possibly after stripping whitespace), consisting only
13386 of bytes that would have the same meaning whether unquoted or enclosed
13387 in double quotes (for example, @samp{a.b} results in @var{if-literal},
13388 even though it is not a valid shell variable name; while both @samp{'a'}
13389 and @samp{[$]} result in @var{if-not}, because they behave differently
13390 than @samp{"'a'"} and @samp{"[$]"}). This macro can be used in contexts
13391 for recognizing portable file names (such as in the implementation of
13392 @code{AC_LIBSOURCE}), or coupled with some transliterations for forming
13393 valid variable names (such as in the implementation of @code{AS_TR_SH},
13394 which uses an additional @code{m4_translit} to convert @samp{.} to
13397 This example shows how to read the contents of the shell variable
13398 @code{bar}, exercising all three arguments to @code{AS_LITERAL_IF}. It
13399 results in a script that will output the line @samp{hello} three times.
13402 AC_DEFUN([MY_ACTION],
13403 [AS_LITERAL_IF([$1],
13405 [AS_VAR_COPY([tmp], [$1])
13407 [eval 'echo "$'"$1"\"])])
13410 MY_ACTION([`echo bar`])
13415 @defmac AS_VAR_APPEND (@var{var}, @var{text})
13416 @asindex{VAR_APPEND}
13417 Emit shell code to append the shell expansion of @var{text} to the end
13418 of the current contents of the polymorphic shell variable @var{var},
13419 taking advantage of shells that provide the @samp{+=} extension for more
13422 For situations where the final contents of @var{var} are relatively
13423 short (less than 256 bytes), it is more efficient to use the simpler
13424 code sequence of @code{@var{var}=$@{@var{var}@}@var{text}} (or its
13425 polymorphic equivalent of @code{AS_VAR_COPY([tmp], [@var{var}])} and
13426 @code{AS_VAR_SET([@var{var}], ["$tmp"@var{text}])}). But in the case
13427 when the script will be repeatedly appending text into @code{var},
13428 issues of scaling start to become apparent. A naive implementation
13429 requires execution time linear to the length of the current contents of
13430 @var{var} as well as the length of @var{text} for a single append, for
13431 an overall quadratic scaling with multiple appends. This macro takes
13432 advantage of shells which provide the extension
13433 @code{@var{var}+=@var{text}}, which can provide amortized constant time
13434 for a single append, for an overall linear scaling with multiple
13435 appends. Note that unlike @code{AS_VAR_SET}, this macro requires that
13436 @var{text} be quoted properly to avoid field splitting and file name
13440 @defmac AS_VAR_ARITH (@var{var}, @var{expression})
13441 @asindex{VAR_ARITH}
13442 Emit shell code to compute the arithmetic expansion of @var{expression},
13443 assigning the result as the contents of the polymorphic shell variable
13444 @var{var}. The code takes advantage of shells that provide @samp{$(())}
13445 for fewer forks, but uses @command{expr} as a fallback. Therefore, the
13446 syntax for a valid @var{expression} is rather limited: all operators
13447 must occur as separate shell arguments and with proper quoting, there is
13448 no portable equality operator, all variables containing numeric values
13449 must be expanded prior to the computation, all numeric values must be
13450 provided in decimal without leading zeroes, and the first shell argument
13451 should not be a negative number. In the following example, this snippet
13452 will print @samp{(2+3)*4 == 20}.
13456 AS_VAR_ARITH([foo], [\( 2 + $bar \) \* 4])
13457 echo "(2+$bar)*4 == $foo"
13461 @defmac AS_VAR_COPY (@var{dest}, @var{source})
13463 Emit shell code to assign the contents of the polymorphic shell variable
13464 @var{source} to the polymorphic shell variable @var{dest}. For example,
13465 executing this M4sh snippet will output @samp{bar hi}:
13469 AS_VAR_COPY([a], [foo])
13470 AS_VAR_COPY([b], [$foo])
13474 When it is necessary to access the contents of an indirect variable
13475 inside a shell double-quoted context, the recommended idiom is to first
13476 copy the contents into a temporary literal shell variable.
13479 for header in stdint_h inttypes_h ; do
13480 AS_VAR_COPY([var], [ac_cv_header_$header])
13481 echo "$header detected: $var"
13486 @comment AS_VAR_GET is intentionally undocumented; it can't handle
13487 @comment trailing newlines uniformly, and forks too much.
13489 @defmac AS_VAR_IF (@var{var}, @ovar{value}, @ovar{if-equal}, @
13490 @ovar{if-not-equal})
13492 Output a shell conditional statement. If the contents of the
13493 polymorphic shell variable @var{var} match the string @var{value},
13494 execute @var{if-equal}; otherwise execute @var{if-not-equal}. Avoids
13495 shell bugs if an interrupt signal arrives while a command substitution
13496 in @var{var} is being expanded.
13499 @defmac AS_VAR_PUSHDEF (@var{m4-name}, @var{value})
13500 @defmacx AS_VAR_POPDEF (@var{m4-name})
13501 @asindex{VAR_PUSHDEF}
13502 @asindex{VAR_POPDEF}
13503 @cindex composing variable names
13504 @cindex variable names, composing
13505 A common M4sh idiom involves composing shell variable names from an m4
13506 argument (for example, writing a macro that uses a cache variable).
13507 @var{value} can be an arbitrary string, which will be transliterated
13508 into a valid shell name by @code{AS_TR_SH}. In order to access the
13509 composed variable name based on @var{value}, it is easier to declare a
13510 temporary m4 macro @var{m4-name} with @code{AS_VAR_PUSHDEF}, then use
13511 that macro as the argument to subsequent @code{AS_VAR} macros as a
13512 polymorphic variable name, and finally free the temporary macro with
13513 @code{AS_VAR_POPDEF}. These macros are often followed with @code{dnl},
13514 to avoid excess newlines in the output.
13516 Here is an involved example, that shows the power of writing macros that
13517 can handle composed shell variable names:
13520 m4_define([MY_CHECK_HEADER],
13521 [AS_VAR_PUSHDEF([my_Header], [ac_cv_header_$1])dnl
13522 AS_VAR_IF([my_Header], [yes], [echo "header $1 detected"])dnl
13523 AS_VAR_POPDEF([my_Header])dnl
13525 MY_CHECK_HEADER([stdint.h])
13526 for header in inttypes.h stdlib.h ; do
13527 MY_CHECK_HEADER([$header])
13532 In the above example, @code{MY_CHECK_HEADER} can operate on polymorphic
13533 variable names. In the first invocation, the m4 argument is
13534 @code{stdint.h}, which transliterates into a literal @code{stdint_h}.
13535 As a result, the temporary macro @code{my_Header} expands to the literal
13536 shell name @samp{ac_cv_header_stdint_h}. In the second invocation, the
13537 m4 argument to @code{MY_CHECK_HEADER} is @code{$header}, and the
13538 temporary macro @code{my_Header} expands to the indirect shell name
13539 @samp{$as_my_Header}. During the shell execution of the for loop, when
13540 @samp{$header} contains @samp{inttypes.h}, then @samp{$as_my_Header}
13541 contains @samp{ac_cv_header_inttypes_h}. If this script is then run on a
13542 platform where all three headers have been previously detected, the
13543 output of the script will include:
13546 header stdint.h detected
13547 header inttypes.h detected
13548 header stdlib.h detected
13552 @defmac AS_VAR_SET (@var{var}, @ovar{value})
13554 Emit shell code to assign the contents of the polymorphic shell variable
13555 @var{var} to the shell expansion of @var{value}. @var{value} is not
13556 subject to field splitting or file name expansion, so if command
13557 substitution is used, it may be done with @samp{`""`} rather than using
13558 an intermediate variable (@pxref{Shell Substitutions}). However,
13559 @var{value} does undergo rescanning for additional macro names; behavior
13560 is unspecified if late expansion results in any shell meta-characters.
13563 @defmac AS_VAR_SET_IF (@var{var}, @ovar{if-set}, @ovar{if-undef})
13564 @asindex{VAR_SET_IF}
13565 Emit a shell conditional statement, which executes @var{if-set} if the
13566 polymorphic shell variable @code{var} is set to any value, and
13567 @var{if-undef} otherwise.
13570 @defmac AS_VAR_TEST_SET (@var{var})
13571 @asindex{VAR_TEST_SET}
13572 Emit a shell statement that results in a successful exit status only if
13573 the polymorphic shell variable @code{var} is set.
13576 @node Initialization Macros
13577 @section Initialization Macros
13579 @defmac AS_BOURNE_COMPATIBLE
13580 @asindex{BOURNE_COMPATIBLE}
13581 Set up the shell to be more compatible with the Bourne shell as
13582 standardized by Posix, if possible. This may involve setting
13583 environment variables, or setting options, or similar
13584 implementation-specific actions. This macro is deprecated, since
13585 @code{AS_INIT} already invokes it.
13592 Initialize the M4sh environment. This macro calls @code{m4_init}, then
13593 outputs the @code{#! /bin/sh} line, a notice about where the output was
13594 generated from, and code to sanitize the environment for the rest of the
13595 script. Among other initializations, this sets @env{SHELL} to the shell
13596 chosen to run the script (@pxref{CONFIG_SHELL}), and @env{LC_ALL} to
13597 ensure the C locale. Finally, it changes the current diversion to
13598 @code{BODY}. @code{AS_INIT} is called automatically by @code{AC_INIT}
13599 and @code{AT_INIT}, so shell code in @file{configure},
13600 @file{config.status}, and @file{testsuite} all benefit from a sanitized
13604 @defmac AS_INIT_GENERATED (@var{file}, @ovar{comment})
13605 @asindex{INIT_GENERATED}
13606 Emit shell code to start the creation of a subsidiary shell script in
13607 @var{file}, including changing @var{file} to be executable. This macro
13608 populates the child script with information learned from the parent
13609 (thus, the emitted code is equivalent in effect, but more efficient,
13610 than the code output by @code{AS_INIT}, @code{AS_BOURNE_COMPATIBLE}, and
13611 @code{AS_SHELL_SANITIZE}). If present, @var{comment} is output near the
13612 beginning of the child, prior to the shell initialization code, and is
13613 subject to parameter expansion, command substitution, and backslash
13615 parent script should check the exit status after this macro, in case
13616 @var{file} could not be properly created (for example, if the disk was
13617 full). If successfully created, the parent script can then proceed to
13618 append additional M4sh constructs into the child script.
13620 Note that the child script starts life without a log file open, so if
13621 the parent script uses logging (@pxref{AS_MESSAGE_LOG_FD}), you
13622 must temporarily disable any attempts to use the log file until after
13623 emitting code to open a log within the child. On the other hand, if the
13624 parent script has @code{AS_MESSAGE_FD} redirected somewhere besides
13625 @samp{1}, then the child script already has code that copies stdout to
13626 that descriptor. Currently, the suggested
13627 idiom for writing a M4sh shell script from within another script is:
13630 AS_INIT_GENERATED([@var{file}], [[# My child script.
13631 ]]) || @{ AS_ECHO(["Failed to create child script"]); AS_EXIT; @}
13632 m4_pushdef([AS_MESSAGE_LOG_FD])dnl
13633 cat >> "@var{file}" <<\__EOF__
13634 # Code to initialize AS_MESSAGE_LOG_FD
13635 m4_popdef([AS_MESSAGE_LOG_FD])dnl
13640 This, however, may change in the future as the M4sh interface is
13641 stabilized further.
13643 Also, be aware that use of @env{LINENO} within the child script may
13644 report line numbers relative to their location in the parent script,
13645 even when using @code{AS_LINENO_PREPARE}, if the parent script was
13646 unable to locate a shell with working @env{LINENO} support.
13649 @defmac AS_LINENO_PREPARE
13650 @asindex{LINENO_PREPARE}
13652 Find a shell that supports the special variable @env{LINENO}, which
13653 contains the number of the currently executing line. This macro is
13654 automatically invoked by @code{AC_INIT} in configure scripts.
13657 @defmac AS_ME_PREPARE
13658 @asindex{ME_PREPARE}
13659 Set up variable @env{as_me} to be the basename of the currently executing
13660 script. This macro is automatically invoked by @code{AC_INIT} in
13664 @defmac AS_SHELL_SANITIZE
13665 @asindex{SHELL_SANITIZE}
13666 Initialize the shell suitably for @command{configure} scripts. This has
13667 the effect of @code{AS_BOURNE_COMPATIBLE}, and sets some other
13668 environment variables for predictable results from configuration tests.
13669 For example, it sets @env{LC_ALL} to change to the default C locale.
13670 @xref{Special Shell Variables}. This macro is deprecated, since
13671 @code{AS_INIT} already invokes it.
13675 @node File Descriptor Macros
13676 @section File Descriptor Macros
13678 @cindex standard input
13679 @cindex file descriptors
13680 @cindex descriptors
13681 @cindex low-level output
13682 @cindex output, low-level
13684 The following macros define file descriptors used to output messages
13685 (or input values) from @file{configure} scripts.
13689 echo "$wombats found" >&AS_MESSAGE_LOG_FD
13690 echo 'Enter desired kangaroo count:' >&AS_MESSAGE_FD
13691 read kangaroos <&AS_ORIGINAL_STDIN_FD`
13695 However doing so is seldom needed, because Autoconf provides higher
13696 level macros as described below.
13698 @defmac AS_MESSAGE_FD
13699 @asindex{MESSAGE_FD}
13700 The file descriptor for @samp{checking for...} messages and results.
13701 By default, @code{AS_INIT} sets this to @samp{1} for standalone M4sh
13702 clients. However, @code{AC_INIT} shuffles things around to another file
13703 descriptor, in order to allow the @option{-q} option of
13704 @command{configure} to choose whether messages should go to the script's
13705 standard output or be discarded.
13707 If you want to display some messages, consider using one of the printing
13708 macros (@pxref{Printing Messages}) instead. Copies of messages output
13709 via these macros are also recorded in @file{config.log}.
13712 @anchor{AS_MESSAGE_LOG_FD}
13713 @defmac AS_MESSAGE_LOG_FD
13714 @asindex{MESSAGE_LOG_FD}
13715 This must either be empty, or expand to a file descriptor for log
13716 messages. By default, @code{AS_INIT} sets this macro to the empty
13717 string for standalone M4sh clients, thus disabling logging. However,
13718 @code{AC_INIT} shuffles things around so that both @command{configure}
13719 and @command{config.status} use @file{config.log} for log messages.
13720 Macros that run tools, like @code{AC_COMPILE_IFELSE} (@pxref{Running the
13721 Compiler}), redirect all output to this descriptor. You may want to do
13722 so if you develop such a low-level macro.
13725 @defmac AS_ORIGINAL_STDIN_FD
13726 @asindex{ORIGINAL_STDIN_FD}
13727 This must expand to a file descriptor for the original standard input.
13728 By default, @code{AS_INIT} sets this macro to @samp{0} for standalone
13729 M4sh clients. However, @code{AC_INIT} shuffles things around for
13732 When @command{configure} runs, it may accidentally execute an
13733 interactive command that has the same name as the non-interactive meant
13734 to be used or checked. If the standard input was the terminal, such
13735 interactive programs would cause @command{configure} to stop, pending
13736 some user input. Therefore @command{configure} redirects its standard
13737 input from @file{/dev/null} during its initialization. This is not
13738 normally a problem, since @command{configure} normally does not need
13741 In the extreme case where your @file{configure} script really needs to
13742 obtain some values from the original standard input, you can read them
13743 explicitly from @code{AS_ORIGINAL_STDIN_FD}.
13747 @c =================================================== Writing Autoconf Macros.
13749 @node Writing Autoconf Macros
13750 @chapter Writing Autoconf Macros
13752 When you write a feature test that could be applicable to more than one
13753 software package, the best thing to do is encapsulate it in a new macro.
13754 Here are some instructions and guidelines for writing Autoconf macros.
13757 * Macro Definitions:: Basic format of an Autoconf macro
13758 * Macro Names:: What to call your new macros
13759 * Reporting Messages:: Notifying @command{autoconf} users
13760 * Dependencies Between Macros:: What to do when macros depend on other macros
13761 * Obsoleting Macros:: Warning about old ways of doing things
13762 * Coding Style:: Writing Autoconf macros @`a la Autoconf
13765 @node Macro Definitions
13766 @section Macro Definitions
13768 @defmac AC_DEFUN (@var{name}, @ovar{body})
13770 Autoconf macros are defined using the @code{AC_DEFUN} macro, which is
13771 similar to the M4 builtin @code{m4_define} macro; this creates a macro
13772 named @var{name} and with @var{body} as its expansion. In addition to
13773 defining a macro, @code{AC_DEFUN} adds to it some code that is used to
13774 constrain the order in which macros are called, while avoiding redundant
13775 output (@pxref{Prerequisite Macros}).
13778 An Autoconf macro definition looks like this:
13781 AC_DEFUN(@var{macro-name}, @var{macro-body})
13784 You can refer to any arguments passed to the macro as @samp{$1},
13785 @samp{$2}, etc. @xref{Definitions, , How to define new macros, m4.info,
13786 GNU M4}, for more complete information on writing M4 macros.
13788 Most macros fall in one of two general categories. The first category
13789 includes macros which take arguments, in order to generate output
13790 parameterized by those arguments. Macros in this category are designed
13791 to be directly expanded, often multiple times, and should not be used as
13792 the argument to @code{AC_REQUIRE}. The other category includes macros
13793 which are shorthand for a fixed block of text, and therefore do not take
13794 arguments. For this category of macros, directly expanding the macro
13795 multiple times results in redundant output, so it is more common to use
13796 the macro as the argument to @code{AC_REQUIRE}, or to declare the macro
13797 with @code{AC_DEFUN_ONCE} (@pxref{One-Shot Macros}).
13799 Be sure to properly quote both the @var{macro-body} @emph{and} the
13800 @var{macro-name} to avoid any problems if the macro happens to have
13801 been previously defined.
13803 Each macro should have a header comment that gives its prototype, and a
13804 brief description. When arguments have default values, display them in
13805 the prototype. For example:
13808 # AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
13809 # --------------------------------------
13810 m4_define([AC_MSG_ERROR],
13811 [@{ AS_MESSAGE([error: $1], [2])
13812 exit m4_default([$2], [1]); @}])
13815 Comments about the macro should be left in the header comment. Most
13816 other comments make their way into @file{configure}, so just keep
13817 using @samp{#} to introduce comments.
13820 If you have some special comments about pure M4 code, comments
13821 that make no sense in @file{configure} and in the header comment, then
13822 use the builtin @code{dnl}: it causes M4 to discard the text
13823 through the next newline.
13825 Keep in mind that @code{dnl} is rarely needed to introduce comments;
13826 @code{dnl} is more useful to get rid of the newlines following macros
13827 that produce no output, such as @code{AC_REQUIRE}.
13829 Public third-party macros need to use @code{AC_DEFUN}, and not
13830 @code{m4_define}, in order to be found by @command{aclocal}
13831 (@pxref{Extending aclocal,,, automake, GNU Automake}).
13832 Additionally, if it is ever determined that a macro should be made
13833 obsolete, it is easy to convert from @code{AC_DEFUN} to @code{AU_DEFUN}
13834 in order to have @command{autoupdate} assist the user in choosing a
13835 better alternative, but there is no corresponding way to make
13836 @code{m4_define} issue an upgrade notice (@pxref{AU_DEFUN}).
13838 There is another subtle, but important, difference between using
13839 @code{m4_define} and @code{AC_DEFUN}: only the former is unaffected by
13840 @code{AC_REQUIRE}. When writing a file, it is always safe to replace a
13841 block of text with a @code{m4_define} macro that will expand to the same
13842 text. But replacing a block of text with an @code{AC_DEFUN} macro with
13843 the same content does not necessarily give the same results, because it
13844 changes the location where any embedded but unsatisfied
13845 @code{AC_REQUIRE} invocations within the block will be expanded. For an
13846 example of this, see @ref{Expanded Before Required}.
13849 @section Macro Names
13851 All of the public Autoconf macros have all-uppercase names in the
13852 namespace @samp{^AC_} to prevent them from accidentally conflicting with
13853 other text; Autoconf also reserves the namespace @samp{^_AC_} for
13854 internal macros. All shell variables that they use for internal
13855 purposes have mostly-lowercase names starting with @samp{ac_}. Autoconf
13856 also uses here-document delimiters in the namespace @samp{^_AC[A-Z]}. During
13857 @command{configure}, files produced by Autoconf make heavy use of the
13858 file system namespace @samp{^conf}.
13860 Since Autoconf is built on top of M4sugar (@pxref{Programming in
13861 M4sugar}) and M4sh (@pxref{Programming in M4sh}), you must also be aware
13862 of those namespaces (@samp{^_?\(m4\|AS\)_}). And since
13863 @file{configure.ac} is also designed to be scanned by Autoheader,
13864 Autoscan, Autoupdate, and Automake, you should be aware of the
13865 @samp{^_?A[HNUM]_} namespaces. In general, you @emph{should not use}
13866 the namespace of a package that does not own the macro or shell code you
13869 To ensure that your macros don't conflict with present or future
13870 Autoconf macros, you should prefix your own macro names and any shell
13871 variables they use with some other sequence. Possibilities include your
13872 initials, or an abbreviation for the name of your organization or
13873 software package. Historically, people have not always followed the
13874 rule of using a namespace appropriate for their package, and this has
13875 made it difficult for determining the origin of a macro (and where to
13876 report bugs about that macro), as well as difficult for the true
13877 namespace owner to add new macros without interference from pre-existing
13878 uses of third-party macros. Perhaps the best example of this confusion
13879 is the @code{AM_GNU_GETTEXT} macro, which belongs, not to Automake, but
13882 Most of the Autoconf macros' names follow a structured naming convention
13883 that indicates the kind of feature check by the name. The macro names
13884 consist of several words, separated by underscores, going from most
13885 general to most specific. The names of their cache variables use the
13886 same convention (@pxref{Cache Variable Names}, for more information on
13889 The first word of the name after the namespace initials (such as
13890 @samp{AC_}) usually tells the category
13891 of the feature being tested. Here are the categories used in Autoconf for
13892 specific test macros, the kind of macro that you are more likely to
13893 write. They are also used for cache variables, in all-lowercase. Use
13894 them where applicable; where they're not, invent your own categories.
13898 C language builtin features.
13900 Declarations of C variables in header files.
13902 Functions in libraries.
13904 Posix group owners of files.
13910 The base names of programs.
13912 Members of aggregates.
13914 Operating system features.
13916 C builtin or declared types.
13918 C variables in libraries.
13921 After the category comes the name of the particular feature being
13922 tested. Any further words in the macro name indicate particular aspects
13923 of the feature. For example, @code{AC_PROG_CC_STDC} checks whether the
13924 C compiler supports ISO Standard C.
13926 An internal macro should have a name that starts with an underscore;
13927 Autoconf internals should therefore start with @samp{_AC_}.
13928 Additionally, a macro that is an internal subroutine of another macro
13929 should have a name that starts with an underscore and the name of that
13930 other macro, followed by one or more words saying what the internal
13931 macro does. For example, @code{AC_PATH_X} has internal macros
13932 @code{_AC_PATH_X_XMKMF} and @code{_AC_PATH_X_DIRECT}.
13934 @node Reporting Messages
13935 @section Reporting Messages
13936 @cindex Messages, from @command{autoconf}
13938 When macros statically diagnose abnormal situations, benign or fatal, it
13939 is possible to make @command{autoconf} detect the problem, and refuse to
13940 create @file{configure} in the case of an error. The macros in this
13941 section are considered obsolescent, and new code should use M4sugar
13942 macros for this purpose, see @ref{Diagnostic Macros}.
13944 On the other hand, it is possible to want to detect errors when
13945 @command{configure} is run, which are dependent on the environment of
13946 the user rather than the maintainer. For dynamic diagnostics, see
13947 @ref{Printing Messages}.
13949 @defmac AC_DIAGNOSE (@var{category}, @var{message})
13951 Report @var{message} as a warning (or as an error if requested by the
13952 user) if warnings of the @var{category} are turned on. This macro is
13953 obsolescent; you are encouraged to use:
13955 m4_warn([@var{category}], [@var{message}])
13958 instead. @xref{m4_warn}, for more details, including valid
13959 @var{category} names.
13962 @defmac AC_WARNING (@var{message})
13964 Report @var{message} as a syntax warning. This macro is obsolescent;
13965 you are encouraged to use:
13967 m4_warn([syntax], [@var{message}])
13970 instead. @xref{m4_warn}, for more details, as well as better
13971 finer-grained categories of warnings (not all problems have to do with
13975 @defmac AC_FATAL (@var{message})
13977 Report a severe error @var{message}, and have @command{autoconf} die.
13978 This macro is obsolescent; you are encouraged to use:
13980 m4_fatal([@var{message}])
13983 instead. @xref{m4_fatal}, for more details.
13986 When the user runs @samp{autoconf -W error}, warnings from
13987 @code{m4_warn} (including those issued through @code{AC_DIAGNOSE} and
13988 @code{AC_WARNING}) are reported as errors, see @ref{autoconf Invocation}.
13990 @node Dependencies Between Macros
13991 @section Dependencies Between Macros
13992 @cindex Dependencies between macros
13994 Some Autoconf macros depend on other macros having been called first in
13995 order to work correctly. Autoconf provides a way to ensure that certain
13996 macros are called if needed and a way to warn the user if macros are
13997 called in an order that might cause incorrect operation.
14000 * Prerequisite Macros:: Ensuring required information
14001 * Suggested Ordering:: Warning about possible ordering problems
14002 * One-Shot Macros:: Ensuring a macro is called only once
14005 @node Prerequisite Macros
14006 @subsection Prerequisite Macros
14007 @cindex Prerequisite macros
14008 @cindex Macros, prerequisites
14010 A macro that you write might need to use values that have previously
14011 been computed by other macros. For example, @code{AC_DECL_YYTEXT}
14012 examines the output of @code{flex} or @code{lex}, so it depends on
14013 @code{AC_PROG_LEX} having been called first to set the shell variable
14016 Rather than forcing the user of the macros to keep track of the
14017 dependencies between them, you can use the @code{AC_REQUIRE} macro to do
14018 it automatically. @code{AC_REQUIRE} can ensure that a macro is only
14019 called if it is needed, and only called once.
14021 @defmac AC_REQUIRE (@var{macro-name})
14023 If the M4 macro @var{macro-name} has not already been called, call it
14024 (without any arguments). Make sure to quote @var{macro-name} with
14025 square brackets. @var{macro-name} must have been defined using
14026 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
14027 that it has been called.
14029 @code{AC_REQUIRE} must be used inside a macro defined by @code{AC_DEFUN}; it
14030 must not be called from the top level. Also, it does not make sense to
14031 require a macro that takes parameters.
14034 @code{AC_REQUIRE} is often misunderstood. It really implements
14035 dependencies between macros in the sense that if one macro depends upon
14036 another, the latter is expanded @emph{before} the body of the
14037 former. To be more precise, the required macro is expanded before
14038 the outermost defined macro in the current expansion stack.
14039 In particular, @samp{AC_REQUIRE([FOO])} is not replaced with the body of
14040 @code{FOO}. For instance, this definition of macros:
14044 AC_DEFUN([TRAVOLTA],
14045 [test "$body_temperature_in_celsius" -gt "38" &&
14046 dance_floor=occupied])
14047 AC_DEFUN([NEWTON_JOHN],
14048 [test "x$hair_style" = xcurly &&
14049 dance_floor=occupied])
14053 AC_DEFUN([RESERVE_DANCE_FLOOR],
14054 [if date | grep '^Sat.*pm' >/dev/null 2>&1; then
14055 AC_REQUIRE([TRAVOLTA])
14056 AC_REQUIRE([NEWTON_JOHN])
14062 with this @file{configure.ac}
14065 AC_INIT([Dance Manager], [1.0], [bug-dance@@example.org])
14066 RESERVE_DANCE_FLOOR
14067 if test "x$dance_floor" = xoccupied; then
14068 AC_MSG_ERROR([cannot pick up here, let's move])
14073 does not leave you with a better chance to meet a kindred soul at
14074 other times than Saturday night since it expands into:
14078 test "$body_temperature_in_Celsius" -gt "38" &&
14079 dance_floor=occupied
14080 test "x$hair_style" = xcurly &&
14081 dance_floor=occupied
14083 if date | grep '^Sat.*pm' >/dev/null 2>&1; then
14090 This behavior was chosen on purpose: (i) it prevents messages in
14091 required macros from interrupting the messages in the requiring macros;
14092 (ii) it avoids bad surprises when shell conditionals are used, as in:
14097 AC_REQUIRE([SOME_CHECK])
14104 However, this implementation can lead to another class of problems.
14105 Consider the case where an outer macro first expands, then indirectly
14106 requires, an inner macro:
14109 AC_DEFUN([TESTA], [[echo in A
14110 if test -n "$SEEN_A" ; then echo duplicate ; fi
14112 AC_DEFUN([TESTB], [AC_REQUIRE([TESTA])[echo in B
14113 if test -z "$SEEN_A" ; then echo bug ; fi]])
14114 AC_DEFUN([TESTC], [AC_REQUIRE([TESTB])[echo in C]])
14115 AC_DEFUN([OUTER], [[echo in OUTER]
14122 Prior to Autoconf 2.64, the implementation of @code{AC_REQUIRE}
14123 recognized that @code{TESTB} needed to be hoisted prior to the expansion
14124 of @code{OUTER}, but because @code{TESTA} had already been directly
14125 expanded, it failed to hoist @code{TESTA}. Therefore, the expansion of
14126 @code{TESTB} occurs prior to its prerequisites, leading to the following
14138 Newer Autoconf is smart enough to recognize this situation, and hoists
14139 @code{TESTA} even though it has already been expanded, but issues a
14140 syntax warning in the process. This is because the hoisted expansion of
14141 @code{TESTA} defeats the purpose of using @code{AC_REQUIRE} to avoid
14142 redundant code, and causes its own set of problems if the hoisted macro
14154 The bug is not in Autoconf, but in the macro definitions. If you ever
14155 pass a particular macro name to @code{AC_REQUIRE}, then you are implying
14156 that the macro only needs to be expanded once. But to enforce this,
14157 either the macro must be declared with @code{AC_DEFUN_ONCE} (although
14158 this only helps in Autoconf 2.64 or newer), or all
14159 uses of that macro should be through @code{AC_REQUIRE}; directly
14160 expanding the macro defeats the point of using @code{AC_REQUIRE} to
14161 eliminate redundant expansion. In the example, this rule of thumb was
14162 violated because @code{TESTB} requires @code{TESTA} while @code{OUTER}
14163 directly expands it. One way of fixing the bug is to factor
14164 @code{TESTA} into two macros, the portion designed for direct and
14165 repeated use (here, named @code{TESTA}), and the portion designed for
14166 one-shot output and used only inside @code{AC_REQUIRE} (here, named
14167 @code{TESTA_PREREQ}). Then, by fixing all clients to use the correct
14168 calling convention according to their needs:
14171 AC_DEFUN([TESTA], [AC_REQUIRE([TESTA_PREREQ])[echo in A]])
14172 AC_DEFUN([TESTA_PREREQ], [[echo in A_PREREQ
14173 if test -n "$SEEN_A" ; then echo duplicate ; fi
14175 AC_DEFUN([TESTB], [AC_REQUIRE([TESTA_PREREQ])[echo in B
14176 if test -z "$SEEN_A" ; then echo bug ; fi]])
14177 AC_DEFUN([TESTC], [AC_REQUIRE([TESTB])[echo in C]])
14178 AC_DEFUN([OUTER], [[echo in OUTER]
14185 the resulting output will then obey all dependency rules and avoid any
14186 syntax warnings, whether the script is built with old or new Autoconf
14197 The helper macros @code{AS_IF} and @code{AS_CASE} may be used to
14198 enforce expansion of required macros outside of shell conditional
14199 constructs. You are furthermore encouraged, although not required, to
14200 put all @code{AC_REQUIRE} calls
14201 at the beginning of a macro. You can use @code{dnl} to avoid the empty
14204 @node Suggested Ordering
14205 @subsection Suggested Ordering
14206 @cindex Macros, ordering
14207 @cindex Ordering macros
14209 Some macros should be run before another macro if both are called, but
14210 neither @emph{requires} that the other be called. For example, a macro
14211 that changes the behavior of the C compiler should be called before any
14212 macros that run the C compiler. Many of these dependencies are noted in
14215 Autoconf provides the @code{AC_BEFORE} macro to warn users when macros
14216 with this kind of dependency appear out of order in a
14217 @file{configure.ac} file. The warning occurs when creating
14218 @command{configure} from @file{configure.ac}, not when running
14219 @command{configure}.
14221 For example, @code{AC_PROG_CPP} checks whether the C compiler
14222 can run the C preprocessor when given the @option{-E} option. It should
14223 therefore be called after any macros that change which C compiler is
14224 being used, such as @code{AC_PROG_CC}. So @code{AC_PROG_CC} contains:
14227 AC_BEFORE([$0], [AC_PROG_CPP])dnl
14231 This warns the user if a call to @code{AC_PROG_CPP} has already occurred
14232 when @code{AC_PROG_CC} is called.
14234 @defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name})
14236 Make M4 print a warning message to the standard error output if
14237 @var{called-macro-name} has already been called. @var{this-macro-name}
14238 should be the name of the macro that is calling @code{AC_BEFORE}. The
14239 macro @var{called-macro-name} must have been defined using
14240 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
14241 that it has been called.
14244 @node One-Shot Macros
14245 @subsection One-Shot Macros
14246 @cindex One-shot macros
14247 @cindex Macros, called once
14249 Some macros should be called only once, either because calling them
14250 multiple time is unsafe, or because it is bad style. For instance
14251 Autoconf ensures that @code{AC_CANONICAL_BUILD} and cousins
14252 (@pxref{Canonicalizing}) are evaluated only once, because it makes no
14253 sense to run these expensive checks more than once. Such one-shot
14254 macros can be defined using @code{AC_DEFUN_ONCE}.
14256 @defmac AC_DEFUN_ONCE (@var{macro-name}, @var{macro-body})
14257 @acindex{DEFUN_ONCE}
14258 Declare macro @var{macro-name} like @code{AC_DEFUN} would (@pxref{Macro
14259 Definitions}), but add additional logic that guarantees that only the
14260 first use of the macro (whether by direct expansion or
14261 @code{AC_REQUIRE}) causes an expansion of @var{macro-body}; the
14262 expansion will occur before the start of any enclosing macro defined by
14263 @code{AC_DEFUN}. Subsequent expansions are silently ignored.
14264 Generally, it does not make sense for @var{macro-body} to use parameters
14268 Prior to Autoconf 2.64, a macro defined by @code{AC_DEFUN_ONCE} would
14269 emit a warning if it was directly expanded a second time, so for
14270 portability, it is better to use @code{AC_REQUIRE} than direct
14271 invocation of @var{macro-name} inside a macro defined by @code{AC_DEFUN}
14272 (@pxref{Prerequisite Macros}).
14274 @node Obsoleting Macros
14275 @section Obsoleting Macros
14276 @cindex Obsoleting macros
14277 @cindex Macros, obsoleting
14279 Configuration and portability technology has evolved over the years.
14280 Often better ways of solving a particular problem are developed, or
14281 ad-hoc approaches are systematized. This process has occurred in many
14282 parts of Autoconf. One result is that some of the macros are now
14283 considered @dfn{obsolete}; they still work, but are no longer considered
14284 the best thing to do, hence they should be replaced with more modern
14285 macros. Ideally, @command{autoupdate} should replace the old macro calls
14286 with their modern implementation.
14288 Autoconf provides a simple means to obsolete a macro.
14291 @defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message})
14293 Define @var{old-macro} as @var{implementation}. The only difference
14294 with @code{AC_DEFUN} is that the user is warned that
14295 @var{old-macro} is now obsolete.
14297 If she then uses @command{autoupdate}, the call to @var{old-macro} is
14298 replaced by the modern @var{implementation}. @var{message} should
14299 include information on what to do after running @command{autoupdate};
14300 @command{autoupdate} prints it as a warning, and includes it
14301 in the updated @file{configure.ac} file.
14303 The details of this macro are hairy: if @command{autoconf} encounters an
14304 @code{AU_DEFUN}ed macro, all macros inside its second argument are expanded
14305 as usual. However, when @command{autoupdate} is run, only M4 and M4sugar
14306 macros are expanded here, while all other macros are disabled and
14307 appear literally in the updated @file{configure.ac}.
14310 @defmac AU_ALIAS (@var{old-name}, @var{new-name})
14312 Used if the @var{old-name} is to be replaced by a call to @var{new-macro}
14313 with the same parameters. This happens for example if the macro was renamed.
14317 @section Coding Style
14318 @cindex Coding style
14320 The Autoconf macros follow a strict coding style. You are encouraged to
14321 follow this style, especially if you intend to distribute your macro,
14322 either by contributing it to Autoconf itself or the
14323 @uref{http://@/www.gnu.org/@/software/@/autoconf-archive/, Autoconf Macro
14324 Archive}, or by other means.
14326 The first requirement is to pay great attention to the quotation. For
14327 more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}.
14329 Do not try to invent new interfaces. It is likely that there is a macro
14330 in Autoconf that resembles the macro you are defining: try to stick to
14331 this existing interface (order of arguments, default values, etc.). We
14332 @emph{are} conscious that some of these interfaces are not perfect;
14333 nevertheless, when harmless, homogeneity should be preferred over
14336 Be careful about clashes both between M4 symbols and between shell
14339 If you stick to the suggested M4 naming scheme (@pxref{Macro Names}),
14340 you are unlikely to generate conflicts. Nevertheless, when you need to
14341 set a special value, @emph{avoid using a regular macro name}; rather,
14342 use an ``impossible'' name. For instance, up to version 2.13, the macro
14343 @code{AC_SUBST} used to remember what @var{symbol} macros were already defined
14344 by setting @code{AC_SUBST_@var{symbol}}, which is a regular macro name.
14345 But since there is a macro named @code{AC_SUBST_FILE}, it was just
14346 impossible to @samp{AC_SUBST(FILE)}! In this case,
14347 @code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should
14348 have been used (yes, with the parentheses).
14349 @c or better yet, high-level macros such as @code{m4_expand_once}
14351 No Autoconf macro should ever enter the user-variable name space; i.e.,
14352 except for the variables that are the actual result of running the
14353 macro, all shell variables should start with @code{ac_}. In
14354 addition, small macros or any macro that is likely to be embedded in
14355 other macros should be careful not to use obvious names.
14358 Do not use @code{dnl} to introduce comments: most of the comments you
14359 are likely to write are either header comments which are not output
14360 anyway, or comments that should make their way into @file{configure}.
14361 There are exceptional cases where you do want to comment special M4
14362 constructs, in which case @code{dnl} is right, but keep in mind that it
14365 M4 ignores the leading blanks and newlines before each argument.
14366 Use this feature to
14367 indent in such a way that arguments are (more or less) aligned with the
14368 opening parenthesis of the macro being called. For instance, instead of
14371 AC_CACHE_CHECK(for EMX OS/2 environment,
14373 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])],
14374 [ac_cv_emxos2=yes], [ac_cv_emxos2=no])])
14381 AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
14382 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
14383 [ac_cv_emxos2=yes],
14384 [ac_cv_emxos2=no])])
14391 AC_CACHE_CHECK([for EMX OS/2 environment],
14393 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([],
14394 [return __EMX__;])],
14395 [ac_cv_emxos2=yes],
14396 [ac_cv_emxos2=no])])
14399 When using @code{AC_RUN_IFELSE} or any macro that cannot work when
14400 cross-compiling, provide a pessimistic value (typically @samp{no}).
14402 Feel free to use various tricks to prevent auxiliary tools, such as
14403 syntax-highlighting editors, from behaving improperly. For instance,
14407 m4_bpatsubst([$1], [$"])
14414 m4_bpatsubst([$1], [$""])
14418 so that Emacsen do not open an endless ``string'' at the first quote.
14419 For the same reasons, avoid:
14429 test $[@@%:@@] != 0
14433 Otherwise, the closing bracket would be hidden inside a @samp{#}-comment,
14434 breaking the bracket-matching highlighting from Emacsen. Note the
14435 preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]}, etc. Do
14436 not escape when it is unnecessary. Common examples of useless quotation
14437 are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}),
14438 etc. If you add portability issues to the picture, you'll prefer
14439 @samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something
14440 better than hacking Autoconf @code{:-)}.
14442 When using @command{sed}, don't use @option{-e} except for indenting
14443 purposes. With the @code{s} and @code{y} commands, the preferred
14444 separator is @samp{/} unless @samp{/} itself might appear in the pattern
14445 or replacement, in which case you should use @samp{|}, or optionally
14446 @samp{,} if you know the pattern and replacement cannot contain a file
14447 name. If none of these characters will do, choose a printable character
14448 that cannot appear in the pattern or replacement. Characters from the
14449 set @samp{"#$&'()*;<=>?`|~} are good choices if the pattern or
14450 replacement might contain a file name, since they have special meaning
14451 to the shell and are less likely to occur in file names.
14453 @xref{Macro Definitions}, for details on how to define a macro. If a
14454 macro doesn't use @code{AC_REQUIRE}, is expected to never be the object
14455 of an @code{AC_REQUIRE} directive, and macros required by other macros
14456 inside arguments do not need to be expanded before this macro, then
14457 use @code{m4_define}. In case of doubt, use @code{AC_DEFUN}.
14458 Also take into account that public third-party macros need to use
14459 @code{AC_DEFUN} in order to be found by @command{aclocal}
14460 (@pxref{Extending aclocal,,, automake, GNU Automake}).
14461 All the @code{AC_REQUIRE} statements should be at the beginning of the
14462 macro, and each statement should be followed by @code{dnl}.
14464 You should not rely on the number of arguments: instead of checking
14465 whether an argument is missing, test that it is not empty. It provides
14466 both a simpler and a more predictable interface to the user, and saves
14467 room for further arguments.
14469 Unless the macro is short, try to leave the closing @samp{])} at the
14470 beginning of a line, followed by a comment that repeats the name of the
14471 macro being defined. This introduces an additional newline in
14472 @command{configure}; normally, that is not a problem, but if you want to
14473 remove it you can use @samp{[]dnl} on the last line. You can similarly
14474 use @samp{[]dnl} after a macro call to remove its newline. @samp{[]dnl}
14475 is recommended instead of @samp{dnl} to ensure that M4 does not
14476 interpret the @samp{dnl} as being attached to the preceding text or
14477 macro output. For example, instead of:
14480 AC_DEFUN([AC_PATH_X],
14481 [AC_MSG_CHECKING([for X])
14483 @r{# @dots{}omitted@dots{}}
14484 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
14492 AC_DEFUN([AC_PATH_X],
14493 [AC_REQUIRE_CPP()[]dnl
14494 AC_MSG_CHECKING([for X])
14495 @r{# @dots{}omitted@dots{}}
14496 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
14501 If the macro is long, try to split it into logical chunks. Typically,
14502 macros that check for a bug in a function and prepare its
14503 @code{AC_LIBOBJ} replacement should have an auxiliary macro to perform
14504 this setup. Do not hesitate to introduce auxiliary macros to factor
14507 In order to highlight the recommended coding style, here is a macro
14508 written the old way:
14511 dnl Check for EMX on OS/2.
14513 AC_DEFUN(_AC_EMXOS2,
14514 [AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2,
14515 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)],
14516 ac_cv_emxos2=yes, ac_cv_emxos2=no)])
14517 test "x$ac_cv_emxos2" = xyes && EMXOS2=yes])
14526 # Check for EMX on OS/2.
14527 m4_define([_AC_EMXOS2],
14528 [AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
14529 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
14530 [ac_cv_emxos2=yes],
14531 [ac_cv_emxos2=no])])
14532 test "x$ac_cv_emxos2" = xyes && EMXOS2=yes[]dnl
14539 @c ============================================= Portable Shell Programming
14541 @node Portable Shell
14542 @chapter Portable Shell Programming
14543 @cindex Portable shell programming
14545 When writing your own checks, there are some shell-script programming
14546 techniques you should avoid in order to make your code portable. The
14547 Bourne shell and upward-compatible shells like the Korn shell and Bash
14548 have evolved over the years, and many features added to the original
14549 System7 shell are now supported on all interesting porting targets.
14550 However, the following discussion between Russ Allbery and Robert Lipe
14557 The GNU assumption that @command{/bin/sh} is the one and only shell
14558 leads to a permanent deadlock. Vendors don't want to break users'
14559 existing shell scripts, and there are some corner cases in the Bourne
14560 shell that are not completely compatible with a Posix shell. Thus,
14561 vendors who have taken this route will @emph{never} (OK@dots{}``never say
14562 never'') replace the Bourne shell (as @command{/bin/sh}) with a
14570 This is exactly the problem. While most (at least most System V's) do
14571 have a Bourne shell that accepts shell functions most vendor
14572 @command{/bin/sh} programs are not the Posix shell.
14574 So while most modern systems do have a shell @emph{somewhere} that meets the
14575 Posix standard, the challenge is to find it.
14578 For this reason, part of the job of M4sh (@pxref{Programming in M4sh})
14579 is to find such a shell. But to prevent trouble, if you're not using
14580 M4sh you should not take advantage of features that were added after Unix
14581 version 7, circa 1977 (@pxref{Systemology}); you should not use aliases,
14582 negated character classes, or even @command{unset}. @code{#} comments,
14583 while not in Unix version 7, were retrofitted in the original Bourne
14584 shell and can be assumed to be part of the least common denominator.
14586 On the other hand, if you're using M4sh you can assume that the shell
14587 has the features that were added in SVR2 (circa 1984), including shell
14589 @command{return}, @command{unset}, and I/O redirection for builtins. For
14590 more information, refer to @uref{http://@/www.in-ulm.de/@/~mascheck/@/bourne/}.
14591 However, some pitfalls have to be avoided for portable use of these
14592 constructs; these will be documented in the rest of this chapter.
14593 See in particular @ref{Shell Functions} and @ref{Limitations of
14594 Builtins, , Limitations of Shell Builtins}.
14596 Some ancient systems have quite
14597 small limits on the length of the @samp{#!} line; for instance, 32
14598 bytes (not including the newline) on SunOS 4.
14599 However, these ancient systems are no longer of practical concern.
14601 The set of external programs you should run in a @command{configure} script
14602 is fairly small. @xref{Utilities in Makefiles, , Utilities in
14603 Makefiles, standards, GNU Coding Standards}, for the list. This
14604 restriction allows users to start out with a fairly small set of
14605 programs and build the rest, avoiding too many interdependencies between
14608 Some of these external utilities have a portable subset of features; see
14609 @ref{Limitations of Usual Tools}.
14611 There are other sources of documentation about shells. The
14612 specification for the Posix
14613 @uref{http://@/www.opengroup.org/@/susv3/@/utilities/@/xcu_chap02@/.html, Shell
14614 Command Language}, though more generous than the restrictive shell
14615 subset described above, is fairly portable nowadays. Also please see
14616 @uref{http://@/www.faqs.org/@/faqs/@/unix-faq/@/shell/, the Shell FAQs}.
14619 * Shellology:: A zoology of shells
14620 * Here-Documents:: Quirks and tricks
14621 * File Descriptors:: FDs and redirections
14622 * File System Conventions:: File names
14623 * Shell Pattern Matching:: Pattern matching
14624 * Shell Substitutions:: Variable and command expansions
14625 * Assignments:: Varying side effects of assignments
14626 * Parentheses:: Parentheses in shell scripts
14627 * Slashes:: Slashes in shell scripts
14628 * Special Shell Variables:: Variables you should not change
14629 * Shell Functions:: What to look out for if you use them
14630 * Limitations of Builtins:: Portable use of not so portable /bin/sh
14631 * Limitations of Usual Tools:: Portable use of portable tools
14635 @section Shellology
14638 There are several families of shells, most prominently the Bourne family
14639 and the C shell family which are deeply incompatible. If you want to
14640 write portable shell scripts, avoid members of the C shell family. The
14641 @uref{http://@/www.faqs.org/@/faqs/@/unix-faq/@/shell/@/shell-differences/, the
14642 Shell difference FAQ} includes a small history of Posix shells, and a
14643 comparison between several of them.
14645 Below we describe some of the members of the Bourne shell family.
14650 Ash is often used on GNU/Linux and BSD
14651 systems as a light-weight Bourne-compatible shell. Ash 0.2 has some
14652 bugs that are fixed in the 0.3.x series, but portable shell scripts
14653 should work around them, since version 0.2 is still shipped with many
14654 GNU/Linux distributions.
14656 To be compatible with Ash 0.2:
14660 don't use @samp{$?} after expanding empty or unset variables,
14661 or at the start of an @command{eval}:
14667 echo "Do not use it: $?"
14669 eval 'echo "Do not use it: $?"'
14673 don't use command substitution within variable expansion:
14680 beware that single builtin substitutions are not performed by a
14681 subshell, hence their effect applies to the current shell! @xref{Shell
14682 Substitutions}, item ``Command Substitution''.
14687 To detect whether you are running Bash, test whether
14688 @code{BASH_VERSION} is set. To require
14689 Posix compatibility, run @samp{set -o posix}. @xref{Bash POSIX
14690 Mode, , Bash Posix Mode, bash, The GNU Bash Reference
14691 Manual}, for details.
14693 @item Bash 2.05 and later
14694 @cindex Bash 2.05 and later
14695 Versions 2.05 and later of Bash use a different format for the
14696 output of the @command{set} builtin, designed to make evaluating its
14697 output easier. However, this output is not compatible with earlier
14698 versions of Bash (or with many other shells, probably). So if
14699 you use Bash 2.05 or higher to execute @command{configure},
14700 you'll need to use Bash 2.05 for all other build tasks as well.
14705 @prindex @samp{ksh}
14706 @prindex @samp{ksh88}
14707 @prindex @samp{ksh93}
14708 The Korn shell is compatible with the Bourne family and it mostly
14709 conforms to Posix. It has two major variants commonly
14710 called @samp{ksh88} and @samp{ksh93}, named after the years of initial
14711 release. It is usually called @command{ksh}, but is called @command{sh}
14712 on some hosts if you set your path appropriately.
14714 Solaris systems have three variants:
14715 @prindex @command{/usr/bin/ksh} on Solaris
14716 @command{/usr/bin/ksh} is @samp{ksh88}; it is
14717 standard on Solaris 2.0 and later.
14718 @prindex @command{/usr/xpg4/bin/sh} on Solaris
14719 @command{/usr/xpg4/bin/sh} is a Posix-compliant variant of
14720 @samp{ksh88}; it is standard on Solaris 9 and later.
14721 @prindex @command{/usr/dt/bin/dtksh} on Solaris
14722 @command{/usr/dt/bin/dtksh} is @samp{ksh93}.
14723 Variants that are not standard may be parts of optional
14724 packages. There is no extra charge for these packages, but they are
14725 not part of a minimal OS install and therefore some installations may
14728 Starting with Tru64 Version 4.0, the Korn shell @command{/usr/bin/ksh}
14729 is also available as @command{/usr/bin/posix/sh}. If the environment
14730 variable @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
14731 the standard shell conform to Posix.
14734 @prindex @samp{pdksh}
14735 A public-domain clone of the Korn shell called @command{pdksh} is widely
14736 available: it has most of the @samp{ksh88} features along with a few of
14737 its own. It usually sets @code{KSH_VERSION}, except if invoked as
14738 @command{/bin/sh} on OpenBSD, and similarly to Bash you can require
14739 Posix compatibility by running @samp{set -o posix}. Unfortunately, with
14740 @command{pdksh} 5.2.14 (the latest stable version as of January 2007)
14741 Posix mode is buggy and causes @command{pdksh} to depart from Posix in
14742 at least one respect, see @ref{Shell Substitutions}.
14746 To detect whether you are running @command{zsh}, test whether
14747 @code{ZSH_VERSION} is set. By default @command{zsh} is @emph{not}
14748 compatible with the Bourne shell: you must execute @samp{emulate sh},
14749 and for @command{zsh} versions before 3.1.6-dev-18 you must also
14750 set @code{NULLCMD} to @samp{:}. @xref{Compatibility, , Compatibility,
14751 zsh, The Z Shell Manual}, for details.
14753 The default Mac OS X @command{sh} was originally Zsh; it was changed to
14754 Bash in Mac OS X 10.2.
14757 @node Here-Documents
14758 @section Here-Documents
14759 @cindex Here-documents
14760 @cindex Shell here-documents
14762 Don't rely on @samp{\} being preserved just because it has no special
14763 meaning together with the next symbol. In the native @command{sh}
14764 on OpenBSD 2.7 @samp{\"} expands to @samp{"} in here-documents with
14765 unquoted delimiter. As a general rule, if @samp{\\} expands to @samp{\}
14766 use @samp{\\} to get @samp{\}.
14768 With OpenBSD 2.7's @command{sh}
14784 bash-2.04$ @kbd{cat <<EOF
14791 Some shells mishandle large here-documents: for example,
14792 Solaris 10 @command{dtksh} and the UnixWare 7.1.1 Posix shell, which are
14793 derived from Korn shell version M-12/28/93d, mishandle braced variable
14794 expansion that crosses a 1024- or 4096-byte buffer boundary
14795 within a here-document. Only the part of the variable name after the boundary
14796 is used. For example, @code{$@{variable@}} could be replaced by the expansion
14797 of @code{$@{ble@}}. If the end of the variable name is aligned with the block
14798 boundary, the shell reports an error, as if you used @code{$@{@}}.
14799 Instead of @code{$@{variable-default@}}, the shell may expand
14800 @code{$@{riable-default@}}, or even @code{$@{fault@}}. This bug can often
14801 be worked around by omitting the braces: @code{$variable}. The bug was
14803 @samp{ksh93g} (1998-04-30) but as of 2006 many operating systems were
14804 still shipping older versions with the bug.
14806 Many shells (including the Bourne shell) implement here-documents
14807 inefficiently. In particular, some shells can be extremely inefficient when
14808 a single statement contains many here-documents. For instance if your
14809 @file{configure.ac} includes something like:
14813 if <cross_compiling>; then
14814 assume this and that
14818 check something else
14826 A shell parses the whole @code{if}/@code{fi} construct, creating
14827 temporary files for each here-document in it. Some shells create links
14828 for such here-documents on every @code{fork}, so that the clean-up code
14829 they had installed correctly removes them. It is creating the links
14830 that can take the shell forever.
14832 Moving the tests out of the @code{if}/@code{fi}, or creating multiple
14833 @code{if}/@code{fi} constructs, would improve the performance
14834 significantly. Anyway, this kind of construct is not exactly the
14835 typical use of Autoconf. In fact, it's even not recommended, because M4
14836 macros can't look into shell conditionals, so we may fail to expand a
14837 macro when it was expanded before in a conditional path, and the
14838 condition turned out to be false at runtime, and we end up not
14839 executing the macro at all.
14841 Be careful with the use of @samp{<<-} to unindent here-documents. The
14842 behavior is only portable for stripping leading @key{TAB}s, and things
14843 can silently break if an overzealous editor converts to using leading
14844 spaces (not all shells are nice enough to warn about unterminated
14848 $ @kbd{printf 'cat <<-x\n\t1\n\t 2\n\tx\n' | bash && echo done}
14852 $ @kbd{printf 'cat <<-x\n 1\n 2\n x\n' | bash-3.2 && echo done}
14859 @node File Descriptors
14860 @section File Descriptors
14861 @cindex Descriptors
14862 @cindex File descriptors
14863 @cindex Shell file descriptors
14865 Most shells, if not all (including Bash, Zsh, Ash), output traces on
14866 stderr, even for subshells. This might result in undesirable content
14867 if you meant to capture the standard-error output of the inner command:
14870 $ @kbd{ash -x -c '(eval "echo foo >&2") 2>stderr'}
14872 + eval echo foo >&2
14875 $ @kbd{bash -x -c '(eval "echo foo >&2") 2>stderr'}
14877 + eval 'echo foo >&2'
14880 $ @kbd{zsh -x -c '(eval "echo foo >&2") 2>stderr'}
14881 @i{# Traces on startup files deleted here.}
14883 +zsh:1> eval echo foo >&2
14889 One workaround is to grep out uninteresting lines, hoping not to remove
14892 If you intend to redirect both standard error and standard output,
14893 redirect standard output first. This works better with HP-UX,
14894 since its shell mishandles tracing if standard error is redirected
14898 $ @kbd{sh -x -c ': 2>err >out'}
14900 + 2> err $ @kbd{cat err}
14904 Don't try to redirect the standard error of a command substitution. It
14905 must be done @emph{inside} the command substitution. When running
14906 @samp{: `cd /zorglub` 2>/dev/null} expect the error message to
14907 escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly.
14909 On the other hand, some shells, such as Solaris or FreeBSD
14910 @command{/bin/sh}, warn about missing programs before performing
14911 redirections. Therefore, to silently check whether a program exists, it
14912 is necessary to perform redirections on a subshell:
14915 $ @kbd{/bin/sh -c 'nosuch 2>/dev/null'}
14917 $ @kbd{/bin/sh -c '(nosuch) 2>/dev/null'}
14918 $ @kbd{bash -c 'nosuch 2>/dev/null'}
14921 FreeBSD 6.2 sh may mix the trace output lines from the statements in a
14924 It is worth noting that Zsh (but not Ash nor Bash) makes it possible
14925 in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}.
14927 Some shells, like @command{ash}, don't recognize bi-directional
14928 redirection (@samp{<>}). And even on shells that recognize it, it is
14929 not portable to use on fifos: Posix does not require read-write support
14930 for named pipes, and Cygwin does not support it:
14933 $ @kbd{mkfifo fifo}
14934 $ @kbd{exec 5<>fifo}
14935 $ @kbd{echo hi >&5}
14936 bash: echo: write error: Communication error on send
14939 When catering to old systems, don't redirect the same file descriptor
14940 several times, as you are doomed to failure under Ultrix.
14943 ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995
14945 $ @kbd{eval 'echo matter >fullness' >void}
14947 $ @kbd{eval '(echo matter >fullness)' >void}
14949 $ @kbd{(eval '(echo matter >fullness)') >void}
14950 Ambiguous output redirect.
14954 In each case the expected result is of course @file{fullness} containing
14955 @samp{matter} and @file{void} being empty. However, this bug is
14956 probably not of practical concern to modern platforms.
14958 Solaris 10 @command{sh} will try to optimize away a @command{:} command
14959 in a loop after the first iteration, even if it is redirected:
14962 $ @kbd{for i in 1 2 3 ; do : >x$i; done}
14968 As a workaround, @command{echo} or @command{eval} can be used.
14970 Don't rely on file descriptors 0, 1, and 2 remaining closed in a
14971 subsidiary program. If any of these descriptors is closed, the
14972 operating system may open an unspecified file for the descriptor in the
14973 new process image. Posix says this may be done only if the subsidiary
14974 program is set-user-ID or set-group-ID, but HP-UX 11.23 does
14975 it even for ordinary programs.
14977 Don't rely on open file descriptors being open in child processes. In
14978 @command{ksh}, file descriptors above 2 which are opened using
14979 @samp{exec @var{n}>file} are closed by a subsequent @samp{exec} (such as
14980 that involved in the fork-and-exec which runs a program or script).
14981 Thus, using @command{sh}, we have:
14984 $ @kbd{cat ./descrips}
15006 Within the process which runs the @samp{descrips} script, file
15007 descriptor 5 is closed.
15009 Don't rely on redirection to a closed file descriptor to cause an
15010 error. With Solaris @command{/bin/sh}, when the redirection fails, the
15011 output goes to the original file descriptor.
15014 $ @kbd{bash -c 'echo hi >&3' 3>&-; echo $?}
15015 bash: 3: Bad file descriptor
15017 $ @kbd{/bin/sh -c 'echo hi >&3' 3>&-; echo $?}
15022 DOS variants cannot rename or remove open files, such as in
15023 @samp{mv foo bar >foo} or @samp{rm foo >foo}, even though this is
15024 perfectly portable among Posix hosts.
15026 A few ancient systems reserved some file descriptors. By convention,
15027 file descriptor 3 was opened to @file{/dev/tty} when you logged into
15028 Eighth Edition (1985) through Tenth Edition Unix (1989). File
15029 descriptor 4 had a special use on the Stardent/Kubota Titan (circa
15030 1990), though we don't now remember what it was. Both these systems are
15031 obsolete, so it's now safe to treat file descriptors 3 and 4 like any
15032 other file descriptors.
15034 @node File System Conventions
15035 @section File System Conventions
15036 @cindex File system conventions
15038 Autoconf uses shell-script processing extensively, so the file names
15039 that it processes should not contain characters that are special to the
15040 shell. Special characters include space, tab, newline, NUL, and
15044 " # $ & ' ( ) * ; < = > ? [ \ ` |
15047 Also, file names should not begin with @samp{~} or @samp{-}, and should
15048 contain neither @samp{-} immediately after @samp{/} nor @samp{~}
15049 immediately after @samp{:}. On Posix-like platforms, directory names
15050 should not contain @samp{:}, as this runs afoul of @samp{:} used as the
15053 These restrictions apply not only to the files that you distribute, but
15054 also to the absolute file names of your source, build, and destination
15057 On some Posix-like platforms, @samp{!} and @samp{^} are special too, so
15058 they should be avoided.
15060 Posix lets implementations treat leading @file{//} specially, but
15061 requires leading @file{///} and beyond to be equivalent to @file{/}.
15062 Most Unix variants treat @file{//} like @file{/}. However, some treat
15063 @file{//} as a ``super-root'' that can provide access to files that are
15064 not otherwise reachable from @file{/}. The super-root tradition began
15065 with Apollo Domain/OS, which died out long ago, but unfortunately Cygwin
15068 While @command{autoconf} and friends are usually run on some Posix
15069 variety, they can be used on other systems, most notably DOS
15070 variants. This impacts several assumptions regarding file names.
15073 For example, the following code:
15080 foo_dir=$dots$foo_dir ;;
15085 fails to properly detect absolute file names on those systems, because
15086 they can use a drivespec, and usually use a backslash as directory
15087 separator. If you want to be portable to DOS variants (at the
15088 price of rejecting valid but oddball Posix file names like @file{a:\b}),
15089 you can check for absolute file names like this:
15091 @cindex absolute file names, detect
15094 [\\/]* | ?:[\\/]* ) # Absolute
15097 foo_dir=$dots$foo_dir ;;
15102 Make sure you quote the brackets if appropriate and keep the backslash as
15103 first character (@pxref{case, , Limitations of Shell Builtins}).
15105 Also, because the colon is used as part of a drivespec, these systems don't
15106 use it as path separator. When creating or accessing paths, you can use the
15107 @code{PATH_SEPARATOR} output variable instead. @command{configure} sets this
15108 to the appropriate value for the build system (@samp{:} or @samp{;}) when it
15111 File names need extra care as well. While DOS variants
15112 that are Posixy enough to run @command{autoconf} (such as DJGPP)
15113 are usually able to handle long file names properly, there are still
15114 limitations that can seriously break packages. Several of these issues
15115 can be easily detected by the
15116 @uref{ftp://@/ftp.gnu.org/@/gnu/@/non-gnu/@/doschk/@/doschk-1.1.tar.gz, doschk}
15119 A short overview follows; problems are marked with SFN/LFN to
15120 indicate where they apply: SFN means the issues are only relevant to
15121 plain DOS, not to DOS under Microsoft Windows
15122 variants, while LFN identifies problems that exist even under
15123 Microsoft Windows variants.
15126 @item No multiple dots (SFN)
15127 DOS cannot handle multiple dots in file names. This is an especially
15128 important thing to remember when building a portable configure script,
15129 as @command{autoconf} uses a .in suffix for template files.
15131 This is perfectly OK on Posix variants:
15134 AC_CONFIG_HEADERS([config.h])
15135 AC_CONFIG_FILES([source.c foo.bar])
15140 but it causes problems on DOS, as it requires @samp{config.h.in},
15141 @samp{source.c.in} and @samp{foo.bar.in}. To make your package more portable
15142 to DOS-based environments, you should use this instead:
15145 AC_CONFIG_HEADERS([config.h:config.hin])
15146 AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in])
15150 @item No leading dot (SFN)
15151 DOS cannot handle file names that start with a dot. This is usually
15152 not important for @command{autoconf}.
15154 @item Case insensitivity (LFN)
15155 DOS is case insensitive, so you cannot, for example, have both a
15156 file called @samp{INSTALL} and a directory called @samp{install}. This
15157 also affects @command{make}; if there's a file called @samp{INSTALL} in
15158 the directory, @samp{make install} does nothing (unless the
15159 @samp{install} target is marked as PHONY).
15161 @item The 8+3 limit (SFN)
15162 Because the DOS file system only stores the first 8 characters of
15163 the file name and the first 3 of the extension, those must be unique.
15164 That means that @file{foobar-part1.c}, @file{foobar-part2.c} and
15165 @file{foobar-prettybird.c} all resolve to the same file name
15166 (@file{FOOBAR-P.C}). The same goes for @file{foo.bar} and
15167 @file{foo.bartender}.
15169 The 8+3 limit is not usually a problem under Microsoft Windows, as it
15171 tails in the short version of file names to make them unique. However, a
15172 registry setting can turn this behavior off. While this makes it
15173 possible to share file trees containing long file names between SFN
15174 and LFN environments, it also means the above problem applies there
15177 @item Invalid characters (LFN)
15178 Some characters are invalid in DOS file names, and should therefore
15179 be avoided. In a LFN environment, these are @samp{/}, @samp{\},
15180 @samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}.
15181 In a SFN environment, other characters are also invalid. These
15182 include @samp{+}, @samp{,}, @samp{[} and @samp{]}.
15184 @item Invalid names (LFN)
15185 Some DOS file names are reserved, and cause problems if you
15186 try to use files with those names. These names include @file{CON},
15187 @file{AUX}, @file{COM1}, @file{COM2}, @file{COM3}, @file{COM4},
15188 @file{LPT1}, @file{LPT2}, @file{LPT3}, @file{NUL}, and @file{PRN}.
15189 File names are case insensitive, so even names like
15190 @file{aux/config.guess} are disallowed.
15194 @node Shell Pattern Matching
15195 @section Shell Pattern Matching
15196 @cindex Shell pattern matching
15198 Nowadays portable patterns can use negated character classes like
15199 @samp{[!-aeiou]}. The older syntax @samp{[^-aeiou]} is supported by
15200 some shells but not others; hence portable scripts should never use
15201 @samp{^} as the first character of a bracket pattern.
15203 Outside the C locale, patterns like @samp{[a-z]} are problematic since
15204 they may match characters that are not lower-case letters.
15206 @node Shell Substitutions
15207 @section Shell Substitutions
15208 @cindex Shell substitutions
15210 Contrary to a persistent urban legend, the Bourne shell does not
15211 systematically split variables and back-quoted expressions, in particular
15212 on the right-hand side of assignments and in the argument of @code{case}.
15213 For instance, the following code:
15216 case "$given_srcdir" in
15217 .) top_srcdir="`echo "$dots" | sed 's|/$||'`" ;;
15218 *) top_srcdir="$dots$given_srcdir" ;;
15223 is more readable when written as:
15226 case $given_srcdir in
15227 .) top_srcdir=`echo "$dots" | sed 's|/$||'` ;;
15228 *) top_srcdir=$dots$given_srcdir ;;
15233 and in fact it is even @emph{more} portable: in the first case of the
15234 first attempt, the computation of @code{top_srcdir} is not portable,
15235 since not all shells properly understand @code{"`@dots{}"@dots{}"@dots{}`"},
15236 for example Solaris 10 ksh:
15239 $ @kbd{foo="`echo " bar" | sed 's, ,,'`"}
15240 ksh: : cannot execute
15241 ksh: bar | sed 's, ,,': cannot execute
15245 Posix does not specify behavior for this sequence. On the other hand,
15246 behavior for @code{"`@dots{}\"@dots{}\"@dots{}`"} is specified by Posix,
15247 but in practice, not all shells understand it the same way: pdksh 5.2.14
15248 prints spurious quotes when in Posix mode:
15251 $ @kbd{echo "`echo \"hello\"`"}
15253 $ @kbd{set -o posix}
15254 $ @kbd{echo "`echo \"hello\"`"}
15259 There is just no portable way to use double-quoted strings inside
15260 double-quoted back-quoted expressions (pfew!).
15264 @cindex @samp{"$@@"}
15265 One of the most famous shell-portability issues is related to
15266 @samp{"$@@"}. When there are no positional arguments, Posix says
15267 that @samp{"$@@"} is supposed to be equivalent to nothing, but the
15268 original Unix version 7 Bourne shell treated it as equivalent to
15269 @samp{""} instead, and this behavior survives in later implementations
15270 like Digital Unix 5.0.
15272 The traditional way to work around this portability problem is to use
15273 @samp{$@{1+"$@@"@}}. Unfortunately this method does not work with
15274 Zsh (3.x and 4.x), which is used on Mac OS X@. When emulating
15275 the Bourne shell, Zsh performs word splitting on @samp{$@{1+"$@@"@}}:
15278 zsh $ @kbd{emulate sh}
15279 zsh $ @kbd{for i in "$@@"; do echo $i; done}
15282 zsh $ @kbd{for i in $@{1+"$@@"@}; do echo $i; done}
15289 Zsh handles plain @samp{"$@@"} properly, but we can't use plain
15290 @samp{"$@@"} because of the portability problems mentioned above.
15291 One workaround relies on Zsh's ``global aliases'' to convert
15292 @samp{$@{1+"$@@"@}} into @samp{"$@@"} by itself:
15295 test "$@{ZSH_VERSION+set@}" = set && alias -g '$@{1+"$@@"@}'='"$@@"'
15298 Zsh only recognizes this alias when a shell word matches it exactly;
15299 @samp{"foo"$@{1+"$@@"@}} remains subject to word splitting. Since this
15300 case always yields at least one shell word, use plain @samp{"$@@"}.
15302 A more conservative workaround is to avoid @samp{"$@@"} if it is
15303 possible that there may be no positional arguments. For example,
15307 cat conftest.c "$@@"
15310 you can use this instead:
15314 0) cat conftest.c;;
15315 *) cat conftest.c "$@@";;
15319 Autoconf macros often use the @command{set} command to update
15320 @samp{$@@}, so if you are writing shell code intended for
15321 @command{configure} you should not assume that the value of @samp{$@@}
15322 persists for any length of time.
15326 @cindex positional parameters
15327 The 10th, 11th, @dots{} positional parameters can be accessed only after
15328 a @code{shift}. The 7th Edition shell reported an error if given
15329 @code{$@{10@}}, and
15330 Solaris 10 @command{/bin/sh} still acts that way:
15333 $ @kbd{set 1 2 3 4 5 6 7 8 9 10}
15334 $ @kbd{echo $@{10@}}
15338 @item $@{@var{var}:-@var{value}@}
15339 @c Info cannot handle `:' in index entries.
15341 @cindex $@{@var{var}:-@var{value}@}
15343 Old BSD shells, including the Ultrix @code{sh}, don't accept the
15344 colon for any shell substitution, and complain and die.
15345 Similarly for $@{@var{var}:=@var{value}@}, $@{@var{var}:?@var{value}@}, etc.
15347 @item $@{@var{var}=@var{literal}@}
15348 @cindex $@{@var{var}=@var{literal}@}
15352 : $@{var='Some words'@}
15356 otherwise some shells, such as on Digital Unix V 5.0, die because
15357 of a ``bad substitution''.
15361 Solaris @command{/bin/sh} has a frightening bug in its interpretation
15362 of this. Imagine you need set a variable to a string containing
15363 @samp{@}}. This @samp{@}} character confuses Solaris @command{/bin/sh}
15364 when the affected variable was already set. This bug can be exercised
15369 $ @kbd{foo=$@{foo='@}'@}}
15372 $ @kbd{foo=$@{foo='@}' # no error; this hints to what the bug is}
15375 $ @kbd{foo=$@{foo='@}'@}}
15381 It seems that @samp{@}} is interpreted as matching @samp{$@{}, even
15382 though it is enclosed in single quotes. The problem doesn't happen
15383 using double quotes.
15385 @item $@{@var{var}=@var{expanded-value}@}
15386 @cindex $@{@var{var}=@var{expanded-value}@}
15392 : $@{var="$default"@}
15396 sets @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of
15397 each char is set. You don't observe the phenomenon using a simple
15398 @samp{echo $var} since apparently the shell resets the 8th bit when it
15399 expands $var. Here are two means to make this shell confess its sins:
15402 $ @kbd{cat -v <<EOF
15411 $ @kbd{set | grep '^var=' | cat -v}
15414 One classic incarnation of this bug is:
15418 : $@{list="$default"@}
15425 You'll get @samp{a b c} on a single line. Why? Because there are no
15426 spaces in @samp{$list}: there are @samp{M- }, i.e., spaces with the 8th
15427 bit set, hence no IFS splitting is performed!!!
15429 One piece of good news is that Ultrix works fine with @samp{:
15430 $@{list=$default@}}; i.e., if you @emph{don't} quote. The bad news is
15431 then that QNX 4.25 then sets @var{list} to the @emph{last} item of
15434 The portable way out consists in using a double assignment, to switch
15435 the 8th bit twice on Ultrix:
15438 list=$@{list="$default"@}
15442 @dots{}but beware of the @samp{@}} bug from Solaris (see above). For safety,
15446 test "$@{var+set@}" = set || var=@var{@{value@}}
15449 @item $@{#@var{var}@}
15450 @itemx $@{@var{var}%@var{word}@}
15451 @itemx $@{@var{var}%%@var{word}@}
15452 @itemx $@{@var{var}#@var{word}@}
15453 @itemx $@{@var{var}##@var{word}@}
15454 @cindex $@{#@var{var}@}
15455 @cindex $@{@var{var}%@var{word}@}
15456 @cindex $@{@var{var}%%@var{word}@}
15457 @cindex $@{@var{var}#@var{word}@}
15458 @cindex $@{@var{var}##@var{word}@}
15459 Posix requires support for these usages, but they do not work with many
15460 traditional shells, e.g., Solaris 10 @command{/bin/sh}.
15462 Also, @command{pdksh} 5.2.14 mishandles some @var{word} forms. For
15463 example if @samp{$1} is @samp{a/b} and @samp{$2} is @samp{a}, then
15464 @samp{$@{1#$2@}} should yield @samp{/b}, but with @command{pdksh} it
15465 yields the empty string.
15468 @item `@var{commands}`
15469 @cindex `@var{commands}`
15470 @cindex Command Substitution
15471 Posix requires shells to trim all trailing newlines from command
15472 output before substituting it, so assignments like
15473 @samp{dir=`echo "$file" | tr a A`} do not work as expected if
15474 @samp{$file} ends in a newline.
15476 While in general it makes no sense, do not substitute a single builtin
15477 with side effects, because Ash 0.2, trying to optimize, does not fork a
15478 subshell to perform the command.
15480 For instance, if you wanted to check that @command{cd} is silent, do not
15481 use @samp{test -z "`cd /`"} because the following can happen:
15486 $ @kbd{test -z "`cd /`" && pwd}
15491 The result of @samp{foo=`exit 1`} is left as an exercise to the reader.
15493 The MSYS shell leaves a stray byte in the expansion of a double-quoted
15494 command substitution of a native program, if the end of the substitution
15495 is not aligned with the end of the double quote. This may be worked
15496 around by inserting another pair of quotes:
15499 $ @kbd{echo "`printf 'foo\r\n'` bar" > broken}
15500 $ @kbd{echo "`printf 'foo\r\n'`"" bar" | cmp - broken}
15501 - broken differ: char 4, line 1
15504 Upon interrupt or SIGTERM, some shells may abort a command substitution,
15505 replace it with a null string, and wrongly evaluate the enclosing
15506 command before entering the trap or ending the script. This can lead to
15510 $ @kbd{sh -c 'if test `sleep 5; echo hi` = hi; then echo yes; fi'}
15512 sh: test: hi: unexpected operator/operand
15516 You can avoid this by assigning the command substitution to a temporary
15520 $ @kbd{sh -c 'res=`sleep 5; echo hi`
15521 if test "x$res" = xhi; then echo yes; fi'}
15525 @item $(@var{commands})
15526 @cindex $(@var{commands})
15527 This construct is meant to replace @samp{`@var{commands}`},
15528 and it has most of the problems listed under @code{`@var{commands}`}.
15530 This construct can be
15531 nested while this is impossible to do portably with back quotes.
15532 Unfortunately it is not yet universally supported. Most notably, even recent
15533 releases of Solaris don't support it:
15536 $ @kbd{showrev -c /bin/sh | grep version}
15537 Command version: SunOS 5.10 Generic 121005-03 Oct 2006
15538 $ @kbd{echo $(echo blah)}
15539 syntax error: `(' unexpected
15543 nor does IRIX 6.5's Bourne shell:
15546 IRIX firebird-image 6.5 07151432 IP22
15547 $ @kbd{echo $(echo blah)}
15551 If you do use @samp{$(@var{commands})}, make sure that the commands
15552 do not start with a parenthesis, as that would cause confusion with
15553 a different notation @samp{$((@var{expression}))} that in modern
15554 shells is an arithmetic expression not a command. To avoid the
15555 confusion, insert a space between the two opening parentheses.
15557 Avoid @var{commands} that contain unbalanced parentheses in
15558 here-documents, comments, or case statement patterns, as many shells
15559 mishandle them. For example, Bash 3.1, @samp{ksh88}, @command{pdksh}
15560 5.2.14, and Zsh 4.2.6 all mishandle the following valid command:
15563 echo $(case x in x) echo hello;; esac)
15567 @item $((@var{expression}))
15568 @cindex $((@var{expression}))
15569 Arithmetic expansion is not portable as some shells (most
15570 notably Solaris 10 @command{/bin/sh}) don't support it.
15572 Among shells that do support @samp{$(( ))}, not all of them obey the
15573 Posix rule that octal and hexadecimal constants must be recognized:
15576 $ @kbd{bash -c 'echo $(( 010 + 0x10 ))'}
15578 $ @kbd{zsh -c 'echo $(( 010 + 0x10 ))'}
15580 $ @kbd{zsh -c 'emulate sh; echo $(( 010 + 0x10 ))'}
15582 $ @kbd{pdksh -c 'echo $(( 010 + 0x10 ))'}
15583 pdksh: 010 + 0x10 : bad number `0x10'
15584 $ @kbd{pdksh -c 'echo $(( 010 ))'}
15588 When it is available, using arithmetic expansion provides a noticeable
15589 speedup in script execution; but testing for support requires
15590 @command{eval} to avoid syntax errors. The following construct is used
15591 by @code{AS_VAR_ARITH} to provide arithmetic computation when all
15592 arguments are provided in decimal and without a leading zero, and all
15593 operators are properly quoted and appear as distinct arguments:
15596 if ( eval 'test $(( 1 + 1 )) = 2' ) 2>/dev/null; then
15597 eval 'func_arith ()
15599 func_arith_result=$(( $* ))
15604 func_arith_result=`expr "$@@"`
15608 foo=$func_arith_result
15614 Always quote @samp{^}, otherwise traditional shells such as
15615 @command{/bin/sh} on Solaris 10 treat this like @samp{|}.
15621 @section Assignments
15622 @cindex Shell assignments
15624 When setting several variables in a row, be aware that the order of the
15625 evaluation is undefined. For instance @samp{foo=1 foo=2; echo $foo}
15626 gives @samp{1} with Solaris @command{/bin/sh}, but @samp{2} with Bash.
15628 @samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}.
15630 Don't rely on the following to find @file{subdir/program}:
15633 PATH=subdir$PATH_SEPARATOR$PATH program
15637 as this does not work with Zsh 3.0.6. Use something like this
15641 (PATH=subdir$PATH_SEPARATOR$PATH; export PATH; exec program)
15644 Don't rely on the exit status of an assignment: Ash 0.2 does not change
15645 the status and propagates that of the last statement:
15648 $ @kbd{false || foo=bar; echo $?}
15650 $ @kbd{false || foo=`:`; echo $?}
15655 and to make things even worse, QNX 4.25 just sets the exit status
15659 $ @kbd{foo=`exit 1`; echo $?}
15663 To assign default values, follow this algorithm:
15667 If the default value is a literal and does not contain any closing
15671 : $@{var='my literal'@}
15675 If the default value contains no closing brace, has to be expanded, and
15676 the variable being initialized is not intended to be IFS-split
15677 (i.e., it's not a list), then use:
15680 : $@{var="$default"@}
15684 If the default value contains no closing brace, has to be expanded, and
15685 the variable being initialized is intended to be IFS-split (i.e., it's a list),
15689 var=$@{var="$default"@}
15693 If the default value contains a closing brace, then use:
15696 test "$@{var+set@}" = set || var="has a '@}'"
15700 In most cases @samp{var=$@{var="$default"@}} is fine, but in case of
15701 doubt, just use the last form. @xref{Shell Substitutions}, items
15702 @samp{$@{@var{var}:-@var{value}@}} and @samp{$@{@var{var}=@var{value}@}}
15706 @section Parentheses in Shell Scripts
15707 @cindex Shell parentheses
15709 Beware of two opening parentheses in a row, as many shell
15710 implementations treat them specially. Posix requires that the command
15711 @samp{((cat))} must behave like @samp{(cat)}, but many shells, including
15712 Bash and the Korn shell, treat @samp{((cat))} as an arithmetic
15713 expression equivalent to @samp{let "cat"}, and may or may not report an
15714 error when they detect that @samp{cat} is not a number. As another
15715 example, @samp{pdksh} 5.2.14 misparses the following code:
15718 if ((true) || false); then
15724 To work around this problem, insert a space between the two opening
15725 parentheses. There is a similar problem and workaround with
15726 @samp{$((}; see @ref{Shell Substitutions}.
15729 @section Slashes in Shell Scripts
15730 @cindex Shell slashes
15732 Unpatched Tru64 5.1 @command{sh} omits the last slash of command-line
15733 arguments that contain two trailing slashes:
15736 $ @kbd{echo / // /// //// .// //.}
15739 $ @kbd{eval "echo \$x"}
15742 $ @kbd{echo abc | tr -t ab //}
15748 Unpatched Tru64 4.0 @command{sh} adds a slash after @samp{"$var"} if the
15749 variable is empty and the second double-quote is followed by a word that
15750 begins and ends with slash:
15753 $ @kbd{sh -xc 'p=; echo "$p"/ouch/'}
15759 However, our understanding is that patches are available, so perhaps
15760 it's not worth worrying about working around these horrendous bugs.
15762 @node Special Shell Variables
15763 @section Special Shell Variables
15764 @cindex Shell variables
15765 @cindex Special shell variables
15767 Some shell variables should not be used, since they can have a deep
15768 influence on the behavior of the shell. In order to recover a sane
15769 behavior from the shell, some variables should be unset; M4sh takes
15770 care of this and provides fallback values, whenever needed, to cater
15771 for a very old @file{/bin/sh} that does not support @command{unset}.
15772 (@pxref{Portable Shell, , Portable Shell Programming}).
15774 As a general rule, shell variable names containing a lower-case letter
15775 are safe; you can define and use these variables without worrying about
15776 their effect on the underlying system, and without worrying about
15777 whether the shell changes them unexpectedly. (The exception is the
15778 shell variable @code{status}, as described below.)
15780 Here is a list of names that are known to cause trouble. This list is
15781 not exhaustive, but you should be safe if you avoid the name
15782 @code{status} and names containing only upper-case letters and
15785 @c Alphabetical order, case insensitive, `A' before `a'.
15788 Not all shells correctly reset @samp{$?} after conditionals (@pxref{if,
15789 , Limitations of Shell Builtins}). Not all shells manage @samp{$?}
15790 correctly in shell functions (@pxref{Shell Functions}) or in traps
15791 (@pxref{trap, , Limitations of Shell Builtins}). Not all shells reset
15792 @samp{$?} to zero after an empty command.
15795 $ @kbd{bash -c 'false; $empty; echo $?'}
15797 $ @kbd{zsh -c 'false; $empty; echo $?'}
15803 Many shells reserve @samp{$_} for various purposes, e.g., the name of
15804 the last command executed.
15808 In Tru64, if @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
15809 the standard shell conform to Posix.
15813 When this variable is set it specifies a list of directories to search
15814 when invoking @code{cd} with a relative file name that did not start
15815 with @samp{./} or @samp{../}. Posix
15816 1003.1-2001 says that if a nonempty directory name from @env{CDPATH}
15817 is used successfully, @code{cd} prints the resulting absolute
15818 file name. Unfortunately this output can break idioms like
15819 @samp{abs=`cd src && pwd`} because @code{abs} receives the name twice.
15820 Also, many shells do not conform to this part of Posix; for
15821 example, @command{zsh} prints the result only if a directory name
15822 other than @file{.} was chosen from @env{CDPATH}.
15824 In practice the shells that have this problem also support
15825 @command{unset}, so you can work around the problem as follows:
15828 (unset CDPATH) >/dev/null 2>&1 && unset CDPATH
15831 You can also avoid output by ensuring that your directory name is
15832 absolute or anchored at @samp{./}, as in @samp{abs=`cd ./src && pwd`}.
15834 Configure scripts use M4sh, which automatically unsets @env{CDPATH} if
15835 possible, so you need not worry about this problem in those scripts.
15837 @item CLICOLOR_FORCE
15838 @evindex CLICOLOR_FORCE
15839 When this variable is set, some implementations of tools like
15840 @command{ls} attempt to add color to their output via terminal escape
15841 sequences, even when the output is not directed to a terminal, and can
15842 thus cause spurious failures in scripts. Configure scripts use M4sh,
15843 which automatically unsets this variable.
15847 In the MKS shell, case statements and file name generation are
15848 case-insensitive unless @env{DUALCASE} is nonzero.
15849 Autoconf-generated scripts export this variable when they start up.
15863 These variables should not matter for shell scripts, since they are
15864 supposed to affect only interactive shells. However, at least one
15865 shell (the pre-3.0 UWIN Korn shell) gets confused about
15866 whether it is interactive, which means that (for example) a @env{PS1}
15867 with a side effect can unexpectedly modify @samp{$?}. To work around
15868 this bug, M4sh scripts (including @file{configure} scripts) do something
15872 (unset ENV) >/dev/null 2>&1 && unset ENV MAIL MAILPATH
15879 (actually, there is some complication due to bugs in @command{unset};
15880 see @pxref{unset, , Limitations of Shell Builtins}).
15884 The Korn shell uses @env{FPATH} to find shell functions, so avoid
15885 @env{FPATH} in portable scripts. @env{FPATH} is consulted after
15886 @env{PATH}, but you still need to be wary of tests that use @env{PATH}
15887 to find whether a command exists, since they might report the wrong
15888 result if @env{FPATH} is also set.
15891 @evindex GREP_OPTIONS
15892 When this variable is set, some implementations of @command{grep} honor
15893 these options, even if the options include direction to enable colored
15894 output via terminal escape sequences, and the result can cause spurious
15895 failures when the output is not directed to a terminal. Configure
15896 scripts use M4sh, which automatically unsets this variable.
15900 Long ago, shell scripts inherited @env{IFS} from the environment,
15901 but this caused many problems so modern shells ignore any environment
15902 settings for @env{IFS}.
15904 Don't set the first character of @env{IFS} to backslash. Indeed,
15905 Bourne shells use the first character (backslash) when joining the
15906 components in @samp{"$@@"} and some shells then reinterpret (!)@: the
15907 backslash escapes, so you can end up with backspace and other strange
15910 The proper value for @env{IFS} (in regular code, not when performing
15911 splits) is @samp{@key{SPC}@key{TAB}@key{RET}}. The first character is
15912 especially important, as it is used to join the arguments in @samp{$*};
15913 however, note that traditional shells, but also bash-2.04, fail to adhere
15914 to this and join with a space anyway.
15916 M4sh guarantees that @env{IFS} will have the default value at the
15917 beginning of a script, and many macros within autoconf rely on this
15918 setting. It is okay to use blocks of shell code that temporarily change
15919 the value of @env{IFS} in order to split on another character, but
15920 remember to restore it before expanding further macros.
15922 Unsetting @code{IFS} instead of resetting it to the default sequence
15923 is not suggested, since code that tries to save and restore the
15924 variable's value will incorrectly reset it to an empty value, thus
15925 disabling field splitting:
15929 # default separators used for field splitting
15935 # no field splitting performed
15948 @evindex LC_COLLATE
15950 @evindex LC_MESSAGES
15951 @evindex LC_MONETARY
15952 @evindex LC_NUMERIC
15955 You should set all these variables to @samp{C} because so much
15956 configuration code assumes the C locale and Posix requires that locale
15957 environment variables be set to @samp{C} if the C locale is desired;
15958 @file{configure} scripts and M4sh do that for you.
15959 Export these variables after setting them.
15961 @c However, some older, nonstandard
15962 @c systems (notably SCO) break if locale environment variables
15963 @c are set to @samp{C}, so when running on these systems
15964 @c Autoconf-generated scripts unset the variables instead.
15969 @env{LANGUAGE} is not specified by Posix, but it is a GNU
15970 extension that overrides @env{LC_ALL} in some cases, so you (or M4sh)
15974 @itemx LC_IDENTIFICATION
15975 @itemx LC_MEASUREMENT
15978 @itemx LC_TELEPHONE
15979 @evindex LC_ADDRESS
15980 @evindex LC_IDENTIFICATION
15981 @evindex LC_MEASUREMENT
15984 @evindex LC_TELEPHONE
15986 These locale environment variables are GNU extensions. They
15987 are treated like their Posix brethren (@env{LC_COLLATE},
15988 etc.)@: as described above.
15992 Most modern shells provide the current line number in @code{LINENO}.
15993 Its value is the line number of the beginning of the current command.
15994 M4sh, and hence Autoconf, attempts to execute @command{configure} with
15995 a shell that supports @code{LINENO}. If no such shell is available, it
15996 attempts to implement @code{LINENO} with a Sed prepass that replaces each
15997 instance of the string @code{$LINENO} (not followed by an alphanumeric
15998 character) with the line's number. In M4sh scripts you should execute
15999 @code{AS_LINENO_PREPARE} so that these workarounds are included in
16000 your script; configure scripts do this automatically in @code{AC_INIT}.
16002 You should not rely on @code{LINENO} within @command{eval} or shell
16003 functions, as the behavior differs in practice. The presence of a
16004 quoted newline within simple commands can alter which line number is
16005 used as the starting point for @code{$LINENO} substitutions within that
16006 command. Also, the possibility of the Sed prepass means that you should
16007 not rely on @code{$LINENO} when quoted, when in here-documents, or when
16008 line continuations are used. Subshells should be OK, though. In the
16009 following example, lines 1, 9, and 14 are portable, but the other
16010 instances of @code{$LINENO} do not have deterministic values:
16023 ( echo 9. $LINENO )
16024 eval 'echo 10. $LINENO'
16025 eval 'echo 11. $LINENO
16030 f () @{ echo $1 $LINENO;
16037 $ @kbd{bash-3.2 ./lineno}
16056 $ @kbd{zsh-4.3.4 ./lineno}
16075 $ @kbd{pdksh-5.2.14 ./lineno}
16094 $ @kbd{sed '=' <lineno |}
16100 > @kbd{ s,^\([0-9]*\)\(.*\)[$]LINENO\([^a-zA-Z0-9_]\),\1\2\1\3,}
16103 > @kbd{ s,^[0-9]*\n,,}
16125 In particular, note that @file{config.status} (and any other subsidiary
16126 script created by @code{AS_INIT_GENERATED}) might report line numbers
16127 relative to the parent script as a result of the potential Sed pass.
16131 When executing the command @samp{>foo}, @command{zsh} executes
16132 @samp{$NULLCMD >foo} unless it is operating in Bourne shell
16133 compatibility mode and the @command{zsh} version is newer
16134 than 3.1.6-dev-18. If you are using an older @command{zsh}
16135 and forget to set @env{NULLCMD},
16136 your script might be suspended waiting for data on its standard input.
16138 @item PATH_SEPARATOR
16139 @evindex PATH_SEPARATOR
16140 On DJGPP systems, the @env{PATH_SEPARATOR} environment
16141 variable can be set to either @samp{:} or @samp{;} to control the path
16142 separator Bash uses to set up certain environment variables (such as
16143 @env{PATH}). You can set this variable to @samp{;} if you want
16144 @command{configure} to use @samp{;} as a separator; this might be useful
16145 if you plan to use non-Posix shells to execute files. @xref{File System
16146 Conventions}, for more information about @code{PATH_SEPARATOR}.
16150 Posix 1003.1-2001 requires that @command{cd} and
16151 @command{pwd} must update the @env{PWD} environment variable to point
16152 to the logical name of the current directory, but traditional shells
16153 do not support this. This can cause confusion if one shell instance
16154 maintains @env{PWD} but a subsidiary and different shell does not know
16155 about @env{PWD} and executes @command{cd}; in this case @env{PWD}
16156 points to the wrong directory. Use @samp{`pwd`} rather than
16161 Many shells provide @code{RANDOM}, a variable that returns a different
16162 integer each time it is used. Most of the time, its value does not
16163 change when it is not used, but on IRIX 6.5 the value changes all
16164 the time. This can be observed by using @command{set}. It is common
16165 practice to use @code{$RANDOM} as part of a file name, but code
16166 shouldn't rely on @code{$RANDOM} expanding to a nonempty string.
16170 This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6),
16171 hence read-only. Do not use it.
16174 @node Shell Functions
16175 @section Shell Functions
16176 @cindex Shell Functions
16178 Nowadays, it is difficult to find a shell that does not support
16179 shell functions at all. However, some differences should be expected.
16181 Inside a shell function, you should not rely on the error status of a
16182 subshell if the last command of that subshell was @code{exit} or
16183 @code{trap}, as this triggers bugs in zsh 4.x; while Autoconf tries to
16184 find a shell that does not exhibit the bug, zsh might be the only shell
16185 present on the user's machine.
16187 Likewise, the state of @samp{$?} is not reliable when entering a shell
16188 function. This has the effect that using a function as the first
16189 command in a @command{trap} handler can cause problems.
16192 $ @kbd{bash -c 'foo()@{ echo $?; @}; trap foo 0; (exit 2); exit 2'; echo $?}
16195 $ @kbd{ash -c 'foo()@{ echo $?; @}; trap foo 0; (exit 2); exit 2'; echo $?}
16200 DJGPP bash 2.04 has a bug in that @command{return} from a
16201 shell function which also used a command substitution causes a
16202 segmentation fault. To work around the issue, you can use
16203 @command{return} from a subshell, or @samp{AS_SET_STATUS} as last command
16204 in the execution flow of the function (@pxref{Common Shell Constructs}).
16206 Not all shells treat shell functions as simple commands impacted by
16207 @samp{set -e}, for example with Solaris 10 @command{bin/sh}:
16210 $ @kbd{bash -c 'f()@{ return 1; @}; set -e; f; echo oops}
16211 $ @kbd{/bin/sh -c 'f()@{ return 1; @}; set -e; f; echo oops}
16215 Shell variables and functions may share the same namespace, for example
16216 with Solaris 10 @command{/bin/sh}:
16219 $ @kbd{f () @{ :; @}; f=; f}
16224 For this reason, Autoconf (actually M4sh, @pxref{Programming in M4sh})
16225 uses the prefix @samp{as_fn_} for its functions.
16227 Handling of positional parameters and shell options varies among shells.
16228 For example, Korn shells reset and restore trace output (@samp{set -x})
16229 and other options upon function entry and exit. Inside a function,
16230 IRIX sh sets @samp{$0} to the function name.
16232 It is not portable to pass temporary environment variables to shell
16233 functions. Solaris @command{/bin/sh} does not see the variable.
16234 Meanwhile, not all shells follow the Posix rule that the assignment must
16235 affect the current environment in the same manner as special built-ins.
16238 $ @kbd{/bin/sh -c 'func()@{ echo $a;@}; a=1 func; echo $a'}
16241 $ @kbd{ash -c 'func()@{ echo $a;@}; a=1 func; echo $a'}
16244 $ @kbd{bash -c 'set -o posix; func()@{ echo $a;@}; a=1 func; echo $a'}
16249 Some ancient Bourne shell variants with function support did not reset
16250 @samp{$@var{i}, @var{i} >= 0}, upon function exit, so effectively the
16251 arguments of the script were lost after the first function invocation.
16252 It is probably not worth worrying about these shells any more.
16254 With AIX sh, a @command{trap} on 0 installed in a shell function
16255 triggers at function exit rather than at script exit, see @xref{trap, ,
16256 Limitations of Shell Builtins}.
16258 @node Limitations of Builtins
16259 @section Limitations of Shell Builtins
16260 @cindex Shell builtins
16261 @cindex Limitations of shell builtins
16263 No, no, we are serious: some shells do have limitations! :)
16265 You should always keep in mind that any builtin or command may support
16266 options, and therefore differ in behavior with arguments
16267 starting with a dash. For instance, even the innocent @samp{echo "$word"}
16268 can give unexpected results when @code{word} starts with a dash. It is
16269 often possible to avoid this problem using @samp{echo "x$word"}, taking
16270 the @samp{x} into account later in the pipe. Many of these limitations
16271 can be worked around using M4sh (@pxref{Programming in M4sh}).
16273 @c This table includes things like `@command{test} (files)', so we can't
16274 @c use @table @command.
16278 @prindex @command{.}
16279 Use @command{.} only with regular files (use @samp{test -f}). Bash
16280 2.03, for instance, chokes on @samp{. /dev/null}. Remember that
16281 @command{.} uses @env{PATH} if its argument contains no slashes. Also,
16282 some shells, including bash 3.2, implicitly append the current directory
16283 to this @env{PATH} search, even though Posix forbids it. So if you want
16284 to use @command{.} on a file @file{foo} in the current directory, you
16285 must use @samp{. ./foo}.
16287 Not all shells gracefully handle syntax errors within a sourced file.
16288 On one extreme, some non-interactive shells abort the entire script. On
16289 the other, @command{zsh} 4.3.10 has a bug where it fails to react to the
16293 $ @kbd{echo 'fi' > syntax}
16294 $ @kbd{bash -c '. ./syntax; echo $?'}
16295 ./syntax: line 1: syntax error near unexpected token `fi'
16296 ./syntax: line 1: `fi'
16298 $ @kbd{ash -c '. ./syntax; echo $?'}
16299 ./syntax: 1: Syntax error: "fi" unexpected
16300 $ @kbd{zsh -c '. ./syntax; echo $?'}
16301 ./syntax:1: parse error near `fi'
16307 @prindex @command{!}
16308 The Unix version 7 shell did not support
16309 negating the exit status of commands with @command{!}, and this feature
16310 is still absent from some shells (e.g., Solaris @command{/bin/sh}).
16311 Other shells, such as FreeBSD @command{/bin/sh} or @command{ash}, have
16312 bugs when using @command{!}:
16315 $ @kbd{sh -c '! : | :'; echo $?}
16317 $ @kbd{ash -c '! : | :'; echo $?}
16319 $ @kbd{sh -c '! @{ :; @}'; echo $?}
16321 $ @kbd{ash -c '! @{ :; @}'; echo $?}
16323 Syntax error: "@}" unexpected
16327 Shell code like this:
16330 if ! cmp file1 file2 >/dev/null 2>&1; then
16331 echo files differ or trouble
16335 is therefore not portable in practice. Typically it is easy to rewrite
16339 cmp file1 file2 >/dev/null 2>&1 ||
16340 echo files differ or trouble
16343 More generally, one can always rewrite @samp{! @var{command}} as:
16346 if @var{command}; then (exit 1); else :; fi
16350 @item @command{@{...@}}
16351 @c --------------------
16352 @prindex @command{@{...@}}
16353 Bash 3.2 (and earlier versions) sometimes does not properly set
16354 @samp{$?} when failing to write redirected output of a compound command.
16355 This problem is most commonly observed with @samp{@{@dots{}@}}; it does
16356 not occur with @samp{(@dots{})}. For example:
16359 $ @kbd{bash -c '@{ echo foo; @} >/bad; echo $?'}
16360 bash: line 1: /bad: Permission denied
16362 $ @kbd{bash -c 'while :; do echo; done >/bad; echo $?'}
16363 bash: line 1: /bad: Permission denied
16367 To work around the bug, prepend @samp{:;}:
16370 $ @kbd{bash -c ':;@{ echo foo; @} >/bad; echo $?'}
16371 bash: line 1: /bad: Permission denied
16375 Posix requires a syntax error if a brace list has no contents. However,
16376 not all shells obey this rule; and on shells where empty lists are
16377 permitted, the effect on @samp{$?} is inconsistent. To avoid problems,
16378 ensure that a brace list is never empty.
16381 $ @kbd{bash -c 'false; @{ @}; echo $?' || echo $?}
16382 bash: line 1: syntax error near unexpected token `@}'
16383 bash: line 1: `false; @{ @}; echo $?'
16385 $ @kbd{zsh -c 'false; @{ @}; echo $?' || echo $?}
16387 $ @kbd{pdksh -c 'false; @{ @}; echo $?' || echo $?}
16392 @item @command{break}
16393 @c ------------------
16394 @prindex @command{break}
16395 The use of @samp{break 2} etc.@: is safe.
16399 @item @command{case}
16400 @c -----------------
16401 @prindex @command{case}
16402 You don't need to quote the argument; no splitting is performed.
16404 You don't need the final @samp{;;}, but you should use it.
16406 Posix requires support for @code{case} patterns with opening
16407 parentheses like this:
16411 (*.c) echo "C source code";;
16416 but the @code{(} in this example is not portable to many Bourne
16417 shell implementations, which is a pity for those of us using tools that
16418 rely on balanced parentheses. For instance, with Solaris
16422 $ @kbd{case foo in (foo) echo foo;; esac}
16423 @error{}syntax error: `(' unexpected
16427 The leading @samp{(} can be omitted safely. Unfortunately, there are
16428 contexts where unbalanced parentheses cause other problems, such as when
16429 using a syntax-highlighting editor that searches for the balancing
16430 counterpart, or more importantly, when using a case statement as an
16431 underquoted argument to an Autoconf macro. @xref{Balancing
16432 Parentheses}, for tradeoffs involved in various styles of dealing with
16433 unbalanced @samp{)}.
16435 Zsh handles pattern fragments derived from parameter expansions or
16436 command substitutions as though quoted:
16439 $ pat=\?; case aa in ?$pat) echo match;; esac
16440 $ pat=\?; case a? in ?$pat) echo match;; esac
16445 Because of a bug in its @code{fnmatch}, Bash fails to properly
16446 handle backslashes in character classes:
16449 bash-2.02$ @kbd{case /tmp in [/\\]*) echo OK;; esac}
16454 This is extremely unfortunate, since you are likely to use this code to
16455 handle Posix or MS-DOS absolute file names. To work around this
16456 bug, always put the backslash first:
16459 bash-2.02$ @kbd{case '\TMP' in [\\/]*) echo OK;; esac}
16461 bash-2.02$ @kbd{case /tmp in [\\/]*) echo OK;; esac}
16465 Many Bourne shells cannot handle closing brackets in character classes
16468 Some shells also have problems with backslash escaping in case you do not want
16469 to match the backslash: both a backslash and the escaped character match this
16470 pattern. To work around this, specify the character class in a variable, so
16471 that quote removal does not apply afterwards, and the special characters don't
16472 have to be backslash-escaped:
16475 $ @kbd{case '\' in [\<]) echo OK;; esac}
16477 $ @kbd{scanset='[<]'; case '\' in $scanset) echo OK;; esac}
16481 Even with this, Solaris @command{ksh} matches a backslash if the set
16483 of the characters @samp{|}, @samp{&}, @samp{(}, or @samp{)}.
16485 Conversely, Tru64 @command{ksh} (circa 2003) erroneously always matches
16486 a closing parenthesis if not specified in a character class:
16489 $ @kbd{case foo in *\)*) echo fail ;; esac}
16491 $ @kbd{case foo in *')'*) echo fail ;; esac}
16495 Some shells, such as Ash 0.3.8, are confused by an empty
16496 @code{case}/@code{esac}:
16499 ash-0.3.8 $ @kbd{case foo in esac;}
16500 @error{}Syntax error: ";" unexpected (expecting ")")
16503 Posix requires @command{case} to give an exit status of 0 if no cases
16504 match. However, @command{/bin/sh} in Solaris 10 does not obey this
16505 rule. Meanwhile, it is unclear whether a case that matches, but
16506 contains no statements, must also change the exit status to 0. The M4sh
16507 macro @code{AS_CASE} works around these inconsistencies.
16510 $ @kbd{bash -c 'case `false` in ?) ;; esac; echo $?'}
16512 $ @kbd{/bin/sh -c 'case `false` in ?) ;; esac; echo $?'}
16519 @prindex @command{cd}
16520 Posix 1003.1-2001 requires that @command{cd} must support
16521 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
16522 with @option{-L} being the default. However, traditional shells do
16523 not support these options, and their @command{cd} command has the
16524 @option{-P} behavior.
16526 Portable scripts should assume neither option is supported, and should
16527 assume neither behavior is the default. This can be a bit tricky,
16528 since the Posix default behavior means that, for example,
16529 @samp{ls ..} and @samp{cd ..} may refer to different directories if
16530 the current logical directory is a symbolic link. It is safe to use
16531 @code{cd @var{dir}} if @var{dir} contains no @file{..} components.
16532 Also, Autoconf-generated scripts check for this problem when computing
16533 variables like @code{ac_top_srcdir} (@pxref{Configuration Actions}),
16534 so it is safe to @command{cd} to these variables.
16536 See @xref{Special Shell Variables}, for portability problems involving
16537 @command{cd} and the @env{CDPATH} environment variable.
16538 Also please see the discussion of the @command{pwd} command.
16542 @item @command{echo}
16543 @c -----------------
16544 @prindex @command{echo}
16545 The simple @command{echo} is probably the most surprising source of
16546 portability troubles. It is not possible to use @samp{echo} portably
16547 unless both options and escape sequences are omitted. Don't expect any
16550 Do not use backslashes in the arguments, as there is no consensus on
16551 their handling. For @samp{echo '\n' | wc -l}, the @command{sh} of
16552 Solaris outputs 2, but Bash and Zsh (in @command{sh} emulation mode) output 1.
16553 The problem is truly @command{echo}: all the shells
16554 understand @samp{'\n'} as the string composed of a backslash and an
16555 @samp{n}. Within a command substitution, @samp{echo 'string\c'} will
16556 mess up the internal state of ksh88 on AIX 6.1 so that it will print
16557 the first character @samp{s} only, followed by a newline, and then
16558 entirely drop the output of the next echo in a command substitution.
16560 Because of these problems, do not pass a string containing arbitrary
16561 characters to @command{echo}. For example, @samp{echo "$foo"} is safe
16562 only if you know that @var{foo}'s value cannot contain backslashes and
16563 cannot start with @samp{-}.
16565 If this may not be true, @command{printf} is in general safer and
16566 easier to use than @command{echo} and @command{echo -n}. Thus, scripts
16567 where portability is not a major concern should use @command{printf
16568 '%s\n'} whenever @command{echo} could fail, and similarly use
16569 @command{printf %s} instead of @command{echo -n}. For portable shell
16570 scripts, instead, it is suggested to use a here-document like this:
16578 Alternatively, M4sh provides @code{AS_ECHO} and @code{AS_ECHO_N} macros
16579 which choose between various portable implementations: @samp{echo}
16580 or @samp{print} where they work, @command{printf} if it is available,
16581 or else other creative tricks in order to work around the above problems.
16584 @item @command{eval}
16585 @c -----------------
16586 @prindex @command{eval}
16587 The @command{eval} command is useful in limited circumstances, e.g.,
16588 using commands like @samp{eval table_$key=\$value} and @samp{eval
16589 value=table_$key} to simulate a hash table when the key is known to be
16592 You should also be wary of common bugs in @command{eval} implementations.
16593 In some shell implementations (e.g., older @command{ash}, OpenBSD 3.8
16594 @command{sh}, @command{pdksh} v5.2.14 99/07/13.2, and @command{zsh}
16595 4.2.5), the arguments of @samp{eval} are evaluated in a context where
16596 @samp{$?} is 0, so they exhibit behavior like this:
16599 $ @kbd{false; eval 'echo $?'}
16603 The correct behavior here is to output a nonzero value,
16604 but portable scripts should not rely on this.
16606 You should not rely on @code{LINENO} within @command{eval}.
16607 @xref{Special Shell Variables}.
16609 Note that, even though these bugs are easily avoided,
16610 @command{eval} is tricky to use on arbitrary arguments.
16611 It is obviously unwise to use @samp{eval $cmd} if the string value of
16612 @samp{cmd} was derived from an untrustworthy source. But even if the
16613 string value is valid, @samp{eval $cmd} might not work as intended,
16614 since it causes field splitting and file name expansion to occur twice,
16615 once for the @command{eval} and once for the command itself. It is
16616 therefore safer to use @samp{eval "$cmd"}. For example, if @var{cmd}
16617 has the value @samp{cat test?.c}, @samp{eval $cmd} might expand to the
16618 equivalent of @samp{cat test;.c} if there happens to be a file named
16619 @file{test;.c} in the current directory; and this in turn
16620 mistakenly attempts to invoke @command{cat} on the file @file{test} and
16621 then execute the command @command{.c}. To avoid this problem, use
16622 @samp{eval "$cmd"} rather than @samp{eval $cmd}.
16624 However, suppose that you want to output the text of the evaluated
16625 command just before executing it. Assuming the previous example,
16626 @samp{echo "Executing: $cmd"} outputs @samp{Executing: cat test?.c}, but
16627 this output doesn't show the user that @samp{test;.c} is the actual name
16628 of the copied file. Conversely, @samp{eval "echo Executing: $cmd"}
16629 works on this example, but it fails with @samp{cmd='cat foo >bar'},
16630 since it mistakenly replaces the contents of @file{bar} by the
16631 string @samp{cat foo}. No simple, general, and portable solution to
16632 this problem is known.
16634 @item @command{exec}
16635 @c -----------------
16636 @prindex @command{exec}
16637 Posix describes several categories of shell built-ins. Special
16638 built-ins (such as @command{exit}) must impact the environment of the
16639 current shell, and need not be available through @command{exec}. All
16640 other built-ins are regular, and must not propagate variable assignments
16641 to the environment of the current shell. However, the group of regular
16642 built-ins is further distinguished by commands that do not require a
16643 @env{PATH} search (such as @command{cd}), in contrast to built-ins that
16644 are offered as a more efficient version of something that must still be
16645 found in a @env{PATH} search (such as @command{echo}). Posix is not
16646 clear on whether @command{exec} must work with the list of 17 utilities
16647 that are invoked without a @env{PATH} search, and many platforms lack an
16648 executable for some of those built-ins:
16651 $ @kbd{sh -c 'exec cd /tmp'}
16652 sh: line 0: exec: cd: not found
16655 All other built-ins that provide utilities specified by Posix must have
16656 a counterpart executable that exists on @env{PATH}, although Posix
16657 allows @command{exec} to use the built-in instead of the executable.
16658 For example, contrast @command{bash} 3.2 and @command{pdksh} 5.2.14:
16661 $ @kbd{bash -c 'pwd --version' | head -n1}
16662 bash: line 0: pwd: --: invalid option
16663 pwd: usage: pwd [-LP]
16664 $ @kbd{bash -c 'exec pwd --version' | head -n1}
16665 pwd (GNU coreutils) 6.10
16666 $ @kbd{pdksh -c 'exec pwd --version' | head -n1}
16667 pdksh: pwd: --: unknown option
16670 When it is desired to avoid a regular shell built-in, the workaround is
16671 to use some other forwarding command, such as @command{env} or
16672 @command{nice}, that will ensure a path search:
16675 $ @kbd{pdksh -c 'exec true --version' | head -n1}
16676 $ @kbd{pdksh -c 'nice true --version' | head -n1}
16677 true (GNU coreutils) 6.10
16678 $ @kbd{pdksh -c 'env true --version' | head -n1}
16679 true (GNU coreutils) 6.10
16682 @item @command{exit}
16683 @c -----------------
16684 @prindex @command{exit}
16685 The default value of @command{exit} is supposed to be @code{$?};
16686 unfortunately, some shells, such as the DJGPP port of Bash 2.04, just
16687 perform @samp{exit 0}.
16690 bash-2.04$ @kbd{foo=`exit 1` || echo fail}
16692 bash-2.04$ @kbd{foo=`(exit 1)` || echo fail}
16694 bash-2.04$ @kbd{foo=`(exit 1); exit` || echo fail}
16698 Using @samp{exit $?} restores the expected behavior.
16700 Some shell scripts, such as those generated by @command{autoconf}, use a
16701 trap to clean up before exiting. If the last shell command exited with
16702 nonzero status, the trap also exits with nonzero status so that the
16703 invoker can tell that an error occurred.
16705 Unfortunately, in some shells, such as Solaris @command{/bin/sh}, an exit
16706 trap ignores the @code{exit} command's argument. In these shells, a trap
16707 cannot determine whether it was invoked by plain @code{exit} or by
16708 @code{exit 1}. Instead of calling @code{exit} directly, use the
16709 @code{AC_MSG_ERROR} macro that has a workaround for this problem.
16713 @item @command{export}
16714 @c -------------------
16715 @prindex @command{export}
16716 The builtin @command{export} dubs a shell variable @dfn{environment
16717 variable}. Each update of exported variables corresponds to an update
16718 of the environment variables. Conversely, each environment variable
16719 received by the shell when it is launched should be imported as a shell
16720 variable marked as exported.
16722 Alas, many shells, such as Solaris @command{/bin/sh},
16723 IRIX 6.3, IRIX 5.2,
16724 AIX 4.1.5, and Digital Unix 4.0, forget to
16725 @command{export} the environment variables they receive. As a result,
16726 two variables coexist: the environment variable and the shell
16727 variable. The following code demonstrates this failure:
16738 when run with @samp{FOO=foo} in the environment, these shells print
16739 alternately @samp{foo} and @samp{bar}, although they should print only
16740 @samp{foo} and then a sequence of @samp{bar}s.
16742 Therefore you should @command{export} again each environment variable
16743 that you update; the export can occur before or after the assignment.
16745 Posix is not clear on whether the @command{export} of an undefined
16746 variable causes the variable to be defined with the value of an empty
16747 string, or merely marks any future definition of a variable by that name
16748 for export. Various shells behave differently in this regard:
16751 $ @kbd{sh -c 'export foo; env | grep foo'}
16752 $ @kbd{ash -c 'export foo; env | grep foo'}
16756 @item @command{false}
16757 @c ------------------
16758 @prindex @command{false}
16759 Don't expect @command{false} to exit with status 1: in native
16760 Solaris @file{/bin/false} exits with status 255.
16763 @item @command{for}
16764 @c ----------------
16765 @prindex @command{for}
16766 To loop over positional arguments, use:
16776 You may @emph{not} leave the @code{do} on the same line as @code{for},
16777 since some shells improperly grok:
16785 If you want to explicitly refer to the positional arguments, given the
16786 @samp{$@@} bug (@pxref{Shell Substitutions}), use:
16789 for arg in $@{1+"$@@"@}; do
16795 But keep in mind that Zsh, even in Bourne shell emulation mode, performs
16796 word splitting on @samp{$@{1+"$@@"@}}; see @ref{Shell Substitutions},
16797 item @samp{$@@}, for more.
16799 In Solaris @command{/bin/sh}, when the list of arguments of a
16800 @command{for} loop starts with @emph{unquoted} tokens looking like
16801 variable assignments, the loop is not executed on those tokens:
16804 $ @kbd{/bin/sh -c 'for v in a=b c=d x e=f; do echo $v; done'}
16810 Thankfully, quoting the assignment-like tokens, or starting the list
16811 with other tokens (including unquoted variable expansion that results in
16812 an assignment-like result), avoids the problem, so it is easy to work
16816 $ @kbd{/bin/sh -c 'for v in "a=b"; do echo $v; done'}
16818 $ @kbd{/bin/sh -c 'x=a=b; for v in $x c=d; do echo $v; done'}
16826 @prindex @command{if}
16827 Using @samp{!} is not portable. Instead of:
16830 if ! cmp -s file file.new; then
16839 if cmp -s file file.new; then :; else
16845 Or, especially if the @dfn{else} branch is short, you can use @code{||}.
16846 In M4sh, the @code{AS_IF} macro provides an easy way to write these kinds
16850 AS_IF([cmp -s file file.new], [], [mv file.new file])
16853 This is especially useful in other M4 macros, where the @dfn{then} and
16854 @dfn{else} branches might be macro arguments.
16856 Some very old shells did not reset the exit status from an @command{if}
16857 with no @command{else}:
16860 $ @kbd{if (exit 42); then true; fi; echo $?}
16865 whereas a proper shell should have printed @samp{0}. But this is no
16866 longer a portability problem; any shell that supports functions gets it
16867 correct. However, it explains why some makefiles have lengthy
16871 if test -f "$file"; then
16872 install "$file" "$dest"
16879 @item @command{printf}
16880 @c ------------------
16881 @prindex @command{printf}
16882 A format string starting with a @samp{-} can cause problems.
16883 Bash interprets it as an option and
16884 gives an error. And @samp{--} to mark the end of options is not good
16885 in the NetBSD Almquist shell (e.g., 0.4.6) which takes that
16886 literally as the format string. Putting the @samp{-} in a @samp{%c}
16887 or @samp{%s} is probably easiest:
16893 Bash 2.03 mishandles an escape sequence that happens to evaluate to @samp{%}:
16896 $ @kbd{printf '\045'}
16897 bash: printf: `%': missing format character
16900 Large outputs may cause trouble. On Solaris 2.5.1 through 10, for
16901 example, @file{/usr/bin/printf} is buggy, so when using
16902 @command{/bin/sh} the command @samp{printf %010000x 123} normally dumps
16905 Since @command{printf} is not always a shell builtin, there is a
16906 potential speed penalty for using @code{printf '%s\n'} as a replacement
16907 for an @command{echo} that does not interpret @samp{\} or leading
16908 @samp{-}. With Solaris @command{ksh}, it is possible to use @code{print
16909 -r --} for this role instead.
16911 For a discussion of portable alternatives to both @command{printf}
16912 and @command{echo}, @xref{echo, , Limitations of Shell Builtins}.
16915 @item @command{pwd}
16916 @c ----------------
16917 @prindex @command{pwd}
16918 With modern shells, plain @command{pwd} outputs a ``logical''
16919 directory name, some of whose components may be symbolic links. These
16920 directory names are in contrast to ``physical'' directory names, whose
16921 components are all directories.
16923 Posix 1003.1-2001 requires that @command{pwd} must support
16924 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
16925 with @option{-L} being the default. However, traditional shells do
16926 not support these options, and their @command{pwd} command has the
16927 @option{-P} behavior.
16929 Portable scripts should assume neither option is supported, and should
16930 assume neither behavior is the default. Also, on many hosts
16931 @samp{/bin/pwd} is equivalent to @samp{pwd -P}, but Posix
16932 does not require this behavior and portable scripts should not rely on
16935 Typically it's best to use plain @command{pwd}. On modern hosts this
16936 outputs logical directory names, which have the following advantages:
16940 Logical names are what the user specified.
16942 Physical names may not be portable from one installation
16943 host to another due to network file system gymnastics.
16945 On modern hosts @samp{pwd -P} may fail due to lack of permissions to
16946 some parent directory, but plain @command{pwd} cannot fail for this
16950 Also please see the discussion of the @command{cd} command.
16953 @item @command{read}
16954 @c -----------------
16955 @prindex @command{read}
16956 No options are portable, not even support @option{-r} (Solaris
16957 @command{/bin/sh} for example).
16961 @item @command{set}
16962 @c ----------------
16963 @prindex @command{set}
16964 With the FreeBSD 6.0 shell, the @command{set} command (without
16965 any options) does not sort its output.
16967 The @command{set} builtin faces the usual problem with arguments
16969 dash. Modern shells such as Bash or Zsh understand @option{--} to specify
16970 the end of the options (any argument after @option{--} is a parameter,
16971 even @samp{-x} for instance), but many traditional shells (e.g., Solaris
16972 10 @command{/bin/sh}) simply stop option
16973 processing as soon as a non-option argument is found. Therefore, use
16974 @samp{dummy} or simply @samp{x} to end the option processing, and use
16975 @command{shift} to pop it out:
16978 set x $my_list; shift
16981 Avoid @samp{set -}, e.g., @samp{set - $my_list}. Posix no
16982 longer requires support for this command, and in traditional shells
16983 @samp{set - $my_list} resets the @option{-v} and @option{-x} options, which
16984 makes scripts harder to debug.
16986 Some nonstandard shells do not recognize more than one option
16987 (e.g., @samp{set -e -x} assigns @samp{-x} to the command line). It is
16988 better to combine them:
16994 @cindex @command{set -e}
16995 The option @option{-e} has historically been underspecified, with enough
16996 ambiguities to cause numerous differences across various shell
16997 implementations. Perhaps the best reference is
16998 @uref{http://www.opengroup.org/@/austin/@/mailarchives/@/ag-review/@/msg03507.html,
16999 this link}, recommending a change to Posix 2008 to match @command{ksh88}
17000 behavior. Note that mixing @code{set -e} and shell functions is asking
17014 According to the recommendation, @samp{one} should always be output
17015 regardless of whether the @command{rm} failed, because it occurs within
17016 the body of the shell function @samp{doit} invoked on the left side of
17017 @samp{||}, where the effects of @samp{set -e} are not enforced.
17018 Likewise, @samp{two} should never be printed, since the failure of
17019 @command{rm} does not abort the function, such that the status of
17022 The BSD shell has had several problems with the @option{-e}
17023 option. Older versions of the BSD
17024 shell (circa 1990) mishandled @samp{&&}, @samp{||}, @samp{if}, and
17025 @samp{case} when @option{-e} was in effect, causing the shell to exit
17026 unexpectedly in some cases. This was particularly a problem with
17027 makefiles, and led to circumlocutions like @samp{sh -c 'test -f file ||
17028 touch file'}, where the seemingly-unnecessary @samp{sh -c '@dots{}'}
17029 wrapper works around the bug (@pxref{Failure in Make Rules}).
17031 Even relatively-recent versions of the BSD shell (e.g., OpenBSD 3.4)
17032 wrongly exit with @option{-e} if the last command within a compound
17033 statement fails and is guarded by an @samp{&&} only. For example:
17039 test -n "$foo" && exit 1
17042 test -n "$foo" && exit 1
17044 test -n "$foo" && exit 1
17050 does not print @samp{three}. One workaround is to change the last
17051 instance of @samp{test -n "$foo" && exit 1} to be @samp{if test -n
17052 "$foo"; then exit 1; fi} instead. Another possibility is to warn BSD
17053 users not to use @samp{sh -e}.
17055 When @samp{set -e} is in effect, a failed command substitution in
17056 Solaris @command{/bin/sh} cannot be ignored, even with @samp{||}.
17059 $ @kbd{/bin/sh -c 'set -e; foo=`false` || echo foo; echo bar'}
17060 $ @kbd{bash -c 'set -e; foo=`false` || echo foo; echo bar'}
17066 Moreover, a command substitution, successful or not, causes this shell to
17067 exit from a failing outer command even in presence of an @samp{&&} list:
17070 $ @kbd{bash -c 'set -e; false `true` && echo notreached; echo ok'}
17072 $ @kbd{sh -c 'set -e; false `true` && echo notreached; echo ok'}
17076 Portable scripts should not use @samp{set -e} if @command{trap} is used
17077 to install an exit handler. This is because Tru64/OSF 5.1 @command{sh}
17078 sometimes enters the trap handler with the exit status of the command
17079 prior to the one that triggered the errexit handler:
17082 $ @kbd{sh -ec 'trap '\''echo $?'\'' 0; false'}
17084 $ @kbd{sh -c 'set -e; trap '\''echo $?'\'' 0; false'}
17089 Thus, when writing a script in M4sh, rather than trying to rely on
17090 @samp{set -e}, it is better to append @samp{|| AS_EXIT} to any
17091 statement where it is desirable to abort on failure.
17093 @cindex @command{set -b}
17094 @cindex @command{set -m}
17095 Job control is not provided by all shells, so the use of @samp{set -m}
17096 or @samp{set -b} must be done with care. When using @command{zsh} in
17097 native mode, asynchronous notification (@samp{set -b}) is enabled by
17098 default, and using @samp{emulate sh} to switch to Posix mode does not
17099 clear this setting (although asynchronous notification has no impact
17100 unless job monitoring is also enabled). Also, @command{zsh} 4.3.10 and
17101 earlier have a bug where job control can be manipulated in interactive
17102 shells, but not in subshells or scripts. Furthermore, some shells, like
17103 @command{pdksh}, fail to treat subshells as interactive, even though the
17107 $ @kbd{echo $ZSH_VERSION}
17109 $ @kbd{set -m; echo $?}
17111 $ @kbd{zsh -c 'set -m; echo $?'}
17112 set: can't change option: -m
17113 $ @kbd{(set -m); echo $?}
17114 set: can't change option: -m
17116 $ @kbd{pdksh -ci 'echo $-; (echo $-)'}
17122 @item @command{shift}
17123 @c ------------------
17124 @prindex @command{shift}
17125 Not only is @command{shift}ing a bad idea when there is nothing left to
17126 shift, but in addition it is not portable: the shell of MIPS
17127 RISC/OS 4.52 refuses to do it.
17129 Don't use @samp{shift 2} etc.; while it in the SVR1 shell (1983),
17130 it is also absent in many pre-Posix shells.
17133 @item @command{source}
17134 @c -------------------
17135 @prindex @command{source}
17136 This command is not portable, as Posix does not require it; use
17137 @command{.} instead.
17140 @item @command{test}
17141 @c -----------------
17142 @prindex @command{test}
17143 The @code{test} program is the way to perform many file and string
17144 tests. It is often invoked by the alternate name @samp{[}, but using
17145 that name in Autoconf code is asking for trouble since it is an M4 quote
17148 The @option{-a}, @option{-o}, @samp{(}, and @samp{)} operands are not
17149 present in all implementations, and have been marked obsolete by Posix
17150 2008. This is because there are inherent ambiguities in using them.
17151 For example, @samp{test "$1" -a "$2"} looks like a binary operator to
17152 check whether two strings are both non-empty, but if @samp{$1} is the
17153 literal @samp{!}, then some implementations of @command{test} treat it
17154 as a negation of the unary operator @option{-a}.
17156 Thus, portable uses of @command{test} should never have more than four
17157 arguments, and scripts should use shell constructs like @samp{&&} and
17158 @samp{||} instead. If you combine @samp{&&} and @samp{||} in the same
17159 statement, keep in mind that they have equal precedence, so it is often
17160 better to parenthesize even when this is redundant. For example:
17164 test "X$a" = "X$b" -a \
17165 '(' "X$c" != "X$d" -o "X$e" = "X$f" ')'
17168 test "X$a" = "X$b" &&
17169 @{ test "X$c" != "X$d" || test "X$e" = "X$f"; @}
17172 @command{test} does not process options like most other commands do; for
17173 example, it does not recognize the @option{--} argument as marking the
17176 It is safe to use @samp{!} as a @command{test} operator. For example,
17177 @samp{if test ! -d foo; @dots{}} is portable even though @samp{if ! test
17178 -d foo; @dots{}} is not.
17181 @item @command{test} (files)
17182 @c -------------------------
17183 To enable @command{configure} scripts to support cross-compilation, they
17184 shouldn't do anything that tests features of the build system instead of
17185 the host system. But occasionally you may find it necessary to check
17186 whether some arbitrary file exists. To do so, use @samp{test -f} or
17187 @samp{test -r}. Do not use @samp{test -x}, because 4.3BSD does not
17188 have it. Do not use @samp{test -e} either, because Solaris @command{/bin/sh}
17189 lacks it. To test for symbolic links on systems that have them, use
17190 @samp{test -h} rather than @samp{test -L}; either form conforms to
17191 Posix 1003.1-2001, but older shells like Solaris 8
17192 @code{/bin/sh} support only @option{-h}.
17194 @item @command{test} (strings)
17195 @c ---------------------------
17196 Posix says that @samp{test "@var{string}"} succeeds if @var{string} is
17197 not null, but this usage is not portable to traditional platforms like
17198 Solaris 10 @command{/bin/sh}, which mishandle strings like @samp{!} and
17201 Posix also says that @samp{test ! "@var{string}"},
17202 @samp{test -n "@var{string}"} and
17203 @samp{test -z "@var{string}"} work with any string, but many
17204 shells (such as Solaris, AIX 3.2, UNICOS 10.0.0.6,
17205 Digital Unix 4, etc.)@: get confused if
17206 @var{string} looks like an operator:
17210 test: argument expected
17212 test: argument expected
17215 Similarly, Posix says that both @samp{test "@var{string1}" = "@var{string2"}}
17216 and @samp{test "@var{string1}" != "@var{string2"}} work for any pairs of
17217 strings, but in practice this is not true for troublesome strings that
17218 look like operators or parentheses, or that begin with @samp{-}.
17220 It is best to protect such strings with a leading @samp{X}, e.g.,
17221 @samp{test "X@var{string}" != X} rather than @samp{test -n
17222 "@var{string}"} or @samp{test ! "@var{string}"}.
17224 It is common to find variations of the following idiom:
17227 test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" &&
17232 to take an action when a token matches a given pattern. Such constructs
17233 should be avoided by using:
17236 case $ac_feature in
17237 *[!-a-zA-Z0-9_]*) @var{action};;
17241 If the pattern is a complicated regular expression that cannot be
17242 expressed as a shell pattern, use something like this instead:
17245 expr "X$ac_feature" : 'X.*[^-a-zA-Z0-9_]' >/dev/null &&
17249 @samp{expr "X@var{foo}" : "X@var{bar}"} is more robust than @samp{echo
17250 "X@var{foo}" | grep "^X@var{bar}"}, because it avoids problems when
17251 @samp{@var{foo}} contains backslashes.
17255 @item @command{trap}
17256 @c -----------------
17257 @prindex @command{trap}
17258 It is safe to trap at least the signals 1, 2, 13, and 15. You can also
17259 trap 0, i.e., have the @command{trap} run when the script ends (either via an
17260 explicit @command{exit}, or the end of the script). The trap for 0 should be
17261 installed outside of a shell function, or AIX 5.3 @command{/bin/sh}
17262 will invoke the trap at the end of this function.
17264 Posix says that @samp{trap - 1 2 13 15} resets the traps for the
17265 specified signals to their default values, but many common shells (e.g.,
17266 Solaris @command{/bin/sh}) misinterpret this and attempt to execute a
17267 ``command'' named @command{-} when the specified conditions arise.
17268 Posix 2008 also added a requirement to support @samp{trap 1 2 13 15} to
17269 reset traps, as this is supported by a larger set of shells, but there
17270 are still shells like @command{dash} that mistakenly try to execute
17271 @command{1} instead of resetting the traps. Therefore, there is no
17272 portable workaround, except for @samp{trap - 0}, for which
17273 @samp{trap '' 0} is a portable substitute.
17275 Although Posix is not absolutely clear on this point, it is widely
17276 admitted that when entering the trap @samp{$?} should be set to the exit
17277 status of the last command run before the trap. The ambiguity can be
17278 summarized as: ``when the trap is launched by an @command{exit}, what is
17279 the @emph{last} command run: that before @command{exit}, or
17280 @command{exit} itself?''
17282 Bash considers @command{exit} to be the last command, while Zsh and
17283 Solaris @command{/bin/sh} consider that when the trap is run it is
17284 @emph{still} in the @command{exit}, hence it is the previous exit status
17285 that the trap receives:
17288 $ @kbd{cat trap.sh}
17291 $ @kbd{zsh trap.sh}
17293 $ @kbd{bash trap.sh}
17297 The portable solution is then simple: when you want to @samp{exit 42},
17298 run @samp{(exit 42); exit 42}, the first @command{exit} being used to
17299 set the exit status to 42 for Zsh, and the second to trigger the trap
17300 and pass 42 as exit status for Bash. In M4sh, this is covered by using
17303 The shell in FreeBSD 4.0 has the following bug: @samp{$?} is
17304 reset to 0 by empty lines if the code is inside @command{trap}.
17307 $ @kbd{trap 'false}
17315 Fortunately, this bug only affects @command{trap}.
17317 Several shells fail to execute an exit trap that is defined inside a
17318 subshell, when the last command of that subshell is not a builtin. A
17319 workaround is to use @samp{exit $?} as the shell builtin.
17322 $ @kbd{bash -c '(trap "echo hi" 0; /bin/true)'}
17324 $ @kbd{/bin/sh -c '(trap "echo hi" 0; /bin/true)'}
17325 $ @kbd{/bin/sh -c '(trap "echo hi" 0; /bin/true; exit $?)'}
17330 Likewise, older implementations of @command{bash} failed to preserve
17331 @samp{$?} across an exit trap consisting of a single cleanup command.
17334 $ @kbd{bash -c 'trap "/bin/true" 0; exit 2'; echo $?}
17336 $ @kbd{bash-2.05b -c 'trap "/bin/true" 0; exit 2'; echo $?}
17338 $ @kbd{bash-2.05b -c 'trap ":; /bin/true" 0; exit 2'; echo $?}
17342 @item @command{true}
17343 @c -----------------
17344 @prindex @command{true}
17345 @c Info cannot handle `:' in index entries.
17346 @c @prindex @command{:}
17347 Don't worry: as far as we know @command{true} is portable.
17348 Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the
17349 portable shell community tends to prefer using @command{:}. This has a
17350 funny side effect: when asked whether @command{false} is more portable
17351 than @command{true} Alexandre Oliva answered:
17354 In a sense, yes, because if it doesn't exist, the shell will produce an
17355 exit status of failure, which is correct for @command{false}, but not
17356 for @command{true}.
17361 @item @command{unset}
17362 @c ------------------
17363 @prindex @command{unset}
17364 In some nonconforming shells (e.g., Bash 2.05a), @code{unset FOO} fails
17365 when @code{FOO} is not set. You can use
17371 if you are not sure that @code{FOO} is set.
17373 A few ancient shells lack @command{unset} entirely. For some variables
17374 such as @code{PS1}, you can use a neutralizing value instead:
17380 Usually, shells that do not support @command{unset} need less effort to
17381 make the environment sane, so for example is not a problem if you cannot
17382 unset @command{CDPATH} on those shells. However, Bash 2.01 mishandles
17383 @code{unset MAIL} in some cases and dumps core. So, you should do
17387 ( (unset MAIL) || exit 1) >/dev/null 2>&1 && unset MAIL || :
17391 @xref{Special Shell Variables}, for some neutralizing values. Also, see
17392 @ref{export, , Limitations of Builtins}, for
17393 the case of environment variables.
17395 @item @command{wait}
17396 @c -----------------
17397 @prindex @command{wait}
17398 The exit status of @command{wait} is not always reliable.
17401 @node Limitations of Usual Tools
17402 @section Limitations of Usual Tools
17403 @cindex Limitations of usual tools
17405 The small set of tools you can expect to find on any machine can still
17406 include some limitations you should be aware of.
17408 @comment Between this list and the list of builtins above, we should
17409 @comment mention all the tools in GNU Coding Standards ``Utilities in
17410 @comment Makefiles''.
17412 @c This table includes things like `@command{expr} (|)', so we can't
17413 @c use @table @command.
17415 @item @command{awk}
17416 @c ----------------
17417 @prindex @command{awk}
17418 Don't leave white space before the opening parenthesis in a user function call.
17419 Posix does not allow this and GNU Awk rejects it:
17422 $ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
17423 BEGIN @{ die () @}'}
17424 gawk: cmd. line:2: BEGIN @{ die () @}
17425 gawk: cmd. line:2: ^ parse error
17426 $ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
17427 BEGIN @{ die() @}'}
17431 Posix says that if a program contains only @samp{BEGIN} actions, and
17432 contains no instances of @code{getline}, then the program merely
17433 executes the actions without reading input. However, traditional Awk
17434 implementations (such as Solaris 10 @command{awk}) read and discard
17435 input in this case. Portable scripts can redirect input from
17436 @file{/dev/null} to work around the problem. For example:
17439 awk 'BEGIN @{print "hello world"@}' </dev/null
17442 Posix says that in an @samp{END} action, @samp{$NF} (and presumably,
17443 @samp{$1}) retain their value from the last record read, if no
17444 intervening @samp{getline} occurred. However, some implementations
17445 (such as Solaris 10 @samp{/usr/bin/awk}, @samp{nawk}, or Darwin
17446 @samp{awk}) reset these variables. A workaround is to use an
17447 intermediate variable prior to the @samp{END} block. For example:
17450 $ @kbd{cat end.awk}
17452 END @{ print "a", $1, $NF, "b", tmp @}
17453 $ @kbd{echo 1 | awk -f end.awk}
17455 $ @kbd{echo 1 | gawk -f end.awk}
17459 If you want your program to be deterministic, don't depend on @code{for}
17463 $ @kbd{cat for.awk}
17470 $ @kbd{gawk -f for.awk </dev/null}
17473 $ @kbd{nawk -f for.awk </dev/null}
17478 Some Awk implementations, such as HP-UX 11.0's native one,
17482 $ @kbd{echo xfoo | $AWK '/foo|^bar/ @{ print @}'}
17483 $ @kbd{echo bar | $AWK '/foo|^bar/ @{ print @}'}
17485 $ @kbd{echo xfoo | $AWK '/^bar|foo/ @{ print @}'}
17487 $ @kbd{echo bar | $AWK '/^bar|foo/ @{ print @}'}
17492 Either do not depend on such patterns (i.e., use @samp{/^(.*foo|bar)/},
17493 or use a simple test to reject such implementations.
17495 On @samp{ia64-hp-hpux11.23}, Awk mishandles @code{printf} conversions
17499 $ @kbd{awk 'BEGIN @{ printf "%u %d\n", 0, -1 @}'}
17503 AIX version 5.2 has an arbitrary limit of 399 on the
17504 length of regular expressions and literal strings in an Awk program.
17506 Traditional Awk implementations derived from Unix version 7, such as
17507 Solaris @command{/bin/awk}, have many limitations and do not
17508 conform to Posix. Nowadays @code{AC_PROG_AWK} (@pxref{Particular
17509 Programs}) finds you an Awk that doesn't have these problems, but if
17510 for some reason you prefer not to use @code{AC_PROG_AWK} you may need to
17513 Traditional Awk does not support multidimensional arrays or user-defined
17516 Traditional Awk does not support the @option{-v} option. You can use
17517 assignments after the program instead, e.g., @code{$AWK '@{print v
17518 $1@}' v=x}; however, don't forget that such assignments are not
17519 evaluated until they are encountered (e.g., after any @code{BEGIN}
17522 Traditional Awk does not support the keywords @code{delete} or @code{do}.
17524 Traditional Awk does not support the expressions
17525 @code{@var{a}?@var{b}:@var{c}}, @code{!@var{a}}, @code{@var{a}^@var{b}},
17526 or @code{@var{a}^=@var{b}}.
17528 Traditional Awk does not support the predefined @code{CONVFMT} variable.
17530 Traditional Awk supports only the predefined functions @code{exp}, @code{index},
17531 @code{int}, @code{length}, @code{log}, @code{split}, @code{sprintf},
17532 @code{sqrt}, and @code{substr}.
17534 Traditional Awk @code{getline} is not at all compatible with Posix;
17537 Traditional Awk has @code{for (i in a) @dots{}} but no other uses of the
17538 @code{in} keyword. For example, it lacks @code{if (i in a) @dots{}}.
17540 In code portable to both traditional and modern Awk, @code{FS} must be a
17541 string containing just one ordinary character, and similarly for the
17542 field-separator argument to @code{split}.
17544 Traditional Awk has a limit of 99 fields in a record. Since some Awk
17545 implementations, like Tru64's, split the input even if you don't refer
17546 to any field in the script, to circumvent this problem, set @samp{FS}
17547 to an unusual character and use @code{split}.
17549 Traditional Awk has a limit of at most 99 bytes in a number formatted by
17550 @code{OFMT}; for example, @code{OFMT="%.300e"; print 0.1;} typically
17553 The original version of Awk had a limit of at most 99 bytes per
17554 @code{split} field, 99 bytes per @code{substr} substring, and 99 bytes
17555 per run of non-special characters in a @code{printf} format, but these
17556 bugs have been fixed on all practical hosts that we know of.
17558 HP-UX 11.00 and IRIX 6.5 Awk require that input files have a line length
17559 of at most 3070 bytes.
17561 @item @command{basename}
17562 @c ---------------------
17563 @prindex @command{basename}
17564 Not all hosts have a working @command{basename}.
17565 You can use @command{expr} instead.
17567 @c AS_BASENAME is to be replaced by a better API.
17569 Not all hosts have a working @command{basename}, and you should instead
17570 use @code{AS_BASENAME} (@pxref{Programming in M4sh}), followed by
17571 @command{expr} if you need to strip a suffix. For example:
17574 a=`basename "$aname"` # This is not portable.
17575 a=`AS_BASENAME(["$aname"])` # This is more portable.
17577 # This is not portable.
17578 c=`basename "$cname" .c`
17580 # This is more portable.
17581 c=`AS_BASENAME(["$cname"])`
17583 ?*.c) c=`expr "X$c" : 'X\(.*\)\.c'`;;
17589 @item @command{cat}
17590 @c ----------------
17591 @prindex @command{cat}
17592 Don't rely on any option.
17597 @prindex @command{cc}
17598 The command @samp{cc -c foo.c} traditionally produces an object file
17599 named @file{foo.o}. Most compilers allow @option{-c} to be combined
17600 with @option{-o} to specify a different object file name, but
17601 Posix does not require this combination and a few compilers
17602 lack support for it. @xref{C Compiler}, for how GNU Make
17603 tests for this feature with @code{AC_PROG_CC_C_O}.
17605 When a compilation such as @samp{cc -o foo foo.c} fails, some compilers
17606 (such as CDS on Reliant Unix) leave a @file{foo.o}.
17608 HP-UX @command{cc} doesn't accept @file{.S} files to preprocess and
17609 assemble. @samp{cc -c foo.S} appears to succeed, but in fact does
17612 The default executable, produced by @samp{cc foo.c}, can be
17615 @item @file{a.out} --- usual Posix convention.
17616 @item @file{b.out} --- i960 compilers (including @command{gcc}).
17617 @item @file{a.exe} --- DJGPP port of @command{gcc}.
17618 @item @file{a_out.exe} --- GNV @command{cc} wrapper for DEC C on OpenVMS.
17619 @item @file{foo.exe} --- various MS-DOS compilers.
17622 The C compiler's traditional name is @command{cc}, but other names like
17623 @command{gcc} are common. Posix 1003.1-2001 specifies the
17624 name @command{c99}, but older Posix editions specified
17625 @command{c89} and anyway these standard names are rarely used in
17626 practice. Typically the C compiler is invoked from makefiles that use
17627 @samp{$(CC)}, so the value of the @samp{CC} make variable selects the
17630 @item @command{chgrp}
17631 @itemx @command{chown}
17632 @c -------------------
17633 @prindex @command{chgrp}
17634 @prindex @command{chown}
17635 It is not portable to change a file's group to a group that the owner
17636 does not belong to.
17638 @item @command{chmod}
17639 @c ------------------
17640 @prindex @command{chmod}
17641 Avoid usages like @samp{chmod -w file}; use @samp{chmod a-w file}
17642 instead, for two reasons. First, plain @option{-w} does not necessarily
17643 make the file unwritable, since it does not affect mode bits that
17644 correspond to bits in the file mode creation mask. Second,
17645 Posix says that the @option{-w} might be interpreted as an
17646 implementation-specific option, not as a mode; Posix suggests
17647 using @samp{chmod -- -w file} to avoid this confusion, but unfortunately
17648 @samp{--} does not work on some older hosts.
17651 @item @command{cmp}
17652 @c ----------------
17653 @prindex @command{cmp}
17654 @command{cmp} performs a raw data comparison of two files, while
17655 @command{diff} compares two text files. Therefore, if you might compare
17656 DOS files, even if only checking whether two files are different, use
17657 @command{diff} to avoid spurious differences due to differences of
17663 @prindex @command{cp}
17664 Avoid the @option{-r} option, since Posix 1003.1-2004 marks it as
17665 obsolescent and its behavior on special files is implementation-defined.
17666 Use @option{-R} instead. On GNU hosts the two options
17667 are equivalent, but on Solaris hosts (for example) @code{cp -r}
17668 reads from pipes instead of replicating them.
17670 Some @command{cp} implementations (e.g., BSD/OS 4.2) do not allow
17671 trailing slashes at the end of nonexistent destination directories. To
17672 avoid this problem, omit the trailing slashes. For example, use
17673 @samp{cp -R source /tmp/newdir} rather than @samp{cp -R source
17674 /tmp/newdir/} if @file{/tmp/newdir} does not exist.
17676 @c This is thanks to Ian.
17677 The ancient SunOS 4 @command{cp} does not support @option{-f}, although
17678 its @command{mv} does.
17680 @cindex timestamp resolution
17681 Traditionally, file timestamps had 1-second resolution, and @samp{cp
17682 -p} copied the timestamps exactly. However, many modern file systems
17683 have timestamps with 1-nanosecond resolution. Unfortunately, @samp{cp
17684 -p} implementations truncate timestamps when copying files, so this
17685 can result in the destination file appearing to be older than the
17686 source. The exact amount of truncation depends on the resolution of
17687 the system calls that @command{cp} uses; traditionally this was
17688 @code{utime}, which has 1-second resolution, but some newer
17689 @command{cp} implementations use @code{utimes}, which has
17690 1-microsecond resolution. These newer implementations include GNU
17691 Core Utilities 5.0.91 or later, and Solaris 8 (sparc) patch 109933-02 or
17692 later. Unfortunately as of January 2006 there is still no system
17693 call to set timestamps to the full nanosecond resolution.
17695 Bob Proulx notes that @samp{cp -p} always @emph{tries} to copy
17696 ownerships. But whether it actually does copy ownerships or not is a
17697 system dependent policy decision implemented by the kernel. If the
17698 kernel allows it then it happens. If the kernel does not allow it then
17699 it does not happen. It is not something @command{cp} itself has control
17702 In Unix System V any user can chown files to any other user, and System
17703 V also has a non-sticky @file{/tmp}. That probably derives from the
17704 heritage of System V in a business environment without hostile users.
17706 to be a more secure model where only root can @command{chown} files and
17707 a sticky @file{/tmp} is used. That undoubtedly derives from the heritage
17708 of BSD in a campus environment.
17710 GNU/Linux and Solaris by default follow BSD, but
17711 can be configured to allow a System V style @command{chown}. On the
17712 other hand, HP-UX follows System V, but can
17713 be configured to use the modern security model and disallow
17714 @command{chown}. Since it is an administrator-configurable parameter
17715 you can't use the name of the kernel as an indicator of the behavior.
17719 @item @command{date}
17720 @c -----------------
17721 @prindex @command{date}
17722 Some versions of @command{date} do not recognize special @samp{%} directives,
17723 and unfortunately, instead of complaining, they just pass them through,
17724 and exit with success:
17728 OSF1 medusa.sis.pasteur.fr V5.1 732 alpha
17734 @item @command{diff}
17735 @c -----------------
17736 @prindex @command{diff}
17737 Option @option{-u} is nonportable.
17739 Some implementations, such as Tru64's, fail when comparing to
17740 @file{/dev/null}. Use an empty file instead.
17743 @item @command{dirname}
17744 @c --------------------
17745 @prindex @command{dirname}
17746 Not all hosts have a working @command{dirname}, and you should instead
17747 use @code{AS_DIRNAME} (@pxref{Programming in M4sh}). For example:
17750 dir=`dirname "$file"` # This is not portable.
17751 dir=`AS_DIRNAME(["$file"])` # This is more portable.
17755 @item @command{egrep}
17756 @c ------------------
17757 @prindex @command{egrep}
17758 Posix 1003.1-2001 no longer requires @command{egrep},
17759 but many hosts do not yet support the Posix
17760 replacement @code{grep -E}. Also, some traditional implementations do
17761 not work on long input lines. To work around these problems, invoke
17762 @code{AC_PROG_EGREP} and then use @code{$EGREP}.
17764 Portable extended regular expressions should use @samp{\} only to escape
17765 characters in the string @samp{$()*+.?[\^@{|}. For example, @samp{\@}}
17766 is not portable, even though it typically matches @samp{@}}.
17768 The empty alternative is not portable. Use @samp{?} instead. For
17769 instance with Digital Unix v5.0:
17772 > printf "foo\n|foo\n" | $EGREP '^(|foo|bar)$'
17774 > printf "bar\nbar|\n" | $EGREP '^(foo|bar|)$'
17776 > printf "foo\nfoo|\n|bar\nbar\n" | $EGREP '^(foo||bar)$'
17781 @command{$EGREP} also suffers the limitations of @command{grep}
17782 (@pxref{grep, , Limitations of Usual Tools}).
17784 @item @command{expr}
17785 @c -----------------
17786 @prindex @command{expr}
17787 Not all implementations obey the Posix rule that @samp{--} separates
17788 options from arguments; likewise, not all implementations provide the
17789 extension to Posix that the first argument can be treated as part of a
17790 valid expression rather than an invalid option if it begins with
17791 @samp{-}. When performing arithmetic, use @samp{expr 0 + $var} if
17792 @samp{$var} might be a negative number, to keep @command{expr} from
17793 interpreting it as an option.
17795 No @command{expr} keyword starts with @samp{X}, so use @samp{expr
17796 X"@var{word}" : 'X@var{regex}'} to keep @command{expr} from
17797 misinterpreting @var{word}.
17799 Don't use @code{length}, @code{substr}, @code{match} and @code{index}.
17801 @item @command{expr} (@samp{|})
17802 @prindex @command{expr} (@samp{|})
17803 You can use @samp{|}. Although Posix does require that @samp{expr
17804 ''} return the empty string, it does not specify the result when you
17805 @samp{|} together the empty string (or zero) with the empty string. For
17812 Posix 1003.2-1992 returns the empty string
17813 for this case, but traditional Unix returns @samp{0} (Solaris is
17814 one such example). In Posix 1003.1-2001, the specification was
17815 changed to match traditional Unix's behavior (which is
17816 bizarre, but it's too late to fix this). Please note that the same
17817 problem does arise when the empty string results from a computation,
17821 expr bar : foo \| foo : bar
17825 Avoid this portability problem by avoiding the empty string.
17828 @item @command{expr} (@samp{:})
17829 @c ----------------------------
17830 @prindex @command{expr}
17831 Portable @command{expr} regular expressions should use @samp{\} to
17832 escape only characters in the string @samp{$()*.0123456789[\^n@{@}}.
17833 For example, alternation, @samp{\|}, is common but Posix does not
17834 require its support, so it should be avoided in portable scripts.
17835 Similarly, @samp{\+} and @samp{\?} should be avoided.
17837 Portable @command{expr} regular expressions should not begin with
17838 @samp{^}. Patterns are automatically anchored so leading @samp{^} is
17841 On the other hand, the behavior of the @samp{$} anchor is not portable
17842 on multi-line strings. Posix is ambiguous whether the anchor applies to
17843 each line, as was done in older versions of GNU Coreutils, or
17844 whether it applies only to the end of the overall string, as in
17845 Coreutils 6.0 and most other implementations.
17850 $ @kbd{expr "X$baz" : 'X\(foo\)$'}
17852 $ @kbd{expr-5.97 "X$baz" : 'X\(foo\)$'}
17856 The Posix standard is ambiguous as to whether
17857 @samp{expr 'a' : '\(b\)'} outputs @samp{0} or the empty string.
17858 In practice, it outputs the empty string on most platforms, but portable
17859 scripts should not assume this. For instance, the QNX 4.25 native
17860 @command{expr} returns @samp{0}.
17862 One might think that a way to get a uniform behavior would be to use
17863 the empty string as a default value:
17866 expr a : '\(b\)' \| ''
17870 Unfortunately this behaves exactly as the original expression; see the
17871 @command{expr} (@samp{|}) entry for more information.
17873 Some ancient @command{expr} implementations (e.g., SunOS 4 @command{expr} and
17874 Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes
17875 @command{expr} to fail if the matched substring is longer than 120
17876 bytes. In this case, you might want to fall back on @samp{echo|sed} if
17877 @command{expr} fails. Nowadays this is of practical importance only for
17878 the rare installer who mistakenly puts @file{/usr/ucb} before
17879 @file{/usr/bin} in @env{PATH}.
17881 On Mac OS X 10.4, @command{expr} mishandles the pattern @samp{[^-]} in
17882 some cases. For example, the command
17884 expr Xpowerpc-apple-darwin8.1.0 : 'X[^-]*-[^-]*-\(.*\)'
17888 outputs @samp{apple-darwin8.1.0} rather than the correct @samp{darwin8.1.0}.
17889 This particular case can be worked around by substituting @samp{[^--]}
17892 Don't leave, there is some more!
17894 The QNX 4.25 @command{expr}, in addition of preferring @samp{0} to
17895 the empty string, has a funny behavior in its exit status: it's always 1
17896 when parentheses are used!
17899 $ @kbd{val=`expr 'a' : 'a'`; echo "$?: $val"}
17901 $ @kbd{val=`expr 'a' : 'b'`; echo "$?: $val"}
17904 $ @kbd{val=`expr 'a' : '\(a\)'`; echo "?: $val"}
17906 $ @kbd{val=`expr 'a' : '\(b\)'`; echo "?: $val"}
17911 In practice this can be a big problem if you are ready to catch failures
17912 of @command{expr} programs with some other method (such as using
17913 @command{sed}), since you may get twice the result. For instance
17916 $ @kbd{expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'}
17920 outputs @samp{a} on most hosts, but @samp{aa} on QNX 4.25. A
17921 simple workaround consists of testing @command{expr} and using a variable
17922 set to @command{expr} or to @command{false} according to the result.
17924 Tru64 @command{expr} incorrectly treats the result as a number, if it
17925 can be interpreted that way:
17928 $ @kbd{expr 00001 : '.*\(...\)'}
17932 On HP-UX 11, @command{expr} only supports a single
17936 $ @kbd{expr 'Xfoo' : 'X\(f\(oo\)*\)$'}
17937 expr: More than one '\(' was used.
17941 @item @command{fgrep}
17942 @c ------------------
17943 @prindex @command{fgrep}
17944 Posix 1003.1-2001 no longer requires @command{fgrep},
17945 but many hosts do not yet support the Posix
17946 replacement @code{grep -F}. Also, some traditional implementations do
17947 not work on long input lines. To work around these problems, invoke
17948 @code{AC_PROG_FGREP} and then use @code{$FGREP}.
17950 Tru64/OSF 5.1 @command{fgrep} does not match an empty pattern.
17953 @item @command{find}
17954 @c -----------------
17955 @prindex @command{find}
17956 The option @option{-maxdepth} seems to be GNU specific.
17957 Tru64 v5.1, NetBSD 1.5 and Solaris @command{find}
17958 commands do not understand it.
17960 The replacement of @samp{@{@}} is guaranteed only if the argument is
17961 exactly @emph{@{@}}, not if it's only a part of an argument. For
17962 instance on DU, and HP-UX 10.20 and HP-UX 11:
17966 $ @kbd{find . -name foo -exec echo "@{@}-@{@}" \;}
17971 while GNU @command{find} reports @samp{./foo-./foo}.
17975 @item @command{grep}
17976 @c -----------------
17977 @prindex @command{grep}
17978 Portable scripts can rely on the @command{grep} options @option{-c},
17979 @option{-l}, @option{-n}, and @option{-v}, but should avoid other
17980 options. For example, don't use @option{-w}, as Posix does not require
17981 it and Irix 6.5.16m's @command{grep} does not support it. Also,
17982 portable scripts should not combine @option{-c} with @option{-l},
17983 as Posix does not allow this.
17985 Some of the options required by Posix are not portable in practice.
17986 Don't use @samp{grep -q} to suppress output, because many @command{grep}
17987 implementations (e.g., Solaris) do not support @option{-q}.
17988 Don't use @samp{grep -s} to suppress output either, because Posix
17989 says @option{-s} does not suppress output, only some error messages;
17990 also, the @option{-s} option of traditional @command{grep} behaved
17991 like @option{-q} does in most modern implementations. Instead,
17992 redirect the standard output and standard error (in case the file
17993 doesn't exist) of @code{grep} to @file{/dev/null}. Check the exit
17994 status of @code{grep} to determine whether it found a match.
17996 The QNX4 implementation fails to count lines with @code{grep -c '$'},
17997 but works with @code{grep -c '^'}. Other alternatives for counting
17998 lines are to use @code{sed -n '$='} or @code{wc -l}.
18000 Some traditional @command{grep} implementations do not work on long
18001 input lines. On AIX the default @code{grep} silently truncates long
18002 lines on the input before matching.
18004 Also, many implementations do not support multiple regexps
18005 with @option{-e}: they either reject @option{-e} entirely (e.g., Solaris)
18006 or honor only the last pattern (e.g., IRIX 6.5 and NeXT). To
18007 work around these problems, invoke @code{AC_PROG_GREP} and then use
18010 Another possible workaround for the multiple @option{-e} problem is to
18011 separate the patterns by newlines, for example:
18019 except that this fails with traditional @command{grep}
18020 implementations and with OpenBSD 3.8 @command{grep}.
18022 Traditional @command{grep} implementations (e.g., Solaris) do not
18023 support the @option{-E} or @option{-F} options. To work around these
18024 problems, invoke @code{AC_PROG_EGREP} and then use @code{$EGREP}, and
18025 similarly for @code{AC_PROG_FGREP} and @code{$FGREP}. Even if you are
18026 willing to require support for Posix @command{grep}, your script should
18027 not use both @option{-E} and @option{-F}, since Posix does not allow
18030 Portable @command{grep} regular expressions should use @samp{\} only to
18031 escape characters in the string @samp{$()*.0123456789[\^@{@}}. For example,
18032 alternation, @samp{\|}, is common but Posix does not require its
18033 support in basic regular expressions, so it should be avoided in
18034 portable scripts. Solaris and HP-UX @command{grep} do not support it.
18035 Similarly, the following escape sequences should also be avoided:
18036 @samp{\<}, @samp{\>}, @samp{\+}, @samp{\?}, @samp{\`}, @samp{\'},
18037 @samp{\B}, @samp{\b}, @samp{\S}, @samp{\s}, @samp{\W}, and @samp{\w}.
18039 Posix does not specify the behavior of @command{grep} on binary files.
18040 An example where this matters is using BSD @command{grep} to
18041 search text that includes embedded ANSI escape sequences for
18042 colored output to terminals (@samp{\033[m} is the sequence to restore
18043 normal output); the behavior depends on whether input is seekable:
18046 $ @kbd{printf 'esc\033[mape\n' > sample}
18047 $ @kbd{grep . sample}
18048 Binary file sample matches
18049 $ @kbd{cat sample | grep .}
18054 @item @command{join}
18055 @c -----------------
18056 @prindex @command{join}
18057 Solaris 8 @command{join} has bugs when the second operand is standard
18058 input, and when standard input is a pipe. For example, the following
18059 shell script causes Solaris 8 @command{join} to loop forever:
18066 cat file | join file -
18069 Use @samp{join - file} instead.
18074 @prindex @command{ln}
18075 @cindex Symbolic links
18076 Don't rely on @command{ln} having a @option{-f} option. Symbolic links
18077 are not available on old systems; use @samp{$(LN_S)} as a portable substitute.
18079 For versions of the DJGPP before 2.04,
18080 @command{ln} emulates symbolic links
18081 to executables by generating a stub that in turn calls the real
18082 program. This feature also works with nonexistent files like in the
18083 Posix spec. So @samp{ln -s file link} generates @file{link.exe},
18084 which attempts to call @file{file.exe} if run. But this feature only
18085 works for executables, so @samp{cp -p} is used instead for these
18086 systems. DJGPP versions 2.04 and later have full support
18087 for symbolic links.
18092 @prindex @command{ls}
18093 @cindex Listing directories
18094 The portable options are @option{-acdilrtu}. Current practice is for
18095 @option{-l} to output both owner and group, even though ancient versions
18096 of @command{ls} omitted the group.
18098 On ancient hosts, @samp{ls foo} sent the diagnostic @samp{foo not found}
18099 to standard output if @file{foo} did not exist. Hence a shell command
18100 like @samp{sources=`ls *.c 2>/dev/null`} did not always work, since it
18101 was equivalent to @samp{sources='*.c not found'} in the absence of
18102 @samp{.c} files. This is no longer a practical problem, since current
18103 @command{ls} implementations send diagnostics to standard error.
18105 The behavior of @command{ls} on a directory that is being concurrently
18106 modified is not always predictable, because of a data race where cached
18107 information returned by @code{readdir} does not match the current
18108 directory state. In fact, MacOS 10.5 has an intermittent bug where
18109 @code{readdir}, and thus @command{ls}, sometimes lists a file more than
18110 once if other files were added or removed from the directory immediately
18111 prior to the @command{ls} call. Since @command{ls} already sorts its
18112 output, the duplicate entries can be avoided by piping the results
18113 through @code{uniq}.
18116 @item @command{mkdir}
18117 @c ------------------
18118 @prindex @command{mkdir}
18119 @cindex Making directories
18120 No @command{mkdir} option is portable to older systems. Instead of
18121 @samp{mkdir -p @var{file-name}}, you should use
18122 @code{AS_MKDIR_P(@var{file-name})} (@pxref{Programming in M4sh})
18123 or @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs}).
18125 Combining the @option{-m} and @option{-p} options, as in @samp{mkdir -m
18126 go-w -p @var{dir}}, often leads to trouble. FreeBSD
18127 @command{mkdir} incorrectly attempts to change the permissions of
18128 @var{dir} even if it already exists. HP-UX 11.23 and
18129 IRIX 6.5 @command{mkdir} often assign the wrong permissions to
18130 any newly-created parents of @var{dir}.
18132 Posix does not clearly specify whether @samp{mkdir -p foo}
18133 should succeed when @file{foo} is a symbolic link to an already-existing
18134 directory. The GNU Core Utilities 5.1.0 @command{mkdir}
18135 succeeds, but Solaris @command{mkdir} fails.
18137 Traditional @code{mkdir -p} implementations suffer from race conditions.
18138 For example, if you invoke @code{mkdir -p a/b} and @code{mkdir -p a/c}
18139 at the same time, both processes might detect that @file{a} is missing,
18140 one might create @file{a}, then the other might try to create @file{a}
18141 and fail with a @code{File exists} diagnostic. The GNU Core
18142 Utilities (@samp{fileutils} version 4.1), FreeBSD 5.0,
18143 NetBSD 2.0.2, and OpenBSD 2.4 are known to be
18144 race-free when two processes invoke @code{mkdir -p} simultaneously, but
18145 earlier versions are vulnerable. Solaris @command{mkdir} is still
18146 vulnerable as of Solaris 10, and other traditional Unix systems are
18147 probably vulnerable too. This possible race is harmful in parallel
18148 builds when several Make rules call @code{mkdir -p} to
18149 construct directories. You may use
18150 @code{install-sh -d} as a safe replacement, provided this script is
18151 recent enough; the copy shipped with Autoconf 2.60 and Automake 1.10 is
18152 OK, but copies from older versions are vulnerable.
18155 @item @command{mkfifo}
18156 @itemx @command{mknod}
18157 @c -------------------
18158 @prindex @command{mkfifo}
18159 @prindex @command{mknod}
18160 The GNU Coding Standards state that @command{mknod} is safe to use on
18161 platforms where it has been tested to exist; but it is generally portable
18162 only for creating named FIFOs, since device numbers are
18163 platform-specific. Autotest uses @command{mkfifo} to implement parallel
18164 testsuites. Posix states that behavior is unspecified when opening a
18165 named FIFO for both reading and writing; on at least Cygwin, this
18166 results in failure on any attempt to read or write to that file
18169 @item @command{mktemp}
18170 @c -------------------
18171 @prindex @command{mktemp}
18172 @cindex Creating temporary files
18173 Shell scripts can use temporary files safely with @command{mktemp}, but
18174 it does not exist on all systems. A portable way to create a safe
18175 temporary file name is to create a temporary directory with mode 700 and
18176 use a file inside this directory. Both methods prevent attackers from
18177 gaining control, though @command{mktemp} is far less likely to fail
18178 gratuitously under attack.
18180 Here is sample code to create a new temporary directory safely:
18183 # Create a temporary directory $tmp in $TMPDIR (default /tmp).
18184 # Use mktemp if possible; otherwise fall back on mkdir,
18185 # with $RANDOM to make collisions less likely.
18189 (umask 077 && mktemp -d "$TMPDIR/fooXXXXXX") 2>/dev/null
18191 test -n "$tmp" && test -d "$tmp"
18193 tmp=$TMPDIR/foo$$-$RANDOM
18194 @c $$ restore font-lock
18195 (umask 077 && mkdir "$tmp")
18202 @prindex @command{mv}
18203 @cindex Moving open files
18204 The only portable options are @option{-f} and @option{-i}.
18206 Moving individual files between file systems is portable (it was in Unix
18208 but it is not always atomic: when doing @samp{mv new existing}, there's
18209 a critical section where neither the old nor the new version of
18210 @file{existing} actually exists.
18212 On some systems moving files from @file{/tmp} can sometimes cause
18213 undesirable (but perfectly valid) warnings, even if you created these
18214 files. This is because @file{/tmp} belongs to a group that ordinary
18215 users are not members of, and files created in @file{/tmp} inherit
18216 the group of @file{/tmp}. When the file is copied, @command{mv} issues
18217 a diagnostic without failing:
18220 $ @kbd{touch /tmp/foo}
18221 $ @kbd{mv /tmp/foo .}
18222 @error{}mv: ./foo: set owner/group (was: 100/0): Operation not permitted
18230 This annoying behavior conforms to Posix, unfortunately.
18232 Moving directories across mount points is not portable, use @command{cp}
18235 DOS variants cannot rename or remove open files, and do not
18236 support commands like @samp{mv foo bar >foo}, even though this is
18237 perfectly portable among Posix hosts.
18242 @prindex @command{od}
18244 In Mac OS X 10.3, @command{od} does not support the
18245 standard Posix options @option{-A}, @option{-j}, @option{-N}, or
18246 @option{-t}, or the XSI option @option{-s}. The only
18247 supported Posix option is @option{-v}, and the only supported
18248 XSI options are those in @option{-bcdox}. The BSD
18249 @command{hexdump} program can be used instead.
18251 This problem no longer exists in Mac OS X 10.4.3.
18256 @prindex @command{rm}
18257 The @option{-f} and @option{-r} options are portable.
18259 It is not portable to invoke @command{rm} without operands. For
18260 example, on many systems @samp{rm -f -r} (with no other arguments)
18261 silently succeeds without doing anything, but it fails with a diagnostic
18264 A file might not be removed even if its parent directory is writable
18265 and searchable. Many Posix hosts cannot remove a mount point, a named
18266 stream, a working directory, or a last link to a file that is being
18269 DOS variants cannot rename or remove open files, and do not
18270 support commands like @samp{rm foo >foo}, even though this is
18271 perfectly portable among Posix hosts.
18273 @item @command{rmdir}
18274 @c ------------------
18275 @prindex @command{rmdir}
18276 Just as with @command{rm}, some platforms refuse to remove a working
18280 @item @command{sed}
18281 @c ----------------
18282 @prindex @command{sed}
18283 Patterns should not include the separator (unless escaped), even as part
18284 of a character class. In conformance with Posix, the Cray
18285 @command{sed} rejects @samp{s/[^/]*$//}: use @samp{s%[^/]*$%%}.
18286 Even when escaped, patterns should not include separators that are also
18287 used as @command{sed} metacharacters. For example, GNU sed 4.0.9 rejects
18288 @samp{s,x\@{1\,\@},,}, while sed 4.1 strips the backslash before the comma
18289 before evaluating the basic regular expression.
18291 Avoid empty patterns within parentheses (i.e., @samp{\(\)}). Posix does
18292 not require support for empty patterns, and Unicos 9 @command{sed} rejects
18295 Unicos 9 @command{sed} loops endlessly on patterns like @samp{.*\n.*}.
18297 Sed scripts should not use branch labels longer than 7 characters and
18298 should not contain comments. HP-UX sed has a limit of 99 commands
18299 (not counting @samp{:} commands) and
18300 48 labels, which can not be circumvented by using more than one script
18301 file. It can execute up to 19 reads with the @samp{r} command per cycle.
18302 Solaris @command{/usr/ucb/sed} rejects usages that exceed a limit of
18303 about 6000 bytes for the internal representation of commands.
18305 Avoid redundant @samp{;}, as some @command{sed} implementations, such as
18306 NetBSD 1.4.2's, incorrectly try to interpret the second
18307 @samp{;} as a command:
18310 $ @kbd{echo a | sed 's/x/x/;;s/x/x/'}
18311 sed: 1: "s/x/x/;;s/x/x/": invalid command code ;
18314 Input should not have unreasonably long lines, since some @command{sed}
18315 implementations have an input buffer limited to 4000 bytes. Likewise,
18316 not all @command{sed} implementations can handle embedded @code{NUL} or
18317 a missing trailing newline.
18319 Portable @command{sed} regular expressions should use @samp{\} only to escape
18320 characters in the string @samp{$()*.0123456789[\^n@{@}}. For example,
18321 alternation, @samp{\|}, is common but Posix does not require its
18322 support, so it should be avoided in portable scripts. Solaris
18323 @command{sed} does not support alternation; e.g., @samp{sed '/a\|b/d'}
18324 deletes only lines that contain the literal string @samp{a|b}.
18325 Similarly, @samp{\+} and @samp{\?} should be avoided.
18327 Anchors (@samp{^} and @samp{$}) inside groups are not portable.
18329 Nested parentheses in patterns (e.g., @samp{\(\(a*\)b*)\)}) are
18330 quite portable to current hosts, but was not supported by some ancient
18331 @command{sed} implementations like SVR3.
18333 Some @command{sed} implementations, e.g., Solaris, restrict the special
18334 role of the asterisk @samp{*} to one-character regular expressions and
18335 back-references, and the special role of interval expressions
18336 @samp{\@{@var{m}\@}}, @samp{\@{@var{m},\@}}, or @samp{\@{@var{m},@var{n}\@}}
18337 to one-character regular expressions. This may lead to unexpected behavior:
18340 $ @kbd{echo '1*23*4' | /usr/bin/sed 's/\(.\)*/x/g'}
18342 $ @kbd{echo '1*23*4' | /usr/xpg4/bin/sed 's/\(.\)*/x/g'}
18346 The @option{-e} option is mostly portable.
18347 However, its argument
18348 cannot start with @samp{a}, @samp{c}, or @samp{i},
18349 as this runs afoul of a Tru64 5.1 bug.
18350 Also, its argument cannot be empty, as this fails on AIX 5.3.
18351 Some people prefer to use @samp{-e}:
18354 sed -e '@var{command-1}' \
18355 -e '@var{command-2}'
18359 as opposed to the equivalent:
18369 The following usage is sometimes equivalent:
18372 sed '@var{command-1};@var{command-2}'
18375 but Posix says that this use of a semicolon has undefined effect if
18376 @var{command-1}'s verb is @samp{@{}, @samp{a}, @samp{b}, @samp{c},
18377 @samp{i}, @samp{r}, @samp{t}, @samp{w}, @samp{:}, or @samp{#}, so you
18378 should use semicolon only with simple scripts that do not use these
18381 Posix up to the 2008 revision requires the argument of the @option{-e}
18382 option to be a syntactically complete script. GNU @command{sed} allows
18383 to pass multiple script fragments, each as argument of a separate
18384 @option{-e} option, that are then combined, with newlines between the
18385 fragments, and a future Posix revision may allow this as well. This
18386 approach is not portable with script fragments ending in backslash; for
18387 example, the @command{sed} programs on Solaris 10, HP-UX 11, and AIX
18388 don't allow splitting in this case:
18391 $ @kbd{echo a | sed -n -e 'i\}
18394 $ @kbd{echo a | sed -n -e 'i\' -e 0}
18395 Unrecognized command: 0
18399 In practice, however, this technique of joining fragments
18400 through @option{-e} works for multiple @command{sed} functions within
18401 @samp{@{} and @samp{@}}, even if that is not specified by Posix:
18404 @c The quote around the closing brace silences interactive zsh.
18405 $ @kbd{echo a | sed -n -e '/a/@{' -e s/a/b/ -e p -e '@}'}
18409 Commands inside @{ @} brackets are further restricted. Posix 2008 says that
18410 they cannot be preceded by addresses, @samp{!}, or @samp{;}, and that
18411 each command must be followed immediately by a newline, without any
18412 intervening blanks or semicolons. The closing bracket must be alone on
18413 a line, other than white space preceding or following it. However, a
18414 future version of Posix may standardize the use of addresses within brackets.
18416 Contrary to yet another urban legend, you may portably use @samp{&} in
18417 the replacement part of the @code{s} command to mean ``what was
18418 matched''. All descendants of Unix version 7 @command{sed}
18420 don't have first hand experience with older @command{sed} implementations) have
18423 Posix requires that you must not have any white space between
18424 @samp{!} and the following command. It is OK to have blanks between
18425 the address and the @samp{!}. For instance, on Solaris:
18428 $ @kbd{echo "foo" | sed -n '/bar/ ! p'}
18429 @error{}Unrecognized command: /bar/ ! p
18430 $ @kbd{echo "foo" | sed -n '/bar/! p'}
18431 @error{}Unrecognized command: /bar/! p
18432 $ @kbd{echo "foo" | sed -n '/bar/ !p'}
18436 Posix also says that you should not combine @samp{!} and @samp{;}. If
18437 you use @samp{!}, it is best to put it on a command that is delimited by
18438 newlines rather than @samp{;}.
18440 Also note that Posix requires that the @samp{b}, @samp{t}, @samp{r}, and
18441 @samp{w} commands be followed by exactly one space before their argument.
18442 On the other hand, no white space is allowed between @samp{:} and the
18443 subsequent label name.
18445 If a sed script is specified on the command line and ends in an
18446 @samp{a}, @samp{c}, or @samp{i} command, the last line of inserted text
18447 should be followed by a newline. Otherwise some @command{sed}
18448 implementations (e.g., OpenBSD 3.9) do not append a newline to the
18451 Many @command{sed} implementations (e.g., MacOS X 10.4,
18452 OpenBSD 3.9, Solaris 10
18453 @command{/usr/ucb/sed}) strip leading white space from the text of
18454 @samp{a}, @samp{c}, and @samp{i} commands. Prepend a backslash to
18455 work around this incompatibility with Posix:
18458 $ @kbd{echo flushleft | sed 'a\}
18463 $ @kbd{echo foo | sed 'a\}
18470 Posix requires that with an empty regular expression, the last non-empty
18471 regular expression from either an address specification or substitution
18472 command is applied. However, busybox 1.6.1 complains when using a
18473 substitution command with a replacement containing a back-reference to
18474 an empty regular expression; the workaround is repeating the regular
18478 $ @kbd{echo abc | busybox sed '/a\(b\)c/ s//\1/'}
18479 sed: No previous regexp.
18480 $ @kbd{echo abc | busybox sed '/a\(b\)c/ s/a\(b\)c/\1/'}
18485 @item @command{sed} (@samp{t})
18486 @c ---------------------------
18487 @prindex @command{sed} (@samp{t})
18488 Some old systems have @command{sed} that ``forget'' to reset their
18489 @samp{t} flag when starting a new cycle. For instance on MIPS
18490 RISC/OS, and on IRIX 5.3, if you run the following @command{sed}
18491 script (the line numbers are not actual part of the texts):
18494 s/keep me/kept/g # a
18530 Why? When processing line 1, (c) matches, therefore sets the @samp{t}
18531 flag, and the output is produced. When processing
18532 line 2, the @samp{t} flag is still set (this is the bug). Command (a)
18533 fails to match, but @command{sed} is not supposed to clear the @samp{t}
18534 flag when a substitution fails. Command (b) sees that the flag is set,
18535 therefore it clears it, and jumps to (d), hence you get @samp{delete me}
18536 instead of @samp{deleted}. When processing line (3), @samp{t} is clear,
18537 (a) matches, so the flag is set, hence (b) clears the flags and jumps.
18538 Finally, since the flag is clear, line 4 is processed properly.
18540 There are two things one should remember about @samp{t} in @command{sed}.
18541 Firstly, always remember that @samp{t} jumps if @emph{some} substitution
18542 succeeded, not only the immediately preceding substitution. Therefore,
18543 always use a fake @samp{t clear} followed by a @samp{:clear} on the next
18544 line, to reset the @samp{t} flag where needed.
18546 Secondly, you cannot rely on @command{sed} to clear the flag at each new
18549 One portable implementation of the script above is:
18560 @item @command{sleep}
18561 @c ------------------
18562 @prindex @command{sleep}
18563 Using @command{sleep} is generally portable. However, remember that
18564 adding a @command{sleep} to work around timestamp issues, with a minimum
18565 granularity of one second, doesn't scale well for parallel builds on
18566 modern machines with sub-second process completion.
18568 @item @command{sort}
18569 @c -----------------
18570 @prindex @command{sort}
18571 Remember that sort order is influenced by the current locale. Inside
18572 @file{configure}, the C locale is in effect, but in Makefile snippets,
18573 you may need to specify @code{LC_ALL=C sort}.
18575 @item @command{tar}
18576 @c ----------------
18577 @prindex @command{tar}
18578 There are multiple file formats for @command{tar}; if you use Automake,
18579 the macro @code{AM_INIT_AUTOMAKE} has some options controlling which
18580 level of portability to use.
18583 @item @command{touch}
18584 @c ------------------
18585 @prindex @command{touch}
18586 @cindex timestamp resolution
18587 If you specify the desired timestamp (e.g., with the @option{-r}
18588 option), @command{touch} typically uses the @code{utime} or
18589 @code{utimes} system call, which can result in the same kind of
18590 timestamp truncation problems that @samp{cp -p} has.
18592 On ancient BSD systems, @command{touch} or any command that
18593 results in an empty file does not update the timestamps, so use a
18594 command like @command{echo} as a workaround.
18596 GNU @command{touch} 3.16r (and presumably all before that)
18597 fails to work on SunOS 4.1.3 when the empty file is on an
18598 NFS-mounted 4.2 volume.
18599 However, these problems are no longer of practical concern.
18603 @prindex @command{tr}
18604 @cindex carriage return, deleting
18605 @cindex newline, deleting
18606 @cindex deleting carriage return
18607 Not all versions of @command{tr} handle all backslash character escapes.
18608 For example, Solaris 10 @command{/usr/ucb/tr} falls over, even though
18609 Solaris contains more modern @command{tr} in other locations.
18610 Using octal escapes is more portable for carriage returns, since
18611 @samp{\015} is the same for both ASCII and EBCDIC, and since use of
18612 literal carriage returns in scripts causes a number of other problems.
18613 But for other characters, like newline, using octal escapes ties the
18614 operation to ASCII, so it is better to use literal characters.
18617 $ @kbd{@{ echo moon; echo light; @} | /usr/ucb/tr -d '\n' ; echo}
18620 $ @kbd{@{ echo moon; echo light; @} | /usr/bin/tr -d '\n' ; echo}
18622 $ @kbd{@{ echo moon; echo light; @} | /usr/ucb/tr -d '\012' ; echo}
18625 @kbd{'; @{ echo moon; echo light; @} | /usr/ucb/tr -d "$nl" ; echo}
18629 Not all versions of @command{tr} recognize ranges of characters: at
18630 least Solaris @command{/usr/bin/tr} still fails to do so. But you can
18631 use @command{/usr/xpg4/bin/tr} instead.
18634 $ @kbd{echo "Hazy Fantazy" | LC_ALL=C /usr/bin/tr a-z A-Z}
18636 $ @kbd{echo "Hazy Fantazy" | LC_ALL=C /usr/xpg4/bin/tr a-z A-Z}
18640 When providing two arguments, be sure the second string is at least as
18644 $ @kbd{echo abc | /usr/xpg4/bin/tr bc d}
18646 $ @kbd{echo abc | coreutils/tr bc d}
18650 Posix requires @command{tr} to operate on binary files. But at least
18651 Solaris @command{/usr/ucb/tr} and @command{/usr/bin/tr} silently discard
18652 @code{NUL} in the input prior to doing any translation. When using
18653 @command{tr} to process a binary file that may contain @code{NUL} bytes,
18654 it is necessary to use @command{/usr/xpg4/bin/tr} instead, or
18655 @command{/usr/xpg6/bin/tr} if that is available.
18658 $ @kbd{printf 'a\0b' | /usr/ucb/tr x x | od -An -tx1}
18660 $ @kbd{printf 'a\0b' | /usr/bin/tr x x | od -An -tx1}
18662 $ @kbd{printf 'a\0b' | /usr/xpg4/bin/tr x x | od -An -tx1}
18666 Solaris @command{/usr/ucb/tr} additionally fails to handle @samp{\0} as the
18667 octal escape for @code{NUL}.
18670 $ @kbd{printf 'abc' | /usr/ucb/tr 'bc' '\0d' | od -An -tx1}
18672 $ @kbd{printf 'abc' | /usr/bin/tr 'bc' '\0d' | od -An -tx1}
18674 $ @kbd{printf 'abc' | /usr/xpg4/bin/tr 'bc' '\0d' | od -An -tx1}
18681 @node Portable Make
18682 @chapter Portable Make Programming
18683 @prindex @command{make}
18684 @cindex Limitations of @command{make}
18686 Writing portable makefiles is an art. Since a makefile's commands are
18687 executed by the shell, you must consider the shell portability issues
18688 already mentioned. However, other issues are specific to @command{make}
18692 * $< in Ordinary Make Rules:: $< in ordinary rules
18693 * Failure in Make Rules:: Failing portably in rules
18694 * Special Chars in Names:: Special Characters in Macro Names
18695 * Backslash-Newline-Newline:: Empty last lines in macro definitions
18696 * Backslash-Newline Comments:: Spanning comments across line boundaries
18697 * Long Lines in Makefiles:: Line length limitations
18698 * Macros and Submakes:: @code{make macro=value} and submakes
18699 * The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues
18700 * The Make Macro SHELL:: @code{$(SHELL)} portability issues
18701 * Parallel Make:: Parallel @command{make} quirks
18702 * Comments in Make Rules:: Other problems with Make comments
18703 * Newlines in Make Rules:: Using literal newlines in rules
18704 * obj/ and Make:: Don't name a subdirectory @file{obj}
18705 * make -k Status:: Exit status of @samp{make -k}
18706 * VPATH and Make:: @code{VPATH} woes
18707 * Single Suffix Rules:: Single suffix rules and separated dependencies
18708 * Timestamps and Make:: Subsecond timestamp resolution
18711 @node $< in Ordinary Make Rules
18712 @section @code{$<} in Ordinary Make Rules
18714 Posix says that the @samp{$<} construct in makefiles can be
18715 used only in inference rules and in the @samp{.DEFAULT} rule; its
18716 meaning in ordinary rules is unspecified. Solaris @command{make}
18717 for instance replaces it with the empty string. OpenBSD (3.0 and
18718 later) @command{make} diagnoses these uses and errors out.
18720 @node Failure in Make Rules
18721 @section Failure in Make Rules
18723 Posix 2008 requires that @command{make} must invoke each command with
18724 the equivalent of a @samp{sh -e -c} subshell, which causes the
18725 subshell to exit immediately if a subsidiary simple-command fails,
18726 although not all @command{make} implementations have historically
18727 followed this rule. For
18728 example, the command @samp{touch T; rm -f U} may attempt to
18729 remove @file{U} even if the @command{touch} fails, although this is not
18730 permitted with Posix make. One way to work around failures in simple
18731 commands is to reword them so that they always succeed, e.g., @samp{touch
18733 However, even this approach can run into common bugs in BSD
18734 implementations of the @option{-e} option of @command{sh} and
18735 @command{set} (@pxref{set, , Limitations of Shell Builtins}), so if you
18737 about porting to buggy BSD shells it may be simpler to migrate
18738 complicated @command{make} actions into separate scripts.
18740 @node Special Chars in Names
18741 @section Special Characters in Make Macro Names
18743 Posix limits macro names to nonempty strings containing only
18744 ASCII letters and digits, @samp{.}, and @samp{_}. Many
18745 @command{make} implementations allow a wider variety of characters, but
18746 portable makefiles should avoid them. It is portable to start a name
18747 with a special character, e.g., @samp{$(.FOO)}.
18749 Some ancient @command{make} implementations don't support leading
18750 underscores in macro names. An example is NEWS-OS 4.2R.
18753 $ @kbd{cat Makefile}
18756 all:; @@echo this is test
18758 Make: Must be a separator on rules line 2. Stop.
18759 $ @kbd{cat Makefile2}
18762 all:; @@echo this is test
18763 $ @kbd{make -f Makefile2}
18768 However, this problem is no longer of practical concern.
18770 @node Backslash-Newline-Newline
18771 @section Backslash-Newline-Newline in Make Macro Values
18773 @c This has been seen on ia64 hpux 11.20, and on one hppa hpux 10.20,
18774 @c but another hppa hpux 10.20 didn't have it. Bob Proulx
18775 @c <bob@proulx.com> thinks it was in hpux 8.0 too.
18776 On some versions of HP-UX, @command{make} reads multiple newlines
18777 following a backslash, continuing to the next non-empty line. For
18791 shows @code{FOO} equal to @code{one BAR = two}. Other implementations
18792 sensibly let a backslash continue only to the immediately following
18795 @node Backslash-Newline Comments
18796 @section Backslash-Newline in Make Comments
18798 According to Posix, Make comments start with @code{#}
18799 and continue until an unescaped newline is reached.
18802 $ @kbd{cat Makefile}
18809 $ @kbd{make} # GNU make
18814 However this is not always the case. Some implementations
18815 discard everything from @code{#} through the end of the line, ignoring any
18816 trailing backslash.
18819 $ @kbd{pmake} # BSD make
18820 "Makefile", line 3: Need an operator
18821 Fatal errors encountered -- cannot continue
18825 Therefore, if you want to comment out a multi-line definition, prefix each
18826 line with @code{#}, not only the first.
18834 @node Long Lines in Makefiles
18835 @section Long Lines in Makefiles
18837 Tru64 5.1's @command{make} has been reported to crash when given a
18838 makefile with lines longer than around 20 kB. Earlier versions are
18839 reported to exit with @code{Line too long} diagnostics.
18841 @node Macros and Submakes
18842 @section @code{make macro=value} and Submakes
18844 A command-line variable definition such as @code{foo=bar} overrides any
18845 definition of @code{foo} in a makefile. Some @command{make}
18846 implementations (such as GNU @command{make}) propagate this
18847 override to subsidiary invocations of @command{make}. Some other
18848 implementations do not pass the substitution along to submakes.
18851 $ @kbd{cat Makefile}
18858 $ @kbd{make foo=bar} # GNU make 3.79.1
18861 make[1]: Entering directory `/home/adl'
18863 make[1]: Leaving directory `/home/adl'
18864 $ @kbd{pmake foo=bar} # BSD make
18870 You have a few possibilities if you do want the @code{foo=bar} override
18871 to propagate to submakes. One is to use the @option{-e}
18872 option, which causes all environment variables to have precedence over
18873 the makefile macro definitions, and declare foo as an environment
18877 $ @kbd{env foo=bar make -e}
18880 The @option{-e} option is propagated to submakes automatically,
18881 and since the environment is inherited between @command{make}
18882 invocations, the @code{foo} macro is overridden in
18883 submakes as expected.
18885 This syntax (@code{foo=bar make -e}) is portable only when used
18886 outside of a makefile, for instance from a script or from the
18887 command line. When run inside a @command{make} rule, GNU
18888 @command{make} 3.80 and prior versions forget to propagate the
18889 @option{-e} option to submakes.
18891 Moreover, using @option{-e} could have unexpected side effects if your
18892 environment contains some other macros usually defined by the
18893 makefile. (See also the note about @code{make -e} and @code{SHELL}
18896 If you can foresee all macros that a user might want to override, then
18897 you can propagate them to submakes manually, from your makefile:
18903 $(MAKE) foo=$(foo) two
18908 Another way to propagate a variable to submakes in a portable way is to
18909 expand an extra variable in every invocation of @samp{$(MAKE)} within
18916 $(MAKE) $(SUBMAKEFLAGS) two
18921 Users must be aware that this technique is in use to take advantage of
18922 it, e.g.@: with @code{make foo=bar SUBMAKEFLAGS='foo=bar'}, but it
18923 allows any macro to be overridden. Makefiles generated by
18924 @command{automake} use this technique, expanding @code{$(AM_MAKEFLAGS)}
18925 on the command lines of submakes (@pxref{Subdirectories, , Automake,
18926 automake, GNU Automake}).
18928 @node The Make Macro MAKEFLAGS
18929 @section The Make Macro MAKEFLAGS
18930 @cindex @code{MAKEFLAGS} and @command{make}
18931 @cindex @command{make} and @code{MAKEFLAGS}
18933 Posix requires @command{make} to use @code{MAKEFLAGS} to affect the
18934 current and recursive invocations of make, but allows implementations
18935 several formats for the variable. It is tricky to parse
18936 @code{$MAKEFLAGS} to determine whether @option{-s} for silent execution
18937 or @option{-k} for continued execution are in effect. For example, you
18938 cannot assume that the first space-separated word in @code{$MAKEFLAGS}
18939 contains single-letter options, since in the Cygwin version of
18940 GNU @command{make} it is either @option{--unix} or
18941 @option{--win32} with the second word containing single-letter options.
18944 $ @kbd{cat Makefile}
18946 @@echo MAKEFLAGS = $(MAKEFLAGS)
18950 MAKEFLAGS = --unix -k
18953 @node The Make Macro SHELL
18954 @section The Make Macro @code{SHELL}
18955 @cindex @code{SHELL} and @command{make}
18956 @cindex @command{make} and @code{SHELL}
18958 Posix-compliant @command{make} internally uses the @code{$(SHELL)}
18959 macro to spawn shell processes and execute Make rules. This
18960 is a builtin macro supplied by @command{make}, but it can be modified
18961 by a makefile or by a command-line argument.
18963 Not all @command{make} implementations define this @code{SHELL} macro.
18965 @command{make} is an example; this implementation always uses
18966 @code{/bin/sh}. So it's a good idea to always define @code{SHELL} in
18967 your makefiles. If you use Autoconf, do
18974 If you use Automake, this is done for you.
18976 Do not force @code{SHELL = /bin/sh} because that is not correct
18977 everywhere. Remember, @file{/bin/sh} is not Posix compliant on many
18978 systems, such as FreeBSD 4, NetBSD 3, AIX 3, Solaris 10, or Tru64.
18979 Additionally, DJGPP lacks @code{/bin/sh}, and when its
18980 GNU @command{make} port sees such a setting it enters a
18981 special emulation mode where features like pipes and redirections are
18982 emulated on top of DOS's @command{command.com}. Unfortunately this
18983 emulation is incomplete; for instance it does not handle command
18984 substitutions. Using @code{@@SHELL@@} means that your makefile will
18985 benefit from the same improved shell, such as @command{bash} or
18986 @command{ksh}, that was discovered during @command{configure}, so that
18987 you aren't fighting two different sets of shell bugs between the two
18990 Posix-compliant @command{make} should never acquire the value of
18991 $(SHELL) from the environment, even when @code{make -e} is used
18992 (otherwise, think about what would happen to your rules if
18993 @code{SHELL=/bin/tcsh}).
18995 However not all @command{make} implementations have this exception.
18996 For instance it's not surprising that Tru64 @command{make} doesn't
18997 protect @code{SHELL}, since it doesn't use it.
19000 $ @kbd{cat Makefile}
19006 $ @kbd{env SHELL=/bin/tcsh FOO=bar make -e} # Tru64 Make
19009 $ @kbd{env SHELL=/bin/tcsh FOO=bar gmake -e} # GNU make
19014 Conversely, @command{make} is not supposed to export any changes to the
19015 macro @code{SHELL} to child processes. Again, many implementations
19019 $ @kbd{cat Makefile}
19023 $ @kbd{env SHELL=sh make -e SHELL=/bin/ksh} # BSD Make, GNU make 3.80
19026 $ @kbd{env SHELL=sh gmake -e SHELL=/bin/ksh} # GNU make 3.81
19031 @node Parallel Make
19032 @section Parallel Make
19033 @cindex Parallel @command{make}
19035 Support for parallel execution in @command{make} implementation varies.
19036 Generally, using GNU make is your best bet. When NetBSD
19037 @command{make} is invoked with @option{-j@var{N}}, it will reuse the
19038 same shell for multiple commands within one recipe. This can have
19039 unexpected consequences.@footnote{Note that GNU make has
19040 heuristics to avoid spawning a shell at all if the command is deemed
19041 safe to be executed directly.} For example, change of directories or
19042 variables persist between commands:
19046 @@var=value; cd /; pwd; echo $$var; echo $$$$
19047 @@pwd; echo $$var; echo $$$$
19051 may output the following with @code{make -j1}:
19063 while without @option{-j1}, or with @option{-B}, the output looks less
19075 Another consequence of this is that, if one command in a recipe uses
19076 @code{exit 0} to indicate a successful exit, the shell will be gone
19077 and the remaining commands of this recipe will not be executed.
19079 The above example also shows additional status output NetBSD
19080 @command{make} produces in parallel mode for targets being updated.
19082 Furthermore, parallel NetBSD @command{make} will route standard error
19083 from commands that it spawns into its own standard output, and may
19084 remove leading whitespace from output lines.
19086 You can avoid these issues by using the @option{-B} option to enable
19087 compatibility semantics. However, that will effectively also disable
19088 all parallelism as that will cause prerequisites to be updated in the
19089 order they are listed in a rule.
19091 @node Comments in Make Rules
19092 @section Comments in Make Rules
19093 @cindex Comments in @file{Makefile} rules
19094 @cindex @file{Makefile} rules and comments
19096 Never put comments in a rule.
19098 Some @command{make} treat anything starting with a tab as a command for
19099 the current rule, even if the tab is immediately followed by a @code{#}.
19100 The @command{make} from Tru64 Unix V5.1 is one of them. The following
19101 makefile runs @code{# foo} through the shell.
19108 As a workaround, you can use the @command{:} no-op command with a string
19109 argument that gets ignored:
19116 @node Newlines in Make Rules
19117 @section Newlines in Make Rules
19118 @cindex Newlines in @file{Makefile} rules
19119 @cindex @file{Makefile} rules and newlines
19121 In shell scripts, newlines can be used inside string literals. But in
19122 the shell statements of @file{Makefile} rules, this is not possible:
19123 A newline not preceded by a backslash is a separator between shell
19124 statements. Whereas a newline that is preceded by a backslash becomes
19125 part of the shell statement according to POSIX, but gets replaced,
19126 together with the backslash that precedes it, by a space in GNU
19127 @command{make} 3.80 and older. So, how can a newline be used in a string
19130 The trick is to set up a shell variable that contains a newline:
19133 nlinit=`echo 'nl="'; echo '"'`; eval "$$nlinit"
19136 For example, in order to create a multiline @samp{sed} expression that
19137 inserts a blank line after every line of a file, this code can be used:
19140 nlinit=`echo 'nl="'; echo '"'`; eval "$$nlinit"; \
19141 sed -e "s/\$$/\\$$@{nl@}/" < input > output
19144 @node obj/ and Make
19145 @section The @file{obj/} Subdirectory and Make
19146 @cindex @file{obj/}, subdirectory
19147 @cindex BSD @command{make} and @file{obj/}
19149 Never name one of your subdirectories @file{obj/} if you don't like
19152 If an @file{obj/} directory exists, BSD @command{make} enters it
19153 before reading the makefile. Hence the makefile in the
19154 current directory is not read.
19157 $ @kbd{cat Makefile}
19160 $ @kbd{cat obj/Makefile}
19163 $ @kbd{make} # GNU make
19166 $ @kbd{pmake} # BSD make
19171 @node make -k Status
19172 @section Exit Status of @code{make -k}
19173 @cindex @code{make -k}
19175 Do not rely on the exit status of @code{make -k}. Some implementations
19176 reflect whether they encountered an error in their exit status; other
19177 implementations always succeed.
19180 $ @kbd{cat Makefile}
19183 $ @kbd{make -k; echo exit status: $?} # GNU make
19185 make: *** [all] Error 1
19187 $ @kbd{pmake -k; echo exit status: $?} # BSD make
19189 *** Error code 1 (continuing)
19193 @node VPATH and Make
19194 @section @code{VPATH} and Make
19195 @cindex @code{VPATH}
19197 Posix does not specify the semantics of @code{VPATH}. Typically,
19198 @command{make} supports @code{VPATH}, but its implementation is not
19201 Autoconf and Automake support makefiles whose usages of @code{VPATH} are
19202 portable to recent-enough popular implementations of @command{make}, but
19203 to keep the resulting makefiles portable, a package's makefile
19204 prototypes must take the following issues into account. These issues
19205 are complicated and are often poorly understood, and installers who use
19206 @code{VPATH} should expect to find many bugs in this area. If you use
19207 @code{VPATH}, the simplest way to avoid these portability bugs is to
19208 stick with GNU @command{make}, since it is the most
19209 commonly-used @command{make} among Autoconf users.
19211 Here are some known issues with some @code{VPATH}
19215 * Variables listed in VPATH:: @code{VPATH} must be literal on ancient hosts
19216 * VPATH and Double-colon:: Problems with @samp{::} on ancient hosts
19217 * $< in Explicit Rules:: @code{$<} does not work in ordinary rules
19218 * Automatic Rule Rewriting:: @code{VPATH} goes wild on Solaris
19219 * Tru64 Directory Magic:: @command{mkdir} goes wild on Tru64
19220 * Make Target Lookup:: More details about @code{VPATH} lookup
19223 @node Variables listed in VPATH
19224 @subsection Variables listed in @code{VPATH}
19225 @cindex @code{VPATH} and variables
19226 @cindex variables and @code{VPATH}
19228 Do not set @code{VPATH} to the value of another variable, for example
19229 @samp{VPATH = $(srcdir)}, because some ancient versions of
19230 @command{make} do not do variable substitutions on the value of
19231 @code{VPATH}. For example, use this
19234 srcdir = @@srcdir@@
19239 rather than @samp{VPATH = $(srcdir)}. Note that with GNU
19240 Automake, there is no need to set this yourself.
19242 @node VPATH and Double-colon
19243 @subsection @code{VPATH} and Double-colon Rules
19244 @cindex @code{VPATH} and double-colon rules
19245 @cindex double-colon rules and @code{VPATH}
19247 With ancient versions of Sun @command{make},
19248 any assignment to @code{VPATH} causes @command{make} to execute only
19249 the first set of double-colon rules.
19250 However, this problem is no longer of practical concern.
19252 @node $< in Explicit Rules
19253 @subsection @code{$<} Not Supported in Explicit Rules
19254 @cindex explicit rules, @code{$<}, and @code{VPATH}
19255 @cindex @code{$<}, explicit rules, and @code{VPATH}
19256 @cindex @code{VPATH}, explicit rules, and @code{$<}
19258 Using @code{$<} in explicit rules is not portable.
19259 The prerequisite file must be named explicitly in the rule. If you want
19260 to find the prerequisite via a @code{VPATH} search, you have to code the
19261 whole thing manually. @xref{Build Directories}.
19263 @node Automatic Rule Rewriting
19264 @subsection Automatic Rule Rewriting
19265 @cindex @code{VPATH} and automatic rule rewriting
19266 @cindex automatic rule rewriting and @code{VPATH}
19268 Some @command{make} implementations, such as Solaris and Tru64,
19269 search for prerequisites in @code{VPATH} and
19270 then rewrite each occurrence as a plain word in the rule.
19274 # This isn't portable to GNU make.
19281 executes @code{cp ../pkg/src/if.c f.c} if @file{if.c} is
19282 found in @file{../pkg/src}.
19284 However, this rule leads to real problems in practice. For example, if
19285 the source directory contains an ordinary file named @file{test} that is
19286 used in a dependency, Solaris @command{make} rewrites commands like
19287 @samp{if test -r foo; @dots{}} to @samp{if ../pkg/src/test -r foo;
19288 @dots{}}, which is typically undesirable. To avoid this problem,
19289 portable makefiles should never mention a source file whose name is that
19290 of a shell keyword like @file{until} or a shell command like
19291 @command{cat} or @command{gcc} or @command{test}.
19293 Because of these problems GNU @command{make} and many other
19294 @command{make} implementations do not rewrite commands, so portable
19296 search @code{VPATH} manually. It is tempting to write this:
19299 # This isn't portable to Solaris make.
19302 cp `test -f if.c || echo $(VPATH)/`if.c f.c
19306 However, the ``prerequisite rewriting'' still applies here. So if
19307 @file{if.c} is in @file{../pkg/src}, Solaris and Tru64 @command{make}
19311 cp `test -f ../pkg/src/if.c || echo ../pkg/src/`if.c f.c
19322 and thus fails. Oops.
19324 A simple workaround, and good practice anyway, is to use @samp{$?} and
19325 @samp{$@@} when possible:
19334 but this does not generalize well to commands with multiple
19335 prerequisites. A more general workaround is to rewrite the rule so that
19336 the prerequisite @file{if.c} never appears as a plain word. For
19337 example, these three rules would be safe, assuming @file{if.c} is in
19338 @file{../pkg/src} and the other files are in the working directory:
19343 cat `test -f ./if.c || echo $(VPATH)/`if.c f1.c >$@@
19345 cat `test -f 'if.c' || echo $(VPATH)/`if.c g1.c >$@@
19347 cat `test -f "if.c" || echo $(VPATH)/`if.c h1.c >$@@
19350 Things get worse when your prerequisites are in a macro.
19354 HEADERS = f.h g.h h.h
19355 install-HEADERS: $(HEADERS)
19356 for i in $(HEADERS); do \
19357 $(INSTALL) -m 644 \
19358 `test -f $$i || echo $(VPATH)/`$$i \
19359 $(DESTDIR)$(includedir)/$$i; \
19360 @c $$ restore font-lock
19364 The above @code{install-HEADERS} rule is not Solaris-proof because @code{for
19365 i in $(HEADERS);} is expanded to @code{for i in f.h g.h h.h;}
19366 where @code{f.h} and @code{g.h} are plain words and are hence
19367 subject to @code{VPATH} adjustments.
19369 If the three files are in @file{../pkg/src}, the rule is run as:
19372 for i in ../pkg/src/f.h ../pkg/src/g.h h.h; do \
19374 `test -f $i || echo ../pkg/src/`$i \
19375 /usr/local/include/$i; \
19379 where the two first @command{install} calls fail. For instance,
19380 consider the @code{f.h} installation:
19384 `test -f ../pkg/src/f.h || \
19387 /usr/local/include/../pkg/src/f.h;
19396 /usr/local/include/../pkg/src/f.h;
19399 Note that the manual @code{VPATH} search did not cause any problems here;
19400 however this command installs @file{f.h} in an incorrect directory.
19402 Trying to quote @code{$(HEADERS)} in some way, as we did for
19403 @code{foo.c} a few makefiles ago, does not help:
19406 install-HEADERS: $(HEADERS)
19407 headers='$(HEADERS)'; \
19408 for i in $$headers; do \
19409 $(INSTALL) -m 644 \
19410 `test -f $$i || echo $(VPATH)/`$$i \
19411 $(DESTDIR)$(includedir)/$$i; \
19415 Now, @code{headers='$(HEADERS)'} macro-expands to:
19418 headers='f.h g.h h.h'
19422 but @code{g.h} is still a plain word. (As an aside, the idiom
19423 @code{headers='$(HEADERS)'; for i in $$headers;} is a good
19424 idea if @code{$(HEADERS)} can be empty, because some shells diagnose a
19425 syntax error on @code{for i in;}.)
19427 One workaround is to strip this unwanted @file{../pkg/src/} prefix manually:
19431 HEADERS = f.h g.h h.h
19432 install-HEADERS: $(HEADERS)
19433 headers='$(HEADERS)'; \
19434 for i in $$headers; do \
19435 i=`expr "$$i" : '$(VPATH)/\(.*\)'`;
19436 $(INSTALL) -m 644 \
19437 `test -f $$i || echo $(VPATH)/`$$i \
19438 $(DESTDIR)$(includedir)/$$i; \
19439 @c $$ restore font-lock
19443 Automake does something similar. However the above hack works only if
19444 the files listed in @code{HEADERS} are in the current directory or a
19445 subdirectory; they should not be in an enclosing directory. If we had
19446 @code{HEADERS = ../f.h}, the above fragment would fail in a VPATH
19447 build with Tru64 @command{make}. The reason is that not only does
19448 Tru64 @command{make} rewrite dependencies, but it also simplifies
19449 them. Hence @code{../f.h} becomes @code{../pkg/f.h} instead of
19450 @code{../pkg/src/../f.h}. This obviously defeats any attempt to strip
19451 a leading @file{../pkg/src/} component.
19453 The following example makes the behavior of Tru64 @command{make}
19457 $ @kbd{cat Makefile}
19469 Dependency @file{../foo} was found in @file{sub/../foo}, but Tru64
19470 @command{make} simplified it as @file{foo}. (Note that the @file{sub/}
19471 directory does not even exist, this just means that the simplification
19472 occurred before the file was checked for.)
19474 For the record here is how SunOS 4 @command{make} behaves on this
19479 make: Fatal error: Don't know how to make target `../foo'
19487 @node Tru64 Directory Magic
19488 @subsection Tru64 @command{make} Creates Prerequisite Directories Magically
19489 @cindex @code{VPATH} and prerequisite directories
19490 @cindex prerequisite directories and @code{VPATH}
19492 When a prerequisite is a subdirectory of @code{VPATH}, Tru64
19493 @command{make} creates it in the current directory.
19496 $ @kbd{mkdir -p foo/bar build}
19498 $ @kbd{cat >Makefile <<END
19507 This can yield unexpected results if a rule uses a manual @code{VPATH}
19508 search as presented before.
19513 command `test -d foo/bar || echo ../`foo/bar
19516 The above @command{command} is run on the empty @file{foo/bar}
19517 directory that was created in the current directory.
19519 @node Make Target Lookup
19520 @subsection Make Target Lookup
19521 @cindex @code{VPATH}, resolving target pathnames
19523 GNU @command{make} uses a complex algorithm to decide when it
19524 should use files found via a @code{VPATH} search. @xref{Search
19525 Algorithm, , How Directory Searches are Performed, make, The GNU Make
19528 If a target needs to be rebuilt, GNU @command{make} discards the
19529 file name found during the @code{VPATH} search for this target, and
19530 builds the file locally using the file name given in the makefile.
19531 If a target does not need to be rebuilt, GNU @command{make} uses the
19532 file name found during the @code{VPATH} search.
19534 Other @command{make} implementations, like NetBSD @command{make}, are
19535 easier to describe: the file name found during the @code{VPATH} search
19536 is used whether the target needs to be rebuilt or not. Therefore
19537 new files are created locally, but existing files are updated at their
19538 @code{VPATH} location.
19540 OpenBSD and FreeBSD @command{make}, however,
19542 @code{VPATH} search for a dependency that has an explicit rule.
19543 This is extremely annoying.
19545 When attempting a @code{VPATH} build for an autoconfiscated package
19546 (e.g., @code{mkdir build && cd build && ../configure}), this means
19548 @command{make} builds everything locally in the @file{build}
19549 directory, while BSD @command{make} builds new files locally and
19550 updates existing files in the source directory.
19553 $ @kbd{cat Makefile}
19556 foo.x bar.x: newer.x
19557 @@echo Building $@@
19558 $ @kbd{touch ../bar.x}
19559 $ @kbd{touch ../newer.x}
19560 $ @kbd{make} # GNU make
19563 $ @kbd{pmake} # NetBSD make
19566 $ @kbd{fmake} # FreeBSD make, OpenBSD make
19569 $ @kbd{tmake} # Tru64 make
19572 $ @kbd{touch ../bar.x}
19573 $ @kbd{make} # GNU make
19575 $ @kbd{pmake} # NetBSD make
19577 $ @kbd{fmake} # FreeBSD make, OpenBSD make
19580 $ @kbd{tmake} # Tru64 make
19585 Note how NetBSD @command{make} updates @file{../bar.x} in its
19586 VPATH location, and how FreeBSD, OpenBSD, and Tru64
19587 @command{make} always
19588 update @file{bar.x}, even when @file{../bar.x} is up to date.
19590 Another point worth mentioning is that once GNU @command{make} has
19591 decided to ignore a @code{VPATH} file name (e.g., it ignored
19592 @file{../bar.x} in the above example) it continues to ignore it when
19593 the target occurs as a prerequisite of another rule.
19595 The following example shows that GNU @command{make} does not look up
19596 @file{bar.x} in @code{VPATH} before performing the @code{.x.y} rule,
19597 because it ignored the @code{VPATH} result of @file{bar.x} while running
19598 the @code{bar.x: newer.x} rule.
19601 $ @kbd{cat Makefile}
19605 @@echo Building $@@
19609 $ @kbd{touch ../bar.x}
19610 $ @kbd{touch ../newer.x}
19611 $ @kbd{make} # GNU make
19614 cp: cannot stat `bar.x': No such file or directory
19615 make: *** [bar.y] Error 1
19616 $ @kbd{pmake} # NetBSD make
19620 $ @kbd{fmake} # FreeBSD make, OpenBSD make
19621 echo Building bar.x
19623 cp: cannot stat `bar.x': No such file or directory
19625 $ @kbd{tmake} # Tru64 make
19627 cp: bar.x: No such file or directory
19631 Note that if you drop away the command from the @code{bar.x: newer.x}
19632 rule, GNU @command{make} magically starts to work: it
19633 knows that @code{bar.x} hasn't been updated, therefore it doesn't
19634 discard the result from @code{VPATH} (@file{../bar.x}) in succeeding
19635 uses. Tru64 also works, but FreeBSD and OpenBSD
19639 $ @kbd{cat Makefile}
19646 $ @kbd{touch ../bar.x}
19647 $ @kbd{touch ../newer.x}
19648 $ @kbd{make} # GNU make
19651 $ @kbd{pmake} # NetBSD make
19654 $ @kbd{fmake} # FreeBSD make, OpenBSD make
19656 cp: cannot stat `bar.x': No such file or directory
19658 $ @kbd{tmake} # Tru64 make
19662 It seems the sole solution that would please every @command{make}
19663 implementation is to never rely on @code{VPATH} searches for targets.
19664 In other words, @code{VPATH} should be reserved to unbuilt sources.
19667 @node Single Suffix Rules
19668 @section Single Suffix Rules and Separated Dependencies
19669 @cindex Single Suffix Inference Rule
19670 @cindex Rule, Single Suffix Inference
19671 A @dfn{Single Suffix Rule} is basically a usual suffix (inference) rule
19672 (@samp{.from.to:}), but which @emph{destination} suffix is empty
19675 @cindex Separated Dependencies
19676 @dfn{Separated dependencies} simply refers to listing the prerequisite
19677 of a target, without defining a rule. Usually one can list on the one
19678 hand side, the rules, and on the other hand side, the dependencies.
19680 Solaris @command{make} does not support separated dependencies for
19681 targets defined by single suffix rules:
19684 $ @kbd{cat Makefile}
19689 $ @kbd{touch foo.in}
19696 while GNU Make does:
19702 Makefile foo foo.in
19705 Note it works without the @samp{foo: foo.in} dependency.
19708 $ @kbd{cat Makefile}
19717 and it works with double suffix inference rules:
19720 $ @kbd{cat Makefile}
19722 .SUFFIXES: .in .out
19729 As a result, in such a case, you have to write target rules.
19731 @node Timestamps and Make
19732 @section Timestamp Resolution and Make
19733 @cindex timestamp resolution
19734 Traditionally, file timestamps had 1-second resolution, and
19735 @command{make} used those timestamps to determine whether one file was
19736 newer than the other. However, many modern file systems have
19737 timestamps with 1-nanosecond resolution. Some @command{make}
19738 implementations look at the entire timestamp; others ignore the
19739 fractional part, which can lead to incorrect results. Normally this
19740 is not a problem, but in some extreme cases you may need to use tricks
19741 like @samp{sleep 1} to work around timestamp truncation bugs.
19743 Commands like @samp{cp -p} and @samp{touch -r} typically do not copy
19744 file timestamps to their full resolutions (@pxref{touch, , Limitations of Usual
19745 Tools}). Hence you should be wary of rules like this:
19752 as @file{dest} often appears to be older than @file{src} after the
19753 timestamp is truncated, and this can cause @command{make} to do
19754 needless rework the next time it is invoked. To work around this
19755 problem, you can use a timestamp file, e.g.:
19766 @c ======================================== Portable C and C++ Programming
19768 @node Portable C and C++
19769 @chapter Portable C and C++ Programming
19770 @cindex Portable C and C++ programming
19772 C and C++ programs often use low-level features of the underlying
19773 system, and therefore are often more difficult to make portable to other
19776 Several standards have been developed to help make your programs more
19777 portable. If you write programs with these standards in mind, you can
19778 have greater confidence that your programs work on a wide variety
19781 @uref{http://@/gcc.gnu.org/@/onlinedocs/@/gcc/@/Standards.html, Language
19782 Standards Supported by GCC}
19785 @xref{Standards, , Language Standards Supported by
19786 GCC, gcc, Using the GNU Compiler Collection
19789 for a list of C-related standards. Many programs also assume the
19790 @uref{http://@/www.opengroup.org/@/susv3, Posix standard}.
19792 Some old code is written to be portable to K&R C, which predates any C
19793 standard. K&R C compilers are no longer of practical interest, though,
19794 and the rest of section assumes at least C89, the first C standard.
19796 Program portability is a huge topic, and this section can only briefly
19797 introduce common pitfalls. @xref{System Portability, , Portability
19798 between System Types, standards, GNU Coding Standards}, for
19802 * Varieties of Unportability:: How to make your programs unportable
19803 * Integer Overflow:: When integers get too large
19804 * Preprocessor Arithmetic:: @code{#if} expression problems
19805 * Null Pointers:: Properties of null pointers
19806 * Buffer Overruns:: Subscript errors and the like
19807 * Volatile Objects:: @code{volatile} and signals
19808 * Floating Point Portability:: Portable floating-point arithmetic
19809 * Exiting Portably:: Exiting and the exit status
19812 @node Varieties of Unportability
19813 @section Varieties of Unportability
19814 @cindex portability
19816 Autoconf tests and ordinary programs often need to test what is allowed
19817 on a system, and therefore they may need to deliberately exceed the
19818 boundaries of what the standards allow, if only to see whether an
19819 optional feature is present. When you write such a program, you should
19820 keep in mind the difference between constraints, unspecified behavior,
19821 and undefined behavior.
19823 In C, a @dfn{constraint} is a rule that the compiler must enforce. An
19824 example constraint is that C programs must not declare a bit-field with
19825 negative width. Tests can therefore reliably assume that programs with
19826 negative-width bit-fields are rejected by a compiler that conforms
19829 @dfn{Unspecified behavior} is valid behavior, where the standard allows
19830 multiple possibilities. For example, the order of evaluation of
19831 function arguments is unspecified. Some unspecified behavior is
19832 @dfn{implementation-defined}, i.e., documented by the implementation,
19833 but since Autoconf tests cannot read the documentation they cannot
19834 distinguish between implementation-defined and other unspecified
19835 behavior. It is common for Autoconf tests to probe implementations to
19836 determine otherwise-unspecified behavior.
19838 @dfn{Undefined behavior} is invalid behavior, where the standard allows
19839 the implementation to do anything it pleases. For example,
19840 dereferencing a null pointer leads to undefined behavior. If possible,
19841 test programs should avoid undefined behavior, since a program with
19842 undefined behavior might succeed on a test that should fail.
19844 The above rules apply to programs that are intended to conform to the
19845 standard. However, strictly-conforming programs are quite rare, since
19846 the standards are so limiting. A major goal of Autoconf is to support
19847 programs that use implementation features not described by the standard,
19848 and it is fairly common for test programs to violate the above rules, if
19849 the programs work well enough in practice.
19851 @node Integer Overflow
19852 @section Integer Overflow
19853 @cindex integer overflow
19854 @cindex overflow, signed integer
19855 @cindex signed integer overflow
19856 @cindex wraparound arithmetic
19858 In practice many portable C programs assume that signed integer overflow wraps
19859 around reliably using two's complement arithmetic. Yet the C standard
19860 says that program behavior is undefined on overflow, and in a few cases
19861 C programs do not work on some modern implementations because their
19862 overflows do not wrap around as their authors expected. Conversely, in
19863 signed integer remainder, the C standard requires overflow
19864 behavior that is commonly not implemented.
19867 * Integer Overflow Basics:: Why integer overflow is a problem
19868 * Signed Overflow Examples:: Examples of code assuming wraparound
19869 * Optimization and Wraparound:: Optimizations that break uses of wraparound
19870 * Signed Overflow Advice:: Practical advice for signed overflow issues
19871 * Signed Integer Division:: @code{INT_MIN / -1} and @code{INT_MIN % -1}
19874 @node Integer Overflow Basics
19875 @subsection Basics of Integer Overflow
19876 @cindex integer overflow
19877 @cindex overflow, signed integer
19878 @cindex signed integer overflow
19879 @cindex wraparound arithmetic
19881 In languages like C, unsigned integer overflow reliably wraps around;
19882 e.g., @code{UINT_MAX + 1} yields zero.
19883 This is guaranteed by the C standard and is
19884 portable in practice, unless you specify aggressive,
19885 nonstandard optimization options
19886 suitable only for special applications.
19888 In contrast, the C standard says that signed integer overflow leads to
19889 undefined behavior where a program can do anything, including dumping
19890 core or overrunning a buffer. The misbehavior can even precede the
19891 overflow. Such an overflow can occur during addition, subtraction,
19892 multiplication, division, and left shift.
19894 Despite this requirement of the standard, many C programs and Autoconf
19895 tests assume that signed integer overflow silently wraps around modulo a
19896 power of two, using two's complement arithmetic, so long as you cast the
19897 resulting value to a signed integer type or store it into a signed
19898 integer variable. If you use conservative optimization flags, such
19899 programs are generally portable to the vast majority of modern
19900 platforms, with a few exceptions discussed later.
19902 For historical reasons the C standard also allows implementations with
19903 ones' complement or signed magnitude arithmetic, but it is safe to
19904 assume two's complement nowadays.
19906 Also, overflow can occur when converting an out-of-range value to a
19907 signed integer type. Here a standard implementation must define what
19908 happens, but this might include raising an exception. In practice all
19909 known implementations support silent wraparound in this case, so you need
19910 not worry about other possibilities.
19912 @node Signed Overflow Examples
19913 @subsection Examples of Code Assuming Wraparound Overflow
19914 @cindex integer overflow
19915 @cindex overflow, signed integer
19916 @cindex signed integer overflow
19917 @cindex wraparound arithmetic
19919 There has long been a tension between what the C standard requires for
19920 signed integer overflow, and what C programs commonly assume. The
19921 standard allows aggressive optimizations based on assumptions that
19922 overflow never occurs, but many practical C programs rely on overflow
19923 wrapping around. These programs do not conform to the standard, but
19924 they commonly work in practice because compiler writers are
19925 understandably reluctant to implement optimizations that would break
19926 many programs, unless perhaps a user specifies aggressive optimization.
19928 The C Standard says that if a program has signed integer overflow its
19929 behavior is undefined, and the undefined behavior can even precede the
19930 overflow. To take an extreme example:
19932 @c Inspired by Robert Dewar's example in
19933 @c <http://gcc.gnu.org/ml/gcc/2007-01/msg00038.html> (2007-01-01).
19935 if (password == expected_password)
19936 allow_superuser_privileges ();
19937 else if (counter++ == INT_MAX)
19940 printf ("%d password mismatches\n", counter);
19944 If the @code{int} variable @code{counter} equals @code{INT_MAX},
19945 @code{counter++} must overflow and the behavior is undefined, so the C
19946 standard allows the compiler to optimize away the test against
19947 @code{INT_MAX} and the @code{abort} call.
19948 Worse, if an earlier bug in the program lets the compiler deduce that
19949 @code{counter == INT_MAX} or that @code{counter} previously overflowed,
19950 the C standard allows the compiler to optimize away the password test
19951 and generate code that allows superuser privileges unconditionally.
19953 Despite this requirement by the standard, it has long been common for C
19954 code to assume wraparound arithmetic after signed overflow, and all
19955 known practical C implementations support some C idioms that assume
19956 wraparound signed arithmetic, even if the idioms do not conform
19957 strictly to the standard. If your code looks like the following
19958 examples it will almost surely work with real-world compilers.
19960 Here is an example derived from the 7th Edition Unix implementation of
19961 @code{atoi} (1979-01-10):
19967 while (*p >= '0' && *p <= '9')
19968 n = n * 10 + *p++ - '0';
19969 return (f ? -n : n);
19973 Even if the input string is in range, on most modern machines this has
19974 signed overflow when computing the most negative integer (the @code{-n}
19975 overflows) or a value near an extreme integer (the first @code{+}
19978 Here is another example, derived from the 7th Edition implementation of
19979 @code{rand} (1979-01-10). Here the programmer expects both
19980 multiplication and addition to wrap on overflow:
19983 static long int randx = 1;
19985 randx = randx * 1103515245 + 12345;
19986 return (randx >> 16) & 077777;
19989 In the following example, derived from the GNU C Library 2.5
19990 implementation of @code{mktime} (2006-09-09), the code assumes
19991 wraparound arithmetic in @code{+} to detect signed overflow:
19995 int sec_requested, sec_adjustment;
19997 t1 = t + sec_requested;
19998 t2 = t1 + sec_adjustment;
19999 if (((t1 < t) != (sec_requested < 0))
20000 | ((t2 < t1) != (sec_adjustment < 0)))
20004 If your code looks like these examples, it is probably safe even though
20005 it does not strictly conform to the C standard. This might lead one to
20006 believe that one can generally assume wraparound on overflow, but that
20007 is not always true, as can be seen in the next section.
20009 @node Optimization and Wraparound
20010 @subsection Optimizations That Break Wraparound Arithmetic
20011 @cindex loop induction
20013 Compilers sometimes generate code that is incompatible with wraparound
20014 integer arithmetic. A simple example is an algebraic simplification: a
20015 compiler might translate @code{(i * 2000) / 1000} to @code{i * 2}
20016 because it assumes that @code{i * 2000} does not overflow. The
20017 translation is not equivalent to the original when overflow occurs:
20018 e.g., in the typical case of 32-bit signed two's complement wraparound
20019 @code{int}, if @code{i} has type @code{int} and value @code{1073742},
20020 the original expression returns @minus{}2147483 but the optimized
20021 version returns the mathematically correct value 2147484.
20023 More subtly, loop induction optimizations often exploit the undefined
20024 behavior of signed overflow. Consider the following contrived function
20029 sumc (int lo, int hi)
20033 for (i = lo; i <= hi; i++)
20040 To avoid multiplying by 53 each time through the loop, an optimizing
20041 compiler might internally transform @code{sumc} to the equivalent of the
20046 transformed_sumc (int lo, int hi)
20051 for (ic = lo * 53; ic <= hic; ic += 53)
20058 This transformation is allowed by the C standard, but it is invalid for
20059 wraparound arithmetic when @code{INT_MAX / 53 < hi}, because then the
20060 overflow in computing expressions like @code{hi * 53} can cause the
20061 expression @code{i <= hi} to yield a different value from the
20062 transformed expression @code{ic <= hic}.
20064 For this reason, compilers that use loop induction and similar
20065 techniques often do not support reliable wraparound arithmetic when a
20066 loop induction variable like @code{ic} is involved. Since loop
20067 induction variables are generated by the compiler, and are not visible
20068 in the source code, it is not always trivial to say whether the problem
20071 Hardly any code actually depends on wraparound arithmetic in cases like
20072 these, so in practice these loop induction optimizations are almost
20073 always useful. However, edge cases in this area can cause problems.
20078 for (j = 1; 0 < j; j *= 2)
20083 Here, the loop attempts to iterate through all powers of 2 that
20084 @code{int} can represent, but the C standard allows a compiler to
20085 optimize away the comparison and generate an infinite loop,
20086 under the argument that behavior is undefined on overflow. As of this
20087 writing this optimization is not done by any production version of
20088 GCC with @option{-O2}, but it might be performed by other
20089 compilers, or by more aggressive GCC optimization options,
20090 and the GCC developers have not decided whether it will
20091 continue to work with GCC and @option{-O2}.
20093 @node Signed Overflow Advice
20094 @subsection Practical Advice for Signed Overflow Issues
20095 @cindex integer overflow
20096 @cindex overflow, signed integer
20097 @cindex signed integer overflow
20098 @cindex wraparound arithmetic
20100 Ideally the safest approach is to avoid signed integer overflow
20101 entirely. For example, instead of multiplying two signed integers, you
20102 can convert them to unsigned integers, multiply the unsigned values,
20103 then test whether the result is in signed range.
20105 Rewriting code in this way will be inconvenient, though, particularly if
20106 the signed values might be negative. Also, it may hurt
20107 performance. Using unsigned arithmetic to check for overflow is
20108 particularly painful to do portably and efficiently when dealing with an
20109 integer type like @code{uid_t} whose width and signedness vary from
20110 platform to platform.
20112 Furthermore, many C applications pervasively assume wraparound behavior
20113 and typically it is not easy to find and remove all these assumptions.
20114 Hence it is often useful to maintain nonstandard code that assumes
20115 wraparound on overflow, instead of rewriting the code. The rest of this
20116 section attempts to give practical advice for this situation.
20118 If your code wants to detect signed integer overflow in @code{sum = a +
20119 b}, it is generally safe to use an expression like @code{(sum < a) != (b
20122 If your code uses a signed loop index, make sure that the index cannot
20123 overflow, along with all signed expressions derived from the index.
20124 Here is a contrived example of problematic code with two instances of
20128 for (i = INT_MAX - 10; i <= INT_MAX; i++)
20131 report_overflow ();
20137 Because of the two overflows, a compiler might optimize away or
20138 transform the two comparisons in a way that is incompatible with the
20139 wraparound assumption.
20141 If your code uses an expression like @code{(i * 2000) / 1000} and you
20142 actually want the multiplication to wrap around on overflow, use
20143 unsigned arithmetic
20144 to do it, e.g., @code{((int) (i * 2000u)) / 1000}.
20146 If your code assumes wraparound behavior and you want to insulate it
20147 against any GCC optimizations that would fail to support that
20148 behavior, you should use GCC's @option{-fwrapv} option, which
20149 causes signed overflow to wrap around reliably (except for division and
20150 remainder, as discussed in the next section).
20152 If you need to port to platforms where signed integer overflow does not
20153 reliably wrap around (e.g., due to hardware overflow checking, or to
20154 highly aggressive optimizations), you should consider debugging with
20155 GCC's @option{-ftrapv} option, which causes signed overflow to
20156 raise an exception.
20158 @node Signed Integer Division
20159 @subsection Signed Integer Division and Integer Overflow
20160 @cindex division, integer
20163 integer division is not always harmless: for example, on CPUs of the
20164 i386 family, dividing @code{INT_MIN} by @code{-1} yields a SIGFPE signal
20165 which by default terminates the program. Worse, taking the remainder
20166 of these two values typically yields the same signal on these CPUs,
20167 even though the C standard requires @code{INT_MIN % -1} to yield zero
20168 because the expression does not overflow.
20170 @node Preprocessor Arithmetic
20171 @section Preprocessor Arithmetic
20172 @cindex preprocessor arithmetic
20174 In C99, preprocessor arithmetic, used for @code{#if} expressions, must
20175 be evaluated as if all signed values are of type @code{intmax_t} and all
20176 unsigned values of type @code{uintmax_t}. Many compilers are buggy in
20177 this area, though. For example, as of 2007, Sun C mishandles @code{#if
20178 LLONG_MIN < 0} on a platform with 32-bit @code{long int} and 64-bit
20179 @code{long long int}. Also, some older preprocessors mishandle
20180 constants ending in @code{LL}. To work around these problems, you can
20181 compute the value of expressions like @code{LONG_MAX < LLONG_MAX} at
20182 @code{configure}-time rather than at @code{#if}-time.
20184 @node Null Pointers
20185 @section Properties of Null Pointers
20186 @cindex null pointers
20188 Most modern hosts reliably fail when you attempt to dereference a null
20191 On almost all modern hosts, null pointers use an all-bits-zero internal
20192 representation, so you can reliably use @code{memset} with 0 to set all
20193 the pointers in an array to null values.
20195 If @code{p} is a null pointer to an object type, the C expression
20196 @code{p + 0} always evaluates to @code{p} on modern hosts, even though
20197 the standard says that it has undefined behavior.
20199 @node Buffer Overruns
20200 @section Buffer Overruns and Subscript Errors
20201 @cindex buffer overruns
20203 Buffer overruns and subscript errors are the most common dangerous
20204 errors in C programs. They result in undefined behavior because storing
20205 outside an array typically modifies storage that is used by some other
20206 object, and most modern systems lack runtime checks to catch these
20207 errors. Programs should not rely on buffer overruns being caught.
20209 There is one exception to the usual rule that a portable program cannot
20210 address outside an array. In C, it is valid to compute the address just
20211 past an object, e.g., @code{&a[N]} where @code{a} has @code{N} elements,
20212 so long as you do not dereference the resulting pointer. But it is not
20213 valid to compute the address just before an object, e.g., @code{&a[-1]};
20214 nor is it valid to compute two past the end, e.g., @code{&a[N+1]}. On
20215 most platforms @code{&a[-1] < &a[0] && &a[N] < &a[N+1]}, but this is not
20216 reliable in general, and it is usually easy enough to avoid the
20217 potential portability problem, e.g., by allocating an extra unused array
20218 element at the start or end.
20220 @uref{http://@/valgrind.org/, Valgrind} can catch many overruns.
20222 users might also consider using the @option{-fmudflap} option to catch
20225 Buffer overruns are usually caused by off-by-one errors, but there are
20226 more subtle ways to get them.
20228 Using @code{int} values to index into an array or compute array sizes
20229 causes problems on typical 64-bit hosts where an array index might
20230 be @math{2^31} or larger. Index values of type @code{size_t} avoid this
20231 problem, but cannot be negative. Index values of type @code{ptrdiff_t}
20232 are signed, and are wide enough in practice.
20234 If you add or multiply two numbers to calculate an array size, e.g.,
20235 @code{malloc (x * sizeof y + z)}, havoc ensues if the addition or
20236 multiplication overflows.
20238 Many implementations of the @code{alloca} function silently misbehave
20239 and can generate buffer overflows if given sizes that are too large.
20240 The size limits are implementation dependent, but are at least 4000
20241 bytes on all platforms that we know about.
20243 The standard functions @code{asctime}, @code{asctime_r}, @code{ctime},
20244 @code{ctime_r}, and @code{gets} are prone to buffer overflows, and
20245 portable code should not use them unless the inputs are known to be
20246 within certain limits. The time-related functions can overflow their
20247 buffers if given timestamps out of range (e.g., a year less than -999
20248 or greater than 9999). Time-related buffer overflows cannot happen with
20249 recent-enough versions of the GNU C library, but are possible
20251 implementations. The @code{gets} function is the worst, since it almost
20252 invariably overflows its buffer when presented with an input line larger
20255 @node Volatile Objects
20256 @section Volatile Objects
20257 @cindex volatile objects
20259 The keyword @code{volatile} is often misunderstood in portable code.
20260 Its use inhibits some memory-access optimizations, but programmers often
20261 wish that it had a different meaning than it actually does.
20263 @code{volatile} was designed for code that accesses special objects like
20264 memory-mapped device registers whose contents spontaneously change.
20265 Such code is inherently low-level, and it is difficult to specify
20266 portably what @code{volatile} means in these cases. The C standard
20267 says, ``What constitutes an access to an object that has
20268 volatile-qualified type is implementation-defined,'' so in theory each
20269 implementation is supposed to fill in the gap by documenting what
20270 @code{volatile} means for that implementation. In practice, though,
20271 this documentation is usually absent or incomplete.
20273 One area of confusion is the distinction between objects defined with
20274 volatile types, and volatile lvalues. From the C standard's point of
20275 view, an object defined with a volatile type has externally visible
20276 behavior. You can think of such objects as having little oscilloscope
20277 probes attached to them, so that the user can observe some properties of
20278 accesses to them, just as the user can observe data written to output
20279 files. However, the standard does not make it clear whether users can
20280 observe accesses by volatile lvalues to ordinary objects. For example:
20283 /* Declare and access a volatile object.
20284 Accesses to X are "visible" to users. */
20285 static int volatile x;
20288 /* Access two ordinary objects via a volatile lvalue.
20289 It's not clear whether accesses to *P are "visible". */
20291 int *z = malloc (sizeof (int));
20299 Programmers often wish that @code{volatile} meant ``Perform the memory
20300 access here and now, without merging several memory accesses, without
20301 changing the memory word size, and without reordering.'' But the C
20302 standard does not require this. For objects defined with a volatile
20303 type, accesses must be done before the next sequence point; but
20304 otherwise merging, reordering, and word-size change is allowed. Worse,
20305 it is not clear from the standard whether volatile lvalues provide more
20306 guarantees in general than nonvolatile lvalues, if the underlying
20307 objects are ordinary.
20309 Even when accessing objects defined with a volatile type,
20310 the C standard allows only
20311 extremely limited signal handlers: the behavior is undefined if a signal
20312 handler reads any nonlocal object, or writes to any nonlocal object
20313 whose type is not @code{sig_atomic_t volatile}, or calls any standard
20314 library function other than @code{abort}, @code{signal}, and (if C99)
20315 @code{_Exit}. Hence C compilers need not worry about a signal handler
20316 disturbing ordinary computation, unless the computation accesses a
20317 @code{sig_atomic_t volatile} lvalue that is not a local variable.
20318 (There is an obscure exception for accesses via a pointer to a volatile
20319 character, since it may point into part of a @code{sig_atomic_t
20320 volatile} object.) Posix
20321 adds to the list of library functions callable from a portable signal
20322 handler, but otherwise is like the C standard in this area.
20324 Some C implementations allow memory-access optimizations within each
20325 translation unit, such that actual behavior agrees with the behavior
20326 required by the standard only when calling a function in some other
20327 translation unit, and a signal handler acts like it was called from a
20328 different translation unit. The C standard hints that in these
20329 implementations, objects referred to by signal handlers ``would require
20330 explicit specification of @code{volatile} storage, as well as other
20331 implementation-defined restrictions.'' But unfortunately even for this
20332 special case these other restrictions are often not documented well.
20333 @xref{Volatiles, , When is a Volatile Object Accessed?, gcc, Using the
20334 GNU Compiler Collection (GCC)}, for some
20335 restrictions imposed by GCC. @xref{Defining Handlers, ,
20336 Defining Signal Handlers, libc, The GNU C Library}, for some
20337 restrictions imposed by the GNU C library. Restrictions
20338 differ on other platforms.
20340 If possible, it is best to use a signal handler that fits within the
20341 limits imposed by the C and Posix standards.
20343 If this is not practical, you can try the following rules of thumb. A
20344 signal handler should access only volatile lvalues, preferably lvalues
20345 that refer to objects defined with a volatile type, and should not
20346 assume that the accessed objects have an internally consistent state
20347 if they are larger than a machine word. Furthermore, installers
20348 should employ compilers and compiler options that are commonly used
20349 for building operating system kernels, because kernels often need more
20350 from @code{volatile} than the C Standard requires, and installers who
20351 compile an application in a similar environment can sometimes benefit
20352 from the extra constraints imposed by kernels on compilers.
20353 Admittedly we are handwaving somewhat here, as there are few
20354 guarantees in this area; the rules of thumb may help to fix some bugs
20355 but there is a good chance that they will not fix them all.
20357 For @code{volatile}, C++ has the same problems that C does.
20358 Multithreaded applications have even more problems with @code{volatile},
20359 but they are beyond the scope of this section.
20361 The bottom line is that using @code{volatile} typically hurts
20362 performance but should not hurt correctness. In some cases its use
20363 does help correctness, but these cases are often so poorly understood
20364 that all too often adding @code{volatile} to a data structure merely
20365 alleviates some symptoms of a bug while not fixing the bug in general.
20367 @node Floating Point Portability
20368 @section Floating Point Portability
20369 @cindex floating point
20371 Almost all modern systems use IEEE-754 floating point, and it is safe to
20372 assume IEEE-754 in most portable code these days. For more information,
20373 please see David Goldberg's classic paper
20374 @uref{http://@/www.validlab.com/@/goldberg/@/paper.pdf, What Every Computer
20375 Scientist Should Know About Floating-Point Arithmetic}.
20377 @node Exiting Portably
20378 @section Exiting Portably
20379 @cindex exiting portably
20381 A C or C++ program can exit with status @var{N} by returning
20382 @var{N} from the @code{main} function. Portable programs are supposed
20383 to exit either with status 0 or @code{EXIT_SUCCESS} to succeed, or with
20384 status @code{EXIT_FAILURE} to fail, but in practice it is portable to
20385 fail by exiting with status 1, and test programs that assume Posix can
20386 fail by exiting with status values from 1 through 255. Programs on
20387 SunOS 2.0 (1985) through 3.5.2 (1988) incorrectly exited with zero
20388 status when @code{main} returned nonzero, but ancient systems like these
20389 are no longer of practical concern.
20391 A program can also exit with status @var{N} by passing @var{N} to the
20392 @code{exit} function, and a program can fail by calling the @code{abort}
20393 function. If a program is specialized to just some platforms, it can fail
20394 by calling functions specific to those platforms, e.g., @code{_exit}
20395 (Posix) and @code{_Exit} (C99). However, like other functions, an exit
20396 function should be declared, typically by including a header. For
20397 example, if a C program calls @code{exit}, it should include @file{stdlib.h}
20398 either directly or via the default includes (@pxref{Default Includes}).
20400 A program can fail due to undefined behavior such as dereferencing a null
20401 pointer, but this is not recommended as undefined behavior allows an
20402 implementation to do whatever it pleases and this includes exiting
20406 @c ================================================== Manual Configuration
20408 @node Manual Configuration
20409 @chapter Manual Configuration
20411 A few kinds of features can't be guessed automatically by running test
20412 programs. For example, the details of the object-file format, or
20413 special options that need to be passed to the compiler or linker. You
20414 can check for such features using ad-hoc means, such as having
20415 @command{configure} check the output of the @code{uname} program, or
20416 looking for libraries that are unique to particular systems. However,
20417 Autoconf provides a uniform method for handling unguessable features.
20420 * Specifying Target Triplets:: Specifying target triplets
20421 * Canonicalizing:: Getting the canonical system type
20422 * Using System Type:: What to do with the system type
20425 @node Specifying Target Triplets
20426 @section Specifying target triplets
20427 @cindex System type
20428 @cindex Target triplet
20429 @c This node used to be named Specifying Names. The @anchor allows old
20430 @c links to still work.
20431 @anchor{Specifying Names}
20434 @command{configure} scripts can make decisions based on a canonical name
20435 for the system type, or @dfn{target triplet}, which has the form:
20436 @samp{@var{cpu}-@var{vendor}-@var{os}}, where @var{os} can be
20437 @samp{@var{system}} or @samp{@var{kernel}-@var{system}}
20439 @command{configure} can usually guess the canonical name for the type of
20440 system it's running on. To do so it runs a script called
20441 @command{config.guess}, which infers the name using the @code{uname}
20442 command or symbols predefined by the C preprocessor.
20444 Alternately, the user can specify the system type with command line
20445 arguments to @command{configure} (@pxref{System Type}. Doing so is
20447 cross-compiling. In the most complex case of cross-compiling, three
20448 system types are involved. The options to specify them are:
20451 @item --build=@var{build-type}
20452 the type of system on which the package is being configured and
20453 compiled. It defaults to the result of running @command{config.guess}.
20455 @item --host=@var{host-type}
20456 the type of system on which the package runs. By default it is the
20457 same as the build machine. Specifying it enables the cross-compilation
20460 @item --target=@var{target-type}
20461 the type of system for which any compiler tools in the package
20462 produce code (rarely needed). By default, it is the same as host.
20465 If you mean to override the result of @command{config.guess}, use
20466 @option{--build}, not @option{--host}, since the latter enables
20467 cross-compilation. For historical reasons,
20468 whenever you specify @option{--host},
20469 be sure to specify @option{--build} too; this will be fixed in the
20470 future. So, to enter cross-compilation mode, use a command like this
20473 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
20477 Note that if you do not specify @option{--host}, @command{configure}
20478 fails if it can't run the code generated by the specified compiler. For
20479 example, configuring as follows fails:
20482 ./configure CC=m68k-coff-gcc
20485 When cross-compiling, @command{configure} will warn about any tools
20486 (compilers, linkers, assemblers) whose name is not prefixed with the
20487 host type. This is an aid to users performing cross-compilation.
20488 Continuing the example above, if a cross-compiler named @command{cc} is
20489 used with a native @command{pkg-config}, then libraries found by
20490 @command{pkg-config} will likely cause subtle build failures; but using
20491 the names @command{m68k-coff-cc} and @command{m68k-coff-pkg-config}
20492 avoids any confusion. Avoiding the warning is as simple as creating the
20493 correct symlinks naming the cross tools.
20495 @cindex @command{config.sub}
20496 @command{configure} recognizes short aliases for many system types; for
20497 example, @samp{decstation} can be used instead of
20498 @samp{mips-dec-ultrix4.2}. @command{configure} runs a script called
20499 @command{config.sub} to canonicalize system type aliases.
20501 This section deliberately omits the description of the obsolete
20502 interface; see @ref{Hosts and Cross-Compilation}.
20505 @node Canonicalizing
20506 @section Getting the Canonical System Type
20507 @cindex System type
20508 @cindex Canonical system type
20510 The following macros make the system type available to @command{configure}
20513 @ovindex build_alias
20514 @ovindex host_alias
20515 @ovindex target_alias
20517 The variables @samp{build_alias}, @samp{host_alias}, and
20518 @samp{target_alias} are always exactly the arguments of @option{--build},
20519 @option{--host}, and @option{--target}; in particular, they are left empty
20520 if the user did not use them, even if the corresponding
20521 @code{AC_CANONICAL} macro was run. Any configure script may use these
20522 variables anywhere. These are the variables that should be used when in
20523 interaction with the user.
20525 If you need to recognize some special environments based on their system
20526 type, run the following macros to get canonical system names. These
20527 variables are not set before the macro call.
20529 If you use these macros, you must distribute @command{config.guess} and
20530 @command{config.sub} along with your source code. @xref{Output}, for
20531 information about the @code{AC_CONFIG_AUX_DIR} macro which you can use
20532 to control in which directory @command{configure} looks for those scripts.
20535 @defmac AC_CANONICAL_BUILD
20536 @acindex{CANONICAL_BUILD}
20539 @ovindex build_vendor
20541 Compute the canonical build-system type variable, @code{build}, and its
20542 three individual parts @code{build_cpu}, @code{build_vendor}, and
20545 If @option{--build} was specified, then @code{build} is the
20546 canonicalization of @code{build_alias} by @command{config.sub},
20547 otherwise it is determined by the shell script @command{config.guess}.
20550 @defmac AC_CANONICAL_HOST
20551 @acindex{CANONICAL_HOST}
20554 @ovindex host_vendor
20556 Compute the canonical host-system type variable, @code{host}, and its
20557 three individual parts @code{host_cpu}, @code{host_vendor}, and
20560 If @option{--host} was specified, then @code{host} is the
20561 canonicalization of @code{host_alias} by @command{config.sub},
20562 otherwise it defaults to @code{build}.
20565 @defmac AC_CANONICAL_TARGET
20566 @acindex{CANONICAL_TARGET}
20568 @ovindex target_cpu
20569 @ovindex target_vendor
20571 Compute the canonical target-system type variable, @code{target}, and its
20572 three individual parts @code{target_cpu}, @code{target_vendor}, and
20575 If @option{--target} was specified, then @code{target} is the
20576 canonicalization of @code{target_alias} by @command{config.sub},
20577 otherwise it defaults to @code{host}.
20580 Note that there can be artifacts due to the backward compatibility
20581 code. See @xref{Hosts and Cross-Compilation}, for more.
20583 @node Using System Type
20584 @section Using the System Type
20586 In @file{configure.ac} the system type is generally used by one or more
20587 @code{case} statements to select system-specifics. Shell wildcards can
20588 be used to match a group of system types.
20590 For example, an extra assembler code object file could be chosen, giving
20591 access to a CPU cycle counter register. @code{$(CYCLE_OBJ)} in the
20592 following would be used in a makefile to add the object to a
20593 program or library.
20597 [alpha*-*-*], [CYCLE_OBJ=rpcc.o],
20598 [i?86-*-*], [CYCLE_OBJ=rdtsc.o],
20601 AC_SUBST([CYCLE_OBJ])
20604 @code{AC_CONFIG_LINKS} (@pxref{Configuration Links}) is another good way
20605 to select variant source files, for example optimized code for some
20606 CPUs. The configured CPU type doesn't always indicate exact CPU types,
20607 so some runtime capability checks may be necessary too.
20611 alpha*-*-*) AC_CONFIG_LINKS([dither.c:alpha/dither.c]) ;;
20612 powerpc*-*-*) AC_CONFIG_LINKS([dither.c:powerpc/dither.c]) ;;
20613 *-*-*) AC_CONFIG_LINKS([dither.c:generic/dither.c]) ;;
20617 The host system type can also be used to find cross-compilation tools
20618 with @code{AC_CHECK_TOOL} (@pxref{Generic Programs}).
20620 The above examples all show @samp{$host}, since this is where the code
20621 is going to run. Only rarely is it necessary to test @samp{$build}
20622 (which is where the build is being done).
20624 Whenever you're tempted to use @samp{$host} it's worth considering
20625 whether some sort of probe would be better. New system types come along
20626 periodically or previously missing features are added. Well-written
20627 probes can adapt themselves to such things, but hard-coded lists of
20628 names can't. Here are some guidelines,
20632 Availability of libraries and library functions should always be checked
20635 Variant behavior of system calls is best identified with runtime tests
20636 if possible, but bug workarounds or obscure difficulties might have to
20637 be driven from @samp{$host}.
20639 Assembler code is inevitably highly CPU-specific and is best selected
20640 according to @samp{$host_cpu}.
20642 Assembler variations like underscore prefix on globals or ELF versus
20643 COFF type directives are however best determined by probing, perhaps
20644 even examining the compiler output.
20647 @samp{$target} is for use by a package creating a compiler or similar.
20648 For ordinary packages it's meaningless and should not be used. It
20649 indicates what the created compiler should generate code for, if it can
20650 cross-compile. @samp{$target} generally selects various hard-coded CPU
20651 and system conventions, since usually the compiler or tools under
20652 construction themselves determine how the target works.
20655 @c ===================================================== Site Configuration.
20657 @node Site Configuration
20658 @chapter Site Configuration
20660 @command{configure} scripts support several kinds of local configuration
20661 decisions. There are ways for users to specify where external software
20662 packages are, include or exclude optional features, install programs
20663 under modified names, and set default values for @command{configure}
20667 * Help Formatting:: Customizing @samp{configure --help}
20668 * External Software:: Working with other optional software
20669 * Package Options:: Selecting optional features
20670 * Pretty Help Strings:: Formatting help string
20671 * Option Checking:: Controlling checking of @command{configure} options
20672 * Site Details:: Configuring site details
20673 * Transforming Names:: Changing program names when installing
20674 * Site Defaults:: Giving @command{configure} local defaults
20677 @node Help Formatting
20678 @section Controlling Help Output
20680 Users consult @samp{configure --help} to learn of configuration
20681 decisions specific to your package. By default, @command{configure}
20682 breaks this output into sections for each type of option; within each
20683 section, help strings appear in the order @file{configure.ac} defines
20689 --enable-bar include bar
20696 @defmac AC_PRESERVE_HELP_ORDER
20697 @acindex{PRESERVE_HELP_ORDER}
20699 Request an alternate @option{--help} format, in which options of all
20700 types appear together, in the order defined. Call this macro before any
20701 @code{AC_ARG_ENABLE} or @code{AC_ARG_WITH}.
20704 Optional Features and Packages:
20706 --enable-bar include bar
20712 @node External Software
20713 @section Working With External Software
20714 @cindex External software
20716 Some packages require, or can optionally use, other software packages
20717 that are already installed. The user can give @command{configure}
20718 command line options to specify which such external software to use.
20719 The options have one of these forms:
20721 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
20724 --with-@var{package}@r{[}=@var{arg}@r{]}
20725 --without-@var{package}
20728 For example, @option{--with-gnu-ld} means work with the GNU linker
20729 instead of some other linker. @option{--with-x} means work with The X
20732 The user can give an argument by following the package name with
20733 @samp{=} and the argument. Giving an argument of @samp{no} is for
20734 packages that are used by default; it says to @emph{not} use the
20735 package. An argument that is neither @samp{yes} nor @samp{no} could
20736 include a name or number of a version of the other package, to specify
20737 more precisely which other package this program is supposed to work
20738 with. If no argument is given, it defaults to @samp{yes}.
20739 @option{--without-@var{package}} is equivalent to
20740 @option{--with-@var{package}=no}.
20742 Normally @command{configure} scripts complain about
20743 @option{--with-@var{package}} options that they do not support.
20744 @xref{Option Checking}, for details, and for how to override the
20747 For each external software package that may be used, @file{configure.ac}
20748 should call @code{AC_ARG_WITH} to detect whether the @command{configure}
20749 user asked to use it. Whether each package is used or not by default,
20750 and which arguments are valid, is up to you.
20752 @anchor{AC_ARG_WITH}
20753 @defmac AC_ARG_WITH (@var{package}, @var{help-string}, @
20754 @ovar{action-if-given}, @ovar{action-if-not-given})
20756 If the user gave @command{configure} the option @option{--with-@var{package}}
20757 or @option{--without-@var{package}}, run shell commands
20758 @var{action-if-given}. If neither option was given, run shell commands
20759 @var{action-if-not-given}. The name @var{package} indicates another
20760 software package that this program should work with. It should consist
20761 only of alphanumeric characters, dashes, plus signs, and dots.
20763 The option's argument is available to the shell commands
20764 @var{action-if-given} in the shell variable @code{withval}, which is
20765 actually just the value of the shell variable named
20766 @code{with_@var{package}}, with any non-alphanumeric characters in
20767 @var{package} changed into @samp{_}. You may use that variable instead,
20770 The argument @var{help-string} is a description of the option that
20773 --with-readline support fancy command line editing
20777 @var{help-string} may be more than one line long, if more detail is
20778 needed. Just make sure the columns line up in @samp{configure
20779 --help}. Avoid tabs in the help string. The easiest way to provide the
20780 proper leading whitespace is to format your @var{help-string} with the macro
20781 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
20783 The following example shows how to use the @code{AC_ARG_WITH} macro in
20784 a common situation. You want to let the user decide whether to enable
20785 support for an external library (e.g., the readline library); if the user
20786 specified neither @option{--with-readline} nor @option{--without-readline},
20787 you want to enable support for readline only if the library is available
20790 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
20792 AC_ARG_WITH([readline],
20793 [AS_HELP_STRING([--with-readline],
20794 [support fancy command line editing @@<:@@default=check@@:>@@])],
20796 [with_readline=check])
20799 AS_IF([test "x$with_readline" != xno],
20800 [AC_CHECK_LIB([readline], [main],
20801 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
20802 AC_DEFINE([HAVE_LIBREADLINE], [1],
20803 [Define if you have libreadline])
20805 [if test "x$with_readline" != xcheck; then
20807 [--with-readline was given, but test for readline failed])
20812 The next example shows how to use @code{AC_ARG_WITH} to give the user the
20813 possibility to enable support for the readline library, in case it is still
20814 experimental and not well tested, and is therefore disabled by default.
20816 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
20818 AC_ARG_WITH([readline],
20819 [AS_HELP_STRING([--with-readline],
20820 [enable experimental support for readline])],
20822 [with_readline=no])
20825 AS_IF([test "x$with_readline" != xno],
20826 [AC_CHECK_LIB([readline], [main],
20827 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
20828 AC_DEFINE([HAVE_LIBREADLINE], [1],
20829 [Define if you have libreadline])
20832 [--with-readline was given, but test for readline failed])],
20836 The last example shows how to use @code{AC_ARG_WITH} to give the user the
20837 possibility to disable support for the readline library, given that it is
20838 an important feature and that it should be enabled by default.
20840 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
20842 AC_ARG_WITH([readline],
20843 [AS_HELP_STRING([--without-readline],
20844 [disable support for readline])],
20846 [with_readline=yes])
20849 AS_IF([test "x$with_readline" != xno],
20850 [AC_CHECK_LIB([readline], [main],
20851 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
20852 AC_DEFINE([HAVE_LIBREADLINE], [1],
20853 [Define if you have libreadline])
20856 [readline test failed (--without-readline to disable)])],
20860 These three examples can be easily adapted to the case where
20861 @code{AC_ARG_ENABLE} should be preferred to @code{AC_ARG_WITH} (see
20862 @ref{Package Options}).
20865 @node Package Options
20866 @section Choosing Package Options
20867 @cindex Package options
20868 @cindex Options, package
20870 If a software package has optional compile-time features, the user can
20871 give @command{configure} command line options to specify whether to
20872 compile them. The options have one of these forms:
20874 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
20877 --enable-@var{feature}@r{[}=@var{arg}@r{]}
20878 --disable-@var{feature}
20881 These options allow users to choose which optional features to build and
20882 install. @option{--enable-@var{feature}} options should never make a
20883 feature behave differently or cause one feature to replace another.
20884 They should only cause parts of the program to be built rather than left
20887 The user can give an argument by following the feature name with
20888 @samp{=} and the argument. Giving an argument of @samp{no} requests
20889 that the feature @emph{not} be made available. A feature with an
20890 argument looks like @option{--enable-debug=stabs}. If no argument is
20891 given, it defaults to @samp{yes}. @option{--disable-@var{feature}} is
20892 equivalent to @option{--enable-@var{feature}=no}.
20894 Normally @command{configure} scripts complain about
20895 @option{--enable-@var{package}} options that they do not support.
20896 @xref{Option Checking}, for details, and for how to override the
20899 For each optional feature, @file{configure.ac} should call
20900 @code{AC_ARG_ENABLE} to detect whether the @command{configure} user asked
20901 to include it. Whether each feature is included or not by default, and
20902 which arguments are valid, is up to you.
20904 @anchor{AC_ARG_ENABLE}
20905 @defmac AC_ARG_ENABLE (@var{feature}, @var{help-string}, @
20906 @ovar{action-if-given}, @ovar{action-if-not-given})
20907 @acindex{ARG_ENABLE}
20908 If the user gave @command{configure} the option
20909 @option{--enable-@var{feature}} or @option{--disable-@var{feature}}, run
20910 shell commands @var{action-if-given}. If neither option was given, run
20911 shell commands @var{action-if-not-given}. The name @var{feature}
20912 indicates an optional user-level facility. It should consist only of
20913 alphanumeric characters, dashes, plus signs, and dots.
20915 The option's argument is available to the shell commands
20916 @var{action-if-given} in the shell variable @code{enableval}, which is
20917 actually just the value of the shell variable named
20918 @code{enable_@var{feature}}, with any non-alphanumeric characters in
20919 @var{feature} changed into @samp{_}. You may use that variable instead,
20920 if you wish. The @var{help-string} argument is like that of
20921 @code{AC_ARG_WITH} (@pxref{External Software}).
20923 You should format your @var{help-string} with the macro
20924 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
20926 See the examples suggested with the definition of @code{AC_ARG_WITH}
20927 (@pxref{External Software}) to get an idea of possible applications of
20928 @code{AC_ARG_ENABLE}.
20931 @node Pretty Help Strings
20932 @section Making Your Help Strings Look Pretty
20933 @cindex Help strings
20935 Properly formatting the @samp{help strings} which are used in
20936 @code{AC_ARG_WITH} (@pxref{External Software}) and @code{AC_ARG_ENABLE}
20937 (@pxref{Package Options}) can be challenging. Specifically, you want
20938 your own @samp{help strings} to line up in the appropriate columns of
20939 @samp{configure --help} just like the standard Autoconf @samp{help
20940 strings} do. This is the purpose of the @code{AS_HELP_STRING} macro.
20942 @anchor{AS_HELP_STRING}
20943 @defmac AS_HELP_STRING (@var{left-hand-side}, @var{right-hand-side} @
20944 @dvar{indent-column, 26}, @dvar{wrap-column, 79})
20945 @asindex{HELP_STRING}
20947 Expands into a help string that looks pretty when the user executes
20948 @samp{configure --help}. It is typically used in @code{AC_ARG_WITH}
20949 (@pxref{External Software}) or @code{AC_ARG_ENABLE} (@pxref{Package
20950 Options}). The following example makes this clearer.
20954 [AS_HELP_STRING([--with-foo],
20955 [use foo (default is no)])],
20956 [use_foo=$withval],
20960 Then the last few lines of @samp{configure --help} appear like
20964 --enable and --with options recognized:
20965 --with-foo use foo (default is no)
20968 Macro expansion is performed on the first argument. However, the second
20969 argument of @code{AS_HELP_STRING} is treated as a whitespace separated
20970 list of text to be reformatted, and is not subject to macro expansion.
20971 Since it is not expanded, it should not be double quoted.
20972 @xref{Autoconf Language}, for a more detailed explanation.
20974 The @code{AS_HELP_STRING} macro is particularly helpful when the
20975 @var{left-hand-side} and/or @var{right-hand-side} are composed of macro
20976 arguments, as shown in the following example. Be aware that
20977 @var{left-hand-side} may not expand to unbalanced quotes,
20978 although quadrigraphs can be used.
20981 AC_DEFUN([MY_ARG_WITH],
20982 [AC_ARG_WITH(m4_translit([[$1]], [_], [-]),
20983 [AS_HELP_STRING([--with-m4_translit([$1], [_], [-])],
20984 [use $1 (default is $2)])],
20985 [use_[]$1=$withval],
20987 MY_ARG_WITH([a_b], [no])
20990 Here, the last few lines of @samp{configure --help} will include:
20993 --enable and --with options recognized:
20994 --with-a-b use a_b (default is no)
20997 The parameters @var{indent-column} and @var{wrap-column} were introduced
20998 in Autoconf 2.62. Generally, they should not be specified; they exist
20999 for fine-tuning of the wrapping.
21001 AS_HELP_STRING([--option], [description of option])
21002 @result{} --option description of option
21003 AS_HELP_STRING([--option], [description of option], [15], [30])
21004 @result{} --option description of
21010 @node Option Checking
21011 @section Controlling Checking of @command{configure} Options
21012 @cindex Options, Package
21014 The @command{configure} script checks its command-line options against a
21015 list of known options, like @option{--help} or @option{--config-cache}.
21016 An unknown option ordinarily indicates a mistake by the user and
21017 @command{configure} halts with an error. However, by default unknown
21018 @option{--with-@var{package}} and @option{--enable-@var{feature}}
21019 options elicit only a warning, to support configuring entire source
21022 Source trees often contain multiple packages with a top-level
21023 @command{configure} script that uses the @code{AC_CONFIG_SUBDIRS} macro
21024 (@pxref{Subdirectories}). Because the packages generally support
21025 different @option{--with-@var{package}} and
21026 @option{--enable-@var{feature}} options, the GNU Coding
21027 Standards say they must accept unrecognized options without halting.
21028 Even a warning message is undesirable here, so @code{AC_CONFIG_SUBDIRS}
21029 automatically disables the warnings.
21031 This default behavior may be modified in two ways. First, the installer
21032 can invoke @code{configure --disable-option-checking} to disable
21033 these warnings, or invoke @code{configure --enable-option-checking=fatal}
21034 options to turn them into fatal errors, respectively. Second, the
21035 maintainer can use @code{AC_DISABLE_OPTION_CHECKING}.
21037 @defmac AC_DISABLE_OPTION_CHECKING
21038 @acindex{DISABLE_OPTION_CHECKING}
21040 By default, disable warnings related to any unrecognized
21041 @option{--with-@var{package}} or @option{--enable-@var{feature}}
21042 options. This is implied by @code{AC_CONFIG_SUBDIRS}.
21044 The installer can override this behavior by passing
21045 @option{--enable-option-checking} (enable warnings) or
21046 @option{--enable-option-checking=fatal} (enable errors) to
21047 @command{configure}.
21052 @section Configuring Site Details
21053 @cindex Site details
21055 Some software packages require complex site-specific information. Some
21056 examples are host names to use for certain services, company names, and
21057 email addresses to contact. Since some configuration scripts generated
21058 by Metaconfig ask for such information interactively, people sometimes
21059 wonder how to get that information in Autoconf-generated configuration
21060 scripts, which aren't interactive.
21062 Such site configuration information should be put in a file that is
21063 edited @emph{only by users}, not by programs. The location of the file
21064 can either be based on the @code{prefix} variable, or be a standard
21065 location such as the user's home directory. It could even be specified
21066 by an environment variable. The programs should examine that file at
21067 runtime, rather than at compile time. Runtime configuration is more
21068 convenient for users and makes the configuration process simpler than
21069 getting the information while configuring. @xref{Directory Variables, ,
21070 Variables for Installation Directories, standards, GNU Coding
21071 Standards}, for more information on where to put data files.
21073 @node Transforming Names
21074 @section Transforming Program Names When Installing
21075 @cindex Transforming program names
21076 @cindex Program names, transforming
21078 Autoconf supports changing the names of programs when installing them.
21079 In order to use these transformations, @file{configure.ac} must call the
21080 macro @code{AC_ARG_PROGRAM}.
21082 @defmac AC_ARG_PROGRAM
21083 @acindex{ARG_PROGRAM}
21084 @ovindex program_transform_name
21085 Place in output variable @code{program_transform_name} a sequence of
21086 @code{sed} commands for changing the names of installed programs.
21088 If any of the options described below are given to @command{configure},
21089 program names are transformed accordingly. Otherwise, if
21090 @code{AC_CANONICAL_TARGET} has been called and a @option{--target} value
21091 is given, the target type followed by a dash is used as a prefix.
21092 Otherwise, no program name transformation is done.
21096 * Transformation Options:: @command{configure} options to transform names
21097 * Transformation Examples:: Sample uses of transforming names
21098 * Transformation Rules:: Makefile uses of transforming names
21101 @node Transformation Options
21102 @subsection Transformation Options
21104 You can specify name transformations by giving @command{configure} these
21105 command line options:
21108 @item --program-prefix=@var{prefix}
21109 prepend @var{prefix} to the names;
21111 @item --program-suffix=@var{suffix}
21112 append @var{suffix} to the names;
21114 @item --program-transform-name=@var{expression}
21115 perform @code{sed} substitution @var{expression} on the names.
21118 @node Transformation Examples
21119 @subsection Transformation Examples
21121 These transformations are useful with programs that can be part of a
21122 cross-compilation development environment. For example, a
21123 cross-assembler running on a Sun 4 configured with
21124 @option{--target=i960-vxworks} is normally installed as
21125 @file{i960-vxworks-as}, rather than @file{as}, which could be confused
21126 with a native Sun 4 assembler.
21128 You can force a program name to begin with @file{g}, if you don't want
21129 GNU programs installed on your system to shadow other programs with
21130 the same name. For example, if you configure GNU @code{diff} with
21131 @option{--program-prefix=g}, then when you run @samp{make install} it is
21132 installed as @file{/usr/local/bin/gdiff}.
21134 As a more sophisticated example, you could use
21137 --program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/'
21141 to prepend @samp{g} to most of the program names in a source tree,
21142 excepting those like @code{gdb} that already have one and those like
21143 @code{less} and @code{lesskey} that aren't GNU programs. (That is
21144 assuming that you have a source tree containing those programs that is
21145 set up to use this feature.)
21147 One way to install multiple versions of some programs simultaneously is
21148 to append a version number to the name of one or both. For example, if
21149 you want to keep Autoconf version 1 around for awhile, you can configure
21150 Autoconf version 2 using @option{--program-suffix=2} to install the
21151 programs as @file{/usr/local/bin/autoconf2},
21152 @file{/usr/local/bin/autoheader2}, etc. Nevertheless, pay attention
21153 that only the binaries are renamed, therefore you'd have problems with
21154 the library files which might overlap.
21156 @node Transformation Rules
21157 @subsection Transformation Rules
21159 Here is how to use the variable @code{program_transform_name} in a
21160 @file{Makefile.in}:
21163 PROGRAMS = cp ls rm
21164 transform = @@program_transform_name@@
21166 for p in $(PROGRAMS); do \
21167 $(INSTALL_PROGRAM) $$p $(DESTDIR)$(bindir)/`echo $$p | \
21168 sed '$(transform)'`; \
21172 for p in $(PROGRAMS); do \
21173 rm -f $(DESTDIR)$(bindir)/`echo $$p | sed '$(transform)'`; \
21174 @c $$ restore font-lock
21178 It is guaranteed that @code{program_transform_name} is never empty, and
21179 that there are no useless separators. Therefore you may safely embed
21180 @code{program_transform_name} within a sed program using @samp{;}:
21183 transform = @@program_transform_name@@
21184 transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/
21187 Whether to do the transformations on documentation files (Texinfo or
21188 @code{man}) is a tricky question; there seems to be no perfect answer,
21189 due to the several reasons for name transforming. Documentation is not
21190 usually particular to a specific architecture, and Texinfo files do not
21191 conflict with system documentation. But they might conflict with
21192 earlier versions of the same files, and @code{man} pages sometimes do
21193 conflict with system documentation. As a compromise, it is probably
21194 best to do name transformations on @code{man} pages but not on Texinfo
21197 @node Site Defaults
21198 @section Setting Site Defaults
21199 @cindex Site defaults
21200 @cindex config.site
21202 Autoconf-generated @command{configure} scripts allow your site to provide
21203 default values for some configuration values. You do this by creating
21204 site- and system-wide initialization files.
21206 @evindex CONFIG_SITE
21207 If the environment variable @code{CONFIG_SITE} is set, @command{configure}
21208 uses its value as the name of a shell script to read; it is recommended
21209 that this be an absolute file name. Otherwise, it
21210 reads the shell script @file{@var{prefix}/share/config.site} if it exists,
21211 then @file{@var{prefix}/etc/config.site} if it exists. Thus,
21212 settings in machine-specific files override those in machine-independent
21213 ones in case of conflict.
21215 Site files can be arbitrary shell scripts, but only certain kinds of
21216 code are really appropriate to be in them. Because @command{configure}
21217 reads any cache file after it has read any site files, a site file can
21218 define a default cache file to be shared between all Autoconf-generated
21219 @command{configure} scripts run on that system (@pxref{Cache Files}). If
21220 you set a default cache file in a site file, it is a good idea to also
21221 set the output variable @code{CC} in that site file, because the cache
21222 file is only valid for a particular compiler, but many systems have
21225 You can examine or override the value set by a command line option to
21226 @command{configure} in a site file; options set shell variables that have
21227 the same names as the options, with any dashes turned into underscores.
21228 The exceptions are that @option{--without-} and @option{--disable-} options
21229 are like giving the corresponding @option{--with-} or @option{--enable-}
21230 option and the value @samp{no}. Thus, @option{--cache-file=localcache}
21231 sets the variable @code{cache_file} to the value @samp{localcache};
21232 @option{--enable-warnings=no} or @option{--disable-warnings} sets the variable
21233 @code{enable_warnings} to the value @samp{no}; @option{--prefix=/usr} sets the
21234 variable @code{prefix} to the value @samp{/usr}; etc.
21236 Site files are also good places to set default values for other output
21237 variables, such as @code{CFLAGS}, if you need to give them non-default
21238 values: anything you would normally do, repetitively, on the command
21239 line. If you use non-default values for @var{prefix} or
21240 @var{exec_prefix} (wherever you locate the site file), you can set them
21241 in the site file if you specify it with the @code{CONFIG_SITE}
21242 environment variable.
21244 You can set some cache values in the site file itself. Doing this is
21245 useful if you are cross-compiling, where it is impossible to check features
21246 that require running a test program. You could ``prime the cache'' by
21247 setting those values correctly for that system in
21248 @file{@var{prefix}/etc/config.site}. To find out the names of the cache
21249 variables you need to set, see the documentation of the respective
21250 Autoconf macro. If the variables or their semantics are undocumented,
21251 you may need to look for shell variables with @samp{_cv_} in their names
21252 in the affected @command{configure} scripts, or in the Autoconf M4
21253 source code for those macros; but in that case, their name or semantics
21254 may change in a future Autoconf version.
21256 The cache file is careful to not override any variables set in the site
21257 files. Similarly, you should not override command-line options in the
21258 site files. Your code should check that variables such as @code{prefix}
21259 and @code{cache_file} have their default values (as set near the top of
21260 @command{configure}) before changing them.
21262 Here is a sample file @file{/usr/share/local/@/gnu/share/@/config.site}. The
21263 command @samp{configure --prefix=/usr/share/local/gnu} would read this
21264 file (if @code{CONFIG_SITE} is not set to a different file).
21267 # /usr/share/local/gnu/share/config.site for configure
21269 # Change some defaults.
21270 test "$prefix" = NONE && prefix=/usr/share/local/gnu
21271 test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu
21272 test "$sharedstatedir" = '$@{prefix@}/com' && sharedstatedir=/var
21273 test "$localstatedir" = '$@{prefix@}/var' && localstatedir=/var
21275 # Give Autoconf 2.x generated configure scripts a shared default
21276 # cache file for feature test results, architecture-specific.
21277 if test "$cache_file" = /dev/null; then
21278 cache_file="$prefix/var/config.cache"
21279 # A cache file is only valid for one C compiler.
21284 @cindex Filesystem Hierarchy Standard
21287 Another use of @file{config.site} is for priming the directory variables
21288 in a manner consistent with the Filesystem Hierarchy Standard
21289 (FHS). Once the following file is installed at
21290 @file{/usr/share/config.site}, a user can execute simply
21291 @code{./configure --prefix=/usr} to get all the directories chosen in
21292 the locations recommended by FHS.
21295 # /usr/share/config.site for FHS defaults when installing below /usr,
21296 # and the respective settings were not changed on the command line.
21297 if test "$prefix" = /usr; then
21298 test "$sysconfdir" = '$@{prefix@}/etc' && sysconfdir=/etc
21299 test "$sharedstatedir" = '$@{prefix@}/com' && sharedstatedir=/var
21300 test "$localstatedir" = '$@{prefix@}/var' && localstatedir=/var
21305 @cindex 64-bit libraries
21306 Likewise, on platforms where 64-bit libraries are built by default, then
21307 installed in @file{/usr/local/@/lib64} instead of @file{/usr/local/@/lib},
21308 it is appropriate to install @file{/usr/local/@/share/config.site}:
21311 # /usr/local/share/config.site for platforms that prefer
21312 # the directory /usr/local/lib64 over /usr/local/lib.
21313 test "$libdir" = '$@{exec_prefix@}/lib' && libdir='$@{exec_prefix@}/lib64'
21317 @c ============================================== Running configure Scripts.
21319 @node Running configure Scripts
21320 @chapter Running @command{configure} Scripts
21321 @cindex @command{configure}
21323 Below are instructions on how to configure a package that uses a
21324 @command{configure} script, suitable for inclusion as an @file{INSTALL}
21325 file in the package. A plain-text version of @file{INSTALL} which you
21326 may use comes with Autoconf.
21329 * Basic Installation:: Instructions for typical cases
21330 * Compilers and Options:: Selecting compilers and optimization
21331 * Multiple Architectures:: Compiling for multiple architectures at once
21332 * Installation Names:: Installing in different directories
21333 * Optional Features:: Selecting optional features
21334 * Particular Systems:: Particular systems
21335 * System Type:: Specifying the system type
21336 * Sharing Defaults:: Setting site-wide defaults for @command{configure}
21337 * Defining Variables:: Specifying the compiler etc.
21338 * configure Invocation:: Changing how @command{configure} runs
21342 @include install.texi
21345 @c ============================================== config.status Invocation
21347 @node config.status Invocation
21348 @chapter config.status Invocation
21349 @cindex @command{config.status}
21351 The @command{configure} script creates a file named @file{config.status},
21352 which actually configures, @dfn{instantiates}, the template files. It
21353 also records the configuration options that were specified when the
21354 package was last configured in case reconfiguring is needed.
21358 ./config.status @ovar{option}@dots{} @ovar{tag}@dots{}
21361 It configures each @var{tag}; if none are specified, all the templates
21362 are instantiated. A @var{tag} refers to a file or other tag associated
21363 with a configuration action, as specified by an @code{AC_CONFIG_@var{ITEMS}}
21364 macro (@pxref{Configuration Actions}). The files must be specified
21365 without their dependencies, as in
21368 ./config.status foobar
21375 ./config.status foobar:foo.in:bar.in
21378 The supported options are:
21383 Print a summary of the command line options, the list of the template
21388 Print the version number of Autoconf and the configuration settings,
21392 Print the configuration settings in reusable way, quoted for the shell,
21393 and exit. For example, for a debugging build that otherwise reuses the
21394 configuration from a different build directory @var{build-dir} of a
21395 package in @var{src-dir}, you could use the following:
21398 args=`@var{build-dir}/config.status --config`
21399 eval @var{src-dir}/configure "$args" CFLAGS=-g --srcdir=@var{src-dir}
21403 Note that it may be necessary to override a @option{--srcdir} setting
21404 that was saved in the configuration, if the arguments are used in a
21405 different build directory.
21410 Do not print progress messages.
21414 Don't remove the temporary files.
21416 @item --file=@var{file}[:@var{template}]
21417 Require that @var{file} be instantiated as if
21418 @samp{AC_CONFIG_FILES(@var{file}:@var{template})} was used. Both
21419 @var{file} and @var{template} may be @samp{-} in which case the standard
21420 output and/or standard input, respectively, is used. If a
21421 @var{template} file name is relative, it is first looked for in the build
21422 tree, and then in the source tree. @xref{Configuration Actions}, for
21425 This option and the following ones provide one way for separately
21426 distributed packages to share the values computed by @command{configure}.
21427 Doing so can be useful if some of the packages need a superset of the
21428 features that one of them, perhaps a common library, does. These
21429 options allow a @file{config.status} file to create files other than the
21430 ones that its @file{configure.ac} specifies, so it can be used for a
21431 different package, or for extracting a subset of values. For example,
21434 echo '@@CC@@' | ./config.status --file=-
21438 provides the value of @code{@@CC@@} on standard output.
21440 @item --header=@var{file}[:@var{template}]
21441 Same as @option{--file} above, but with @samp{AC_CONFIG_HEADERS}.
21444 Ask @file{config.status} to update itself and exit (no instantiation).
21445 This option is useful if you change @command{configure}, so that the
21446 results of some tests might be different from the previous run. The
21447 @option{--recheck} option reruns @command{configure} with the same arguments
21448 you used before, plus the @option{--no-create} option, which prevents
21449 @command{configure} from running @file{config.status} and creating
21450 @file{Makefile} and other files, and the @option{--no-recursion} option,
21451 which prevents @command{configure} from running other @command{configure}
21452 scripts in subdirectories. (This is so other Make rules can
21453 run @file{config.status} when it changes; @pxref{Automatic Remaking},
21457 @file{config.status} checks several optional environment variables that
21458 can alter its behavior:
21460 @anchor{CONFIG_SHELL}
21461 @defvar CONFIG_SHELL
21462 @evindex CONFIG_SHELL
21463 The shell with which to run @command{configure} for the @option{--recheck}
21464 option. It must be Bourne-compatible. The default is a shell that
21465 supports @code{LINENO} if available, and @file{/bin/sh} otherwise.
21466 Invoking @command{configure} by hand bypasses this setting, so you may
21467 need to use a command like @samp{CONFIG_SHELL=/bin/bash /bin/bash ./configure}
21468 to insure that the same shell is used everywhere. The absolute name of the
21469 shell should be passed.
21472 @defvar CONFIG_STATUS
21473 @evindex CONFIG_STATUS
21474 The file name to use for the shell script that records the
21475 configuration. The default is @file{./config.status}. This variable is
21476 useful when one package uses parts of another and the @command{configure}
21477 scripts shouldn't be merged because they are maintained separately.
21480 You can use @file{./config.status} in your makefiles. For example, in
21481 the dependencies given above (@pxref{Automatic Remaking}),
21482 @file{config.status} is run twice when @file{configure.ac} has changed.
21483 If that bothers you, you can make each run only regenerate the files for
21488 stamp-h: config.h.in config.status
21489 ./config.status config.h
21492 Makefile: Makefile.in config.status
21493 ./config.status Makefile
21497 The calling convention of @file{config.status} has changed; see
21498 @ref{Obsolete config.status Use}, for details.
21501 @c =================================================== Obsolete Constructs
21503 @node Obsolete Constructs
21504 @chapter Obsolete Constructs
21505 @cindex Obsolete constructs
21507 Autoconf changes, and throughout the years some constructs have been
21508 obsoleted. Most of the changes involve the macros, but in some cases
21509 the tools themselves, or even some concepts, are now considered
21512 You may completely skip this chapter if you are new to Autoconf. Its
21513 intention is mainly to help maintainers updating their packages by
21514 understanding how to move to more modern constructs.
21517 * Obsolete config.status Use:: Obsolete convention for @command{config.status}
21518 * acconfig Header:: Additional entries in @file{config.h.in}
21519 * autoupdate Invocation:: Automatic update of @file{configure.ac}
21520 * Obsolete Macros:: Backward compatibility macros
21521 * Autoconf 1:: Tips for upgrading your files
21522 * Autoconf 2.13:: Some fresher tips
21525 @node Obsolete config.status Use
21526 @section Obsolete @file{config.status} Invocation
21528 @file{config.status} now supports arguments to specify the files to
21529 instantiate; see @ref{config.status Invocation}, for more details.
21530 Before, environment variables had to be used.
21532 @defvar CONFIG_COMMANDS
21533 @evindex CONFIG_COMMANDS
21534 The tags of the commands to execute. The default is the arguments given
21535 to @code{AC_OUTPUT} and @code{AC_CONFIG_COMMANDS} in
21536 @file{configure.ac}.
21539 @defvar CONFIG_FILES
21540 @evindex CONFIG_FILES
21541 The files in which to perform @samp{@@@var{variable}@@} substitutions.
21542 The default is the arguments given to @code{AC_OUTPUT} and
21543 @code{AC_CONFIG_FILES} in @file{configure.ac}.
21546 @defvar CONFIG_HEADERS
21547 @evindex CONFIG_HEADERS
21548 The files in which to substitute C @code{#define} statements. The
21549 default is the arguments given to @code{AC_CONFIG_HEADERS}; if that
21550 macro was not called, @file{config.status} ignores this variable.
21553 @defvar CONFIG_LINKS
21554 @evindex CONFIG_LINKS
21555 The symbolic links to establish. The default is the arguments given to
21556 @code{AC_CONFIG_LINKS}; if that macro was not called,
21557 @file{config.status} ignores this variable.
21560 In @ref{config.status Invocation}, using this old interface, the example
21566 stamp-h: config.h.in config.status
21567 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \
21568 CONFIG_HEADERS=config.h ./config.status
21571 Makefile: Makefile.in config.status
21572 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \
21573 CONFIG_FILES=Makefile ./config.status
21578 (If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is
21579 no need to set @code{CONFIG_HEADERS} in the @command{make} rules. Equally
21580 for @code{CONFIG_COMMANDS}, etc.)
21583 @node acconfig Header
21584 @section @file{acconfig.h}
21586 @cindex @file{acconfig.h}
21587 @cindex @file{config.h.top}
21588 @cindex @file{config.h.bot}
21590 In order to produce @file{config.h.in}, @command{autoheader} needs to
21591 build or to find templates for each symbol. Modern releases of Autoconf
21592 use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader
21593 Macros}), but in older releases a file, @file{acconfig.h}, contained the
21594 list of needed templates. @command{autoheader} copied comments and
21595 @code{#define} and @code{#undef} statements from @file{acconfig.h} in
21596 the current directory, if present. This file used to be mandatory if
21597 you @code{AC_DEFINE} any additional symbols.
21599 Modern releases of Autoconf also provide @code{AH_TOP} and
21600 @code{AH_BOTTOM} if you need to prepend/append some information to
21601 @file{config.h.in}. Ancient versions of Autoconf had a similar feature:
21602 if @file{./acconfig.h} contains the string @samp{@@TOP@@},
21603 @command{autoheader} copies the lines before the line containing
21604 @samp{@@TOP@@} into the top of the file that it generates. Similarly,
21605 if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@},
21606 @command{autoheader} copies the lines after that line to the end of the
21607 file it generates. Either or both of those strings may be omitted. An
21608 even older alternate way to produce the same effect in ancient versions
21609 of Autoconf is to create the files @file{@var{file}.top} (typically
21610 @file{config.h.top}) and/or @file{@var{file}.bot} in the current
21611 directory. If they exist, @command{autoheader} copies them to the
21612 beginning and end, respectively, of its output.
21614 In former versions of Autoconf, the files used in preparing a software
21615 package for distribution were:
21618 configure.ac --. .------> autoconf* -----> configure
21620 [aclocal.m4] --+ `---.
21622 +--> [autoheader*] -> [config.h.in]
21623 [acconfig.h] ----. |
21630 Using only the @code{AH_} macros, @file{configure.ac} should be
21631 self-contained, and should not depend upon @file{acconfig.h} etc.
21634 @node autoupdate Invocation
21635 @section Using @command{autoupdate} to Modernize @file{configure.ac}
21636 @cindex @command{autoupdate}
21638 The @command{autoupdate} program updates a @file{configure.ac} file that
21639 calls Autoconf macros by their old names to use the current macro names.
21640 In version 2 of Autoconf, most of the macros were renamed to use a more
21641 uniform and descriptive naming scheme. @xref{Macro Names}, for a
21642 description of the new scheme. Although the old names still work
21643 (@pxref{Obsolete Macros}, for a list of the old macros and the corresponding
21644 new names), you can make your @file{configure.ac} files more readable
21645 and make it easier to use the current Autoconf documentation if you
21646 update them to use the new macro names.
21648 @evindex SIMPLE_BACKUP_SUFFIX
21649 If given no arguments, @command{autoupdate} updates @file{configure.ac},
21650 backing up the original version with the suffix @file{~} (or the value
21651 of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is
21652 set). If you give @command{autoupdate} an argument, it reads that file
21653 instead of @file{configure.ac} and writes the updated file to the
21657 @command{autoupdate} accepts the following options:
21662 Print a summary of the command line options and exit.
21666 Print the version number of Autoconf and exit.
21670 Report processing steps.
21674 Don't remove the temporary files.
21678 Force the update even if the file has not changed. Disregard the cache.
21680 @item --include=@var{dir}
21681 @itemx -I @var{dir}
21682 Also look for input files in @var{dir}. Multiple invocations accumulate.
21683 Directories are browsed from last to first.
21685 @item --prepend-include=@var{dir}
21686 @itemx -B @var{dir}
21687 Prepend directory @var{dir} to the search path. This is used to include
21688 the language-specific files before any third-party macros.
21691 @node Obsolete Macros
21692 @section Obsolete Macros
21694 Several macros are obsoleted in Autoconf, for various reasons (typically
21695 they failed to quote properly, couldn't be extended for more recent
21696 issues, etc.). They are still supported, but deprecated: their use
21699 During the jump from Autoconf version 1 to version 2, most of the
21700 macros were renamed to use a more uniform and descriptive naming scheme,
21701 but their signature did not change. @xref{Macro Names}, for a
21702 description of the new naming scheme. Below, if there is just the mapping
21703 from old names to new names for these macros, the reader is invited to
21704 refer to the definition of the new macro for the signature and the
21709 @cvindex _ALL_SOURCE
21710 This macro is a platform-specific subset of
21711 @code{AC_USE_SYSTEM_EXTENSIONS} (@pxref{AC_USE_SYSTEM_EXTENSIONS}).
21716 Replaced by @code{AC_FUNC_ALLOCA} (@pxref{AC_FUNC_ALLOCA}).
21719 @defmac AC_ARG_ARRAY
21720 @acindex{ARG_ARRAY}
21721 Removed because of limited usefulness.
21726 This macro is obsolete; it does nothing.
21729 @defmac AC_C_LONG_DOUBLE
21730 @acindex{C_LONG_DOUBLE}
21731 @cvindex HAVE_LONG_DOUBLE
21732 If the C compiler supports a working @code{long double} type with more
21733 range or precision than the @code{double} type, define
21734 @code{HAVE_LONG_DOUBLE}.
21736 You should use @code{AC_TYPE_LONG_DOUBLE} or
21737 @code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}.
21740 @defmac AC_CANONICAL_SYSTEM
21741 @acindex{CANONICAL_SYSTEM}
21742 Determine the system type and set output variables to the names of the
21743 canonical system types. @xref{Canonicalizing}, for details about the
21744 variables this macro sets.
21746 The user is encouraged to use either @code{AC_CANONICAL_BUILD}, or
21747 @code{AC_CANONICAL_HOST}, or @code{AC_CANONICAL_TARGET}, depending on
21748 the needs. Using @code{AC_CANONICAL_TARGET} is enough to run the two
21749 other macros (@pxref{Canonicalizing}).
21752 @defmac AC_CHAR_UNSIGNED
21753 @acindex{CHAR_UNSIGNED}
21754 Replaced by @code{AC_C_CHAR_UNSIGNED} (@pxref{AC_C_CHAR_UNSIGNED}).
21757 @defmac AC_CHECK_TYPE (@var{type}, @var{default})
21758 @acindex{CHECK_TYPE}
21759 Autoconf, up to 2.13, used to provide this version of
21760 @code{AC_CHECK_TYPE}, deprecated because of its flaws. First, although
21761 it is a member of the @code{CHECK} clan, it does
21762 more than just checking. Secondly, missing types are defined
21763 using @code{#define}, not @code{typedef}, and this can lead to
21764 problems in the case of pointer types.
21766 This use of @code{AC_CHECK_TYPE} is obsolete and discouraged; see
21767 @ref{Generic Types}, for the description of the current macro.
21769 If the type @var{type} is not defined, define it to be the C (or C++)
21770 builtin type @var{default}, e.g., @samp{short int} or @samp{unsigned int}.
21772 This macro is equivalent to:
21775 AC_CHECK_TYPE([@var{type}], [],
21776 [AC_DEFINE_UNQUOTED([@var{type}], [@var{default}],
21777 [Define to `@var{default}'
21778 if <sys/types.h> does not define.])])
21781 In order to keep backward compatibility, the two versions of
21782 @code{AC_CHECK_TYPE} are implemented, selected using these heuristics:
21786 If there are three or four arguments, the modern version is used.
21789 If the second argument appears to be a C or C++ type, then the
21790 obsolete version is used. This happens if the argument is a C or C++
21791 @emph{builtin} type or a C identifier ending in @samp{_t}, optionally
21792 followed by one of @samp{[(* } and then by a string of zero or more
21793 characters taken from the set @samp{[]()* _a-zA-Z0-9}.
21796 If the second argument is spelled with the alphabet of valid C and C++
21797 types, the user is warned and the modern version is used.
21800 Otherwise, the modern version is used.
21804 You are encouraged either to use a valid builtin type, or to use the
21805 equivalent modern code (see above), or better yet, to use
21806 @code{AC_CHECK_TYPES} together with
21809 #ifndef HAVE_LOFF_T
21810 typedef loff_t off_t;
21814 @c end of AC_CHECK_TYPE
21816 @defmac AC_CHECKING (@var{feature-description})
21821 AC_MSG_NOTICE([checking @var{feature-description}@dots{}]
21825 @xref{AC_MSG_NOTICE}.
21828 @defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @
21829 @var{function-body}, @var{action-if-true}, @ovar{action-if-false})
21830 @acindex{COMPILE_CHECK}
21831 This is an obsolete version of @code{AC_TRY_COMPILE} itself replaced by
21832 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}), with the
21833 addition that it prints @samp{checking for @var{echo-text}} to the
21834 standard output first, if @var{echo-text} is non-empty. Use
21835 @code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT} instead to print
21836 messages (@pxref{Printing Messages}).
21841 Replaced by @code{AC_C_CONST} (@pxref{AC_C_CONST}).
21844 @defmac AC_CROSS_CHECK
21845 @acindex{CROSS_CHECK}
21846 Same as @code{AC_C_CROSS}, which is obsolete too, and does nothing
21853 Check for the Cygwin environment in which case the shell variable
21854 @code{CYGWIN} is set to @samp{yes}. Don't use this macro, the dignified
21855 means to check the nature of the host is using @code{AC_CANONICAL_HOST}
21856 (@pxref{Canonicalizing}). As a matter of fact this macro is defined as:
21859 AC_REQUIRE([AC_CANONICAL_HOST])[]dnl
21861 *cygwin* ) CYGWIN=yes;;
21866 Beware that the variable @env{CYGWIN} has a special meaning when
21867 running Cygwin, and should not be changed. That's yet another reason
21868 not to use this macro.
21871 @defmac AC_DECL_SYS_SIGLIST
21872 @acindex{DECL_SYS_SIGLIST}
21873 @cvindex SYS_SIGLIST_DECLARED
21877 AC_CHECK_DECLS([sys_siglist], [], [],
21878 [#include <signal.h>
21879 /* NetBSD declares sys_siglist in unistd.h. */
21880 #ifdef HAVE_UNISTD_H
21881 # include <unistd.h>
21887 @xref{AC_CHECK_DECLS}.
21890 @defmac AC_DECL_YYTEXT
21891 @acindex{DECL_YYTEXT}
21892 Does nothing, now integrated in @code{AC_PROG_LEX} (@pxref{AC_PROG_LEX}).
21895 @defmac AC_DIR_HEADER
21896 @acindex{DIR_HEADER}
21901 Like calling @code{AC_FUNC_CLOSEDIR_VOID}
21902 (@pxref{AC_FUNC_CLOSEDIR_VOID}) and @code{AC_HEADER_DIRENT}
21903 (@pxref{AC_HEADER_DIRENT}),
21904 but defines a different set of C preprocessor macros to indicate which
21905 header file is found:
21907 @multitable {@file{sys/ndir.h}} {Old Symbol} {@code{HAVE_SYS_NDIR_H}}
21908 @item Header @tab Old Symbol @tab New Symbol
21909 @item @file{dirent.h} @tab @code{DIRENT} @tab @code{HAVE_DIRENT_H}
21910 @item @file{sys/ndir.h} @tab @code{SYSNDIR} @tab @code{HAVE_SYS_NDIR_H}
21911 @item @file{sys/dir.h} @tab @code{SYSDIR} @tab @code{HAVE_SYS_DIR_H}
21912 @item @file{ndir.h} @tab @code{NDIR} @tab @code{HAVE_NDIR_H}
21916 @defmac AC_DYNIX_SEQ
21917 @acindex{DYNIX_SEQ}
21918 If on DYNIX/ptx, add @option{-lseq} to output variable
21919 @code{LIBS}. This macro used to be defined as
21922 AC_CHECK_LIB([seq], [getmntent], [LIBS="-lseq $LIBS"])
21926 now it is just @code{AC_FUNC_GETMNTENT} (@pxref{AC_FUNC_GETMNTENT}).
21932 Defined the output variable @code{EXEEXT} based on the output of the
21933 compiler, which is now done automatically. Typically set to empty
21934 string if Posix and @samp{.exe} if a DOS variant.
21939 Similar to @code{AC_CYGWIN} but checks for the EMX environment on OS/2
21940 and sets @code{EMXOS2}. Don't use this macro, the dignified means to
21941 check the nature of the host is using @code{AC_CANONICAL_HOST}
21942 (@pxref{Canonicalizing}).
21945 @defmac AC_ENABLE (@var{feature}, @var{action-if-given}, @
21946 @ovar{action-if-not-given})
21948 This is an obsolete version of @code{AC_ARG_ENABLE} that does not
21949 support providing a help string (@pxref{AC_ARG_ENABLE}).
21954 Replaced by @code{AC_MSG_ERROR} (@pxref{AC_MSG_ERROR}).
21959 Replaced by @code{AC_PATH_X} (@pxref{AC_PATH_X}).
21962 @defmac AC_FIND_XTRA
21963 @acindex{FIND_XTRA}
21964 Replaced by @code{AC_PATH_XTRA} (@pxref{AC_PATH_XTRA}).
21969 Replaced by @code{m4_foreach_w} (@pxref{m4_foreach_w}).
21972 @defmac AC_FUNC_CHECK
21973 @acindex{FUNC_CHECK}
21974 Replaced by @code{AC_CHECK_FUNC} (@pxref{AC_CHECK_FUNC}).
21977 @anchor{AC_FUNC_SETVBUF_REVERSED}
21978 @defmac AC_FUNC_SETVBUF_REVERSED
21979 @acindex{FUNC_SETVBUF_REVERSED}
21980 @cvindex SETVBUF_REVERSED
21981 @c @fuindex setvbuf
21982 @prindex @code{setvbuf}
21983 Do nothing. Formerly, this macro checked whether @code{setvbuf} takes
21984 the buffering type as its second argument and the buffer pointer as the
21985 third, instead of the other way around, and defined
21986 @code{SETVBUF_REVERSED}. However, the last systems to have the problem
21987 were those based on SVR2, which became obsolete in 1987, and the macro
21988 is no longer needed.
21991 @defmac AC_FUNC_WAIT3
21992 @acindex{FUNC_WAIT3}
21993 @cvindex HAVE_WAIT3
21995 @prindex @code{wait3}
21996 If @code{wait3} is found and fills in the contents of its third argument
21997 (a @samp{struct rusage *}), which HP-UX does not do, define
22000 These days portable programs should use @code{waitpid}, not
22001 @code{wait3}, as @code{wait3} has been removed from Posix.
22004 @defmac AC_GCC_TRADITIONAL
22005 @acindex{GCC_TRADITIONAL}
22006 Replaced by @code{AC_PROG_GCC_TRADITIONAL} (@pxref{AC_PROG_GCC_TRADITIONAL}).
22009 @defmac AC_GETGROUPS_T
22010 @acindex{GETGROUPS_T}
22011 Replaced by @code{AC_TYPE_GETGROUPS} (@pxref{AC_TYPE_GETGROUPS}).
22014 @defmac AC_GETLOADAVG
22015 @acindex{GETLOADAVG}
22016 Replaced by @code{AC_FUNC_GETLOADAVG} (@pxref{AC_FUNC_GETLOADAVG}).
22019 @defmac AC_GNU_SOURCE
22020 @acindex{GNU_SOURCE}
22021 @cvindex _GNU_SOURCE
22022 This macro is a platform-specific subset of
22023 @code{AC_USE_SYSTEM_EXTENSIONS} (@pxref{AC_USE_SYSTEM_EXTENSIONS}).
22026 @defmac AC_HAVE_FUNCS
22027 @acindex{HAVE_FUNCS}
22028 Replaced by @code{AC_CHECK_FUNCS} (@pxref{AC_CHECK_FUNCS}).
22031 @defmac AC_HAVE_HEADERS
22032 @acindex{HAVE_HEADERS}
22033 Replaced by @code{AC_CHECK_HEADERS} (@pxref{AC_CHECK_HEADERS}).
22036 @defmac AC_HAVE_LIBRARY (@var{library}, @ovar{action-if-found}, @
22037 @ovar{action-if-not-found}, @ovar{other-libraries})
22038 @acindex{HAVE_LIBRARY}
22039 This macro is equivalent to calling @code{AC_CHECK_LIB} with a
22040 @var{function} argument of @code{main}. In addition, @var{library} can
22041 be written as any of @samp{foo}, @option{-lfoo}, or @samp{libfoo.a}. In
22042 all of those cases, the compiler is passed @option{-lfoo}. However,
22043 @var{library} cannot be a shell variable; it must be a literal name.
22044 @xref{AC_CHECK_LIB}.
22047 @defmac AC_HAVE_POUNDBANG
22048 @acindex{HAVE_POUNDBANG}
22049 Replaced by @code{AC_SYS_INTERPRETER} (@pxref{AC_SYS_INTERPRETER}).
22052 @defmac AC_HEADER_CHECK
22053 @acindex{HEADER_CHECK}
22054 Replaced by @code{AC_CHECK_HEADER} (@pxref{AC_CHECK_HEADER}).
22057 @defmac AC_HEADER_EGREP
22058 @acindex{HEADER_EGREP}
22059 Replaced by @code{AC_EGREP_HEADER} (@pxref{AC_EGREP_HEADER}).
22062 @defmac AC_HELP_STRING
22063 @acindex{HELP_STRING}
22064 Replaced by @code{AS_HELP_STRING} (@pxref{AS_HELP_STRING}).
22067 @defmac AC_INIT (@var{unique-file-in-source-dir})
22069 Formerly @code{AC_INIT} used to have a single argument, and was
22074 AC_CONFIG_SRCDIR(@var{unique-file-in-source-dir})
22076 See @ref{AC_INIT} and @ref{AC_CONFIG_SRCDIR}.
22081 Replaced by @code{AC_C_INLINE} (@pxref{AC_C_INLINE}).
22084 @defmac AC_INT_16_BITS
22085 @acindex{INT_16_BITS}
22086 @cvindex INT_16_BITS
22087 If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}.
22088 Use @samp{AC_CHECK_SIZEOF(int)} instead (@pxref{AC_CHECK_SIZEOF}).
22091 @defmac AC_IRIX_SUN
22093 If on IRIX (Silicon Graphics Unix), add @option{-lsun} to output
22094 @code{LIBS}. If you were using it to get @code{getmntent}, use
22095 @code{AC_FUNC_GETMNTENT} instead. If you used it for the NIS versions
22096 of the password and group functions, use @samp{AC_CHECK_LIB(sun,
22097 getpwnam)}. Up to Autoconf 2.13, it used to be
22100 AC_CHECK_LIB([sun], [getmntent], [LIBS="-lsun $LIBS"])
22104 now it is defined as
22108 AC_CHECK_LIB([sun], [getpwnam])
22112 See @ref{AC_FUNC_GETMNTENT} and @ref{AC_CHECK_LIB}.
22115 @defmac AC_ISC_POSIX
22116 @acindex{ISC_POSIX}
22118 This macro adds @option{-lcposix} to output variable @code{LIBS} if
22119 necessary for Posix facilities. Sun dropped support for the obsolete
22120 INTERACTIVE Systems Corporation Unix on 2006-07-23. New programs
22121 need not use this macro. It is implemented as
22122 @code{AC_SEARCH_LIBS([strerror], [cposix])} (@pxref{AC_SEARCH_LIBS}).
22127 Same as @samp{AC_LANG([C])} (@pxref{AC_LANG}).
22130 @defmac AC_LANG_CPLUSPLUS
22131 @acindex{LANG_CPLUSPLUS}
22132 Same as @samp{AC_LANG([C++])} (@pxref{AC_LANG}).
22135 @defmac AC_LANG_FORTRAN77
22136 @acindex{LANG_FORTRAN77}
22137 Same as @samp{AC_LANG([Fortran 77])} (@pxref{AC_LANG}).
22140 @defmac AC_LANG_RESTORE
22141 @acindex{LANG_RESTORE}
22142 Select the @var{language} that is saved on the top of the stack, as set
22143 by @code{AC_LANG_SAVE}, remove it from the stack, and call
22144 @code{AC_LANG(@var{language})}. @xref{Language Choice}, for the
22145 preferred way to change languages.
22148 @defmac AC_LANG_SAVE
22149 @acindex{LANG_SAVE}
22150 Remember the current language (as set by @code{AC_LANG}) on a stack.
22151 The current language does not change. @code{AC_LANG_PUSH} is preferred
22152 (@pxref{AC_LANG_PUSH}).
22155 @defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{})
22156 @acindex{LINK_FILES}
22157 This is an obsolete version of @code{AC_CONFIG_LINKS}
22158 (@pxref{AC_CONFIG_LINKS}. An updated version of:
22161 AC_LINK_FILES(config/$machine.h config/$obj_format.h,
22169 AC_CONFIG_LINKS([host.h:config/$machine.h
22170 object.h:config/$obj_format.h])
22176 Replaced by @code{AC_PROG_LN_S} (@pxref{AC_PROG_LN_S}).
22179 @defmac AC_LONG_64_BITS
22180 @acindex{LONG_64_BITS}
22181 @cvindex LONG_64_BITS
22182 Define @code{LONG_64_BITS} if the C type @code{long int} is 64 bits wide.
22183 Use the generic macro @samp{AC_CHECK_SIZEOF([long int])} instead
22184 (@pxref{AC_CHECK_SIZEOF}).
22187 @defmac AC_LONG_DOUBLE
22188 @acindex{LONG_DOUBLE}
22189 If the C compiler supports a working @code{long double} type with more
22190 range or precision than the @code{double} type, define
22191 @code{HAVE_LONG_DOUBLE}.
22193 You should use @code{AC_TYPE_LONG_DOUBLE} or
22194 @code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}.
22197 @defmac AC_LONG_FILE_NAMES
22198 @acindex{LONG_FILE_NAMES}
22201 AC_SYS_LONG_FILE_NAMES
22204 @xref{AC_SYS_LONG_FILE_NAMES}.
22207 @defmac AC_MAJOR_HEADER
22208 @acindex{MAJOR_HEADER}
22209 Replaced by @code{AC_HEADER_MAJOR} (@pxref{AC_HEADER_MAJOR}).
22212 @defmac AC_MEMORY_H
22214 @cvindex NEED_MEMORY_H
22215 Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were
22216 defined in @file{memory.h}. Today it is equivalent to
22217 @samp{AC_CHECK_HEADERS([memory.h])} (@pxref{AC_CHECK_HEADERS}). Adjust
22218 your code to depend upon
22219 @code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}; see @ref{Standard
22225 Similar to @code{AC_CYGWIN} but checks for the MinGW compiler
22226 environment and sets @code{MINGW32}. Don't use this macro, the
22227 dignified means to check the nature of the host is using
22228 @code{AC_CANONICAL_HOST} (@pxref{Canonicalizing}).
22234 @cvindex _POSIX_SOURCE
22235 @cvindex _POSIX_1_SOURCE
22236 This macro is a platform-specific subset of
22237 @code{AC_USE_SYSTEM_EXTENSIONS} (@pxref{AC_USE_SYSTEM_EXTENSIONS}).
22240 @defmac AC_MINUS_C_MINUS_O
22241 @acindex{MINUS_C_MINUS_O}
22242 Replaced by @code{AC_PROG_CC_C_O} (@pxref{AC_PROG_CC_C_O}).
22247 Replaced by @code{AC_FUNC_MMAP} (@pxref{AC_FUNC_MMAP}).
22252 Replaced by @code{AC_TYPE_MODE_T} (@pxref{AC_TYPE_MODE_T}).
22258 Defined the output variable @code{OBJEXT} based on the output of the
22259 compiler, after .c files have been excluded. Typically set to @samp{o}
22260 if Posix, @samp{obj} if a DOS variant.
22261 Now the compiler checking macros handle
22262 this automatically.
22265 @defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion})
22267 Make M4 print a message to the standard error output warning that
22268 @var{this-macro-name} is obsolete, and giving the file and line number
22269 where it was called. @var{this-macro-name} should be the name of the
22270 macro that is calling @code{AC_OBSOLETE}. If @var{suggestion} is given,
22271 it is printed at the end of the warning message; for example, it can be
22272 a suggestion for what to use instead of @var{this-macro-name}.
22277 AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl
22281 You are encouraged to use @code{AU_DEFUN} instead, since it gives better
22282 services to the user (@pxref{AU_DEFUN}).
22287 Replaced by @code{AC_TYPE_OFF_T} (@pxref{AC_TYPE_OFF_T}).
22290 @defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds})
22292 The use of @code{AC_OUTPUT} with arguments is deprecated. This obsoleted
22293 interface is equivalent to:
22297 AC_CONFIG_FILES(@var{file}@dots{})
22298 AC_CONFIG_COMMANDS([default],
22299 @var{extra-cmds}, @var{init-cmds})
22305 See @ref{AC_CONFIG_FILES}, @ref{AC_CONFIG_COMMANDS}, and @ref{AC_OUTPUT}.
22308 @defmac AC_OUTPUT_COMMANDS (@var{extra-cmds}, @ovar{init-cmds})
22309 @acindex{OUTPUT_COMMANDS}
22310 Specify additional shell commands to run at the end of
22311 @file{config.status}, and shell commands to initialize any variables
22312 from @command{configure}. This macro may be called multiple times. It is
22313 obsolete, replaced by @code{AC_CONFIG_COMMANDS} (@pxref{AC_CONFIG_COMMANDS}).
22315 Here is an unrealistic example:
22319 AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.],
22321 AC_OUTPUT_COMMANDS([echo this is another, extra, bit],
22325 Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an
22326 additional key, an important difference is that
22327 @code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, unlike
22328 @code{AC_CONFIG_COMMANDS}. This means that @code{AC_CONFIG_COMMANDS}
22329 can safely be given macro calls as arguments:
22332 AC_CONFIG_COMMANDS(foo, [my_FOO()])
22336 Conversely, where one level of quoting was enough for literal strings
22337 with @code{AC_OUTPUT_COMMANDS}, you need two with
22338 @code{AC_CONFIG_COMMANDS}. The following lines are equivalent:
22342 AC_OUTPUT_COMMANDS([echo "Square brackets: []"])
22343 AC_CONFIG_COMMANDS([default], [[echo "Square brackets: []"]])
22350 Replaced by @code{AC_TYPE_PID_T} (@pxref{AC_TYPE_PID_T}).
22355 Replaced by @code{AC_PREFIX_PROGRAM} (@pxref{AC_PREFIX_PROGRAM}).
22358 @defmac AC_PROGRAMS_CHECK
22359 @acindex{PROGRAMS_CHECK}
22360 Replaced by @code{AC_CHECK_PROGS} (@pxref{AC_CHECK_PROGS}).
22363 @defmac AC_PROGRAMS_PATH
22364 @acindex{PROGRAMS_PATH}
22365 Replaced by @code{AC_PATH_PROGS} (@pxref{AC_PATH_PROGS}).
22368 @defmac AC_PROGRAM_CHECK
22369 @acindex{PROGRAM_CHECK}
22370 Replaced by @code{AC_CHECK_PROG} (@pxref{AC_CHECK_PROG}).
22373 @defmac AC_PROGRAM_EGREP
22374 @acindex{PROGRAM_EGREP}
22375 Replaced by @code{AC_EGREP_CPP} (@pxref{AC_EGREP_CPP}).
22378 @defmac AC_PROGRAM_PATH
22379 @acindex{PROGRAM_PATH}
22380 Replaced by @code{AC_PATH_PROG} (@pxref{AC_PATH_PROG}).
22383 @defmac AC_REMOTE_TAPE
22384 @acindex{REMOTE_TAPE}
22385 Removed because of limited usefulness.
22388 @defmac AC_RESTARTABLE_SYSCALLS
22389 @acindex{RESTARTABLE_SYSCALLS}
22390 This macro was renamed @code{AC_SYS_RESTARTABLE_SYSCALLS}. However,
22391 these days portable programs should use @code{sigaction} with
22392 @code{SA_RESTART} if they want restartable system calls. They should
22393 not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a
22394 system call is restartable is a dynamic issue, not a configuration-time
22398 @defmac AC_RETSIGTYPE
22399 @acindex{RETSIGTYPE}
22400 Replaced by @code{AC_TYPE_SIGNAL} (@pxref{AC_TYPE_SIGNAL}), which itself
22401 is obsolete when assuming C89 or better.
22406 Removed because of limited usefulness.
22409 @defmac AC_SCO_INTL
22412 If on SCO Unix, add @option{-lintl} to output variable @code{LIBS}. This
22413 macro used to do this:
22416 AC_CHECK_LIB([intl], [strftime], [LIBS="-lintl $LIBS"])
22420 Now it just calls @code{AC_FUNC_STRFTIME} instead (@pxref{AC_FUNC_STRFTIME}).
22423 @defmac AC_SETVBUF_REVERSED
22424 @acindex{SETVBUF_REVERSED}
22427 AC_FUNC_SETVBUF_REVERSED
22430 @xref{AC_FUNC_SETVBUF_REVERSED}.
22433 @defmac AC_SET_MAKE
22435 Replaced by @code{AC_PROG_MAKE_SET} (@pxref{AC_PROG_MAKE_SET}).
22438 @defmac AC_SIZEOF_TYPE
22439 @acindex{SIZEOF_TYPE}
22440 Replaced by @code{AC_CHECK_SIZEOF} (@pxref{AC_CHECK_SIZEOF}).
22445 Replaced by @code{AC_TYPE_SIZE_T} (@pxref{AC_TYPE_SIZE_T}).
22448 @defmac AC_STAT_MACROS_BROKEN
22449 @acindex{STAT_MACROS_BROKEN}
22450 Replaced by @code{AC_HEADER_STAT} (@pxref{AC_HEADER_STAT}).
22453 @defmac AC_STDC_HEADERS
22454 @acindex{STDC_HEADERS}
22455 Replaced by @code{AC_HEADER_STDC} (@pxref{AC_HEADER_STDC}).
22460 Replaced by @code{AC_FUNC_STRCOLL} (@pxref{AC_FUNC_STRCOLL}).
22463 @defmac AC_STRUCT_ST_BLKSIZE
22464 @acindex{STRUCT_ST_BLKSIZE}
22465 @cvindex HAVE_STRUCT_STAT_ST_BLKSIZE
22466 @cvindex HAVE_ST_BLKSIZE
22467 If @code{struct stat} contains an @code{st_blksize} member, define
22468 @code{HAVE_STRUCT_STAT_ST_BLKSIZE}. The former name,
22469 @code{HAVE_ST_BLKSIZE} is to be avoided, as its support will cease in
22470 the future. This macro is obsoleted, and should be replaced by
22473 AC_CHECK_MEMBERS([struct stat.st_blksize])
22476 @xref{AC_CHECK_MEMBERS}.
22479 @defmac AC_STRUCT_ST_RDEV
22480 @acindex{STRUCT_ST_RDEV}
22481 @cvindex HAVE_ST_RDEV
22482 @cvindex HAVE_STRUCT_STAT_ST_RDEV
22483 If @code{struct stat} contains an @code{st_rdev} member, define
22484 @code{HAVE_STRUCT_STAT_ST_RDEV}. The former name for this macro,
22485 @code{HAVE_ST_RDEV}, is to be avoided as it will cease to be supported
22486 in the future. Actually, even the new macro is obsolete and should be
22489 AC_CHECK_MEMBERS([struct stat.st_rdev])
22492 @xref{AC_CHECK_MEMBERS}.
22495 @defmac AC_ST_BLKSIZE
22496 @acindex{ST_BLKSIZE}
22497 Replaced by @code{AC_CHECK_MEMBERS} (@pxref{AC_CHECK_MEMBERS}).
22500 @defmac AC_ST_BLOCKS
22501 @acindex{ST_BLOCKS}
22502 Replaced by @code{AC_STRUCT_ST_BLOCKS} (@pxref{AC_STRUCT_ST_BLOCKS}).
22507 Replaced by @code{AC_CHECK_MEMBERS} (@pxref{AC_CHECK_MEMBERS}).
22510 @defmac AC_SYS_RESTARTABLE_SYSCALLS
22511 @acindex{SYS_RESTARTABLE_SYSCALLS}
22512 @cvindex HAVE_RESTARTABLE_SYSCALLS
22513 If the system automatically restarts a system call that is interrupted
22514 by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}. This macro does
22515 not check whether system calls are restarted in general---it checks whether a
22516 signal handler installed with @code{signal} (but not @code{sigaction})
22517 causes system calls to be restarted. It does not check whether system calls
22518 can be restarted when interrupted by signals that have no handler.
22520 These days portable programs should use @code{sigaction} with
22521 @code{SA_RESTART} if they want restartable system calls. They should
22522 not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a
22523 system call is restartable is a dynamic issue, not a configuration-time
22527 @defmac AC_SYS_SIGLIST_DECLARED
22528 @acindex{SYS_SIGLIST_DECLARED}
22529 This macro was renamed @code{AC_DECL_SYS_SIGLIST}. However, even that
22530 name is obsolete, as the same functionality is now acheived via
22531 @code{AC_CHECK_DECLS} (@pxref{AC_CHECK_DECLS}).
22534 @defmac AC_TEST_CPP
22536 This macro was renamed @code{AC_TRY_CPP}, which in turn was replaced by
22537 @code{AC_PREPROC_IFELSE} (@pxref{AC_PREPROC_IFELSE}).
22540 @defmac AC_TEST_PROGRAM
22541 @acindex{TEST_PROGRAM}
22542 This macro was renamed @code{AC_TRY_RUN}, which in turn was replaced by
22543 @code{AC_RUN_IFELSE} (@pxref{AC_RUN_IFELSE}).
22546 @defmac AC_TIMEZONE
22548 Replaced by @code{AC_STRUCT_TIMEZONE} (@pxref{AC_STRUCT_TIMEZONE}).
22551 @defmac AC_TIME_WITH_SYS_TIME
22552 @acindex{TIME_WITH_SYS_TIME}
22553 Replaced by @code{AC_HEADER_TIME} (@pxref{AC_HEADER_TIME}).
22556 @defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @
22557 @ovar{action-if-true}, @ovar{action-if-false})
22558 @acindex{TRY_COMPILE}
22563 [AC_LANG_PROGRAM([[@var{includes}]],
22564 [[@var{function-body}]])],
22565 [@var{action-if-true}],
22566 [@var{action-if-false}])
22570 @xref{Running the Compiler}.
22572 This macro double quotes both @var{includes} and @var{function-body}.
22574 For C and C++, @var{includes} is any @code{#include} statements needed
22575 by the code in @var{function-body} (@var{includes} is ignored if
22576 the currently selected language is Fortran or Fortran 77). The compiler
22577 and compilation flags are determined by the current language
22578 (@pxref{Language Choice}).
22581 @defmac AC_TRY_CPP (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
22587 [AC_LANG_SOURCE([[@var{input}]])],
22588 [@var{action-if-true}],
22589 [@var{action-if-false}])
22593 @xref{Running the Preprocessor}.
22595 This macro double quotes the @var{input}.
22598 @defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @
22599 @ovar{action-if-true}, @ovar{action-if-false})
22605 [AC_LANG_PROGRAM([[@var{includes}]],
22606 [[@var{function-body}]])],
22607 [@var{action-if-true}],
22608 [@var{action-if-false}])
22612 @xref{Running the Compiler}.
22614 This macro double quotes both @var{includes} and @var{function-body}.
22616 Depending on the current language (@pxref{Language Choice}), create a
22617 test program to see whether a function whose body consists of
22618 @var{function-body} can be compiled and linked. If the file compiles
22619 and links successfully, run shell commands @var{action-if-found},
22620 otherwise run @var{action-if-not-found}.
22622 This macro double quotes both @var{includes} and @var{function-body}.
22624 For C and C++, @var{includes} is any @code{#include} statements needed
22625 by the code in @var{function-body} (@var{includes} is ignored if
22626 the currently selected language is Fortran or Fortran 77). The compiler
22627 and compilation flags are determined by the current language
22628 (@pxref{Language Choice}), and in addition @code{LDFLAGS} and
22629 @code{LIBS} are used for linking.
22632 @defmac AC_TRY_LINK_FUNC (@var{function}, @ovar{action-if-found}, @
22633 @ovar{action-if-not-found})
22634 @acindex{TRY_LINK_FUNC}
22635 This macro is equivalent to
22637 AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])],
22638 [@var{action-if-found}], [@var{action-if-not-found}])
22641 @xref{AC_LINK_IFELSE}.
22644 @defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @
22645 @ovar{action-if-false}, @ovar{action-if-cross-compiling})
22651 [AC_LANG_SOURCE([[@var{program}]])],
22652 [@var{action-if-true}],
22653 [@var{action-if-false}],
22654 [@var{action-if-cross-compiling}])
22661 @anchor{AC_TYPE_SIGNAL}
22662 @defmac AC_TYPE_SIGNAL
22663 @acindex{TYPE_SIGNAL}
22664 @cvindex RETSIGTYPE
22665 @hdrindex{signal.h}
22666 If @file{signal.h} declares @code{signal} as returning a pointer to a
22667 function returning @code{void}, define @code{RETSIGTYPE} to be
22668 @code{void}; otherwise, define it to be @code{int}. These days, it is
22669 portable to assume C89, and that signal handlers return @code{void},
22670 without needing to use this macro or @code{RETSIGTYPE}.
22672 When targetting older K&R C, it is possible to define signal handlers as
22673 returning type @code{RETSIGTYPE}, and omit a return statement:
22688 Replaced by @code{AC_TYPE_UID_T} (@pxref{AC_TYPE_UID_T}).
22691 @defmac AC_UNISTD_H
22693 Same as @samp{AC_CHECK_HEADERS([unistd.h])} (@pxref{AC_CHECK_HEADERS}).
22699 Define @code{USG} if the BSD string functions are defined in
22700 @file{strings.h}. You should no longer depend upon @code{USG}, but on
22701 @code{HAVE_STRING_H}; see @ref{Standard Symbols}.
22704 @defmac AC_UTIME_NULL
22705 @acindex{UTIME_NULL}
22706 Replaced by @code{AC_FUNC_UTIME_NULL} (@pxref{AC_FUNC_UTIME_NULL}).
22709 @defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@ovar{cmd})
22710 @acindex{VALIDATE_CACHED_SYSTEM_TUPLE}
22711 If the cache file is inconsistent with the current host, target and
22712 build system types, it used to execute @var{cmd} or print a default
22713 error message. This is now handled by default.
22716 @defmac AC_VERBOSE (@var{result-description})
22718 Replaced by @code{AC_MSG_RESULT} (@pxref{AC_MSG_RESULT}).
22723 Replaced by @code{AC_FUNC_FORK} (@pxref{AC_FUNC_FORK}).
22728 Replaced by @code{AC_FUNC_VPRINTF} (@pxref{AC_FUNC_VPRINTF}).
22733 This macro was renamed @code{AC_FUNC_WAIT3}. However, these days
22734 portable programs should use @code{waitpid}, not @code{wait3}, as
22735 @code{wait3} has been removed from Posix.
22740 Replaced by @code{AC_MSG_WARN} (@pxref{AC_MSG_WARN}).
22743 @defmac AC_WITH (@var{package}, @var{action-if-given}, @
22744 @ovar{action-if-not-given})
22746 This is an obsolete version of @code{AC_ARG_WITH} that does not
22747 support providing a help string (@pxref{AC_ARG_WITH}).
22750 @defmac AC_WORDS_BIGENDIAN
22751 @acindex{WORDS_BIGENDIAN}
22752 Replaced by @code{AC_C_BIGENDIAN} (@pxref{AC_C_BIGENDIAN}).
22755 @defmac AC_XENIX_DIR
22756 @acindex{XENIX_DIR}
22758 This macro used to add @option{-lx} to output variable @code{LIBS} if on
22759 Xenix. Also, if @file{dirent.h} is being checked for, added
22760 @option{-ldir} to @code{LIBS}. Now it is merely an alias of
22761 @code{AC_HEADER_DIRENT} instead, plus some code to detect whether
22762 running XENIX on which you should not depend:
22765 AC_MSG_CHECKING([for Xenix])
22766 AC_EGREP_CPP([yes],
22767 [#if defined M_XENIX && !defined M_UNIX
22770 [AC_MSG_RESULT([yes]); XENIX=yes],
22771 [AC_MSG_RESULT([no]); XENIX=])
22774 Don't use this macro, the dignified means to check the nature of the
22775 host is using @code{AC_CANONICAL_HOST} (@pxref{Canonicalizing}).
22778 @defmac AC_YYTEXT_POINTER
22779 @acindex{YYTEXT_POINTER}
22780 This macro was renamed @code{AC_DECL_YYTEXT}, which in turn was
22781 integrated into @code{AC_PROG_LEX} (@pxref{AC_PROG_LEX}).
22785 @section Upgrading From Version 1
22786 @cindex Upgrading autoconf
22787 @cindex Autoconf upgrading
22789 Autoconf version 2 is mostly backward compatible with version 1.
22790 However, it introduces better ways to do some things, and doesn't
22791 support some of the ugly things in version 1. So, depending on how
22792 sophisticated your @file{configure.ac} files are, you might have to do
22793 some manual work in order to upgrade to version 2. This chapter points
22794 out some problems to watch for when upgrading. Also, perhaps your
22795 @command{configure} scripts could benefit from some of the new features in
22796 version 2; the changes are summarized in the file @file{NEWS} in the
22797 Autoconf distribution.
22800 * Changed File Names:: Files you might rename
22801 * Changed Makefiles:: New things to put in @file{Makefile.in}
22802 * Changed Macros:: Macro calls you might replace
22803 * Changed Results:: Changes in how to check test results
22804 * Changed Macro Writing:: Better ways to write your own macros
22807 @node Changed File Names
22808 @subsection Changed File Names
22810 If you have an @file{aclocal.m4} installed with Autoconf (as opposed to
22811 in a particular package's source directory), you must rename it to
22812 @file{acsite.m4}. @xref{autoconf Invocation}.
22814 If you distribute @file{install.sh} with your package, rename it to
22815 @file{install-sh} so @command{make} builtin rules don't inadvertently
22816 create a file called @file{install} from it. @code{AC_PROG_INSTALL}
22817 looks for the script under both names, but it is best to use the new name.
22819 If you were using @file{config.h.top}, @file{config.h.bot}, or
22820 @file{acconfig.h}, you still can, but you have less clutter if you
22821 use the @code{AH_} macros. @xref{Autoheader Macros}.
22823 @node Changed Makefiles
22824 @subsection Changed Makefiles
22826 Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in
22827 your @file{Makefile.in} files, so they can take advantage of the values
22828 of those variables in the environment when @command{configure} is run.
22829 Doing this isn't necessary, but it's a convenience for users.
22831 Also add @samp{@@configure_input@@} in a comment to each input file for
22832 @code{AC_OUTPUT}, so that the output files contain a comment saying
22833 they were produced by @command{configure}. Automatically selecting the
22834 right comment syntax for all the kinds of files that people call
22835 @code{AC_OUTPUT} on became too much work.
22837 Add @file{config.log} and @file{config.cache} to the list of files you
22838 remove in @code{distclean} targets.
22840 If you have the following in @file{Makefile.in}:
22843 prefix = /usr/local
22844 exec_prefix = $(prefix)
22848 you must change it to:
22851 prefix = @@prefix@@
22852 exec_prefix = @@exec_prefix@@
22856 The old behavior of replacing those variables without @samp{@@}
22857 characters around them has been removed.
22859 @node Changed Macros
22860 @subsection Changed Macros
22862 Many of the macros were renamed in Autoconf version 2. You can still
22863 use the old names, but the new ones are clearer, and it's easier to find
22864 the documentation for them. @xref{Obsolete Macros}, for a table showing the
22865 new names for the old macros. Use the @command{autoupdate} program to
22866 convert your @file{configure.ac} to using the new macro names.
22867 @xref{autoupdate Invocation}.
22869 Some macros have been superseded by similar ones that do the job better,
22870 but are not call-compatible. If you get warnings about calling obsolete
22871 macros while running @command{autoconf}, you may safely ignore them, but
22872 your @command{configure} script generally works better if you follow
22873 the advice that is printed about what to replace the obsolete macros with. In
22874 particular, the mechanism for reporting the results of tests has
22875 changed. If you were using @command{echo} or @code{AC_VERBOSE} (perhaps
22876 via @code{AC_COMPILE_CHECK}), your @command{configure} script's output
22877 looks better if you switch to @code{AC_MSG_CHECKING} and
22878 @code{AC_MSG_RESULT}. @xref{Printing Messages}. Those macros work best
22879 in conjunction with cache variables. @xref{Caching Results}.
22883 @node Changed Results
22884 @subsection Changed Results
22886 If you were checking the results of previous tests by examining the
22887 shell variable @code{DEFS}, you need to switch to checking the values of
22888 the cache variables for those tests. @code{DEFS} no longer exists while
22889 @command{configure} is running; it is only created when generating output
22890 files. This difference from version 1 is because properly quoting the
22891 contents of that variable turned out to be too cumbersome and
22892 inefficient to do every time @code{AC_DEFINE} is called. @xref{Cache
22895 For example, here is a @file{configure.ac} fragment written for Autoconf
22899 AC_HAVE_FUNCS(syslog)
22901 *-DHAVE_SYSLOG*) ;;
22902 *) # syslog is not in the default libraries. See if it's in some other.
22904 for lib in bsd socket inet; do
22905 AC_CHECKING(for syslog in -l$lib)
22906 LIBS="-l$lib $saved_LIBS"
22907 AC_HAVE_FUNCS(syslog)
22909 *-DHAVE_SYSLOG*) break ;;
22917 Here is a way to write it for version 2:
22920 AC_CHECK_FUNCS([syslog])
22921 if test "x$ac_cv_func_syslog" = xno; then
22922 # syslog is not in the default libraries. See if it's in some other.
22923 for lib in bsd socket inet; do
22924 AC_CHECK_LIB([$lib], [syslog], [AC_DEFINE([HAVE_SYSLOG])
22925 LIBS="-l$lib $LIBS"; break])
22930 If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding
22931 backslashes before quotes, you need to remove them. It now works
22932 predictably, and does not treat quotes (except back quotes) specially.
22933 @xref{Setting Output Variables}.
22935 All of the Boolean shell variables set by Autoconf macros now use
22936 @samp{yes} for the true value. Most of them use @samp{no} for false,
22937 though for backward compatibility some use the empty string instead. If
22938 you were relying on a shell variable being set to something like 1 or
22939 @samp{t} for true, you need to change your tests.
22941 @node Changed Macro Writing
22942 @subsection Changed Macro Writing
22944 When defining your own macros, you should now use @code{AC_DEFUN}
22945 instead of @code{define}. @code{AC_DEFUN} automatically calls
22946 @code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE}
22947 do not interrupt other macros, to prevent nested @samp{checking@dots{}}
22948 messages on the screen. There's no actual harm in continuing to use the
22949 older way, but it's less convenient and attractive. @xref{Macro
22952 You probably looked at the macros that came with Autoconf as a guide for
22953 how to do things. It would be a good idea to take a look at the new
22954 versions of them, as the style is somewhat improved and they take
22955 advantage of some new features.
22957 If you were doing tricky things with undocumented Autoconf internals
22958 (macros, variables, diversions), check whether you need to change
22959 anything to account for changes that have been made. Perhaps you can
22960 even use an officially supported technique in version 2 instead of
22961 kludging. Or perhaps not.
22963 To speed up your locally written feature tests, add caching to them.
22964 See whether any of your tests are of general enough usefulness to
22965 encapsulate them into macros that you can share.
22968 @node Autoconf 2.13
22969 @section Upgrading From Version 2.13
22970 @cindex Upgrading autoconf
22971 @cindex Autoconf upgrading
22973 The introduction of the previous section (@pxref{Autoconf 1}) perfectly
22974 suits this section@enddots{}
22977 Autoconf version 2.50 is mostly backward compatible with version 2.13.
22978 However, it introduces better ways to do some things, and doesn't
22979 support some of the ugly things in version 2.13. So, depending on how
22980 sophisticated your @file{configure.ac} files are, you might have to do
22981 some manual work in order to upgrade to version 2.50. This chapter
22982 points out some problems to watch for when upgrading. Also, perhaps
22983 your @command{configure} scripts could benefit from some of the new
22984 features in version 2.50; the changes are summarized in the file
22985 @file{NEWS} in the Autoconf distribution.
22989 * Changed Quotation:: Broken code which used to work
22990 * New Macros:: Interaction with foreign macros
22991 * Hosts and Cross-Compilation:: Bugward compatibility kludges
22992 * AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token
22993 * AC_ACT_IFELSE vs AC_TRY_ACT:: A more generic scheme for testing sources
22996 @node Changed Quotation
22997 @subsection Changed Quotation
22999 The most important changes are invisible to you: the implementation of
23000 most macros have completely changed. This allowed more factorization of
23001 the code, better error messages, a higher uniformity of the user's
23002 interface etc. Unfortunately, as a side effect, some construct which
23003 used to (miraculously) work might break starting with Autoconf 2.50.
23004 The most common culprit is bad quotation.
23006 For instance, in the following example, the message is not properly
23011 AC_CHECK_HEADERS(foo.h, ,
23012 AC_MSG_ERROR(cannot find foo.h, bailing out))
23017 Autoconf 2.13 simply ignores it:
23020 $ @kbd{autoconf-2.13; ./configure --silent}
23021 creating cache ./config.cache
23022 configure: error: cannot find foo.h
23027 while Autoconf 2.50 produces a broken @file{configure}:
23030 $ @kbd{autoconf-2.50; ./configure --silent}
23031 configure: error: cannot find foo.h
23032 ./configure: exit: bad non-numeric arg `bailing'
23033 ./configure: exit: bad non-numeric arg `bailing'
23037 The message needs to be quoted, and the @code{AC_MSG_ERROR} invocation
23041 AC_INIT([Example], [1.0], [bug-example@@example.org])
23042 AC_CHECK_HEADERS([foo.h], [],
23043 [AC_MSG_ERROR([cannot find foo.h, bailing out])])
23047 Many many (and many more) Autoconf macros were lacking proper quotation,
23048 including no less than@dots{} @code{AC_DEFUN} itself!
23051 $ @kbd{cat configure.in}
23052 AC_DEFUN([AC_PROG_INSTALL],
23053 [# My own much better version
23058 $ @kbd{autoconf-2.13}
23059 autoconf: Undefined macros:
23060 ***BUG in Autoconf--please report*** AC_FD_MSG
23061 ***BUG in Autoconf--please report*** AC_EPI
23062 configure.in:1:AC_DEFUN([AC_PROG_INSTALL],
23063 configure.in:5:AC_PROG_INSTALL
23064 $ @kbd{autoconf-2.50}
23070 @subsection New Macros
23072 @cindex undefined macro
23073 @cindex @code{_m4_divert_diversion}
23075 While Autoconf was relatively dormant in the late 1990s, Automake
23076 provided Autoconf-like macros for a while. Starting with Autoconf 2.50
23077 in 2001, Autoconf provided
23078 versions of these macros, integrated in the @code{AC_} namespace,
23079 instead of @code{AM_}. But in order to ease the upgrading via
23080 @command{autoupdate}, bindings to such @code{AM_} macros are provided.
23082 Unfortunately older versions of Automake (e.g., Automake 1.4)
23083 did not quote the names of these macros.
23084 Therefore, when @command{m4} finds something like
23085 @samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, @dots{})} in @file{aclocal.m4},
23086 @code{AM_TYPE_PTRDIFF_T} is
23087 expanded, replaced with its Autoconf definition.
23089 Fortunately Autoconf catches pre-@code{AC_INIT} expansions, and
23090 complains, in its own words:
23093 $ @kbd{cat configure.ac}
23094 AC_INIT([Example], [1.0], [bug-example@@example.org])
23096 $ @kbd{aclocal-1.4}
23098 aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion
23099 aclocal.m4:17: the top level
23100 autom4te: m4 failed with exit status: 1
23104 Modern versions of Automake no longer define most of these
23105 macros, and properly quote the names of the remaining macros.
23106 If you must use an old Automake, do not depend upon macros from Automake
23107 as it is simply not its job
23108 to provide macros (but the one it requires itself):
23111 $ @kbd{cat configure.ac}
23112 AC_INIT([Example], [1.0], [bug-example@@example.org])
23114 $ @kbd{rm aclocal.m4}
23116 autoupdate: `configure.ac' is updated
23117 $ @kbd{cat configure.ac}
23118 AC_INIT([Example], [1.0], [bug-example@@example.org])
23119 AC_CHECK_TYPES([ptrdiff_t])
23120 $ @kbd{aclocal-1.4}
23126 @node Hosts and Cross-Compilation
23127 @subsection Hosts and Cross-Compilation
23128 @cindex Cross compilation
23130 Based on the experience of compiler writers, and after long public
23131 debates, many aspects of the cross-compilation chain have changed:
23135 the relationship between the build, host, and target architecture types,
23138 the command line interface for specifying them to @command{configure},
23141 the variables defined in @command{configure},
23144 the enabling of cross-compilation mode.
23149 The relationship between build, host, and target have been cleaned up:
23150 the chain of default is now simply: target defaults to host, host to
23151 build, and build to the result of @command{config.guess}. Nevertheless,
23152 in order to ease the transition from 2.13 to 2.50, the following
23153 transition scheme is implemented. @emph{Do not rely on it}, as it will
23154 be completely disabled in a couple of releases (we cannot keep it, as it
23155 proves to cause more problems than it cures).
23157 They all default to the result of running @command{config.guess}, unless
23158 you specify either @option{--build} or @option{--host}. In this case,
23159 the default becomes the system type you specified. If you specify both,
23160 and they're different, @command{configure} enters cross compilation
23161 mode, so it doesn't run any tests that require execution.
23163 Hint: if you mean to override the result of @command{config.guess},
23164 prefer @option{--build} over @option{--host}. In the future,
23165 @option{--host} will not override the name of the build system type.
23166 Whenever you specify @option{--host}, be sure to specify @option{--build}
23171 For backward compatibility, @command{configure} accepts a system
23172 type as an option by itself. Such an option overrides the
23173 defaults for build, host, and target system types. The following
23174 configure statement configures a cross toolchain that runs on
23175 NetBSD/alpha but generates code for GNU Hurd/sparc,
23176 which is also the build platform.
23179 ./configure --host=alpha-netbsd sparc-gnu
23184 In Autoconf 2.13 and before, the variables @code{build}, @code{host},
23185 and @code{target} had a different semantics before and after the
23186 invocation of @code{AC_CANONICAL_BUILD} etc. Now, the argument of
23187 @option{--build} is strictly copied into @code{build_alias}, and is left
23188 empty otherwise. After the @code{AC_CANONICAL_BUILD}, @code{build} is
23189 set to the canonicalized build type. To ease the transition, before,
23190 its contents is the same as that of @code{build_alias}. Do @emph{not}
23191 rely on this broken feature.
23193 For consistency with the backward compatibility scheme exposed above,
23194 when @option{--host} is specified but @option{--build} isn't, the build
23195 system is assumed to be the same as @option{--host}, and
23196 @samp{build_alias} is set to that value. Eventually, this
23197 historically incorrect behavior will go away.
23201 The former scheme to enable cross-compilation proved to cause more harm
23202 than good, in particular, it used to be triggered too easily, leaving
23203 regular end users puzzled in front of cryptic error messages.
23204 @command{configure} could even enter cross-compilation mode only
23205 because the compiler was not functional. This is mainly because
23206 @command{configure} used to try to detect cross-compilation, instead of
23207 waiting for an explicit flag from the user.
23209 Now, @command{configure} enters cross-compilation mode if and only if
23210 @option{--host} is passed.
23212 That's the short documentation. To ease the transition between 2.13 and
23213 its successors, a more complicated scheme is implemented. @emph{Do not
23214 rely on the following}, as it will be removed in the near future.
23216 If you specify @option{--host}, but not @option{--build}, when
23217 @command{configure} performs the first compiler test it tries to run
23218 an executable produced by the compiler. If the execution fails, it
23219 enters cross-compilation mode. This is fragile. Moreover, by the time
23220 the compiler test is performed, it may be too late to modify the
23221 build-system type: other tests may have already been performed.
23222 Therefore, whenever you specify @option{--host}, be sure to specify
23223 @option{--build} too.
23226 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
23230 enters cross-compilation mode. The former interface, which
23231 consisted in setting the compiler to a cross-compiler without informing
23232 @command{configure} is obsolete. For instance, @command{configure}
23233 fails if it can't run the code generated by the specified compiler if you
23234 configure as follows:
23237 ./configure CC=m68k-coff-gcc
23241 @node AC_LIBOBJ vs LIBOBJS
23242 @subsection @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}
23244 Up to Autoconf 2.13, the replacement of functions was triggered via the
23245 variable @code{LIBOBJS}. Since Autoconf 2.50, the macro
23246 @code{AC_LIBOBJ} should be used instead (@pxref{Generic Functions}).
23247 Starting at Autoconf 2.53, the use of @code{LIBOBJS} is an error.
23249 This change is mandated by the unification of the GNU Build System
23250 components. In particular, the various fragile techniques used to parse
23251 a @file{configure.ac} are all replaced with the use of traces. As a
23252 consequence, any action must be traceable, which obsoletes critical
23253 variable assignments. Fortunately, @code{LIBOBJS} was the only problem,
23254 and it can even be handled gracefully (read, ``without your having to
23255 change something'').
23257 There were two typical uses of @code{LIBOBJS}: asking for a replacement
23258 function, and adjusting @code{LIBOBJS} for Automake and/or Libtool.
23262 As for function replacement, the fix is immediate: use
23263 @code{AC_LIBOBJ}. For instance:
23266 LIBOBJS="$LIBOBJS fnmatch.o"
23267 LIBOBJS="$LIBOBJS malloc.$ac_objext"
23271 should be replaced with:
23274 AC_LIBOBJ([fnmatch])
23275 AC_LIBOBJ([malloc])
23281 When used with Automake 1.10 or newer, a suitable value for
23282 @code{LIBOBJDIR} is set so that the @code{LIBOBJS} and @code{LTLIBOBJS}
23283 can be referenced from any @file{Makefile.am}. Even without Automake,
23284 arranging for @code{LIBOBJDIR} to be set correctly enables
23285 referencing @code{LIBOBJS} and @code{LTLIBOBJS} in another directory.
23286 The @code{LIBOBJDIR} feature is experimental.
23289 @node AC_ACT_IFELSE vs AC_TRY_ACT
23290 @subsection @code{AC_@var{ACT}_IFELSE} vs.@: @code{AC_TRY_@var{ACT}}
23291 @c the anchor keeps the old node name, to try to avoid breaking links
23292 @anchor{AC_FOO_IFELSE vs AC_TRY_FOO}
23294 @acindex{@var{ACT}_IFELSE}
23295 @acindex{TRY_@var{ACT}}
23296 Since Autoconf 2.50, internal codes uses @code{AC_PREPROC_IFELSE},
23297 @code{AC_COMPILE_IFELSE}, @code{AC_LINK_IFELSE}, and
23298 @code{AC_RUN_IFELSE} on one hand and @code{AC_LANG_SOURCE},
23299 and @code{AC_LANG_PROGRAM} on the other hand instead of the deprecated
23300 @code{AC_TRY_CPP}, @code{AC_TRY_COMPILE}, @code{AC_TRY_LINK}, and
23301 @code{AC_TRY_RUN}. The motivations where:
23304 a more consistent interface: @code{AC_TRY_COMPILE} etc.@: were double
23305 quoting their arguments;
23308 the combinatoric explosion is solved by decomposing on the one hand the
23309 generation of sources, and on the other hand executing the program;
23312 this scheme helps supporting more languages than plain C and C++.
23315 In addition to the change of syntax, the philosophy has changed too:
23316 while emphasis was put on speed at the expense of accuracy, today's
23317 Autoconf promotes accuracy of the testing framework at, ahem@dots{}, the
23321 As a perfect example of what is @emph{not} to be done, here is how to
23322 find out whether a header file contains a particular declaration, such
23323 as a typedef, a structure, a structure member, or a function. Use
23324 @code{AC_EGREP_HEADER} instead of running @code{grep} directly on the
23325 header file; on some systems the symbol might be defined in another
23326 header file that the file you are checking includes.
23328 As a (bad) example, here is how you should not check for C preprocessor
23329 symbols, either defined by header files or predefined by the C
23330 preprocessor: using @code{AC_EGREP_CPP}:
23338 ], is_aix=yes, is_aix=no)
23342 The above example, properly written would (i) use
23343 @code{AC_LANG_PROGRAM}, and (ii) run the compiler:
23347 AC_COMPILE_IFELSE([AC_LANG_PROGRAM(
23349 error: This isn't AIX!
23358 @c ============================= Generating Test Suites with Autotest
23360 @node Using Autotest
23361 @chapter Generating Test Suites with Autotest
23366 @strong{N.B.: This section describes a feature which is still
23367 stabilizing. Although we believe that Autotest is useful as-is, this
23368 documentation describes an interface which might change in the future:
23369 do not depend upon Autotest without subscribing to the Autoconf mailing
23373 It is paradoxical that portable projects depend on nonportable tools
23374 to run their test suite. Autoconf by itself is the paragon of this
23375 problem: although it aims at perfectly portability, up to 2.13 its
23376 test suite was using DejaGNU, a rich and complex testing
23377 framework, but which is far from being standard on Posix systems.
23378 Worse yet, it was likely to be missing on the most fragile platforms,
23379 the very platforms that are most likely to torture Autoconf and
23380 exhibit deficiencies.
23382 To circumvent this problem, many package maintainers have developed their
23383 own testing framework, based on simple shell scripts whose sole outputs
23384 are exit status values describing whether the test succeeded. Most of
23385 these tests share common patterns, and this can result in lots of
23386 duplicated code and tedious maintenance.
23388 Following exactly the same reasoning that yielded to the inception of
23389 Autoconf, Autotest provides a test suite generation framework, based on
23390 M4 macros building a portable shell script. The suite itself is
23391 equipped with automatic logging and tracing facilities which greatly
23392 diminish the interaction with bug reporters, and simple timing reports.
23394 Autoconf itself has been using Autotest for years, and we do attest that
23395 it has considerably improved the strength of the test suite and the
23396 quality of bug reports. Other projects are known to use some generation
23397 of Autotest, such as Bison, Free Recode, Free Wdiff, GNU Tar, each of
23398 them with different needs, and this usage has validated Autotest as a general
23401 Nonetheless, compared to DejaGNU, Autotest is inadequate for
23402 interactive tool testing, which is probably its main limitation.
23405 * Using an Autotest Test Suite:: Autotest and the user
23406 * Writing Testsuites:: Autotest macros
23407 * testsuite Invocation:: Running @command{testsuite} scripts
23408 * Making testsuite Scripts:: Using autom4te to create @command{testsuite}
23411 @node Using an Autotest Test Suite
23412 @section Using an Autotest Test Suite
23415 * testsuite Scripts:: The concepts of Autotest
23416 * Autotest Logs:: Their contents
23419 @node testsuite Scripts
23420 @subsection @command{testsuite} Scripts
23422 @cindex @command{testsuite}
23424 Generating testing or validation suites using Autotest is rather easy.
23425 The whole validation suite is held in a file to be processed through
23426 @command{autom4te}, itself using GNU M4 under the hood, to
23427 produce a stand-alone Bourne shell script which then gets distributed.
23428 Neither @command{autom4te} nor GNU M4 are needed at
23429 the installer's end.
23432 Each test of the validation suite should be part of some test group. A
23433 @dfn{test group} is a sequence of interwoven tests that ought to be
23434 executed together, usually because one test in the group creates data
23435 files than a later test in the same group needs to read. Complex test
23436 groups make later debugging more tedious. It is much better to
23437 keep only a few tests per test group. Ideally there is only one test
23440 For all but the simplest packages, some file such as @file{testsuite.at}
23441 does not fully hold all test sources, as these are often easier to
23442 maintain in separate files. Each of these separate files holds a single
23443 test group, or a sequence of test groups all addressing some common
23444 functionality in the package. In such cases, @file{testsuite.at}
23445 merely initializes the validation suite, and sometimes does elementary
23446 health checking, before listing include statements for all other test
23447 files. The special file @file{package.m4}, containing the
23448 identification of the package, is automatically included if found.
23450 A convenient alternative consists in moving all the global issues
23451 (local Autotest macros, elementary health checking, and @code{AT_INIT}
23452 invocation) into the file @code{local.at}, and making
23453 @file{testsuite.at} be a simple list of @code{m4_include} of sub test
23454 suites. In such case, generating the whole test suite or pieces of it
23455 is only a matter of choosing the @command{autom4te} command line
23458 The validation scripts that Autotest produces are by convention called
23459 @command{testsuite}. When run, @command{testsuite} executes each test
23460 group in turn, producing only one summary line per test to say if that
23461 particular test succeeded or failed. At end of all tests, summarizing
23462 counters get printed. One debugging directory is left for each test
23463 group which failed, if any: such directories are named
23464 @file{testsuite.dir/@var{nn}}, where @var{nn} is the sequence number of
23465 the test group, and they include:
23468 @item a debugging script named @file{run} which reruns the test in
23469 @dfn{debug mode} (@pxref{testsuite Invocation}). The automatic generation
23470 of debugging scripts has the purpose of easing the chase for bugs.
23472 @item all the files created with @code{AT_DATA}
23474 @item all the Erlang source code files created with @code{AT_CHECK_EUNIT}
23476 @item a log of the run, named @file{testsuite.log}
23479 In the ideal situation, none of the tests fail, and consequently no
23480 debugging directory is left behind for validation.
23482 It often happens in practice that individual tests in the validation
23483 suite need to get information coming out of the configuration process.
23484 Some of this information, common for all validation suites, is provided
23485 through the file @file{atconfig}, automatically created by
23486 @code{AC_CONFIG_TESTDIR}. For configuration informations which your
23487 testing environment specifically needs, you might prepare an optional
23488 file named @file{atlocal.in}, instantiated by @code{AC_CONFIG_FILES}.
23489 The configuration process produces @file{atconfig} and @file{atlocal}
23490 out of these two input files, and these two produced files are
23491 automatically read by the @file{testsuite} script.
23493 Here is a diagram showing the relationship between files.
23496 Files used in preparing a software package for distribution:
23501 subfile-1.at ->. [local.at] ---->+
23503 subfile-i.at ---->-- testsuite.at -->-- autom4te* -->testsuite
23509 Files used in configuring a software package:
23514 [atlocal.in] --> config.status* --<
23520 Files created during test suite execution:
23523 atconfig -->. .--> testsuite.log
23527 [atlocal] ->' `--> [testsuite.dir]
23531 @node Autotest Logs
23532 @subsection Autotest Logs
23534 When run, the test suite creates a log file named after itself, e.g., a
23535 test suite named @command{testsuite} creates @file{testsuite.log}. It
23536 contains a lot of information, usually more than maintainers actually
23537 need, but therefore most of the time it contains all that is needed:
23540 @item command line arguments
23541 A bad but unfortunately widespread habit consists of
23542 setting environment variables before the command, such as in
23543 @samp{CC=my-home-grown-cc ./testsuite}. The test suite does not
23544 know this change, hence (i) it cannot report it to you, and (ii)
23545 it cannot preserve the value of @code{CC} for subsequent runs.
23546 Autoconf faced exactly the same problem, and solved it by asking
23547 users to pass the variable definitions as command line arguments.
23548 Autotest requires this rule, too, but has no means to enforce it; the log
23549 then contains a trace of the variables that were changed by the user.
23551 @item @file{ChangeLog} excerpts
23552 The topmost lines of all the @file{ChangeLog} files found in the source
23553 hierarchy. This is especially useful when bugs are reported against
23554 development versions of the package, since the version string does not
23555 provide sufficient information to know the exact state of the sources
23556 the user compiled. Of course, this relies on the use of a
23559 @item build machine
23560 Running a test suite in a cross-compile environment is not an easy task,
23561 since it would mean having the test suite run on a machine @var{build},
23562 while running programs on a machine @var{host}. It is much simpler to
23563 run both the test suite and the programs on @var{host}, but then, from
23564 the point of view of the test suite, there remains a single environment,
23565 @var{host} = @var{build}. The log contains relevant information on the
23566 state of the @var{build} machine, including some important environment
23568 @c FIXME: How about having an M4sh macro to say `hey, log the value
23569 @c of `@dots{}'? This would help both Autoconf and Autotest.
23571 @item tested programs
23572 The absolute file name and answers to @option{--version} of the tested
23573 programs (see @ref{Writing Testsuites}, @code{AT_TESTED}).
23575 @item configuration log
23576 The contents of @file{config.log}, as created by @command{configure},
23577 are appended. It contains the configuration flags and a detailed report
23578 on the configuration itself.
23582 @node Writing Testsuites
23583 @section Writing @file{testsuite.at}
23585 The @file{testsuite.at} is a Bourne shell script making use of special
23586 Autotest M4 macros. It often contains a call to @code{AT_INIT} near
23587 its beginning followed by one call to @code{m4_include} per source file
23588 for tests. Each such included file, or the remainder of
23589 @file{testsuite.at} if include files are not used, contain a sequence of
23590 test groups. Each test group begins with a call to @code{AT_SETUP},
23591 then an arbitrary number of shell commands or calls to @code{AT_CHECK},
23592 and then completes with a call to @code{AT_CLEANUP}. Multiple test
23593 groups can be categorized by a call to @code{AT_BANNER}.
23595 All of the public Autotest macros have all-uppercase names in the
23596 namespace @samp{^AT_} to prevent them from accidentally conflicting with
23597 other text; Autoconf also reserves the namespace @samp{^_AT_} for
23598 internal macros. All shell variables used in the testsuite for internal
23599 purposes have mostly-lowercase names starting with @samp{at_}. Autotest
23600 also uses here-document delimiters in the namespace @samp{^_AT[A-Z]}, and
23601 makes use of the file system namespace @samp{^at-}.
23603 Since Autoconf is built on top of M4sugar (@pxref{Programming in
23604 M4sugar}) and M4sh (@pxref{Programming in M4sh}), you must also be aware
23605 of those namespaces (@samp{^_?\(m4\|AS\)_}). In general, you
23606 @emph{should not use} the namespace of a package that does not own the
23607 macro or shell code you are writing.
23609 @defmac AT_INIT (@ovar{name})
23611 @c FIXME: Not clear, plus duplication of the information.
23612 Initialize Autotest. Giving a @var{name} to the test suite is
23613 encouraged if your package includes several test suites. Before this
23614 macro is called, @code{AT_PACKAGE_STRING} and
23615 @code{AT_PACKAGE_BUGREPORT} must be defined, which are used to display
23616 information about the testsuite to the user. Typically, these macros
23617 are provided by a file @file{package.m4} built by @command{make}
23618 (@pxref{Making testsuite Scripts}), in order to inherit the package
23619 name, version, and bug reporting address from @file{configure.ac}.
23622 @defmac AT_COPYRIGHT (@var{copyright-notice})
23623 @atindex{COPYRIGHT}
23624 @cindex Copyright Notice
23625 State that, in addition to the Free Software Foundation's copyright on
23626 the Autotest macros, parts of your test suite are covered by
23627 @var{copyright-notice}.
23629 The @var{copyright-notice} shows up in both the head of
23630 @command{testsuite} and in @samp{testsuite --version}.
23633 @defmac AT_ARG_OPTION (@var{options}, @var{help-text}, @
23634 @ovar{action-if-given}, @ovar{action-if-not-given})
23635 @atindex{ARG_OPTION}
23636 Accept options from the space-separated list @var{options}, a list that
23637 has leading dashes removed from the options. Long options will be
23638 prefixed with @samp{--}, single-character options with @samp{-}. The
23639 first word in this list is the primary @var{option}, any others are
23640 assumed to be short-hand aliases. The variable associated with it
23641 is @code{at_arg_@var{option}}, with any dashes in @var{option} replaced
23644 If the user passes @option{--@var{option}} to the @command{testsuite},
23645 the variable will be set to @samp{:}. If the user does not pass the
23646 option, or passes @option{--no-@var{option}}, then the variable will be
23647 set to @samp{false}.
23649 @var{action-if-given} is run each time the option is encountered; here,
23650 the variable @code{at_optarg} will be set to @samp{:} or @samp{false} as
23651 appropriate. @code{at_optarg} is actually just a copy of
23652 @code{at_arg_@var{option}}.
23654 @var{action-if-not-given} will be run once after option parsing is
23655 complete and if no option from @var{options} was used.
23657 @var{help-text} is added to the end of the list of options shown in
23658 @command{testsuite --help} (@pxref{AS_HELP_STRING}).
23660 It it recommended that you use a package-specific prefix to @var{options}
23661 names in order to avoid clashes with future Autotest built-in options.
23664 @defmac AT_ARG_OPTION_ARG (@var{options}, @var{help-text}, @
23665 @ovar{action-if-given}, @ovar{action-if-not-given})
23666 @atindex{ARG_OPTION_ARG}
23667 Accept options with arguments from the space-separated list
23668 @var{options}, a list that has leading dashes removed from the options.
23669 Long options will be prefixed with @samp{--}, single-character options
23670 with @samp{-}. The first word in this list is the primary @var{option},
23671 any others are assumed to be short-hand aliases. The variable associated
23672 with it is @code{at_arg_@var{option}}, with any dashes in @var{option}
23673 replaced with underscores.
23675 If the user passes @option{--@var{option}=@var{arg}} or
23676 @option{--@var{option} @var{arg}} to the @command{testsuite}, the
23677 variable will be set to @samp{@var{arg}}.
23679 @var{action-if-given} is run each time the option is encountered; here,
23680 the variable @code{at_optarg} will be set to @samp{@var{arg}}.
23681 @code{at_optarg} is actually just a copy of @code{at_arg_@var{option}}.
23683 @var{action-if-not-given} will be run once after option parsing is
23684 complete and if no option from @var{options} was used.
23686 @var{help-text} is added to the end of the list of options shown in
23687 @command{testsuite --help} (@pxref{AS_HELP_STRING}).
23689 It it recommended that you use a package-specific prefix to @var{options}
23690 names in order to avoid clashes with future Autotest built-in options.
23693 @defmac AT_COLOR_TESTS
23694 @atindex{COLOR_TESTS}
23695 Enable colored test results by default when the output is connected to
23699 @defmac AT_TESTED (@var{executables})
23701 Log the file name and answer to @option{--version} of each program in
23702 space-separated list @var{executables}. Several invocations register
23703 new executables, in other words, don't fear registering one program
23706 Autotest test suites rely on @env{PATH} to find the tested program.
23707 This avoids the need to generate absolute names of the various tools, and
23708 makes it possible to test installed programs. Therefore, knowing which
23709 programs are being exercised is crucial to understanding problems in
23710 the test suite itself, or its occasional misuses. It is a good idea to
23711 also subscribe foreign programs you depend upon, to avoid incompatible
23717 @defmac AT_BANNER (@var{test-category-name})
23719 This macro identifies the start of a category of related test groups.
23720 When the resulting @file{testsuite} is invoked with more than one test
23721 group to run, its output will include a banner containing
23722 @var{test-category-name} prior to any tests run from that category. The
23723 banner should be no more than about 40 or 50 characters. A blank banner
23724 will not print, effectively ending a category and letting subsequent
23725 test groups behave as though they are uncategorized when run in
23729 @defmac AT_SETUP (@var{test-group-name})
23731 This macro starts a group of related tests, all to be executed in the
23732 same subshell. It accepts a single argument, which holds a few words
23733 (no more than about 30 or 40 characters) quickly describing the purpose
23734 of the test group being started. @var{test-group-name} must not expand
23735 to unbalanced quotes, although quadrigraphs can be used.
23738 @defmac AT_KEYWORDS (@var{keywords})
23740 Associate the space-separated list of @var{keywords} to the enclosing
23741 test group. This makes it possible to run ``slices'' of the test suite.
23742 For instance, if some of your test groups exercise some @samp{foo}
23743 feature, then using @samp{AT_KEYWORDS(foo)} lets you run
23744 @samp{./testsuite -k foo} to run exclusively these test groups. The
23745 @var{test-group-name} of the test group is automatically recorded to
23746 @code{AT_KEYWORDS}.
23748 Several invocations within a test group accumulate new keywords. In
23749 other words, don't fear registering the same keyword several times in a
23753 @defmac AT_CAPTURE_FILE (@var{file})
23754 @atindex{CAPTURE_FILE}
23755 If the current test group fails, log the contents of @var{file}.
23756 Several identical calls within one test group have no additional effect.
23759 @defmac AT_FAIL_IF (@var{shell-condition})
23761 Make the test group fail and skip the rest of its execution, if
23762 @var{shell-condition} is true. @var{shell-condition} is a shell expression
23763 such as a @code{test} command. Tests before @command{AT_FAIL_IF}
23764 will be executed and may still cause the test group to be skipped.
23765 You can instantiate this macro many times from within the same test group.
23767 You should use this macro only for very simple failure conditions. If the
23768 @var{shell-condition} could emit any kind of output you should instead
23769 use @command{AT_CHECK} like
23771 AT_CHECK([if @var{shell-condition}; then exit 99; fi])
23774 so that such output is properly recorded in the @file{testsuite.log}
23778 @defmac AT_SKIP_IF (@var{shell-condition})
23780 Determine whether the test should be skipped because it requires
23781 features that are unsupported on the machine under test.
23782 @var{shell-condition} is a shell expression such as a @code{test}
23783 command. Tests before @command{AT_SKIP_IF} will be executed
23784 and may still cause the test group to fail. You can instantiate this
23785 macro many times from within the same test group.
23787 You should use this macro only for very simple skip conditions. If the
23788 @var{shell-condition} could emit any kind of output you should instead
23789 use @command{AT_CHECK} like
23791 AT_CHECK([if @var{shell-condition}; then exit 77; fi])
23794 so that such output is properly recorded in the @file{testsuite.log}
23798 @defmac AT_XFAIL_IF (@var{shell-condition})
23800 Determine whether the test is expected to fail because it is a known
23801 bug (for unsupported features, you should skip the test).
23802 @var{shell-condition} is a shell expression such as a @code{test}
23803 command; you can instantiate this macro many times from within the
23804 same test group, and one of the conditions is enough to turn
23805 the test into an expected failure.
23810 End the current test group.
23815 @defmac AT_DATA (@var{file}, @var{contents})
23817 Initialize an input data @var{file} with given @var{contents}. Of
23818 course, the @var{contents} have to be properly quoted between square
23819 brackets to protect against included commas or spurious M4
23820 expansion. The contents must end with an end of line. @var{file} must
23821 be a single shell word that expands into a single file name.
23824 @defmac AT_CHECK (@var{commands}, @dvar{status, 0}, @ovar{stdout}, @
23825 @ovar{stderr}, @ovar{run-if-fail}, @ovar{run-if-pass})
23826 @defmacx AT_CHECK_UNQUOTED (@var{commands}, @dvar{status, 0}, @ovar{stdout}, @
23827 @ovar{stderr}, @ovar{run-if-fail}, @ovar{run-if-pass})
23829 @atindex{CHECK_UNQUOTED}
23830 Execute a test by performing given shell @var{commands}. @var{commands}
23831 is output as-is, so shell expansions are honored. These commands
23832 should normally exit with @var{status}, while producing expected
23833 @var{stdout} and @var{stderr} contents. If @var{commands} exit with
23834 unexpected status 77, then the rest of the test group is skipped. If
23835 @var{commands} exit with unexpected status 99, then the test group is
23836 immediately failed. Otherwise, if this test
23837 fails, run shell commands @var{run-if-fail} or, if this test passes, run shell
23838 commands @var{run-if-pass}.
23840 This macro must be invoked in between @code{AT_SETUP} and @code{AT_CLEANUP}.
23842 If @var{status} is the literal @samp{ignore}, then the corresponding
23843 exit status is not checked, except for the special cases of 77 (skip)
23844 and 99 (hard failure). The existence of hard failures allows one to
23845 mark a test as an expected failure with @code{AT_XFAIL_IF} because a
23846 feature has not yet been implemented, but to still distinguish between
23847 gracefully handling the missing feature and dumping core. A hard
23848 failure also inhibits post-test actions in @var{run-if-fail}.
23850 If the value of the @var{stdout} or @var{stderr} parameter is one of the
23851 literals in the following table, then the test treats the output
23852 according to the rules of that literal. Otherwise, the value of the
23853 parameter is treated as text that must exactly match the output given by
23854 @var{commands} on standard output and standard error (including an empty
23855 parameter for no output); any differences are captured in the testsuite
23856 log and the test is failed (unless an unexpected exit status of 77
23857 skipped the test instead). The difference between @code{AT_CHECK} and
23858 @code{AT_CHECK_UNQUOTED} is that only the latter performs shell variable
23859 expansion (@samp{$}), command substitution (@samp{`}), and backslash
23860 escaping (@samp{\}) on comparison text given in the @var{stdout} and
23861 @var{stderr} arguments; if the text includes a trailing newline, this
23862 would be the same as if it were specified via an unquoted
23863 here-document. (However, there is no difference in the interpretation
23864 of @var{commands}).
23868 The content of the output is ignored, but still captured in the test
23869 group log (if the testsuite is run with option @option{-v}, the test
23870 group log is displayed as the test is run; if the test group later
23871 fails, the test group log is also copied into the overall testsuite
23872 log). This action is valid for both @var{stdout} and @var{stderr}.
23875 The content of the output is ignored, and nothing is captured in the log
23876 files. If @var{commands} are likely to produce binary output (including
23877 long lines) or large amounts of output, then logging the output can make
23878 it harder to locate details related to subsequent tests within the
23879 group, and could potentially corrupt terminal display of a user running
23880 @command{testsuite -v}.
23883 For the @var{stdout} parameter, capture the content of standard output
23884 to both the file @file{stdout} and the test group log. Subsequent
23885 commands in the test group can then post-process the file. This action
23886 is often used when it is desired to use @command{grep} to look for a
23887 substring in the output, or when the output must be post-processed to
23888 normalize error messages into a common form.
23891 Like @samp{stdout}, except that it only works for the @var{stderr}
23892 parameter, and the standard error capture file will be named
23896 @itemx stderr-nolog
23897 Like @samp{stdout} or @samp{stderr}, except that the captured output is
23898 not duplicated into the test group log. This action is particularly
23899 useful for an intermediate check that produces large amounts of data,
23900 which will be followed by another check that filters down to the
23901 relevant data, as it makes it easier to locate details in the log.
23904 For the @var{stdout} parameter, compare standard output contents with
23905 the previously created file @file{expout}, and list any differences in
23909 Like @samp{expout}, except that it only works for the @var{stderr}
23910 parameter, and the standard error contents are compared with
23915 @defmac AT_CHECK_EUNIT (@var{module}, @var{test-spec}, @ovar{erlflags}, @
23916 @ovar{run-if-fail}, @ovar{run-if-pass})
23917 @atindex{CHECK_EUNIT}
23918 Initialize and execute an Erlang module named @var{module} that performs
23919 tests following the @var{test-spec} EUnit test specification.
23920 @var{test-spec} must be a valid EUnit test specification, as defined in
23921 the @uref{http://@/erlang.org/@/doc/@/apps/@/eunit/@/index.html, EUnit
23922 Reference Manual}. @var{erlflags} are optional command-line options
23923 passed to the Erlang interpreter to execute the test Erlang module.
23924 Typically, @var{erlflags} defines at least the paths to directories
23925 containing the compiled Erlang modules under test, as @samp{-pa path1
23928 For example, the unit tests associated with Erlang module @samp{testme},
23929 which compiled code is in subdirectory @file{src}, can be performed
23933 AT_CHECK_EUNIT([testme_testsuite], [@{module, testme@}],
23934 [-pa "$@{abs_top_builddir@}/src"])
23937 This macro must be invoked in between @code{AT_SETUP} and @code{AT_CLEANUP}.
23939 Variables @code{ERL}, @code{ERLC}, and (optionally) @code{ERLCFLAGS}
23940 must be defined as the path of the Erlang interpreter, the path of the
23941 Erlang compiler, and the command-line flags to pass to the compiler,
23942 respectively. Those variables should be configured in
23943 @file{configure.ac} using the @command{AC_ERLANG_PATH_ERL} and
23944 @command{AC_ERLANG_PATH_ERLC} macros, and the configured values of those
23945 variables are automatically defined in the testsuite. If @code{ERL} or
23946 @code{ERLC} is not defined, the test group is skipped.
23948 If the EUnit library cannot be found, i.e. if module @code{eunit} cannot
23949 be loaded, the test group is skipped. Otherwise, if @var{test-spec} is
23950 an invalid EUnit test specification, the test group fails. Otherwise,
23951 if the EUnit test passes, shell commands @var{run-if-pass} are executed
23952 or, if the EUnit test fails, shell commands @var{run-if-fail} are
23953 executed and the test group fails.
23955 Only the generated test Erlang module is automatically compiled and
23956 executed. If @var{test-spec} involves testing other Erlang modules,
23957 e.g. module @samp{testme} in the example above, those modules must be
23960 If the testsuite is run in verbose mode, with option @option{--verbose},
23961 EUnit is also run in verbose mode to output more details about
23962 individual unit tests.
23966 @node testsuite Invocation
23967 @section Running @command{testsuite} Scripts
23968 @cindex @command{testsuite}
23970 Autotest test suites support the following options:
23975 Display the list of options and exit successfully.
23979 Display the version of the test suite and exit successfully.
23981 @item --directory=@var{dir}
23982 @itemx -C @var{dir}
23983 Change the current directory to @var{dir} before creating any files.
23984 Useful for running the testsuite in a subdirectory from a top-level
23987 @item --jobs@r{[}=@var{n}@r{]}
23989 Run @var{n} tests in parallel, if possible. If @var{n} is not given,
23990 run all given tests in parallel. Note that there should be no space
23991 before the argument to @option{-j}, as @option{-j @var{number}} denotes
23992 the separate arguments @option{-j} and @option{@var{number}}, see below.
23994 In parallel mode, the standard input device of the testsuite script is
23995 not available to commands inside a test group. Furthermore, banner
23996 lines are not printed, and the summary line for each test group is
23997 output after the test group completes. Summary lines may appear
23998 unordered. If verbose and trace output are enabled (see below), they
23999 may appear intermixed from concurrently running tests.
24001 Parallel mode requires the @command{mkfifo} command to work, and will be
24002 silently disabled otherwise.
24006 Remove all the files the test suite might have created and exit. Meant
24007 for @code{clean} Make targets.
24011 List all the tests (or only the selection), including their possible
24017 By default all tests are performed (or described with @option{--list})
24018 silently in the default environment, but the environment, set of tests,
24019 and verbosity level can be tuned:
24022 @item @var{variable}=@var{value}
24023 Set the environment @var{variable} to @var{value}. Use this rather
24024 than @samp{FOO=foo ./testsuite} as debugging scripts would then run in a
24025 different environment.
24027 @cindex @code{AUTOTEST_PATH}
24028 The variable @code{AUTOTEST_PATH} specifies the testing path to prepend
24029 to @env{PATH}. Relative directory names (not starting with
24030 @samp{/}) are considered to be relative to the top level of the
24031 package being built. All directories are made absolute, first
24032 starting from the top level @emph{build} tree, then from the
24033 @emph{source} tree. For instance @samp{./testsuite
24034 AUTOTEST_PATH=tests:bin} for a @file{/src/foo-1.0} source package built
24035 in @file{/tmp/foo} results in @samp{/tmp/foo/tests:/tmp/foo/bin} and
24036 then @samp{/src/foo-1.0/tests:/src/foo-1.0/bin} being prepended to
24040 @itemx @var{number}-@var{number}
24041 @itemx @var{number}-
24042 @itemx -@var{number}
24043 Add the corresponding test groups, with obvious semantics, to the
24046 @item --keywords=@var{keywords}
24047 @itemx -k @var{keywords}
24048 Add to the selection the test groups with title or keywords (arguments
24049 to @code{AT_SETUP} or @code{AT_KEYWORDS}) that match @emph{all} keywords
24050 of the comma separated list @var{keywords}, case-insensitively. Use
24051 @samp{!} immediately before the keyword to invert the selection for this
24052 keyword. By default, the keywords match whole words; enclose them in
24053 @samp{.*} to also match parts of words.
24055 For example, running
24058 @kbd{./testsuite -k 'autoupdate,.*FUNC.*'}
24062 selects all tests tagged @samp{autoupdate} @emph{and} with tags
24063 containing @samp{FUNC} (as in @samp{AC_CHECK_FUNC}, @samp{AC_FUNC_ALLOCA},
24067 @kbd{./testsuite -k '!autoupdate' -k '.*FUNC.*'}
24071 selects all tests not tagged @samp{autoupdate} @emph{or} with tags
24072 containing @samp{FUNC}.
24076 If any test fails, immediately abort testing. This implies
24077 @option{--debug}: post test group clean up, and top-level logging
24078 are inhibited. This option is meant for the full test
24079 suite, it is not really useful for generated debugging scripts.
24080 If the testsuite is run in parallel mode using @option{--jobs},
24081 then concurrently running tests will finish before exiting.
24085 Force more verbosity in the detailed output of what is being done. This
24086 is the default for debugging scripts.
24089 @itemx --color@r{[}=never@r{|}auto@r{|}always@r{]}
24090 Enable colored test results. Without an argument, or with @samp{always},
24091 test results will be colored. With @samp{never}, color mode is turned
24092 off. Otherwise, if either the macro @code{AT_COLOR_TESTS} is used by
24093 the testsuite author, or the argument @samp{auto} is given, then test
24094 results are colored if standard output is connected to a terminal.
24098 Do not remove the files after a test group was performed---but they are
24099 still removed @emph{before}, therefore using this option is sane when
24100 running several test groups. Create debugging scripts. Do not
24101 overwrite the top-level
24102 log (in order to preserve a supposedly existing full log file). This is
24103 the default for debugging scripts, but it can also be useful to debug
24104 the testsuite itself.
24107 Add to the selection all test groups that failed or passed unexpectedly
24108 during the last non-debugging test run.
24112 Trigger shell tracing of the test groups.
24115 Besides these options accepted by every Autotest testsuite, the
24116 testsuite author might have added package-specific options
24117 via the @code{AT_ARG_OPTION} and @code{AT_ARG_OPTION_ARG} macros
24118 (@pxref{Writing Testsuites}); refer to @command{testsuite --help} and
24119 the package documentation for details.
24122 @node Making testsuite Scripts
24123 @section Making @command{testsuite} Scripts
24125 For putting Autotest into movement, you need some configuration and
24126 makefile machinery. We recommend, at least if your package uses deep or
24127 shallow hierarchies, that you use @file{tests/} as the name of the
24128 directory holding all your tests and their makefile. Here is a
24129 check list of things to do.
24134 @cindex @file{package.m4}
24135 @atindex{PACKAGE_STRING}
24136 @atindex{PACKAGE_BUGREPORT}
24137 @atindex{PACKAGE_NAME}
24138 @atindex{PACKAGE_TARNAME}
24139 @atindex{PACKAGE_VERSION}
24140 @atindex{PACKAGE_URL}
24141 Make sure to create the file @file{package.m4}, which defines the
24142 identity of the package. It must define @code{AT_PACKAGE_STRING}, the
24143 full signature of the package, and @code{AT_PACKAGE_BUGREPORT}, the
24144 address to which bug reports should be sent. For sake of completeness,
24145 we suggest that you also define @code{AT_PACKAGE_NAME},
24146 @code{AT_PACKAGE_TARNAME}, @code{AT_PACKAGE_VERSION}, and
24147 @code{AT_PACKAGE_URL}.
24148 @xref{Initializing configure}, for a description of these variables.
24149 Be sure to distribute @file{package.m4} and to put it into the source
24150 hierarchy: the test suite ought to be shipped! See below for an example
24151 @file{Makefile} excerpt.
24154 Invoke @code{AC_CONFIG_TESTDIR}.
24156 @defmac AC_CONFIG_TESTDIR (@var{directory}, @dvar{test-path, directory})
24157 @acindex{CONFIG_TESTDIR}
24158 An Autotest test suite is to be configured in @var{directory}. This
24159 macro requires the instantiation of @file{@var{directory}/atconfig} from
24160 @file{@var{directory}/atconfig.in}, and sets the default
24161 @code{AUTOTEST_PATH} to @var{test-path} (@pxref{testsuite Invocation}).
24165 Still within @file{configure.ac}, as appropriate, ensure that some
24166 @code{AC_CONFIG_FILES} command includes substitution for
24167 @file{tests/atlocal}.
24170 The appropriate @file{Makefile} should be modified so the validation in
24171 your package is triggered by @samp{make check}. An example is provided
24175 With Automake, here is a minimal example for inclusion in
24176 @file{tests/Makefile.am}, in order to link @samp{make check} with a
24180 # The `:;' works around a Bash 3.2 bug when the output is not writeable.
24181 $(srcdir)/package.m4: $(top_srcdir)/configure.ac
24183 echo '# Signature of the current package.' && \
24184 echo 'm4_define([AT_PACKAGE_NAME],' && \
24185 echo ' [$(PACKAGE_NAME)])' && \
24186 echo 'm4_define([AT_PACKAGE_TARNAME],' && \
24187 echo ' [$(PACKAGE_TARNAME)])' && \
24188 echo 'm4_define([AT_PACKAGE_VERSION],' && \
24189 echo ' [$(PACKAGE_VERSION)])' && \
24190 echo 'm4_define([AT_PACKAGE_STRING],' && \
24191 echo ' [$(PACKAGE_STRING)])' && \
24192 echo 'm4_define([AT_PACKAGE_BUGREPORT],' && \
24193 echo ' [$(PACKAGE_BUGREPORT)])'; \
24194 echo 'm4_define([AT_PACKAGE_URL],' && \
24195 echo ' [$(PACKAGE_URL)])'; \
24196 @} >'$(srcdir)/package.m4'
24198 EXTRA_DIST = testsuite.at $(srcdir)/package.m4 $(TESTSUITE) atlocal.in
24199 TESTSUITE = $(srcdir)/testsuite
24201 check-local: atconfig atlocal $(TESTSUITE)
24202 $(SHELL) '$(TESTSUITE)' $(TESTSUITEFLAGS)
24204 installcheck-local: atconfig atlocal $(TESTSUITE)
24205 $(SHELL) '$(TESTSUITE)' AUTOTEST_PATH='$(bindir)' \
24209 test ! -f '$(TESTSUITE)' || \
24210 $(SHELL) '$(TESTSUITE)' --clean
24212 AUTOM4TE = $(SHELL) $(srcdir)/build-aux/missing --run autom4te
24213 AUTOTEST = $(AUTOM4TE) --language=autotest
24214 $(TESTSUITE): $(srcdir)/testsuite.at $(srcdir)/package.m4
24215 $(AUTOTEST) -I '$(srcdir)' -o $@@.tmp $@@.at
24219 Note that the built testsuite is distributed; this is necessary because
24220 users might not have Autoconf installed, and thus would not be able to
24221 rebuild it. Likewise, the use of @file{missing} provides the user with
24222 a nicer error message if they modify a source file to the testsuite, and
24223 accidentally trigger the rebuild rules.
24225 You might want to list explicitly the dependencies, i.e., the list of
24226 the files @file{testsuite.at} includes.
24228 If you don't use Automake, you should include the above example in
24229 @file{tests/@/Makefile.in}, along with additional lines inspired from
24234 PACKAGE_NAME = @@PACKAGE_NAME@@
24235 PACKAGE_TARNAME = @@PACKAGE_TARNAME@@
24236 PACKAGE_VERSION = @@PACKAGE_VERSION@@
24237 PACKAGE_STRING = @@PACKAGE_STRING@@
24238 PACKAGE_BUGREPORT = @@PACKAGE_BUGREPORT@@
24239 PACKAGE_URL = @@PACKAGE_URL@@
24241 atconfig: $(top_builddir)/config.status
24242 cd $(top_builddir) && \
24243 $(SHELL) ./config.status $(subdir)/$@@
24245 atlocal: $(srcdir)/atlocal.in $(top_builddir)/config.status
24246 cd $(top_builddir) && \
24247 $(SHELL) ./config.status $(subdir)/$@@
24251 and manage to have @code{$(EXTRA_DIST)} distributed. You will also want
24252 to distribute the file @file{build-aux/@/missing} from the Automake
24253 project; a copy of this file resides in the Autoconf source tree.
24255 With all this in place, and if you have not initialized @samp{TESTSUITEFLAGS}
24256 within your makefile, you can fine-tune test suite execution with this
24257 variable, for example:
24260 make check TESTSUITEFLAGS='-v -d -x 75 -k AC_PROG_CC CFLAGS=-g'
24265 @c =============================== Frequent Autoconf Questions, with answers
24268 @chapter Frequent Autoconf Questions, with answers
24270 Several questions about Autoconf come up occasionally. Here some of them
24274 * Distributing:: Distributing @command{configure} scripts
24275 * Why GNU M4:: Why not use the standard M4?
24276 * Bootstrapping:: Autoconf and GNU M4 require each other?
24277 * Why Not Imake:: Why GNU uses @command{configure} instead of Imake
24278 * Defining Directories:: Passing @code{datadir} to program
24279 * Autom4te Cache:: What is it? Can I remove it?
24280 * Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree
24281 * Expanded Before Required:: Expanded Before Required
24282 * Debugging:: Debugging @command{configure} scripts
24286 @section Distributing @command{configure} Scripts
24290 What are the restrictions on distributing @command{configure}
24291 scripts that Autoconf generates? How does that affect my
24292 programs that use them?
24295 There are no restrictions on how the configuration scripts that Autoconf
24296 produces may be distributed or used. In Autoconf version 1, they were
24297 covered by the GNU General Public License. We still encourage
24298 software authors to distribute their work under terms like those of the
24299 GPL, but doing so is not required to use Autoconf.
24301 Of the other files that might be used with @command{configure},
24302 @file{config.h.in} is under whatever copyright you use for your
24303 @file{configure.ac}. @file{config.sub} and @file{config.guess} have an
24304 exception to the GPL when they are used with an Autoconf-generated
24305 @command{configure} script, which permits you to distribute them under the
24306 same terms as the rest of your package. @file{install-sh} is from the X
24307 Consortium and is not copyrighted.
24310 @section Why Require GNU M4?
24313 Why does Autoconf require GNU M4?
24316 Many M4 implementations have hard-coded limitations on the size and
24317 number of macros that Autoconf exceeds. They also lack several
24318 builtin macros that it would be difficult to get along without in a
24319 sophisticated application like Autoconf, including:
24329 Autoconf requires version 1.4.6 or later of GNU M4.
24331 Since only software maintainers need to use Autoconf, and since GNU
24332 M4 is simple to configure and install, it seems reasonable to require
24333 GNU M4 to be installed also. Many maintainers of GNU and
24334 other free software already have most of the GNU utilities
24335 installed, since they prefer them.
24337 @node Bootstrapping
24338 @section How Can I Bootstrap?
24342 If Autoconf requires GNU M4 and GNU M4 has an Autoconf
24343 @command{configure} script, how do I bootstrap? It seems like a chicken
24347 This is a misunderstanding. Although GNU M4 does come with a
24348 @command{configure} script produced by Autoconf, Autoconf is not required
24349 in order to run the script and install GNU M4. Autoconf is only
24350 required if you want to change the M4 @command{configure} script, which few
24351 people have to do (mainly its maintainer).
24353 @node Why Not Imake
24354 @section Why Not Imake?
24358 Why not use Imake instead of @command{configure} scripts?
24361 Several people have written addressing this question, so I include
24362 adaptations of their explanations here.
24364 The following answer is based on one written by Richard Pixley:
24367 Autoconf generated scripts frequently work on machines that it has
24368 never been set up to handle before. That is, it does a good job of
24369 inferring a configuration for a new system. Imake cannot do this.
24371 Imake uses a common database of host specific data. For X11, this makes
24372 sense because the distribution is made as a collection of tools, by one
24373 central authority who has control over the database.
24375 GNU tools are not released this way. Each GNU tool has a
24376 maintainer; these maintainers are scattered across the world. Using a
24377 common database would be a maintenance nightmare. Autoconf may appear
24378 to be this kind of database, but in fact it is not. Instead of listing
24379 host dependencies, it lists program requirements.
24381 If you view the GNU suite as a collection of native tools, then the
24382 problems are similar. But the GNU development tools can be
24383 configured as cross tools in almost any host+target permutation. All of
24384 these configurations can be installed concurrently. They can even be
24385 configured to share host independent files across hosts. Imake doesn't
24386 address these issues.
24388 Imake templates are a form of standardization. The GNU coding
24389 standards address the same issues without necessarily imposing the same
24394 Here is some further explanation, written by Per Bothner:
24397 One of the advantages of Imake is that it easy to generate large
24398 makefiles using the @samp{#include} and macro mechanisms of @command{cpp}.
24399 However, @code{cpp} is not programmable: it has limited conditional
24400 facilities, and no looping. And @code{cpp} cannot inspect its
24403 All of these problems are solved by using @code{sh} instead of
24404 @code{cpp}. The shell is fully programmable, has macro substitution,
24405 can execute (or source) other shell scripts, and can inspect its
24410 Paul Eggert elaborates more:
24413 With Autoconf, installers need not assume that Imake itself is already
24414 installed and working well. This may not seem like much of an advantage
24415 to people who are accustomed to Imake. But on many hosts Imake is not
24416 installed or the default installation is not working well, and requiring
24417 Imake to install a package hinders the acceptance of that package on
24418 those hosts. For example, the Imake template and configuration files
24419 might not be installed properly on a host, or the Imake build procedure
24420 might wrongly assume that all source files are in one big directory
24421 tree, or the Imake configuration might assume one compiler whereas the
24422 package or the installer needs to use another, or there might be a
24423 version mismatch between the Imake expected by the package and the Imake
24424 supported by the host. These problems are much rarer with Autoconf,
24425 where each package comes with its own independent configuration
24428 Also, Imake often suffers from unexpected interactions between
24429 @command{make} and the installer's C preprocessor. The fundamental problem
24430 here is that the C preprocessor was designed to preprocess C programs,
24431 not makefiles. This is much less of a problem with Autoconf,
24432 which uses the general-purpose preprocessor M4, and where the
24433 package's author (rather than the installer) does the preprocessing in a
24438 Finally, Mark Eichin notes:
24441 Imake isn't all that extensible, either. In order to add new features to
24442 Imake, you need to provide your own project template, and duplicate most
24443 of the features of the existing one. This means that for a sophisticated
24444 project, using the vendor-provided Imake templates fails to provide any
24445 leverage---since they don't cover anything that your own project needs
24446 (unless it is an X11 program).
24448 On the other side, though:
24450 The one advantage that Imake has over @command{configure}:
24451 @file{Imakefile} files tend to be much shorter (likewise, less redundant)
24452 than @file{Makefile.in} files. There is a fix to this, however---at least
24453 for the Kerberos V5 tree, we've modified things to call in common
24454 @file{post.in} and @file{pre.in} makefile fragments for the
24455 entire tree. This means that a lot of common things don't have to be
24456 duplicated, even though they normally are in @command{configure} setups.
24460 @node Defining Directories
24461 @section How Do I @code{#define} Installation Directories?
24464 My program needs library files, installed in @code{datadir} and
24468 AC_DEFINE_UNQUOTED([DATADIR], [$datadir],
24469 [Define to the read-only architecture-independent
24477 #define DATADIR "$@{prefix@}/share"
24481 As already explained, this behavior is on purpose, mandated by the
24482 GNU Coding Standards, see @ref{Installation Directory
24483 Variables}. There are several means to achieve a similar goal:
24487 Do not use @code{AC_DEFINE} but use your makefile to pass the
24488 actual value of @code{datadir} via compilation flags.
24489 @xref{Installation Directory Variables}, for the details.
24492 This solution can be simplified when compiling a program: you may either
24493 extend the @code{CPPFLAGS}:
24496 CPPFLAGS = -DDATADIR='"$(datadir)"' @@CPPFLAGS@@
24500 If you are using Automake, you should use @code{AM_CPPFLAGS} instead:
24503 AM_CPPFLAGS = -DDATADIR='"$(datadir)"'
24507 Alternatively, create a dedicated header file:
24510 DISTCLEANFILES = myprog-paths.h
24511 myprog-paths.h: Makefile
24512 echo '#define DATADIR "$(datadir)"' >$@@
24516 Use @code{AC_DEFINE} but have @command{configure} compute the literal
24517 value of @code{datadir} and others. Many people have wrapped macros to
24518 automate this task; for an example, see the macro @code{AC_DEFINE_DIR} from
24519 the @uref{http://@/www.gnu.org/@/software/@/autoconf-archive/, Autoconf Macro
24522 This solution does not conform to the GNU Coding Standards.
24525 Note that all the previous solutions hard wire the absolute name of
24526 these directories in the executables, which is not a good property. You
24527 may try to compute the names relative to @code{prefix}, and try to
24528 find @code{prefix} at runtime, this way your package is relocatable.
24532 @node Autom4te Cache
24533 @section What is @file{autom4te.cache}?
24536 What is this directory @file{autom4te.cache}? Can I safely remove it?
24539 In the GNU Build System, @file{configure.ac} plays a central
24540 role and is read by many tools: @command{autoconf} to create
24541 @file{configure}, @command{autoheader} to create @file{config.h.in},
24542 @command{automake} to create @file{Makefile.in}, @command{autoscan} to
24543 check the completeness of @file{configure.ac}, @command{autoreconf} to
24544 check the GNU Build System components that are used. To
24545 ``read @file{configure.ac}'' actually means to compile it with M4,
24546 which can be a long process for complex @file{configure.ac}.
24548 This is why all these tools, instead of running directly M4, invoke
24549 @command{autom4te} (@pxref{autom4te Invocation}) which, while answering to
24550 a specific demand, stores additional information in
24551 @file{autom4te.cache} for future runs. For instance, if you run
24552 @command{autoconf}, behind the scenes, @command{autom4te} also
24553 stores information for the other tools, so that when you invoke
24554 @command{autoheader} or @command{automake} etc., reprocessing
24555 @file{configure.ac} is not needed. The speed up is frequently 30%,
24556 and is increasing with the size of @file{configure.ac}.
24558 But it is and remains being simply a cache: you can safely remove it.
24563 Can I permanently get rid of it?
24566 The creation of this cache can be disabled from
24567 @file{~/.autom4te.cfg}, see @ref{Customizing autom4te}, for more
24568 details. You should be aware that disabling the cache slows down the
24569 Autoconf test suite by 40%. The more GNU Build System
24570 components are used, the more the cache is useful; for instance
24571 running @samp{autoreconf -f} on the Core Utilities is twice slower without
24572 the cache @emph{although @option{--force} implies that the cache is
24573 not fully exploited}, and eight times slower than without
24577 @node Present But Cannot Be Compiled
24578 @section Header Present But Cannot Be Compiled
24580 The most important guideline to bear in mind when checking for
24581 features is to mimic as much as possible the intended use.
24582 Unfortunately, old versions of @code{AC_CHECK_HEADER} and
24583 @code{AC_CHECK_HEADERS} failed to follow this idea, and called
24584 the preprocessor, instead of the compiler, to check for headers. As a
24585 result, incompatibilities between headers went unnoticed during
24586 configuration, and maintainers finally had to deal with this issue
24589 The transition began with Autoconf 2.56. As of Autoconf 2.64 both
24590 checks are performed, and @command{configure} complains loudly if the
24591 compiler and the preprocessor do not agree. However, only the compiler
24592 result is considered.
24594 Consider the following example:
24597 $ @kbd{cat number.h}
24598 typedef int number;
24600 const number pi = 3;
24601 $ @kbd{cat configure.ac}
24602 AC_INIT([Example], [1.0], [bug-example@@example.org])
24603 AC_CHECK_HEADERS([pi.h])
24604 $ @kbd{autoconf -Wall}
24605 $ @kbd{./configure}
24606 checking for gcc... gcc
24607 checking for C compiler default output file name... a.out
24608 checking whether the C compiler works... yes
24609 checking whether we are cross compiling... no
24610 checking for suffix of executables...
24611 checking for suffix of object files... o
24612 checking whether we are using the GNU C compiler... yes
24613 checking whether gcc accepts -g... yes
24614 checking for gcc option to accept ISO C89... none needed
24615 checking how to run the C preprocessor... gcc -E
24616 checking for grep that handles long lines and -e... grep
24617 checking for egrep... grep -E
24618 checking for ANSI C header files... yes
24619 checking for sys/types.h... yes
24620 checking for sys/stat.h... yes
24621 checking for stdlib.h... yes
24622 checking for string.h... yes
24623 checking for memory.h... yes
24624 checking for strings.h... yes
24625 checking for inttypes.h... yes
24626 checking for stdint.h... yes
24627 checking for unistd.h... yes
24628 checking pi.h usability... no
24629 checking pi.h presence... yes
24630 configure: WARNING: pi.h: present but cannot be compiled
24631 configure: WARNING: pi.h: check for missing prerequisite headers?
24632 configure: WARNING: pi.h: see the Autoconf documentation
24633 configure: WARNING: pi.h: section "Present But Cannot Be Compiled"
24634 configure: WARNING: pi.h: proceeding with the compiler's result
24635 configure: WARNING: ## -------------------------------------- ##
24636 configure: WARNING: ## Report this to bug-example@@example.org ##
24637 configure: WARNING: ## -------------------------------------- ##
24638 checking for pi.h... yes
24642 The proper way the handle this case is using the fourth argument
24643 (@pxref{Generic Headers}):
24646 $ @kbd{cat configure.ac}
24647 AC_INIT([Example], [1.0], [bug-example@@example.org])
24648 AC_CHECK_HEADERS([number.h pi.h], [], [],
24649 [[#ifdef HAVE_NUMBER_H
24650 # include <number.h>
24653 $ @kbd{autoconf -Wall}
24654 $ @kbd{./configure}
24655 checking for gcc... gcc
24656 checking for C compiler default output... a.out
24657 checking whether the C compiler works... yes
24658 checking whether we are cross compiling... no
24659 checking for suffix of executables...
24660 checking for suffix of object files... o
24661 checking whether we are using the GNU C compiler... yes
24662 checking whether gcc accepts -g... yes
24663 checking for gcc option to accept ANSI C... none needed
24664 checking for number.h... yes
24665 checking for pi.h... yes
24668 See @ref{Particular Headers}, for a list of headers with their
24671 @node Expanded Before Required
24672 @section Expanded Before Required
24674 @cindex expanded before required
24675 Older versions of Autoconf silently built files with incorrect ordering
24676 between dependent macros if an outer macro first expanded, then later
24677 indirectly required, an inner macro. Starting with Autoconf 2.64, this
24678 situation no longer generates out-of-order code, but results in
24679 duplicate output and a syntax warning:
24682 $ @kbd{cat configure.ac}
24683 @result{}AC_DEFUN([TESTA], [[echo in A
24684 @result{}if test -n "$SEEN_A" ; then echo duplicate ; fi
24685 @result{}SEEN_A=:]])
24686 @result{}AC_DEFUN([TESTB], [AC_REQUIRE([TESTA])[echo in B
24687 @result{}if test -z "$SEEN_A" ; then echo bug ; fi]])
24688 @result{}AC_DEFUN([TESTC], [AC_REQUIRE([TESTB])[echo in C]])
24689 @result{}AC_DEFUN([OUTER], [[echo in OUTER]
24696 @result{}configure.ac:11: warning: AC_REQUIRE:
24697 @result{} `TESTA' was expanded before it was required
24698 @result{}configure.ac:4: TESTB is expanded from...
24699 @result{}configure.ac:6: TESTC is expanded from...
24700 @result{}configure.ac:7: OUTER is expanded from...
24701 @result{}configure.ac:11: the top level
24705 To avoid this warning, decide what purpose the macro in question serves.
24706 If it only needs to be expanded once (for example, if it provides
24707 initialization text used by later macros), then the simplest fix is to
24708 change the macro to be declared with @code{AC_DEFUN_ONCE}
24709 (@pxref{One-Shot Macros}), although this only works in Autoconf 2.64 and
24710 newer. A more portable fix is to change all
24711 instances of direct calls to instead go through @code{AC_REQUIRE}
24712 (@pxref{Prerequisite Macros}). If, instead, the macro is parameterized
24713 by arguments or by the current definition of other macros in the m4
24714 environment, then the macro should always be directly expanded instead
24717 For another case study, consider this example trimmed down from an
24718 actual package. Originally, the package contained shell code and
24719 multiple macro invocations at the top level of @file{configure.ac}:
24722 AC_DEFUN([FOO], [AC_COMPILE_IFELSE([@dots{}])])
24729 but that was getting complex, so the author wanted to offload some of
24730 the text into a new macro in another file included via
24731 @file{aclocal.m4}. The na@"ive approach merely wraps the text in a new
24735 AC_DEFUN([FOO], [AC_COMPILE_IFELSE([@dots{}])])
24745 With older versions of Autoconf, the setting of @samp{foobar=} occurs
24746 before the single compiler check, as the author intended. But with
24747 Autoconf 2.64, this issues the ``expanded before it was required''
24748 warning for @code{AC_PROG_CC}, and outputs two copies of the compiler
24749 check, one before @samp{foobar=}, and one after. To understand why this
24750 is happening, remember that the use of @code{AC_COMPILE_IFELSE} includes
24751 a call to @code{AC_REQUIRE([AC_PROG_CC])} under the hood. According to
24752 the documented semantics of @code{AC_REQUIRE}, this means that
24753 @code{AC_PROG_CC} @emph{must} occur before the body of the outermost
24754 @code{AC_DEFUN}, which in this case is @code{BAR}, thus preceeding the
24755 use of @samp{foobar=}. The older versions of Autoconf were broken with
24756 regards to the rules of @code{AC_REQUIRE}, which explains why the code
24757 changed from one over to two copies of @code{AC_PROG_CC} when upgrading
24758 autoconf. In other words, the author was unknowingly relying on a bug
24759 exploit to get the desired results, and that exploit broke once the bug
24762 So, what recourse does the author have, to restore their intended
24763 semantics of setting @samp{foobar=} prior to a single compiler check,
24764 regardless of whether Autoconf 2.63 or 2.64 is used? One idea is to
24765 remember that only @code{AC_DEFUN} is impacted by @code{AC_REQUIRE};
24766 there is always the possibility of using the lower-level
24770 AC_DEFUN([FOO], [AC_COMPILE_IFELSE([@dots{}])])
24780 This works great if everything is in the same file. However, it does
24781 not help in the case where the author wants to have @command{aclocal}
24782 find the definition of @code{BAR} from its own file, since
24783 @command{aclocal} requires the use of @code{AC_DEFUN}. In this case, a
24784 better fix is to recognize that if @code{BAR} also uses
24785 @code{AC_REQUIRE}, then there will no longer be direct expansion prior
24786 to a subsequent require. Then, by creating yet another helper macro,
24787 the author can once again guarantee a single invocation of
24788 @code{AC_PROG_CC}, which will still occur after @code{foobar=}. The
24789 author can also use @code{AC_BEFORE} to make sure no other macro
24790 appearing before @code{BAR} has triggered an unwanted expansion of
24794 AC_DEFUN([FOO], [AC_COMPILE_IFELSE([@dots{}])])
24795 AC_DEFUN([BEFORE_CC], [
24799 AC_BEFORE([$0], [AC_PROG_CC])dnl
24800 AC_REQUIRE([BEFORE_CC])dnl
24801 AC_REQUIRE([AC_PROG_CC])dnl
24809 @section Debugging @command{configure} scripts
24811 While in general, @command{configure} scripts generated by Autoconf
24812 strive to be fairly portable to various systems, compilers, shells, and
24813 other tools, it may still be necessary to debug a failing test, broken
24814 script or makefile, or fix or override an incomplete, faulty, or erroneous
24815 test, especially during macro development. Failures can occur at all levels,
24816 in M4 syntax or semantics, shell script issues, or due to bugs in the
24817 test or the tools invoked by @command{configure}. Together with the
24818 rather arcane error message that @command{m4} and @command{make} may
24819 produce when their input contains syntax errors, this can make debugging
24822 Nevertheless, here is a list of hints and strategies that may help:
24826 When @command{autoconf} fails, common causes for error include:
24830 mismatched or unbalanced parentheses or braces (@pxref{Balancing
24833 @item under- or overquoted macro arguments (@pxref{Autoconf
24834 Language}, @pxref{Quoting and Parameters}, @pxref{Quotation and Nested
24837 @item spaces between macro name and opening parenthesis (@pxref{Autoconf
24841 Typically, it helps to go back to the last working version of the input
24842 and compare the differences for each of these errors. Another
24843 possibility is to sprinkle pairs of @code{m4_traceon} and
24844 @code{m4_traceoff} judiciously in the code, either without a parameter
24845 or listing some macro names and watch @command{m4} expand its input
24846 verbosely (@pxref{Debugging via autom4te}).
24849 Sometimes @command{autoconf} succeeds but the generated
24850 @command{configure} script has invalid shell syntax. You can detect this
24851 case by running @samp{bash -n configure} or @samp{sh -n configure}.
24852 If this command fails, the same tips apply, as if @command{autoconf} had
24856 Debugging @command{configure} script execution may be done by sprinkling
24857 pairs of @code{set -x} and @code{set +x} into the shell script before
24858 and after the region that contains a bug. Running the whole script with
24859 @samp{@var{shell} ./configure -vx 2>&1 | tee @var{log-file}} with a decent
24860 @var{shell} may work, but produces lots of output. Here, it can help to
24861 search for markers like @samp{checking for} a particular test in the
24865 When @command{configure} tests produce invalid results for your system,
24866 it may be necessary to override them:
24870 For programs, tools or libraries variables, preprocessor, compiler, or
24871 linker flags, it is often sufficient to override them at @command{make}
24872 run time with some care (@pxref{Macros and Submakes}). Since this
24873 normally won't cause @command{configure} to be run again with these
24874 changed settings, it may fail if the changed variable would have caused
24875 different test results from @command{configure}, so this may work only
24876 for simple differences.
24879 Most tests which produce their result in a substituted variable allow to
24880 override the test by setting the variable on the @command{configure}
24881 command line (@pxref{Compilers and Options}, @pxref{Defining Variables},
24882 @pxref{Particular Systems}).
24885 Many tests store their result in a cache variable (@pxref{Caching
24886 Results}). This lets you override them either on the
24887 @command{configure} command line as above, or through a primed cache or
24888 site file (@pxref{Cache Files}, @pxref{Site Defaults}). The name of a
24889 cache variable is documented with a test macro or may be inferred from
24890 @ref{Cache Variable Names}; the precise semantics of undocumented
24891 variables are often internal details, subject to change.
24895 Alternatively, @command{configure} may produce invalid results because
24896 of uncaught programming errors, in your package or in an upstream
24897 library package. For example, when @code{AC_CHECK_LIB} fails to find a
24898 library with a specified function, always check @file{config.log}. This
24899 will reveal the exact error that produced the failing result: the
24900 library linked by @code{AC_CHECK_LIB} probably has a fatal bug.
24903 Conversely, as macro author, you can make it easier for users of your
24908 by minimizing dependencies between tests and between test results as far
24912 by using @command{make} variables to factorize and allow
24913 override of settings at @command{make} run time,
24916 by honoring the GNU Coding Standards and not overriding flags
24917 reserved for the user except temporarily during @command{configure}
24921 by not requiring users of your macro to use the cache variables.
24922 Instead, expose the result of the test via @var{run-if-true} and
24923 @var{run-if-false} parameters. If the result is not a boolean,
24924 then provide it through documented shell variables.
24928 @c ===================================================== History of Autoconf.
24931 @chapter History of Autoconf
24932 @cindex History of autoconf
24934 You may be wondering, Why was Autoconf originally written? How did it
24935 get into its present form? (Why does it look like gorilla spit?) If
24936 you're not wondering, then this chapter contains no information useful
24937 to you, and you might as well skip it. If you @emph{are} wondering,
24938 then let there be light@enddots{}
24941 * Genesis:: Prehistory and naming of @command{configure}
24942 * Exodus:: The plagues of M4 and Perl
24943 * Leviticus:: The priestly code of portability arrives
24944 * Numbers:: Growth and contributors
24945 * Deuteronomy:: Approaching the promises of easy configuration
24951 In June 1991 I was maintaining many of the GNU utilities for the
24952 Free Software Foundation. As they were ported to more platforms and
24953 more programs were added, the number of @option{-D} options that users
24954 had to select in the makefile (around 20) became burdensome.
24955 Especially for me---I had to test each new release on a bunch of
24956 different systems. So I wrote a little shell script to guess some of
24957 the correct settings for the fileutils package, and released it as part
24958 of fileutils 2.0. That @command{configure} script worked well enough that
24959 the next month I adapted it (by hand) to create similar @command{configure}
24960 scripts for several other GNU utilities packages. Brian Berliner
24961 also adapted one of my scripts for his CVS revision control system.
24963 Later that summer, I learned that Richard Stallman and Richard Pixley
24964 were developing similar scripts to use in the GNU compiler tools;
24965 so I adapted my @command{configure} scripts to support their evolving
24966 interface: using the file name @file{Makefile.in} as the templates;
24967 adding @samp{+srcdir}, the first option (of many); and creating
24968 @file{config.status} files.
24973 As I got feedback from users, I incorporated many improvements, using
24974 Emacs to search and replace, cut and paste, similar changes in each of
24975 the scripts. As I adapted more GNU utilities packages to use
24976 @command{configure} scripts, updating them all by hand became impractical.
24977 Rich Murphey, the maintainer of the GNU graphics utilities, sent me
24978 mail saying that the @command{configure} scripts were great, and asking if
24979 I had a tool for generating them that I could send him. No, I thought,
24980 but I should! So I started to work out how to generate them. And the
24981 journey from the slavery of hand-written @command{configure} scripts to the
24982 abundance and ease of Autoconf began.
24984 Cygnus @command{configure}, which was being developed at around that time,
24985 is table driven; it is meant to deal mainly with a discrete number of
24986 system types with a small number of mainly unguessable features (such as
24987 details of the object file format). The automatic configuration system
24988 that Brian Fox had developed for Bash takes a similar approach. For
24989 general use, it seems to me a hopeless cause to try to maintain an
24990 up-to-date database of which features each variant of each operating
24991 system has. It's easier and more reliable to check for most features on
24992 the fly---especially on hybrid systems that people have hacked on
24993 locally or that have patches from vendors installed.
24995 I considered using an architecture similar to that of Cygnus
24996 @command{configure}, where there is a single @command{configure} script that
24997 reads pieces of @file{configure.in} when run. But I didn't want to have
24998 to distribute all of the feature tests with every package, so I settled
24999 on having a different @command{configure} made from each
25000 @file{configure.in} by a preprocessor. That approach also offered more
25001 control and flexibility.
25003 I looked briefly into using the Metaconfig package, by Larry Wall,
25004 Harlan Stenn, and Raphael Manfredi, but I decided not to for several
25005 reasons. The @command{Configure} scripts it produces are interactive,
25006 which I find quite inconvenient; I didn't like the ways it checked for
25007 some features (such as library functions); I didn't know that it was
25008 still being maintained, and the @command{Configure} scripts I had
25009 seen didn't work on many modern systems (such as System V R4 and NeXT);
25010 it wasn't flexible in what it could do in response to a feature's
25011 presence or absence; I found it confusing to learn; and it was too big
25012 and complex for my needs (I didn't realize then how much Autoconf would
25013 eventually have to grow).
25015 I considered using Perl to generate my style of @command{configure}
25016 scripts, but decided that M4 was better suited to the job of simple
25017 textual substitutions: it gets in the way less, because output is
25018 implicit. Plus, everyone already has it. (Initially I didn't rely on
25019 the GNU extensions to M4.) Also, some of my friends at the
25020 University of Maryland had recently been putting M4 front ends on
25021 several programs, including @code{tvtwm}, and I was interested in trying
25022 out a new language.
25027 Since my @command{configure} scripts determine the system's capabilities
25028 automatically, with no interactive user intervention, I decided to call
25029 the program that generates them Autoconfig. But with a version number
25030 tacked on, that name would be too long for old Unix file systems,
25031 so I shortened it to Autoconf.
25033 In the fall of 1991 I called together a group of fellow questers after
25034 the Holy Grail of portability (er, that is, alpha testers) to give me
25035 feedback as I encapsulated pieces of my handwritten scripts in M4 macros
25036 and continued to add features and improve the techniques used in the
25037 checks. Prominent among the testers were Fran@,{c}ois Pinard, who came up
25038 with the idea of making an Autoconf shell script to run M4
25039 and check for unresolved macro calls; Richard Pixley, who suggested
25040 running the compiler instead of searching the file system to find
25041 include files and symbols, for more accurate results; Karl Berry, who
25042 got Autoconf to configure @TeX{} and added the macro index to the
25043 documentation; and Ian Lance Taylor, who added support for creating a C
25044 header file as an alternative to putting @option{-D} options in a
25045 makefile, so he could use Autoconf for his UUCP package.
25046 The alpha testers cheerfully adjusted their files again and again as the
25047 names and calling conventions of the Autoconf macros changed from
25048 release to release. They all contributed many specific checks, great
25049 ideas, and bug fixes.
25054 In July 1992, after months of alpha testing, I released Autoconf 1.0,
25055 and converted many GNU packages to use it. I was surprised by how
25056 positive the reaction to it was. More people started using it than I
25057 could keep track of, including people working on software that wasn't
25058 part of the GNU Project (such as TCL, FSP, and Kerberos V5).
25059 Autoconf continued to improve rapidly, as many people using the
25060 @command{configure} scripts reported problems they encountered.
25062 Autoconf turned out to be a good torture test for M4 implementations.
25063 Unix M4 started to dump core because of the length of the
25064 macros that Autoconf defined, and several bugs showed up in GNU
25065 M4 as well. Eventually, we realized that we needed to use some
25066 features that only GNU M4 has. 4.3BSD M4, in
25067 particular, has an impoverished set of builtin macros; the System V
25068 version is better, but still doesn't provide everything we need.
25070 More development occurred as people put Autoconf under more stresses
25071 (and to uses I hadn't anticipated). Karl Berry added checks for X11.
25072 david zuhn contributed C++ support. Fran@,{c}ois Pinard made it diagnose
25073 invalid arguments. Jim Blandy bravely coerced it into configuring
25074 GNU Emacs, laying the groundwork for several later improvements.
25075 Roland McGrath got it to configure the GNU C Library, wrote the
25076 @command{autoheader} script to automate the creation of C header file
25077 templates, and added a @option{--verbose} option to @command{configure}.
25078 Noah Friedman added the @option{--autoconf-dir} option and
25079 @code{AC_MACRODIR} environment variable. (He also coined the term
25080 @dfn{autoconfiscate} to mean ``adapt a software package to use
25081 Autoconf''.) Roland and Noah improved the quoting protection in
25082 @code{AC_DEFINE} and fixed many bugs, especially when I got sick of
25083 dealing with portability problems from February through June, 1993.
25086 @section Deuteronomy
25088 A long wish list for major features had accumulated, and the effect of
25089 several years of patching by various people had left some residual
25090 cruft. In April 1994, while working for Cygnus Support, I began a major
25091 revision of Autoconf. I added most of the features of the Cygnus
25092 @command{configure} that Autoconf had lacked, largely by adapting the
25093 relevant parts of Cygnus @command{configure} with the help of david zuhn
25094 and Ken Raeburn. These features include support for using
25095 @file{config.sub}, @file{config.guess}, @option{--host}, and
25096 @option{--target}; making links to files; and running @command{configure}
25097 scripts in subdirectories. Adding these features enabled Ken to convert
25098 GNU @code{as}, and Rob Savoye to convert DejaGNU, to using
25101 I added more features in response to other peoples' requests. Many
25102 people had asked for @command{configure} scripts to share the results of
25103 the checks between runs, because (particularly when configuring a large
25104 source tree, like Cygnus does) they were frustratingly slow. Mike
25105 Haertel suggested adding site-specific initialization scripts. People
25106 distributing software that had to unpack on MS-DOS asked for a way to
25107 override the @file{.in} extension on the file names, which produced file
25108 names like @file{config.h.in} containing two dots. Jim Avera did an
25109 extensive examination of the problems with quoting in @code{AC_DEFINE}
25110 and @code{AC_SUBST}; his insights led to significant improvements.
25111 Richard Stallman asked that compiler output be sent to @file{config.log}
25112 instead of @file{/dev/null}, to help people debug the Emacs
25113 @command{configure} script.
25115 I made some other changes because of my dissatisfaction with the quality
25116 of the program. I made the messages showing results of the checks less
25117 ambiguous, always printing a result. I regularized the names of the
25118 macros and cleaned up coding style inconsistencies. I added some
25119 auxiliary utilities that I had developed to help convert source code
25120 packages to use Autoconf. With the help of Fran@,{c}ois Pinard, I made
25121 the macros not interrupt each others' messages. (That feature revealed
25122 some performance bottlenecks in GNU M4, which he hastily
25123 corrected!) I reorganized the documentation around problems people want
25124 to solve. And I began a test suite, because experience had shown that
25125 Autoconf has a pronounced tendency to regress when we change it.
25127 Again, several alpha testers gave invaluable feedback, especially
25128 Fran@,{c}ois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn,
25131 Finally, version 2.0 was ready. And there was much rejoicing. (And I
25132 have free time again. I think. Yeah, right.)
25135 @c ========================================================== Appendices
25138 @node GNU Free Documentation License
25139 @appendix GNU Free Documentation License
25147 * Environment Variable Index:: Index of environment variables used
25148 * Output Variable Index:: Index of variables set in output files
25149 * Preprocessor Symbol Index:: Index of C preprocessor symbols defined
25150 * Cache Variable Index:: Index of documented cache variables
25151 * Autoconf Macro Index:: Index of Autoconf macros
25152 * M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
25153 * Autotest Macro Index:: Index of Autotest macros
25154 * Program & Function Index:: Index of those with portability problems
25155 * Concept Index:: General index
25158 @node Environment Variable Index
25159 @appendixsec Environment Variable Index
25161 This is an alphabetical list of the environment variables that might
25162 influence Autoconf checks.
25166 @node Output Variable Index
25167 @appendixsec Output Variable Index
25169 This is an alphabetical list of the variables that Autoconf can
25170 substitute into files that it creates, typically one or more
25171 makefiles. @xref{Setting Output Variables}, for more information
25172 on how this is done.
25176 @node Preprocessor Symbol Index
25177 @appendixsec Preprocessor Symbol Index
25179 This is an alphabetical list of the C preprocessor symbols that the
25180 Autoconf macros define. To work with Autoconf, C source code needs to
25181 use these names in @code{#if} or @code{#ifdef} directives.
25185 @node Cache Variable Index
25186 @appendixsec Cache Variable Index
25188 This is an alphabetical list of documented cache variables used
25189 by macros defined in Autoconf. Autoconf macros may use additional cache
25190 variables internally.
25191 @ifset shortindexflag
25192 To make the list easier to use, the variables are listed without their
25193 preceding @samp{ac_cv_}.
25198 @node Autoconf Macro Index
25199 @appendixsec Autoconf Macro Index
25201 This is an alphabetical list of the Autoconf macros.
25202 @ifset shortindexflag
25203 To make the list easier to use, the macros are listed without their
25204 preceding @samp{AC_}.
25209 @node M4 Macro Index
25210 @appendixsec M4 Macro Index
25212 This is an alphabetical list of the M4, M4sugar, and M4sh macros.
25213 @ifset shortindexflag
25214 To make the list easier to use, the macros are listed without their
25215 preceding @samp{m4_} or @samp{AS_}.
25220 @node Autotest Macro Index
25221 @appendixsec Autotest Macro Index
25223 This is an alphabetical list of the Autotest macros.
25224 @ifset shortindexflag
25225 To make the list easier to use, the macros are listed without their
25226 preceding @samp{AT_}.
25231 @node Program & Function Index
25232 @appendixsec Program and Function Index
25234 This is an alphabetical list of the programs and functions whose
25235 portability is discussed in this document.
25239 @node Concept Index
25240 @appendixsec Concept Index
25242 This is an alphabetical list of the files, tools, and concepts
25243 introduced in this document.
25249 @c LocalWords: texinfo setfilename autoconf texi settitle setchapternewpage
25250 @c LocalWords: setcontentsaftertitlepage finalout ARG ovar varname dvar acx
25251 @c LocalWords: makeinfo dvi defcodeindex ev ov CPP cv Autotest mv defindex fn
25252 @c LocalWords: shortindexflag iftex ifset acindex ACindex ifclear ahindex fu
25253 @c LocalWords: asindex MSindex atindex ATindex auindex hdrindex prindex FIXME
25254 @c LocalWords: msindex alloca fnindex Aaarg indices FSF's dircategory ifnames
25255 @c LocalWords: direntry autoscan autoreconf autoheader autoupdate config FDs
25256 @c LocalWords: testsuite titlepage Elliston Demaille vskip filll ifnottex hmm
25257 @c LocalWords: insertcopying Autoconf's detailmenu Automake Libtool Posix ois
25258 @c LocalWords: Systemology Checkpointing Changequote INTERCAL changequote dfn
25259 @c LocalWords: Quadrigraphs builtins Shellology acconfig Bugward LIBOBJ Imake
25260 @c LocalWords: LIBOBJS IFELSE cindex flushright Pinard Metaconfig uref Simons
25261 @c LocalWords: distclean uninstall noindent versioning Tromey dir
25262 @c LocalWords: SAMS samp aclocal acsite underquoted emph itemx prepend SUBST
25263 @c LocalWords: evindex automake Gettext autopoint gettext symlink libtoolize
25264 @c LocalWords: defmac INIT tarname ovindex cvindex BUGREPORT PREREQ asis PROG
25265 @c LocalWords: SRCDIR srcdir globbing afterwards cmds foos fooo foooo init cd
25266 @c LocalWords: builddir timestamp src Imakefile chmod defvar CFLAGS CPPFLAGS
25267 @c LocalWords: CXXFLAGS DEFS DHAVE defvarx FCFLAGS FFLAGS LDFLAGS bindir GCC
25268 @c LocalWords: datadir datarootdir docdir dvidir htmldir libdir ifnothtml kbd
25269 @c LocalWords: includedir infodir libexecdir localedir localstatedir mandir
25270 @c LocalWords: oldincludedir pdfdir PDF psdir PostScript sbindir sysconfdir
25271 @c LocalWords: sharedstatedir DDATADIR sed tmp pkgdatadir VPATH conf unistd
25272 @c LocalWords: undef endif builtin FUNCS ifndef STACKSEG getb GETB YMP fubar
25273 @c LocalWords: PRE dest SUBDIRS subdirs fi struct STDC stdlib stddef INTTYPES
25274 @c LocalWords: inttypes STDINT stdint AWK AIX Solaris NeXT env EGREP FGREP yy
25275 @c LocalWords: LEXLIB YYTEXT lfl nonportable Automake's LN RANLIB byacc INETD
25276 @c LocalWords: inetd prog PROGS progs ranlib lmp lXt lX nsl gethostbyname UX
25277 @c LocalWords: NextStep isinf isnan glibc IRIX sunmath lm lsunmath pre sizeof
25278 @c LocalWords: ld inline malloc putenv setenv FreeBSD realloc SunOS MinGW
25279 @c LocalWords: snprintf vsnprintf sprintf vsprintf sscanf gcc strerror ifdef
25280 @c LocalWords: strnlen sysconf PAGESIZE unsetenv va fallback memcpy dst FUNC
25281 @c LocalWords: PowerPC GNUC libPW pragma Olibcalls CHOWN chown CLOSEDIR VFORK
25282 @c LocalWords: closedir FNMATCH fnmatch vfork FSEEKO LARGEFILE fseeko SVR sc
25283 @c LocalWords: largefile GETGROUPS getgroups GETLOADAVG DGUX UMAX NLIST KMEM
25284 @c LocalWords: SETGID getloadavg nlist GETMNTENT irix
25285 @c LocalWords: getmntent UnixWare GETPGRP getpgid getpgrp Posix's pid LSTAT
25286 @c LocalWords: lstat rpl MEMCMP memcmp OpenStep MBRTOWC mbrtowc MKTIME mktime
25287 @c LocalWords: localtime MMAP mmap OBSTACK obstack obstacks ARGTYPES timeval
25288 @c LocalWords: SETPGRP setpgrp defmacx Hurd SETVBUF setvbuf STRCOLL strcoll
25289 @c LocalWords: STRTOD strtod DECL STRFTIME strftime SCO UTIME utime VPRINTF
25290 @c LocalWords: DOPRNT vprintf doprnt sp unfixable LIBSOURCE LIBSOURCES Eggert
25291 @c LocalWords: linux netinet ia Tru XFree DIRENT NDIR dirent ndir multitable
25292 @c LocalWords: NAMLEN strlen namlen MKDEV SYSMACROS makedev RESOLV resolv DNS
25293 @c LocalWords: inet structs NAMESER arpa NETDB netdb UTekV UTS GCC's kB
25294 @c LocalWords: STDBOOL BOOL stdbool conformant cplusplus bool Bool stdarg tm
25295 @c LocalWords: ctype strchr strrchr rindex bcopy memmove memchr WEXITSTATUS
25296 @c LocalWords: WIFEXITED TIOCGWINSZ GWINSZ termios preprocess preprocessable
25297 @c LocalWords: DECLS strdup calloc BLKSIZE blksize RDEV rdev TZNAME tzname pw
25298 @c LocalWords: passwd gecos pwd MBSTATE mbstate wchar RETSIGTYPE hup UID uid
25299 @c LocalWords: gid ptrdiff uintmax EXEEXT OBJEXT Ae conftest AXP str
25300 @c LocalWords: ALIGNOF WERROR Werror cpp HP's WorkShop egcs un fied stdc CXX
25301 @c LocalWords: varargs BIGENDIAN Endianness SPARC endianness grep'ed CONST FC
25302 @c LocalWords: const STRINGIZE stringizing PARAMS unprotoize protos KCC cxx
25303 @c LocalWords: xlC aCC CXXCPP FREEFORM xlf FLIBS FCLIBS ish SRCEXT XTRA LFS
25304 @c LocalWords: ISC lcposix MINIX Minix conditionalized inlines hw dD confdefs
25305 @c LocalWords: fputs stdout PREPROC ar UFS HFS QNX realtime fstype STATVFS se
25306 @c LocalWords: statvfs STATFS statfs func machfile hdr lelf raboof DEFUN GTK
25307 @c LocalWords: GTKMM Grmph ified ine defn baz EOF qar Ahhh changecom algol io
25308 @c LocalWords: changeword quadrigraphs quadrigraph dnl SGI atoi overquoting
25309 @c LocalWords: Aas Wcross sep args namespace undefine bpatsubst popdef dquote
25310 @c LocalWords: bregexp Overquote overquotation meisch maisch meische maische
25311 @c LocalWords: miscian DIRNAME dirname MKDIR CATFILE XMKMF TRAVOLTA celsius
25312 @c LocalWords: EMX emxos Emacsen Korn DYNIX subshell posix Ksh ksh Pdksh Zsh
25313 @c LocalWords: pdksh zsh Allbery Lipe Kubota UWS zorglub stderr eval esac lfn
25314 @c LocalWords: drivespec Posixy DJGPP doschk prettybird LPT pfew Zsh's yu yaa
25315 @c LocalWords: yM uM aM firebird IP subdir misparses ok Unpatched abc bc zA
25316 @c LocalWords: CDPATH DUALCASE LINENO prepass Subshells lineno NULLCMD cmp wc
25317 @c LocalWords: MAILPATH scanset arg NetBSD Almquist printf expr cp
25318 @c LocalWords: Oliva awk Aaaaarg cmd regex xfoo GNV OpenVMS VM
25319 @c LocalWords: sparc Proulx nbar nfoo maxdepth acdilrtu TWG mc
25320 @c LocalWords: mkdir exe uname OpenBSD Fileutils mktemp umask TMPDIR guid os
25321 @c LocalWords: fooXXXXXX Unicos utimes hpux hppa unescaped
25322 @c LocalWords: pmake DOS's gmake ifoo DESTDIR autoconfiscated pc coff mips gg
25323 @c LocalWords: dec ultrix cpu wildcards rpcc rdtsc powerpc readline
25324 @c LocalWords: withval vxworks gless localcache usr LOFF loff CYGWIN Cygwin
25325 @c LocalWords: cygwin SIGLIST siglist SYSNDIR SYSDIR ptx lseq rusage elif MSC
25326 @c LocalWords: lfoo POUNDBANG lsun NIS getpwnam SYSCALLS RSH INTL lintl aix
25327 @c LocalWords: intl lx ldir syslog bsd EPI toolchain netbsd objext de KNR nn
25328 @c LocalWords: fication LTLIBOBJS Wdiff TESTDIR atconfig atlocal akim XFAIL
25329 @c LocalWords: ChangeLog prepended errexit smallexample TESTSUITEFLAGS GPL er
25330 @c LocalWords: installcheck autotest indir Pixley Bothner Eichin Kerberos adl
25331 @c LocalWords: DISTCLEANFILES preprocessor's fileutils Stallman Murphey Stenn
25332 @c LocalWords: Manfredi Autoconfig TCL FSP david zuhn Blandy MACRODIR Raeburn
25333 @c LocalWords: autoconfiscate Savoye Haertel Avera Meyering fdl appendixsec
25334 @c LocalWords: printindex american LIBOBJDIR LibdirTest ERLCFLAGS OBJCFLAGS
25335 @c LocalWords: VER Gnulib online xyes strcpy TYPEOF typeof OBJC objcc objc ln
25336 @c LocalWords: GOBJC OTP ERLC erl valloc decr dumpdef errprint incr
25337 @c LocalWords: esyscmd len maketemp pushdef substr syscmd sysval translit txt
25338 @c LocalWords: sinclude foreach myvar tolower toupper uniq BASENAME STDIN
25339 @c LocalWords: Dynix descrips basename aname cname macroexpands xno xcheck
25340 @c LocalWords: LIBREADLINE lreadline lncurses libreadline
25342 @c Local Variables:
25344 @c ispell-local-dictionary: "american"
25345 @c indent-tabs-mode: nil
25346 @c whitespace-check-buffer-indent: nil